Service Agent Spawn Packets

Status: orchestrator-owned prompt packet catalog for service-owner workers.

Use this page with service-agent-manifest.json, service-agent-proof-ledger.json, service-agent-spawn-runbook.md, service-agent-dispatch-roster.md, service-agent-wave-board.md, service-workflow-test-matrix.md, service-agent-execution-queue.json, service-agent-next-slice-queue.json, service-agent-next-slice-spawn-packets.md, service-agent-closeout-ledger.json, and the assigned service task pack. It exists so the orchestrator can spawn service agents without hand-filling the same owner, task-pack, closeout, taskId, and verification fields each time.

Packet Rules

• The packet rows must stay aligned with docs/agents/service-agent-manifest.json.
• The proof state must stay aligned with docs/agents/service-agent-proof-ledger.json; spawn-ready is not a completion claim.
• The closeout state must stay aligned with docs/agents/service-agent-closeout-ledger.json; accepted handoffs are the machine-readable completion evidence for a bounded service slice.
• The first queued taskId and dependency notes must stay aligned with docs/agents/service-agent-execution-queue.json.
• After a first-slice handoff is accepted, the next nextTaskId and open proof gate must stay aligned with docs/agents/service-agent-next-slice-queue.json.
• Spawn at most one worker per implementation owner at a time.
• Use the Dispatch ID as the task-id prefix, for example SVC-003-refresh-token-rotation.
• Prefer the exact queued first-slice taskId from service-agent-execution-queue.json before closeout is accepted. After closeout acceptance, prefer the exact nextTaskId from service-agent-next-slice-queue.json and rerun make test-service-agent-execution-queue after queue edits. Use service-agent-next-slice-spawn-packets.md for prompt-ready next-slice fields.
• The worker must read the listed task pack before reading legacy evidence or changing code.
• Root Makefile, Compose, Helm, K8s, VitePress, generated OpenAPI indexes, and default gateway route tables stay orchestrator-owned unless the packet is explicitly extended with a delegated gateway verification scope.
• Do not spawn auth-service; auth/login/session/access work routes to SVC-003 iam-service.
• Do not spawn a separate entitlement-service; route entitlement work to SVC-018 usage-service.
• SVC-013 formula-docx-service is a runtime-adapter packet for the external Go Formula runtime. It must not create services/formula-docx-service.
• Legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/ is read-only evidence.

Base Prompt

You own <canonical-service> for one bounded vertical slice in go-platform.
Task ID: <dispatch-id>-<short-slice-slug>.

Read first:
- docs/architecture/service-responsibility-matrix.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-closeout-ledger.json
- docs/agents/service-agent-execution-queue.json
- docs/agents/service-agent-next-slice-queue.json
- 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.

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 alias directories or an auth-service/user-service boundary.
- Keep default gateway routes legacy unless this is a named route rehearsal with
  browser/runtime proof and rollback notes.

Deliver:
- Task ID and handoff title using docs/agents/agent-handoff-format.md.
- Closeout ledger row and required handoff path from
  docs/agents/service-agent-closeout-ledger.json.
- Docs read and legacy files read.
- Files changed.
- Behavior implemented.
- Focused tests plus the first verification command from this packet.
- Route/default cutover status and rollback notes.
- Remaining risks and next recommended task.

Wave 1 Packets

Dispatch ID	Canonical service	Implementation owner	Task pack	First verification
SVC-001	api-gateway	services/api-gateway	docs/agents/service-tasks/api-gateway.md	GOTOOLCHAIN=go1.25.11 go test ./services/api-gateway/...
SVC-002	bff-service	services/bff-service	docs/agents/service-tasks/bff-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/bff-service/...
SVC-003	iam-service	services/iam-service	docs/agents/service-tasks/iam-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/iam-service/...
SVC-004	profile-service	services/profile-service	docs/agents/service-tasks/profile-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/profile-service/...
SVC-005	organization-service	services/school-service alias	docs/agents/service-tasks/organization-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/school-service/...
SVC-006	classroom-service	services/classroom-service	docs/agents/service-tasks/classroom-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/classroom-service/...

