| name | codex-orchestration |
| description | Orchestrate multi-sprint phases where csc (Codex) is the sole developer, with pipelined QA via quality-mgr teammate. Team-lead tracks findings and schedules fix passes. |
Codex Orchestration
This skill defines how the team-lead (ARCH-ATM) orchestrates phases where csc (Codex) is the sole developer, executing sprints sequentially while QA runs in parallel via a dedicated quality-mgr teammate.
Audience: Team-lead only.
When to use: When a phase's implementation is done entirely by csc (a Codex agent communicating via ATM CLI), not by Claude Code scrum-masters. This pattern was proven in Phase M (8 sprints) and Phase O.
Prerequisites
Before starting a phase:
- Phase plan document exists with sprint specs and dependencies
- Integration branch
integrate/phase-{P} created off develop
- ATM team (
$ATM_TEAM) is active with team-lead and csc as members
- csc is running and reachable via ATM CLI (
atm send csc "ping")
Architecture
team-lead (ARCH-ATM)
├── csc (Codex) ──── sole developer, sequential sprints
│ communicates via ATM CLI only
└── quality-mgr (Claude Code) ──── QA coordinator teammate
spawns go-qa-agent + req-qa-agent + arch-qa-agent as background agents
Key principle: csc does NOT wait for QA. He proceeds to the next sprint as soon as he completes one, unless there are outstanding fix requests from earlier sprints.
Phase Setup
1. Create Integration Branch
git fetch origin develop
git branch integrate/phase-{P} origin/develop
git push -u origin integrate/phase-{P}
2. Create First Sprint Worktree
/sc-git-worktree --create feature/p{P}-s1-{slug} integrate/phase-{P}
3. Spawn Quality Manager
Spawn once per phase. The quality-mgr persists across all sprints.
Use the Task tool with name parameter to spawn as a named teammate:
{
"subagent_type": "quality-mgr",
"name": "quality-mgr",
"team_name": "$ATM_TEAM",
"model": "sonnet",
"prompt": "You are quality-mgr for Phase {P}. You will receive QA assignments from team-lead for each sprint as they complete. Stand by for first assignment. Integration branch: integrate/phase-{P}. Phase docs: docs/project-plan.md, docs/requirements.md."
}
4. Send O.1 Assignment to csc
atm send csc "Phase {P} Sprint {P}.1 assignment: {title}
Worktree: /path/to/worktree
Branch: feature/p{P}-s1-{slug}
PR target: integrate/phase-{P}
Deliverables:
- {list deliverables}
Requirements: docs/requirements.md ({relevant FRs})
Sprint plan: docs/project-plan.md (Phase {P} section)
When complete: commit, push, then notify me via atm send with branch + commit SHA. Do not create PR."
Sprint Pipeline
Steady-State Flow
Timeline:
csc: [── S.1 ──]──fixes──[── S.2 ──]──fixes──[── S.3 ──]
quality-mgr: [── QA S.1 ──] [── QA S.2 ──] [── QA S.3 ──]
team-lead: assign S.1 → track → assign S.2 → track → assign S.3 → track
When csc Completes Sprint S
- csc sends completion message via ATM CLI with branch + commit SHA after commit/push.
- Team-lead creates PR targeting
integrate/phase-{P} and immediately starts CI monitoring:
atm gh monitor pr <PR_NUMBER>
- Team-lead creates worktree for S+1 based on sprint S branch:
/sc-git-worktree --create feature/p{P}-s{N+1}-{slug} feature/p{P}-s{N}-{slug}
All worktrees chain: S+1 bases on S, so later sprints include earlier work.
- Team-lead sends next sprint assignment to csc (use Jinja2 task template + ATM send).
- Team-lead assigns QA to quality-mgr via SendMessage (use Jinja2 QA template):
"Run QA on Sprint {P}.{S}. Worktree: {path}. Sprint deliverables: {summary}.
Design docs: {list}. PR: #{N}."
- If QA findings exist, queue fixes ahead of new sprint dev tasks:
- If findings are on an active codex worktree, send ATM fix assignment to csc.
- Otherwise schedule merge/conflict remediation via a background agent.
- Merge gate: merge only when QA is PASS and CI is GREEN.
- After merge, verify remaining open PRs for merge conflicts and schedule fixes immediately.
When csc Has Outstanding Findings
Priority order for csc:
- Fix findings on oldest sprint first (S-2 before S-1)
- Merge fixes forward into later sprint worktrees
- Then proceed to next sprint
Fix workflow:
Merge Forward Protocol
After fixes merge to integrate/phase-{P}:
QA Coordination
Team-lead → quality-mgr Messages
Assignment format:
Run QA on Sprint {P}.{S}: {title}
Worktree: {absolute path}
Sprint deliverables: {bullet list}
Design docs: {list of relevant doc paths}
PR: #{number}
Re-run after fixes:
Re-run QA on Sprint {P}.{S} (post-fix).
Worktree: {path}
Fixed findings: {list of QA IDs addressed}
quality-mgr → team-lead Reports
quality-mgr reports PASS/FAIL with finding IDs. Team-lead tracks:
| Sprint | QA Run | Verdict | Blocking Findings | Status |
|---|
| O.1 | 1 | FAIL | QA-001, QA-002 | Fixes assigned |
| O.1 | 2 | PASS | — | Merged |
| O.2 | 1 | PASS | — | Merged |
Finding Lifecycle
OPEN → assigned to csc → FIXED (csc pushes) → re-QA → VERIFIED (QA passes)
→ WONTFIX (team-lead approves deviation)
PR and Merge Strategy
- All PRs target
integrate/phase-{P} (never develop directly)
- Merge order: Sprint PRs merge in order (S.1 before S.2)
- Merge gate: QA pass + CI green
- Team-lead merges (not csc)
- After all sprints merge: one final PR
integrate/phase-{P} → develop
ATM Communication Protocol
All csc communication is via ATM CLI. Follow the dogfooding protocol (ACK → work → complete → ACK).
Sending assignments
atm send csc "message"
Checking for replies
atm read
Nudging (if no reply in 2+ minutes)
Use ATM first:
atm send csc "You have unread ATM messages. Run: atm read --team $ATM_TEAM"
If your local runtime uses tmux pane orchestration, tmux nudges are optional and environment-specific.
Advise csc to poll with timeout
When csc is waiting for assignments, tell him:
"Standing by? Use: atm read --team $ATM_TEAM --timeout 60"
This keeps him responsive without busy-polling.
Phase Completion
After all sprints pass QA and merge to integration branch:
- Run final integration QA (quality-mgr validates full integration branch)
- Create PR:
integrate/phase-{P} → develop
- Wait for CI green
- Merge after user approval
- Shutdown quality-mgr teammate
- Do NOT clean up worktrees until user reviews
Anti-Patterns
- Do NOT tell csc to wait for QA before starting the next sprint
- Do NOT skip QA on any sprint — quality-mgr runs both agents every time
- Do NOT merge PRs without QA pass + CI green
- Do NOT let findings accumulate — schedule fixes before assigning new sprints
- Do NOT create worktrees off
develop — chain from previous sprint or integration branch
- Do NOT communicate with csc via SendMessage — use ATM CLI only
- Do NOT reuse quality-mgr across phases — spawn fresh per phase
- Do NOT clean up worktrees without user approval