How every file connects. What produces what. The complete flow from sprint idea to shipped code.
OPERATOR ORCHESTRATOR (Agent O) AGENTS (AI × N)
│ │ │
│ "Fix auth bugs, │ │
│ add rate limiting" │ │
│ ───────────────────────► │ │
│ │ │
│ ┌──────────┴──────────────┐ │
│ │ WAVE 0 — PLANNING: │ │
│ │ 1. Reads codebase │ │
│ │ 2. Analyzes architecture │ │
│ │ 3. Discovers work │ │
│ │ 4. Writes exec traces │ │
│ │ 5. Maps territories │ │
│ └──────────┬──────────────┘ │
│ │ │
│ ┌──────────┴──────────────┐ │
│ │ PRODUCES: │ │
│ │ • DISPATCH.md │ │
│ │ • agent-X-*.md (×N) │ │
│ │ • activation prompts │ │
│ └──────────┬──────────────┘ │
│ │ │
│ Reviews proposal │ │
│ ◄───────────────────────────│ │
│ Approves │ │
│ ───────────────────────► │ │
│ │ │
│ Sets up worktrees │ │
│ Opens terminals │ │
│ Pastes prompts ──────────────────────────────────────► │
│ │ ┌────┴──────┐
│ │ WAVES 1-3: │ Each agent│
│ │ Monitors progress, │ works on │
│ │ intervenes when │ its branch│
│ │ agents drift │ in its │
│ │ off-mission │ territory │
│ │ ◄────────────────────────│ │
│ │ │ Produces: │
│ │ │ • Code │
│ │ │ • Tests │
│ │ │ • Complet-│
│ │ │ ion doc │
│ │ └────┬──────┘
│ │ │
│ ┌──────────┴──────────────┐ │
│ │ WAVE 4: RED TEAM reviews │ │
│ │ WAVE 5: LEAD merges │ │
│ └──────────┬──────────────┘ │
│ │ │
│ ┌──────────┴──────────────┐ │
│ │ WAVE 6 — ASSESSMENT: │ │
│ │ • Grades each agent │ │
│ │ • Mission alignment │ │
│ │ • SPRINT-ASSESSMENT.md │ │
│ │ • Carry-forward work │ │
│ └──────────┬──────────────┘ │
│ │ │
│ Ship ✓ │ │
What reads what. Follow the arrows.
┌──────────────────┐
│ OPERATOR GIVES │
│ sprint goal + │
│ codebase access │
└────────┬─────────┘
│
▼
┌─────────────────────────┐
│ ORCHESTRATOR (Agent O) │ ◄── agents/orchestrator.md
│ reads: │
│ • guides/sprint-planner │
│ • agents/README │
│ • config/dispatch-styles│
│ • config/code-standards │
│ • Your codebase │
└─────────────┬───────────┘
│ produces (Wave 0)
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ DISPATCH.md │ │ agent-X-*.md │ │ activation │
│ (sprint plan, │ │ (per-agent │ │ prompts │
│ waves, merge │ │ task docs) │ │ (copy-paste │
│ order) │ │ │ │ into terminals│
└───────┬────────┘ └───────┬────────┘ └───────┬────────┘
│ │ │
└───────────────────┼─────────────────────┘
│ pasted into terminals
▼
┌───────────────────────┐
│ EACH AGENT READS: │
│ │
│ 1. Project context │
│ 2. Its task doc │
│ 3. code-standards │
│ 4. Source files │
│ 5. Its activation │
│ prompt (inline) │
└───────────┬───────────┘
│ works, then produces
▼
┌───────────────────────┐
│ AGENT PRODUCES: │
│ │
│ • Code changes │
│ • agent-X-completion │ ◄── templates/completion
│ .md │
└───────────┬───────────┘
│ read by RED TEAM, ORCHESTRATOR, LEAD
▼
┌───────────────────────┐
│ MERGE + ASSESS │
│ │
│ ORCHESTRATOR reads: │
│ • All completion docs │
│ • RED TEAM findings │
│ • Grades each agent │
│ • Produces SPRINT- │
│ ASSESSMENT.md │
│ │
│ LEAD reads: │
│ • ORCHESTRATOR grade │
│ • RED TEAM findings │ ◄── templates/red-team-findings
│ • Merges in order │
│ • Build+test each │
│ • Ships or blocks │
└───────────────────────┘
Every file in the repo has exactly one job.
Config — Controls Agent Behavior
File
Read By
Job
config/dispatch-styles.mdDispatcher
Tone blocks appended to every activation prompt
config/code-standards.mdEvery agent
How to write code. Shortest correct implementation.
File
Read By
Job
core/methodology.mdDispatcher + agents
Execution traces, chain protocol, priority levels
core/workflow.mdOperator
Sprint lifecycle: plan → dispatch → merge → ship
core/anti-patterns.mdDispatcher
What not to do (12 patterns)
core/architecture.mdAnyone
This file. How everything connects.
Agents — Role Definitions
File
Read By
Job
agents/README.mdORCHESTRATOR
Roster, waves, merge order
agents/orchestrator.mdORCHESTRATOR
Sprint command: planning, monitoring, grading
agents/[role].mdORCHESTRATOR + that agent
Territory, responsibilities, merge position
File
Read By
Job
guides/orchestrator-playbook.mdORCHESTRATOR
THE PLAYBOOK — single sequential doc with hard checkpoints
guides/carry-forward-protocol.mdORCHESTRATOR
How deferred work bridges sprints
guides/agent-briefing.mdAny AI first encountering this system
"What is this. What do I do."
guides/sprint-planner.mdORCHESTRATOR
6-phase methodology for analyzing codebase → sprint plan
guides/parallel-execution.mdOperator
Terminal scaling model, sub-agent math
guides/operators-guide.mdOperator
Full tutorial, start to finish
guides/quickstart.mdOperator
5-minute version
guides/customization.mdORCHESTRATOR + operator
Adapt territories per stack
guides/tool-guide.mdOperator
AI tool comparison + setup
guides/legacy-codebases.mdORCHESTRATOR
How to handle codebases with no tests/docs
guides/dispatch-config.mdAutomation scripts
Machine-readable YAML config
Templates — Copy-Paste Starting Points
File
Produces
Job
templates/dispatcher-prompt.mdORCHESTRATOR activation
Meta-prompt to kick off sprint
templates/dispatch.mdsprint-XX/DISPATCH.mdSprint plan structure
templates/agent.mdsprint-XX/agent-X-*.mdPer-agent task doc structure
templates/activation.mdActivation prompts
Prompt structure + dispatch pipeline
templates/completion.mdagent-X-completion.mdAgent completion report structure
templates/sprint-assessment.mdSPRINT-ASSESSMENT.mdORCHESTRATOR grading output
templates/sprint-registry.mdREGISTRY.mdSprint index + carry-forward tracker
templates/status.mdStatus board
Sprint tracking during execution
templates/red-team-findings.mdRED TEAM report
Adversarial findings format
templates/preflight-checklist.mdPre-dispatch gate
Verify before pasting prompts
templates/post-sprint-checklist.mdPost-sprint gate
Teardown + carry-forward
templates/retrospective.mdSprint retro
Post-sprint review
Runtime — While Agents Work
File
Read By
Job
runtime/pipeline-gates.mdORCHESTRATOR + operator
6 hard gates: plan → dispatch → waves → merge → close
runtime/retry-protocol.mdAgents + ORCHESTRATOR
Escalating 3-tier retries with per-chain verification
runtime/status-tracking.mdORCHESTRATOR + operator
Agent states, health indicators
runtime/reactions.mdORCHESTRATOR + operator
12 decision trees for runtime events
runtime/interventions.mdORCHESTRATOR + operator
24 copy-paste correction messages
Scaling — Beyond 10 Agents
File
Read By
Job
scaling/scaling.mdDispatcher + operator
Nested teams, 20-30+ agents
scaling/multi-repo.mdOperator
Multi-repo coordination
Examples — Reference Implementations
Directory
Stack
Job
examples/ecommerce-api/Go + Chi + Stripe
Complete dispatch example
examples/saas-dashboard/Python + FastAPI + React
Complete dispatch example
examples/realtime-chat/Elixir + Phoenix
Complete dispatch example
examples/embedded-firmware/C/C++ + FreeRTOS
Complete dispatch example
examples/legacy-php-webapp/PHP 7.4 + jQuery
Complete dispatch example
examples/enterprise-java-api/Java 17 + Spring Boot
Complete dispatch example
What a completed sprint looks like on disk:
docs/agent-dispatch/sprints/
├── sprint-01/
├── sprint-02/
└── sprint-03/
├── DISPATCH.md # Sprint plan (generated by ORCHESTRATOR)
├── codebase-analysis.md # Codebase snapshot (generated by ORCHESTRATOR)
├── DISPATCH-PROMPTS.md # All activation prompts (archive)
│
├── agent-A-backend.md # Task docs (generated by ORCHESTRATOR)
├── agent-B-frontend.md
├── agent-C-infra.md
├── agent-D-services.md
├── agent-E-qa.md
├── agent-F-data.md
├── agent-G-lead.md
│
├── agent-A-completion.md # Completion reports (written by agents)
├── agent-B-completion.md # ─── or use NATO codenames: ───
├── agent-C-completion.md # ALPHA-COMPLETION.md
├── agent-D-completion.md # BRAVO-COMPLETION.md
├── agent-E-completion.md # CHARLIE-COMPLETION.md
├── agent-F-completion.md # DELTA-COMPLETION.md
├── agent-G-completion.md # ECHO-COMPLETION.md
│
├── red-team-findings.md # RED TEAM adversarial report
├── SECURITY-REVIEW.md # Security review (if applicable)
├── SPRINT-SUMMARY.md # LEAD's final summary + ship decision
└── SPRINT-ASSESSMENT.md # ORCHESTRATOR's grading + mission assessment
TIME ──────────────────────────────────────────────────────────────────────────►
WAVE 0 WAVE 1 WAVE 2 WAVE 3 WAVE 4 WAVE 5 WAVE 6
│ │ │ │ │ │ │
│ ORCHESTRATOR │ DATA ████████░ │ BACKEND ██████ │ FRONTEND │ RED │ LEAD │ ORCHESTRATOR
│ analyzes │ QA ████████░ │ SERVICES █████ │ ████████░ │ TEAM │ merges │ grades
│ codebase, │ INFRA ███████░ │ │ │ ██████░ │ ships │ assesses
│ generates │ DESIGN ██████░ │ │ │ │ │ closes
│ all docs │ │ │ │ │ │ sprint
│ │ All Wave 1 done │ All Wave 2 │ Wave 3 │ Review │ Merged │
│ │ before Wave 2 │ done before │ done │ done │ │ Done
│ │ starts │ Wave 3 starts │ │ │ │
Each ████ block = one terminal with one agent + its sub-agents running in parallel.
Reading Order for New Users
guides/agent-briefing.md — What is this systemguides/quickstart.md — 5-minute overviewcore/architecture.md — This file. How everything connects.guides/operators-guide.md — Full tutorial (when ready to run a sprint)
Reading Order for ORCHESTRATOR
agents/orchestrator.md — Your role, grading rubric, assessment templateguides/sprint-planner.md — 6-phase planning methodologyagents/README.md — Roles, waves, merge orderconfig/dispatch-styles.md — Style blocks for promptsconfig/code-standards.md — How agents write codetemplates/ — All templates for generating docs
Reading Order for Activated Agents
Your activation prompt (given to you)
Your task doc (agent-X-*.md)
config/code-standards.md — How to write codetemplates/completion.md — What you produce when done