Coordination notes:

• IAM and organization membership changes need an explicit contract handoff before shared route/deploy edits.
• IAM/Profile default-route promotion must use docs/agents/service-tasks/iam-profile-default-cutover-proof.md.
• Profile agents must keep password, JWT, role, permission, payment, and usage quota state out of profile-service.

Wave 2 Packets

Dispatch ID	Canonical service	Implementation owner	Task pack	First verification
SVC-007	course-service	services/course-service	docs/agents/service-tasks/course-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/course-service/...
SVC-008	question-service	services/question-bank-service alias	docs/agents/service-tasks/question-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/question-bank-service/...
SVC-009	exam-service	services/exam-service	docs/agents/service-tasks/exam-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/exam-service/...
SVC-010	attempt-service	services/attempt-service	docs/agents/service-tasks/attempt-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/attempt-service/...
SVC-011	file-service	services/document-service alias	docs/agents/service-tasks/file-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/document-service/...
SVC-012	import-service	services/docx-import-service alias	docs/agents/service-tasks/import-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/docx-import-service/...
SVC-013	formula-docx-service	source-controlled runtimes/go-formula-docx runtime	docs/agents/service-tasks/formula-docx-service.md	sh scripts/test/go-formula-runtime-coverage.sh
SVC-014	search-service	services/search-service	docs/agents/service-tasks/search-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/search-service/... -count=1

Coordination notes:

• Import approval, exam-start, attempt, question write, and search route work must keep gateway route files orchestrator-owned unless a delegated route verification scope is attached.
• question-service owns canonical question rows. Exam and attempt services store snapshots by value.
• Search indexes are rebuildable projections only, never source-of-truth data.

Wave 3 Packets

Dispatch ID	Canonical service	Implementation owner	Task pack	First verification
SVC-015	ai-service	services/ai-classifier-service alias	docs/agents/service-tasks/ai-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/ai-classifier-service/...
SVC-016	billing-service	services/billing-service	docs/agents/service-tasks/billing-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/billing-service/...
SVC-017	wallet-service	services/wallet-service	docs/agents/service-tasks/wallet-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/wallet-service/...
SVC-018	usage-service	services/usage-service	docs/agents/service-tasks/usage-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/usage-service/...
SVC-019	payment-service	services/payment-service	docs/agents/service-tasks/payment-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/payment-service/...

Coordination notes:

• Billing, wallet, usage, and payment event contracts stay orchestrator-owned until broker transport and replay semantics are stabilized.
• AI may call usage/wallet through explicit APIs, but it must not own quota decisions or credit movement.
• Subscriptions stay in billing, AZ Credits stay in wallet, and payment provider reconciliation stays in payment.

Wave 4 Packets

Dispatch ID	Canonical service	Implementation owner	Task pack	First verification
SVC-020	notification-service	services/notification-service	docs/agents/service-tasks/notification-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/notification-service/...
SVC-021	audit-service	services/audit-service	docs/agents/service-tasks/audit-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/audit-service/...
SVC-022	analytics-service	services/analytics-service	docs/agents/service-tasks/analytics-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/analytics-service/...
SVC-023	admin-service	services/admin-service	docs/agents/service-tasks/admin-service.md	GOTOOLCHAIN=go1.25.11 go test ./services/admin-service/...

Coordination notes:

• Admin-service may coordinate dashboards through owner APIs, but it must not absorb audit, notification, IAM, wallet, payment, or analytics source-of-truth storage.
• Audit-service owns compliance-grade append-only event history.
• Notification-service receives already-resolved recipients; profile/classroom recipient discovery remains an explicit handoff.

Retirement Packet

Dispatch ID	Canonical service	Implementation owner	Task pack	First verification
RET-USER	user-service retirement only	services/user-service deprecated compatibility scaffold	docs/agents/service-tasks/user-service-retirement.md	GOTOOLCHAIN=go1.25.11 go test ./services/user-service/...

Use this packet only for quarantine/removal work after IAM/Profile route parity, backfill validation, browser evidence, and rollback proof are attached. Do not route new product work to user-service.