Service Agent Spawn Runbook

Status: orchestrator-owned runbook for parallel service-agent waves.

Use this runbook when the orchestrator is ready to spawn service-owner agents from the canonical service map. It complements, but does not replace, service-agent-manifest.json, service-agent-dispatch-roster.md, service-agent-proof-ledger.json, service-agent-wave-board.md, service-workflow-test-matrix.md, service-agent-spawn-packets.md, service-agent-execution-queue.json, service-agent-closeout-ledger.json, and service-agent-next-slice-closeout-ledger.json, and the per-service task packs. The Service Agent Execution Queue names the first concrete taskId for each canonical service owner. After that first handoff is accepted, use the Service Agent Next Slice Queue to pick the next bounded proof-gate slice and machine-readable nextTaskId instead of respawning the accepted task. Use docs/agents/service-agent-next-slice-spawn-packets.md as the prompt packet catalog for those next slices and docs/agents/service-agent-next-slice-closeout-ledger.json as the acceptance ledger for their future handoffs.

Preflight

Before spawning any worker:

1. Read the current goal attachments and docs/microservices/.
2. Run or inspect the latest results for:
   • sh scripts/test/agent-dispatch-readiness-coverage.sh
   • sh scripts/test/service-task-pack-coverage.sh
   • make test-service-readiness
   • make test-runtime-foundation
3. Confirm the worktree is dirty-aware and do not revert unrelated changes.
4. Pick one wave or one bounded cross-service slice from docs/agents/service-agent-wave-board.md.
5. Check docs/agents/service-agent-proof-ledger.json for the current not-complete proof gate. A spawn-ready row is dispatchable, not complete. Check docs/agents/service-agent-closeout-ledger.json for the required handoff path and current closeout status.
6. If docs/agents/service-agent-execution-queue.json marks the row first-slice-accepted, do not reuse that first-slice taskId; pick the next bounded proof-gate slice from docs/agents/service-agent-next-slice-queue.json. Use docs/agents/service-agent-next-slice-spawn-packets.md as the prompt packet source for that nextTaskId, then use docs/agents/service-agent-next-slice-closeout-ledger.json for the required handoff path and closeout status.
7. If no accepted handoff exists yet, pick the concrete first-slice taskId from docs/agents/service-agent-execution-queue.json; do not invent a broader worker slice when the queue marks the row contract/audit-first.
8. Assign at most one worker per implementation directory.
9. Treat scripts/dev/services.sh as the active runtime manifest. Every deployable worker must map back to one listed implementation service through docs/agents/service-agent-manifest.json and docs/agents/service-agent-dispatch-roster.md; adapter, alias-only, and retirement rows need their explicit non-deployable rule before spawning.
10. Use the roster Dispatch ID as the worker task-id prefix, for example SVC-003-password-reset-parity.
11. Copy the matching row from docs/agents/service-agent-spawn-packets.md before spawning a worker so the prompt includes the task pack, writable implementation scope, first verification command, and wave coordination notes.
12. Run make test-service-agent-execution-queue after changing queued slice docs, task IDs, dependency notes, or first verification commands.

Batch Rules

Batch	Safe parallel owners	Coordination rule
Wave 1 foundation	api-gateway, iam-service, profile-service, organization-service, classroom-service, bff-service	IAM and organization membership changes need an explicit contract handoff before shared route/deploy edits.
Wave 2 learning/import	course-service, question-service, exam-service, attempt-service, file-service, import-service, formula-docx-service, search-service	Import approval, exam-start, attempt, and search route work must keep gateway route files orchestrator-owned unless delegated.
Wave 3 monetization/AI	ai-service, billing-service, wallet-service, usage-service, payment-service	Billing, wallet, usage, and payment event contracts are shared orchestrator-owned contracts until stabilized.
Wave 4 operations	notification-service, audit-service, analytics-service, admin-service	Admin must not absorb audit, notification, IAM, wallet, payment, or analytics source-of-truth logic.
Retirement	user-service retirement only	No new product work goes into services/user-service.

Do not spawn deployable implementation workers for alias-only rows:

