orchestrate

Orchestrate

This is the /orchestrate skill. It reads a plan's Agent Dispatch Manifest and executes the agent queue directly from the main session.

Native Dynamic Workflows (Phase 10) are preferred for new non-critical dispatches. This skill is the stable LEGACY fallback.

Arguments

$ARGUMENTS

Step 1 — Resolve the plan path

If a file path was provided as an argument: use it directly.

If argument is next or no argument: find the most recent plan file:

ls -t ~/.claude/plans/*.md | head -1

If argument is resume: find any checkpoint log in ~/.claude/cast/orchestrator-checkpoint-*.log. Read the most recent one to extract the plan path and last completed batch.

If no plan file can be found, output: "No plan file found in ~/.claude/plans/. Run /plan first to write one."

Step 2 — Read the Manifest

Read the plan file. Find the ## Agent Dispatch Manifest section and parse the json dispatch block.

If no manifest exists: report "No Agent Dispatch Manifest found in [plan file]." and stop.

Check for a checkpoint:

PLAN_HASH=$(echo -n "$PLAN_FILE_PATH" | shasum -a 256 | cut -c1-8)
CHECKPOINT_FILE=~/.claude/cast/orchestrator-checkpoint-${PLAN_HASH}.log

If the checkpoint exists, read the last completed batch ID and skip batches with id <= that number.

Dispatch Backend Check

DISPATCH_BACKEND=$(python3 ~/.claude/scripts/orchestrate-dispatch.py get-dispatch-backend 2>/dev/null || echo 'cast')
python3 ~/.claude/scripts/orchestrate-dispatch.py log-dispatch \
  --backend "$DISPATCH_BACKEND" --plan "$PLAN_FILE_PATH" 2>/dev/null || true

If DISPATCH_BACKEND is "coordinator" or "auto", print: [CAST] dispatch_backend=$DISPATCH_BACKEND — COORDINATOR_MODE not yet supported; falling back to cast dispatch. and continue.

Create one TaskCreate entry per batch (subject = "Batch N: [description]").

Step 2.5 — Branch Pre-Flight

Read target_branch from the manifest JSON (parsed in Step 2), then:

CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
TODAY=$(date +%Y%m%d); CUTOVER=20260603

Case 1 — target_branch absent AND today < CUTOVER: warn [CAST-ORCHESTRATE] DEPRECATION WARNING: omits target_branch. Plans without target_branch will fail from 2026-06-03. Log and proceed. Case 2 — target_branch absent AND today ≥ CUTOVER: BLOCK. target_branch is required in the manifest (enforced since 2026-06-03). Stop. Case 3 — target_branch matches current branch: log [CAST-ORCHESTRATE] Branch check passed: $CURRENT_BRANCH and continue. Case 4 — target_branch present but branch mismatch: print current vs target, stop and wait for explicit "y"/"yes" before proceeding to Step 3. Prevents C3-on-C2-branch errors.

Step 3 — Present the Queue

Print the batch list as an informational summary. Do not wait for input. Proceed immediately.

Agent Dispatch Queue — [Plan Name]
═══════════════════════════════════════════════
  Batch 1 (sequential): agent-name
  Batch 2 (parallel)  : agent-a, agent-b
═══════════════════════════════════════════════
Total: N agents across M batches
Executing in 10 seconds...

Run the interrupt window:

for i in $(seq 10 -1 1); do printf "\r  Starting in %2ds..." $i; sleep 1; done; echo

If you receive a message containing "abort" before Batch 1 dispatches, print "Aborted." and stop.

Step 4 — Execute Each Batch

At the start of this step, before dispatching any batch, set:

export CAST_ORCHESTRATE_ACTIVE=1

This suppresses CAST-CHAIN and CAST-REVIEW hook noise for the duration of the orchestrate session.

Before each batch:

• Mark its task in_progress
• Check turn budget: if fewer than 5 turns remain, write checkpoint and stop: "TURN LIMIT APPROACHING: paused at Batch N. Resume with /orchestrate resume."
• For parallel batches: check owns_files — if two agents claim the same file, report FILE OWNERSHIP CONFLICT and stop.
• For parallel batches: check co-scheduling — if the batch contains test-runner AND any of {code-reviewer, security, frontend-qa}, report CO-SCHEDULING CONFLICT and either stop or auto-serialize test-runner into its own sequential batch before dispatching the rest. (test-runner's suite-timeout/kill path can reap co-scheduled sibling review processes — observed 2026-06-14.)

Prompt construction for Agent tool calls: Before passing the prompt field from the ADM to the Agent tool, prepend a context preamble. Use the full preamble for implementation agents and the minimal preamble for lightweight agents:

Full preamble — use for: code-writer, debugger, security, researcher, planner, test-writer, bash-specialist

[CAST SHARED CONTEXT]
Project: claude-agent-team
Repo: $CAST_REPO_DIR (or infer from git root)
Stack: Bash + Python + SQLite | BATS tests in tests/
DB access: always use scripts/cast_db.py (db_write, db_query, db_execute)
Conventions: YAGNI, DRY, exit 0 on all async hooks, exit 2 to block PreToolUse
Working dir: $CAST_REPO_DIR (or infer from git root)
[END CAST SHARED CONTEXT]

Minimal preamble — use for: commit, push, test-runner, code-reviewer, frontend-qa, merge, docs, devops, morning-briefing

[CAST CONTEXT]
Repo: $CAST_REPO_DIR (or infer from git root)
[END CAST CONTEXT]

Then wrap with:

[AGENT TASK]
{prompt from ADM goes here}
[END AGENT TASK]

Apply the appropriate preamble tier to ALL agent dispatches — both parallel and sequential batches.

Parallel batches ("parallel": true): dispatch all agents simultaneously in one response using the Agent tool.

Sequential batches ("parallel": false): dispatch the single agent, wait for response.

After each agent responds:

1. If response length < 50 chars, retry once: "Your response was truncated. Please provide your complete Status block."
2. Contract validation — valid Status values: DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT. If missing AND length > 50 chars, retry once: "Your response is missing a Status block. End with Status: DONE (or DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT)." On retry failure, attempt status file fallback (below).

Status file fallback (Phase 4.9): Before declaring BLOCKED, run:

FILE_STATUS=$(python3 ~/.claude/scripts/orchestrate-dispatch.py recent-status --agent "$AGENT_NAME" --max-age 300 2>/dev/null)

If non-empty, use as recovered Status and log contract_passed=-1 to quality_gates. Only treat as BLOCKED if both retry AND file fallback fail.

Test-runner file truth (Phase 4.11): For test-runner, file status wins over prose — run:

FILE_STATUS=$(python3 ~/.claude/scripts/orchestrate-dispatch.py recent-status --agent test-runner --max-age 300 2>/dev/null)

If file differs from prose, trust file and log [CAST] test-runner prose said X but file says Y — trusting file. This rule applies BEFORE Phase 4.9.

3. Log validation result to cast.db:

python3 ~/.claude/scripts/orchestrate-dispatch.py log-quality-gate \
  --batch-id "$BATCH_ID" --agent "$AGENT_NAME" \
  --status "$STATUS_LINE" --contract-passed "$CONTRACT_PASSED" \
  --retry-count "$RETRY_COUNT" 2>/dev/null || true

($CONTRACT_PASSED = 1 if valid Status found first try, 0 otherwise; $RETRY_COUNT = 0 or 1; $STATUS_LINE = extracted Status line or "MISSING")

4. Route based on Status:

   • Status: DONE → mark task completed, write checkpoint, continue
   • Status: DONE_WITH_CONCERNS → log concern text, mark completed, continue
   • Status: BLOCKED or no Status after retry → write checkpoint and stop: "Batch N blocked. Human intervention required. Blocker: [reason]"
   • Status: NEEDS_CONTEXT → stop and request clarification before continuing

5. File presence check — after DONE/DONE_WITH_CONCERNS, run git status --short and git diff --stat HEAD | tail -20. Read 2-3 files the agent claimed to modify. If no changes but edits claimed, retry once or escalate — do NOT silently continue.

After each batch: mark task completed, print [BATCH N COMPLETE], then:

mkdir -p ~/.claude/cast && echo "[BATCH $BATCH_ID COMPLETE] $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$CHECKPOINT_FILE"
source ~/.claude/scripts/cast-events.sh && cast_emit_event 'task_completed' 'orchestrate-skill' "batch-$BATCH_ID" '' '<summary>' '<STATUS>'

Token budget check (between batches): python3 ~/.claude/scripts/cast-token-budget-check.py --threshold 50000 2>/dev/null — if exit 1, log warning. Advisory; do not stop.

After all batches or early exit: unset CAST_ORCHESTRATE_ACTIVE.

Step 5 — Summarize

Print a ≤200-word summary (what each batch did, any concerns). Then:

rm -f "$CHECKPOINT_FILE"
source ~/.claude/scripts/cast-events.sh
cast_emit_event 'task_completed' 'orchestrate-skill' 'session' '' 'All batches complete' 'DONE'

When VerifyPlanExecutionTool becomes available, call it before the terminal event and log verdict to quality_gates. See docs/native-tools-reference.md.

Mandatory Chain Entries

The following agents automatically dispatch their successor agents when status = DONE:

• code-writer → code-reviewer
• bash-specialist → code-reviewer
• debugger → test-runner
• security → code-reviewer

These fire automatically after each upstream agent completes and should not be re-dispatched manually in the plan.

Output Compression Rules

• Summarize each agent's response in under 100 words. Never reproduce content from the agent's spawn prompt.
• Never paste full tool output, file contents, or raw WebFetch results into your context.
• If your accumulated context exceeds ~30,000 tokens (roughly 15+ agent dispatches), perform inline compaction: discard completed batch details, keep only the status summary per batch.
• When passing context to the next batch, include only: (1) the plan's remaining batches, (2) a 1-sentence summary per completed batch, (3) any blocking issues.

Commit Pre-Stage Protocol (mandatory)

Before dispatching any commit agent:

1. The ORCHESTRATOR runs git add <exact-files-for-this-commit> — not the commit agent. The commit agent CANNOT git add (HARD RULE — its task is compose-and-commit only).
2. The dispatch prompt MUST state: "Staged files: [list]."
3. Multi-commit batches: stage → dispatch commit → SendMessage-resume for next commit → stage → dispatch. Never batch multiple logical units into one commit dispatch without staging each set first.

Blocker class: commit agent BLOCKED on "nothing to commit" = orchestrator forgot to stage.

Agent Teams (experimental): When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, parallel batches may use team-lead mode. See docs/native-tools-reference.md. Falls back to hub-and-spoke when unavailable.

Truncation Fallback for Gate Agents

[CAST-TRUNCATED] fires on REAL output truncation only (model output cut mid-stream). MISSING_FORMALITY (complete-looking response, absent Status block) does NOT fire [CAST-TRUNCATED] — it logs an agent_protocol_violations row and triggers the existing Status-retry path (no banner).

SendMessage-resume: A resume grants a fresh turn budget. Scope dispatches to fit caps rather than relying on resumes. When resuming a capped agent, state exactly what work remains.

If [CAST-TRUNCATED] fires on a gate agent (test-runner, code-reviewer, security): do NOT auto-retry. Use inline fallback — test-runner: bash tests/run.sh --tap 2>&1 | tail -20; code-reviewer: apply checklist manually; security: grep for anti-patterns. Log as Status: DONE_WITH_CONCERNS and cast.db entry agent_name='<role>-INLINE-FALLBACK' with contract_passed=1 (0 if issues found). If inline fallback cannot complete: BLOCK and stop.

Rules

• Never skip a batch unless the user explicitly says to
• Maximum 4 agents per parallel batch
• Output discipline: summarize each agent in 3 sentences max. Never paste full agent output verbatim.
• If blocked after one retry: write checkpoint, stop, tell user how to resume with /orchestrate resume