/orchestrate-round

name: orchestrate-round
description: Main-session orchestrator for arcgentic rounds. Use when in single-session mode, when a project-level session mode must drive dispatch order, or when manually advancing the state machine. Dispatches role sub-agents, verifies structured outputs, and owns PASS-only close-round execution.

Orchestrate round

When to use

• Single-session mode (founder + Claude session = whole team)
• Multi-session mode when you need the dispatch order and role handoff prompts
• Any time you want a structured walk-through of round states without writing a custom orchestration
• Whenever you need to remember "what's the next state, what's the next gate, who's the next role"

When NOT to use

• You're explicitly playing one role (e.g. just auditing) — load that role's skill directly

Core loop

LOAD pre-round-scan skill → run scan
LOAD state.yaml → identify current_state
IF project.session_mode is present:
  → use it; do not ask the user for mode again
ELSE:
  → run `arcgentic session-mode recommend`
  → store the project-level decision before dev starts
RUN `arcgentic orchestrator-dispatch --round <round-id> --handoff <path> --mode <mode>`
DETERMINE next action:
  IF current_state in {intake, planning}:
    → role = planner; dispatch planner-agent OR print planner role prompt
  IF current_state in {awaiting_dev_start, dev_in_progress, needs_fix, fix_in_progress}:
    → role = developer; dispatch developer-agent OR print developer role prompt
  IF current_state == awaiting_audit / audit_in_progress:
    → role = auditor; LOAD audit-round skill OR dispatch auditor-agent
  IF current_state == passed:
    → role = planner for next-phase decision OR run orchestrator-owned close-round
  IF current_state == closed:
    → ROUND COMPLETE; refresh state.yaml prior-round-anchor; start next round
EXECUTE action → wait for structured artifact
VERIFY artifact against state.yaml schema
CALL transition.sh with appropriate gate
LOOP

Sub-agent dispatch (Claude Code Task tool)

Pattern for dispatching `auditor`:

Use the Task tool with:
  description: "Audit round <round-id>"
  subagent_type: "general-purpose"  # or platform-specific
  prompt: |
    You are the auditor for arcgentic round <round-id>. Your job:
    1. Read $PLUGIN_ROOT/skills/audit-round/SKILL.md and its references/
    2. Read .agentic-rounds/state.yaml
    3. Read the handoff doc at <handoff-path>
    4. Read every commit in <dev_commits>
    5. Produce a verdict file at <verdict-path> following verdict-template.md
    6. Mechanically verify every fact in your fact table
    7. Apply lesson-codification-protocol.md
    8. Update state.yaml's current_round.audit_verdict block
    9. Return: "DONE — verdict at <verdict-path>, outcome <PASS|NEEDS_FIX>"

Planner, developer, auditor, lesson-codifier, and ref-tracker agents exist in the plugin. Dispatch availability still depends on the host environment's Task tool; when unavailable, print the role prompt and stop for the matching session.

For V1 hardening, use the CLI dispatch plan as the source of role order:

arcgentic orchestrator-dispatch \
  --round <round-id> \
  --handoff <handoff-path> \
  --mode <single-session|multi-session>

In multi-session mode, the order is developer → auditor → closeout. Do not give the closeout prompt to the developer or auditor session.

V2 fixed-role Codex session plan

For V2 Codex-native orchestration, do not create per-round session names such as `R1 Developer` or `R2 Auditor`. The host-visible thread titles stay fixed:

• `Orchestrator`
• `Planner`
• `Developer`
• `Auditor`

Round identity lives in `.agentic-rounds/state.yaml` and in the prompt payload, not in the thread title. The orchestrator emits the host plan with:

arcgentic v2-session-plan --state .agentic-rounds/state.yaml --host codex

V2 routing rules:

• `needs_fix` / `fix_in_progress` → `Developer`
• `awaiting_audit` / `audit_in_progress` → `Auditor`
• `passed` → `Planner` for phase decision, not a closeout session
• `close-round` remains an orchestrator-owned mechanical command after PASS is

anchored; it is not a fifth role session

Verifying sub-agent output

NEVER trust the sub-agent's success report alone. After it returns:

1. `git status` — what files changed? 2. `git diff` — what's the actual content? 3. Read the artifact (verdict / handoff / etc.) directly 4. Run any mechanical fact-table commands the artifact claims passed 5. Run state.yaml schema validation 6. Only THEN advance the state machine

This is the "trust but verify" pattern from superpowers:verification-before-completion, applied to sub-agent outputs.

State transitions (when to call transition.sh)

| After event | Call | |---|---| | Handoff doc committed | `transition.sh --target awaiting_dev_start --by orchestrator --artifact <handoff-path>@<sha>` | | Dev commits chain committed | `transition.sh --target awaiting_audit --by orchestrator` | | Auditor verdict committed | `transition.sh --target passed --by orchestrator` (or `--target needs_fix`) | | External audit PASS is anchored | `arcgentic close-round --state-file .agentic-rounds/state.yaml --verdict <verdict-path> --audit-commit <sha>` |

If `transition.sh` exits non-zero, READ THE ERROR. The state machine refusal is informational. Common reasons:

• Gate failed — fix the gated artifact, re-run transition
• State.yaml inconsistent — schema validation will reveal which field is wrong

Cost-discipline (in orchestrator role)

When dispatching sub-agents, NEVER include in the prompt:

• Paid-API keys / endpoints
• Instructions to call paid services
• Background-process / daemon spawning

Sub-agents inherit the founder's Claude Code subscription. That's enough.

References (load on demand)

• `references/state-machine-overview.md` — visual + tabular state machine
• `references/sub-agent-dispatch.md` — full dispatch patterns + prompt templates
• `references/single-vs-multi-session.