• auth-service routes to iam-service.
• entitlement-service routes to usage-service.
• formula-docx-service is a runtime-adapter task pack. It may receive parser/runtime compatibility work through SVC-013, but it must not create a services/formula-docx-service implementation directory.

If a proposed worker name is absent from scripts/dev/services.sh, stop and check whether it is a canonical alias, runtime adapter, or retirement row. Do not create a new service directory just to make the spawn plan fit.

Worker Prompt

Use this skeleton for each worker and fill in the service-specific fields from the dispatch roster or the ready packet catalog:

You own <canonical-service> for one bounded vertical slice in go-platform.
Task ID: <Dispatch ID>-<short-slice-slug> from docs/agents/service-agent-dispatch-roster.md.

Read first:
- docs/architecture/service-responsibility-matrix.md
- docs/agents/service-agent-manifest.json
- docs/agents/service-agent-proof-ledger.json
- docs/agents/service-agent-closeout-ledger.json
- docs/agents/service-agent-execution-queue.json
- docs/agents/service-agent-next-slice-queue.md
- docs/agents/service-agent-next-slice-queue.json
- docs/agents/service-agent-next-slice-spawn-packets.md
- docs/agents/service-agent-next-slice-closeout-ledger.json
- docs/agents/service-agent-next-slice-closeout-ledger.md
- docs/agents/service-agent-dispatch-roster.md
- docs/agents/service-agent-wave-board.md
- docs/agents/service-workflow-test-matrix.md
- docs/agents/service-agent-spawn-packets.md
- docs/agents/agent-handoff-format.md
- <task-pack>
- legacy evidence cited by <task-pack>

Ownership:
- Writable implementation scope: <implementation-owner>
- Writable docs/contracts scope: <task-pack writable files only>
- Orchestrator-owned files stay read-only unless this task explicitly delegates them.
- Runtime manifest check: <implementation-owner> is listed in scripts/dev/services.sh, or this is an explicitly documented adapter/retirement row.

Rules:
- You are not alone in the codebase. Do not revert unrelated worktree changes.
- Keep frontend callers behind api-gateway or an approved BFF.
- Do not create duplicate alias service directories.
- Keep default gateway routes legacy unless this is a named route rehearsal with rollback evidence.

Deliver:
- Task ID and handoff title using docs/agents/agent-handoff-format.md.
- Docs read and legacy files read.
- Files changed.
- Behavior implemented.
- Focused tests plus the first verification command from the dispatch roster.
- Route/default cutover status and rollback notes.
- Remaining risks and next recommended task.

Integration Checklist

After each worker returns:

• Review the diff against the worker's writable scope.
• Confirm the closeout follows docs/agents/agent-handoff-format.md and names the task ID, docs read, legacy evidence, files changed, tests, route state, risks, and next step.
• Update docs/agents/service-agent-closeout-ledger.json only after the accepted handoff exists and make test-service-agent-closeout-ledger can validate it.
• For next-slice handoffs, update docs/agents/service-agent-next-slice-closeout-ledger.json; keep the first-slice handoff in docs/agents/service-agent-closeout-ledger.json. Validate with make test-service-agent-next-slice-closeout.
• Run the worker's focused verification command.
• Run the relevant route guard if gateway routes changed.
• Run OpenAPI mirror checks if a service contract changed.
• Run sh scripts/test/service-task-pack-coverage.sh when task packs, dispatch docs, VitePress, or shared coverage scripts changed.
• Run make test-service-agent-execution-queue when queued task IDs, dependency notes, or first verification commands changed.
• Run make test-runtime-foundation after integrating a wave or changing Compose, K8s, Helm, migration, task-pack, or runtime-proof files.
• Update docs/qa/service-agent-readiness-smoke.md when the integrated readiness evidence changes materially.
• Update docs/agents/service-agent-wave-board.md only from the orchestrator thread after reviewing the worker result.

Stop Conditions

Pause spawning more workers when:

• Two workers need the same implementation directory or shared file.
• A service boundary contradicts service-responsibility-matrix.md.
• A worker needs to edit legacy source.
• A route cutover lacks browser/runtime proof or rollback notes.
• A DB-backed service tries to read another service database directly.