Appearance
Agent Task Matrix
Phase: 1 Agent Plan Status: initial assignment matrix
Canonical Service Task Packs
Per-service task packs live under docs/agents/service-tasks/. Use these canonical service-owner packs as the first handoff unit when spawning one agent per service. Feature, cutover, and alias packs are listed separately below so they are not mistaken for independent service agents.
For workflow/test dispatch, pair each row with the machine-readable docs/agents/service-agent-manifest.json, docs/agents/service-agent-proof-ledger.json, docs/agents/service-agent-execution-queue.json, docs/agents/service-agent-dispatch-roster.md, and docs/agents/service-workflow-test-matrix.md; the roster fixes the spawn unit and first verification command, the execution queue fixes the first concrete taskId, the proof ledger records the not-complete closeout gates, and the workflow matrix records route/default cutover status expected from each service agent. Use the stable Dispatch ID as the task-id prefix in prompts and handoffs.
| Dispatch ID | Canonical service owner | Task pack |
|---|---|---|
| SVC-001 | api-gateway | docs/agents/service-tasks/api-gateway.md |
| SVC-002 | bff-service | docs/agents/service-tasks/bff-service.md |
| SVC-003 | iam-service | docs/agents/service-tasks/iam-service.md |
| SVC-004 | profile-service | docs/agents/service-tasks/profile-service.md |
| SVC-005 | organization-service | docs/agents/service-tasks/organization-service.md |
| SVC-006 | classroom-service | docs/agents/service-tasks/classroom-service.md |
| SVC-007 | course-service | docs/agents/service-tasks/course-service.md |
| SVC-008 | question-service | docs/agents/service-tasks/question-service.md |
| SVC-009 | exam-service | docs/agents/service-tasks/exam-service.md |
| SVC-010 | attempt-service | docs/agents/service-tasks/attempt-service.md |
| SVC-011 | file-service | docs/agents/service-tasks/file-service.md |
| SVC-012 | import-service | docs/agents/service-tasks/import-service.md |
| SVC-013 | formula-docx-service runtime adapter, not deployable service | docs/agents/service-tasks/formula-docx-service.md |
| SVC-014 | search-service | docs/agents/service-tasks/search-service.md |
| SVC-015 | ai-service | docs/agents/service-tasks/ai-service.md |
| SVC-016 | billing-service | docs/agents/service-tasks/billing-service.md |
| SVC-017 | wallet-service | docs/agents/service-tasks/wallet-service.md |
| SVC-018 | usage-service | docs/agents/service-tasks/usage-service.md |
| SVC-019 | payment-service | docs/agents/service-tasks/payment-service.md |
| SVC-020 | notification-service | docs/agents/service-tasks/notification-service.md |
| SVC-021 | audit-service | docs/agents/service-tasks/audit-service.md |
| SVC-022 | analytics-service | docs/agents/service-tasks/analytics-service.md |
| SVC-023 | admin-service | docs/agents/service-tasks/admin-service.md |
Orchestrator, Alias, And Cutover Packs
These packs coordinate service owners or route compatibility. They are not independent service-agent rows unless a later architecture decision promotes them to canonical services.
| Pack | Task pack | Routed owner |
|---|---|---|
| IAM Org Membership Canonical | docs/agents/service-tasks/iam-org-membership-canonical.md | IAM plus Organization coordination |
| IAM Invites | docs/agents/service-tasks/iam-invites.md | IAM feature slice |
| Profile Gateway Adapter | docs/agents/service-tasks/profile-gateway-adapter.md | Profile plus Gateway coordination |
| IAM/Profile Cutover Hardening | docs/agents/service-tasks/iam-profile-cutover-hardening.md | Orchestrator cutover |
| IAM/Profile Backfill Loader | docs/agents/service-tasks/iam-profile-backfill-loader.md | Orchestrator with IAM/Profile migration owners |
| IAM/Profile Default Cutover Proof | docs/agents/service-tasks/iam-profile-default-cutover-proof.md | Orchestrator with gateway/browser/migration owners |
| User Service Retirement | docs/agents/service-tasks/user-service-retirement.md | Orchestrator retirement only |
| Classroom Public Adapter Preflight | docs/agents/service-tasks/classroom-public-adapter-preflight.md | Classroom plus Gateway coordination |
| Course Workflow Hardening | docs/agents/service-tasks/course-workflow-hardening.md | Course feature slice |
| Course Learning Projection Contract | docs/agents/service-tasks/analytics-course-learning-projection.md | Course, Attempt, and Analytics coordination |
| Question Write Parity | docs/agents/service-tasks/question-write-parity.md | Question feature slice |
| Exam Runtime Access | docs/agents/service-tasks/exam-runtime-access.md | Exam plus Attempt coordination |
| Exam Start Adapter | docs/agents/service-tasks/exam-start-adapter.md | Exam plus Attempt plus Gateway/BFF coordination |
| Attempt Public Surfaces | docs/agents/service-tasks/attempt-public-surfaces.md | Attempt feature slice |
| Learning Public Gateway Cutover | docs/agents/service-tasks/learning-public-gateway-cutover.md | Orchestrator cutover |
| Import PDF/OCR Boundary | docs/agents/service-tasks/import-pdf-ocr-boundary.md | Import plus Usage/Wallet coordination |
| Import MathType Conversion Boundary | docs/agents/service-tasks/import-mathtype-conversion-boundary.md | Import plus Formula runtime adapter coordination |
| Operational Producer Events | docs/agents/service-tasks/operational-producer-events.md | Producer plus operational consumer coordination |
| Entitlement Alias | docs/agents/service-tasks/entitlement-service.md | Usage-service alias only |
| Monetization Scaffold Wave | docs/agents/service-tasks/monetization-scaffold-wave.md | Billing/Wallet/Usage/Payment coordination |
| Monetization Broker Transport | docs/agents/service-tasks/monetization-broker-transport.md | Billing/Wallet/Usage/Payment transport coordination |
Agent Streams
| Agent/Stream | Owns | Must Read First | Initial Tasks | Must Not Do |
|---|---|---|---|---|
| Platform Agent | shared Go packages, compose, CI scripts | target architecture, database strategy | P2-001 to P2-005, P2-008 | domain business logic |
| Gateway Agent | api-gateway, route table, proxy, adapters | API contract strategy, legacy API map | P2-006, P2-007, P3-004 | hide domain rules in gateway |
| BFF Agent | bff-service screen aggregation | responsibility matrix, API guide, frontend route docs | owner-service read adapters and gateway rehearsal | canonical domain writes or a primary business DB |
| IAM Agent | iam-service auth/access boundary | IAM task pack, legacy auth inventory | credential/session/permission workflows | profile, wallet, billing, or learning data |
| Profile Agent | profile-service education profiles | profile task pack, legacy auth/profile routes | role-profile and public/internal profile parity | login, passwords, JWTs, roles, permissions, payment |
| IAM/Profile Cutover Agent | IAM/Profile hardening and cutover blockers | IAM/Profile cutover task pack, IAM/Profile default cutover proof pack, IAM/Profile implementation report | UUID migration plan, make test-iam-profile-backfill-report, write-side backfill loader, run-report validation, browser proof, route rollback proof | recreate auth-service, add broad user-service work, or bypass gateway |
| Organization Agent | school-service as organization-service alias | organization task pack, IAM membership task | tenant validation and org metadata parity | profile details or IAM role policy |
| Classroom Agent | classroom-service | classroom task pack, organization boundary | class/member workflow parity | account creation or exam grading |
| Course Agent | course-service | course task pack, file/question/exam boundaries | course content/enrollment/progress parity | file bytes, payment logic, live question rows |
| Contract Agent | OpenAPI snapshots, fixtures, parity tools | legacy API map, business rules | P3-001, examples for auth/import/questions/exams | change frontend or backend legacy |
| Migration Agent | extract/backfill/validation tooling | database inventory, database mapping, validation plan | read-only source connection, count reports | write to legacy DB |
| File Agent | document-service/file-service, storage metadata | service boundaries, storage audit notes | media read parity, presigned upload contract | migrate wallet purchase logic without approval |
| Import Agent | docx-import-service/import-service | DOCX import audit, migration risks | job model, SSE model, Go Formula wrapper, PDF/OCR/MathType status and download slices | change question type inference without evidence |
| Formula DOCX Runtime Adapter Agent | go-formula-docx runtime behind docx-import-service; not a deployable services/formula-docx-service | formula task pack, parser handoffs | parser determinism, metrics, corpus/benchmark coverage, adapter evidence | import approval, frontend routes, or creating a duplicate service directory |
| Question Agent | question-bank-service/question-service | question rules, database mapping | question type list, question read parity | normalize scoring/rich content prematurely |
| Exam Agent | exam-service | exam rules, attempt rules | exam read parity, publish snapshot contract | start attempts directly |
| Attempt Agent | attempt-service | attempt rules, rollback plan | attempt snapshot model, answer save parity | cut over production attempts early |
| AI Agent | ai-classifier-service as ai-service alias | AI task pack, provider/settings evidence | provider/job/context/apply plus generate/explain/grade contract slices | quota decisions or wallet debits |
| Monetization Agent | billing, wallet, usage, payment foundations | responsibility matrix, legacy wallet/payment evidence, monetization broker transport pack | event integration, broker transport proof, gateway rehearsal, cutover tasks | add credits/subscriptions to IAM/Profile |
| Billing Agent | billing-service | billing task pack, legacy AZ plan/subscription evidence | plan seeds, payment event consumers, entitlement events | provider webhook ingestion or wallet ledger |
| Wallet Agent | wallet-service | wallet task pack, legacy wallet evidence | top-up/withdrawal/admin-review state machines | subscriptions or provider reconciliation |
| Usage Agent | usage-service; entitlement alias only | usage and entitlement task packs | feature gates, check/consume, billing sync | money movement or workload execution |
| Payment Agent | payment-service | payment task pack, SePay evidence | webhook auth, payment events, reconciliation | subscription activation or wallet balances |
| Notification Agent | notification-service | notification task pack, parent/profile boundaries | inbox/preferences/fanout producer contracts and delivery metadata | user lookup or audit logs |
| Search Agent | search-service | search task pack, owner-service indexing plan | rebuildable indexes and sync checkpoints | canonical business data |
| Audit Agent | audit-service | audit task pack, admin audit compatibility notes | append-only producer adapters, replay, backfill, and query parity | domain decisions or feature maintenance |
| Admin Agent | admin-service | feature maintenance rules, risk register | feature maintenance guard, support/admin inbox, and dashboard read-model slices | change Vietnamese labels or own source-service data |
Handoff Requirements
Every agent handoff must include:
- task ID
- docs read
- legacy files read
- files changed
- tests run
- open risks
- rollback notes
- next recommended task
Use agent-handoff-format.md.