When user triggers orchestration (e.g., "Start orchestration from spec at .kiro/specs/orchestration-dashboard"):
One-Command Mode [MANDATORY for opencode CLI]
Run the entire workflow in a single blocking command (no user click / no manual continuation):
```bash
python scripts/orchestration_loop.py --spec --workdir . --assign-backend codex
# Note: state files default to /.. (e.g. .kiro/specs/). To write into CWD, add: --output .
```
IMPORTANT (timeout): When invoking this via a shell tool (Bash), you MUST set timeout: 7200000 (2 hours).
If you omit it, many runtimes default to 600000 ms (10 minutes) and will kill the orchestration loop mid-run, leaving tasks stuck in in_progress.
This command will:
- Initialize (TASKS_PARSED.json / AGENT_STATE.json / PROJECT_PULSE.md)
- Generate + apply dispatch assignments (owner_agent/target_window/criticality/writes/reads) for dispatch units
- Loop dispatch β review β consolidate β sync until all dispatch units are completed
- Halt if
pending_decisions requires human input
Exit codes: 0 complete, 1 halted/incomplete, 2 pending_decisions (human input required).
Defaults: --mode llm --backend opencode. If needed, set CODEAGENT_OPENCODE_AGENT to select an opencode agent.
Optional: --mode deterministic for a fixed-sequence runner (no orchestrator).
Use the manual steps below only for debugging.
Step 1: Initialize Orchestration [AUTOMATIC]
Use the shell command tool to parse/validate:
```bash
python scripts/init_orchestration.py --session roundtable --mode codex
# Note: outputs default to /.. (e.g. .kiro/specs/). To write into CWD, add: --output .
```
This creates:
TASKS_PARSED.json - Parsed tasks for CodexAGENT_STATE.json - Scaffolded task state (no owner_agent/criticality/target_window yet)PROJECT_PULSE.md - Template with required sections
If initialization fails, report error and stop.
Legacy mode (--mode legacy) is available for backward compatibility only.
Step 1b: Codex Decision & Generation [AUTOMATIC]
Codex must use codeagent-wrapper to read TASKS_PARSED.json + AGENT_STATE.json, generate dispatch assignments, then apply them:
```bash
codeagent-wrapper --backend codex - <<'EOF'
You are generating dispatch assignments for multi-agent orchestration.
Inputs:
- @TASKS_PARSED.json
- @AGENT_STATE.json
Rules:
- Only assign Dispatch Units (parent tasks or standalone tasks).
- Do NOT assign leaf tasks with parents.
- Analyze each task's description and details to determine:
- type: Infer from task semantics:
- code β Backend logic, API, database, scripts, algorithms
- ui β Frontend, React/Vue components, CSS, pages, forms, styling
- review β Code review, audit, property testing
- owner_agent: Based on type:
- codex β code tasks
- gemini β ui tasks
- codex-review β review tasks
- target_window: task- or grouped names (max 9)
- criticality: standard | complex | security-sensitive
- writes/reads: list of files (best-effort)
Output JSON only:
{
"dispatch_units": [
{
"task_id": "1",
"type": "code",
"owner_agent": "codex",
"target_window": "task-1",
"criticality": "standard",
"writes": ["src/example.py"],
"reads": ["src/config.py"]
}
],
"window_mapping": {
"1": "task-1"
}
}
EOF
```
Then apply the JSON into AGENT_STATE.json (Write tool), and update PROJECT_PULSE.md using design.md + current state.
File Manifest (writes / reads):
writes: Files the task will create or modify (e.g., ["src/api/auth.py", "src/models/user.py"])reads: Files the task will read but not modify (e.g., ["src/config.py"])- Tasks with non-overlapping
writes can run in parallel - Tasks WITHOUT
writes/reads will be executed serially (conservative default)
Then write PROJECT_PULSE.md using design.md and current state.
Note: dispatch_batch.py will fail if owner_agent or target_window is missing. Tasks without writes/reads will run serially.
Step 2: Dispatch Loop [AUTOMATIC - REPEAT UNTIL COMPLETE]
CRITICAL: This is a LOOP. Continue dispatching until no tasks remain.
```
WHILE there are dispatch units not in "completed" status:
1. Dispatch ready tasks
2. Wait for completion
3. Dispatch reviews for completed tasks
4. Consolidate reviews (final reports / fix loop)
5. Sync state to PULSE
6. Check if all tasks completed
7. If not complete, CONTINUE LOOP
```
#### 2a. Dispatch Ready Tasks
```bash
python scripts/dispatch_batch.py
```
This:
- Finds tasks with satisfied dependencies
- Invokes codeagent-wrapper --parallel
- Updates task statuses to "in_progress" then "pending_review"
#### 2b. Dispatch Reviews
```bash
python scripts/dispatch_reviews.py
```
This:
- Finds tasks in "pending_review" status
- Spawns Codex reviewers
- Updates task statuses to "under_review" then "final_review"
#### 2c. Consolidate Reviews
```bash
python scripts/consolidate_reviews.py
```
This:
- Consolidates
review_findings into final_reports - Updates task statuses to "completed" (or enters "fix_required" for the fix loop)
#### 2d. Sync to PULSE
```bash
python scripts/sync_pulse.py
```
#### 2e. Check Completion Status
```bash
# Check if any tasks are NOT completed
cat | python -c "import json,sys; d=json.load(sys.stdin); tasks=d.get('tasks',[]); units=[t for t in tasks if t.get('subtasks') or (not t.get('parent_id') and not t.get('subtasks'))]; incomplete=[t['task_id'] for t in units if t.get('status')!='completed']; print(f'Incomplete dispatch units: {len(incomplete)}/{len(units)}'); [print(f' - {tid}') for tid in incomplete[:5]]"
```
Decision Point:
- If incomplete tasks > 0: CONTINUE LOOP (go back to 2a)
- If incomplete tasks == 0: PROCEED TO STEP 3
Step 2f: **Add valuable learnings** - If you discovered something future developers/agents should know:
- API patterns or conventions specific to that module
- Gotchas or non-obvious requirements
- Dependencies between files
- Testing approaches for that area
- Configuration or environment requirements
Examples of good AGENTS.md additions:
- "When modifying X, also update Y to keep them in sync"
- "This module uses pattern Z for all API calls"
- "Tests require the dev server running on PORT 3000"
- "Field names must match the template exactly"
Do NOT add:
- Story-specific implementation details
- Temporary debugging notes
- Information already in progress.txt
Only update AGENTS.md if you have genuinely reusable knowledge that would help future work in that directory.
Step 3: Completion Summary [AUTOMATIC]
When all tasks are completed, provide a summary:
```
|