Agent Orchestration

Phase: 1 Agent Plan Status: pre-implementation contract

Purpose

Coordinate parallel work on the Go rewrite without editing legacy source or creating conflicting service boundaries.

Global Rules For All Agents

• Do not modify legacy source outside go-platform/ unless a later explicit task says otherwise.
• Read relevant Phase 0 and Phase 1 docs before coding.
• Read the assigned file under docs/agents/service-tasks/ before coding.
• Cite legacy evidence paths in implementation notes.
• Keep service changes scoped to the assigned service.
• Follow canonical aliases from service-boundaries.md; for example file-service work writes document-service, question-service writes question-bank-service, and entitlement work writes usage-service.
• Do not invent business rules when legacy evidence is missing.
• Add or update tests for every behavior-bearing implementation.
• Keep gateway route state and rollback instructions current.

Work Streams

Stream	Scope	First Outputs
Platform	Go workspace, shared packages, compose, observability	module skeleton, config/logging/errors/health
Gateway	/api proxy, route state, adapters, SSE forwarding	proxy-only gateway
BFF	no-primary-DB frontend aggregation	screen shells, owner-service source status, route rehearsal
Identity/Profile/Tenant	IAM, profile, organization/school-service	auth/session, profile, tenant validation
Contracts	legacy OpenAPI snapshots, examples, parity fixtures	contract snapshots
Migration	data mapping, validation, backfill tooling	read-only extract reports
Document/Import	media, storage, DOCX jobs, review workflow	storage read parity, import job model
Question/Exam/Attempt	question types, bank, exam snapshots, attempts	read parity then write parity
Admin/Operations	feature maintenance, audit, dashboards	route prefix compatibility
Monetization	billing, wallet, usage, payment	event integration, ledger/payment/quota task slices
Communication/Discovery/Governance	notification, search, audit, analytics	fanout/read-model/index/audit task slices

One-Agent-Per-Service Flow

1. Assign exactly one service task pack from docs/agents/service-tasks/.
2. Treat the task pack as the agent's write-boundary owner document.
3. Shared files are orchestrator-owned unless explicitly delegated.
4. The agent returns findings, changed files, tests run, open risks, and next task.
5. The orchestrator integrates shared docs/deploy/config after reviewing diffs.

Dependency Order

1. Platform skeleton.
2. Gateway proxy-only mode.
3. Contract snapshot tooling.
4. Service skeletons.
5. Read-only routes.
6. Backfill and validation tooling.
7. Native write routes.

Review Gates

Before merge:

• files are under go-platform/ unless explicitly approved
• go test ./... or scoped equivalent passes
• sh scripts/test/service-task-pack-coverage.sh passes when task packs change
• route contract evidence is attached for route changes
• rollback note exists for route state changes
• docs updated if a decision/risk changed

Before route cutover:

• parity tests pass
• staging smoke passes
• monitoring exists
• rollback command tested
• owner approval recorded

Conflict Resolution

If two agents need the same boundary:

1. Stop implementation.
2. Update service-boundaries.md proposal.
3. Add decision to decision-log.md.
4. Resume only after the boundary is explicit.