orchestrate

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:
```bash
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:
```bash
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.

### Log Dispatch

```bash
python3 ~/.claude/scripts/orchestrate-dispatch.py log-dispatch \
  --plan "$PLAN_FILE_PATH" --session-id "${CAST_SESSION_ID:-${CLAUDE_SESSION_ID:-}}" 2>/dev/null || true
```

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:
```bash
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:
```bash
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:
```bash
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: backend-writer, frontend-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]

From ek33450505/claude-agent-team, MIT.

More from ek33450505/claude-agent-team