orchestrate

name

orchestrate

description

Run the AgentBoard workspace pipeline across a board's cards — planning → review → implementation → audit waves with parallel subagents per card, server-driven verdict routing, and checkpoint pauses. Use ONLY when the user explicitly wants to run or continue the pipeline on a board that already has cards — e.g. "/orchestrate", "run the pipeline", "orchestrate the board". Do NOT trigger on general discussion of orchestration, or when no cards exist yet (create them via architecture or sweep first).

Workspace Orchestration

Orchestrate parallel subagents through workspace board columns: planning → review → implementation → audit → finished.

Source of truth and invocation. This skill is the authoritative reference for the orchestrate workflow — wave logic, prompt templates, checkpoint policy, retry policy, build verification, and per-wave failure handling all live here. Run it directly as /orchestrate (optionally /orchestrate --auto). Before the first wave, load the agentboard, codegraph, and rag tool schemas via ToolSearch and call agentboard_health_check. The one flag is --auto — skip checkpoints where the board's blocking toggle is OFF (blocking ON always pauses; see Checkpoint Logic below).

Prerequisites

• AgentBoard cloud reachable (call agentboard_health_check — AgentBoard is cloud-hosted, this is a reachability/auth check, not a local-process check)
• A workspace board with cards in backlog (created via /architecture, which itself depends on a spec from /foundation)
• An approved architecture document at docs/arch/architecture-<spec-basename>.md whose Card Slices section corresponds to the cards on this board. Note: the architecture pipeline has a correction loop, so the document a card's slice came from may have been revised since the cards were created — if cards predate the current architecture document, re-create them from the current Card Slices section before running this skill.
• MCP tools loaded: agentboard, codegraph, codebase-rag

Pipeline Overview

Wave 1: Planning    → parallel agents build plans per card     → cards advance to review
Wave 2: Review      → parallel agents validate plans           → cards advance to implementation (or back to planning)
Wave 3: Implementation → parallel agents write code            → build/lint check → cards advance to audit
Wave 4: Audit       → parallel read-only agents verify         → cards advance to finished (or back to implementation)

Transitions are server-enforced and verdict-driven — agents and the orchestrator never move a card themselves. Both rejection loops route on the submitted artifact's ## Verdict: heading:

backlog → planning → review → implementation → audit → finished
              ▲          │            ▲            │
              │  review  │ FAIL       │  audit     │ FAIL
              └──────────┘            └────────────┘
   review_note FAIL → planning     audit_report FAIL → implementation

Checkpoint Logic

Read the board's auto_transitions to determine pausing:

Board Setting	Default Behavior	With --auto Flag
review_blocking: true	PAUSE after Wave 1	PAUSE (blocking always wins)
review_blocking: false	PAUSE after Wave 1	Auto-proceed
audit_blocking: true	PAUSE after Wave 3	PAUSE (blocking always wins)
audit_blocking: false	PAUSE after Wave 3	Auto-proceed

Default is always pause. The --auto flag only skips pauses when blocking is OFF.

Running a Wave

For each wave, follow this pattern:

1. Collect Cards

Query cards by status matching the wave's input column:

• Wave 1 (Planning): cards in backlog
• Wave 2 (Review): cards in review
• Wave 3 (Implementation): cards in implementation
• Wave 4 (Audit): cards in audit

Use mcp__agentboard__agentboard_list_workspace_cards filtered by status. Always pass limit=100 to prevent silent truncation on large boards — if the result count equals your limit, paginate with offset to retrieve the rest.

2. Spawn Parallel Subagents

Launch one Agent per card using run_in_background: true. Set subagent_type to the agent name for the wave. The agents carry their own system prompts, tool allowlists, and model assignments — the prompt only needs to pass the per-card variables.

Wave	Phase	subagent_type
1 — Planning	A (haiku)	planning-research-agent
1 — Planning	B (opus)	plan-compose-agent
2 — Review	—	review-agent
3 — Implementation	—	implementation-agent
4 — Audit	A (haiku)	audit-research-agent
4 — Audit	B (opus)	audit-compose-agent

Phase A prompt (Waves 1 and 4):

The research agents (planning-research-agent, audit-research-agent) fetch their own card data via agentboard_get_card; do not pass card_title in the prompt — those agents do not declare it as a declared input.

card_id: 7f3c...
board_id: a91e...
agent_id: claude-opus-4-6
arch_slice: <paste the card's section from `## Card Slices` in the arch doc — full slice with all eight §6.3 fields: Description / Allowed-touch list / Forbidden-touch list / Produces / Consumes / Verification scope / Depends on / Source decisions>   ← Wave 1 only
repo_root: /absolute/path/to/repo                                                                                                                                                            ← Wave 4 only

After Phase A completes for each card, capture the artifact ID returned by the research agent's agentboard_submit_workspace_artifact call — Phase B needs it as facts_bundle_artifact_id (Wave 1) or audit_facts_bundle_artifact_id (Wave 4).

Phase B prompt (Waves 1 and 4):

Before spawning Phase B agents, capture the Phase A artifact ID from each card:

• Call agentboard_list_workspace_artifacts for the card (or use the artifact ID the Phase A submission returned, if you captured it directly).
• Identify the artifact whose artifact_type is FACTS_BUNDLE_V1 (Wave 1) or AUDIT_FACTS_BUNDLE_V1 (Wave 4) and capture its artifact ID.

Pass the artifact ID to the compose agent — the compose agent fetches the bundle itself via agentboard_get_workspace_artifact. Never embed bundle JSON in the prompt; the orchestrator does not parse the bundle, and Phase B compose agents declare the artifact ID as a required input. For Wave 1, also pass the arch_slice so the compose agent does not need to re-extract it:

card_id: 7f3c...
board_id: a91e...
agent_id: claude-opus-4-6
card_title: Add pagination to workspace cards endpoint                    ← Phase B compose agents declare card_title as a declared input
arch_slice: <the same per-card slice passed to Phase A — full slice with all eight §6.3 fields: Description / Allowed-touch list / Forbidden-touch list / Produces / Consumes / Verification scope / Depends on / Source decisions>   ← Wave 1 only
facts_bundle_artifact_id: <uuid of the FACTS_BUNDLE_V1 artifact>          ← Wave 1 (use audit_facts_bundle_artifact_id on Wave 4)

If a Phase A artifact is missing for a card, skip Phase B for that card and report the failure — do not spawn a compose agent without a bundle artifact ID.

Waves 2 and 3 prompt:

card_id: 7f3c...
board_id: a91e...
agent_id: claude-opus-4-6
card_title: Add pagination to workspace cards endpoint
arch_path: /repo/docs/arch/2026-05-08-<topic>.md    ← review-agent only — full architecture doc, not just the slice

3. Wait for All Agents

All background agents must complete before proceeding. Report results:

## Wave [N] Complete: [Wave Name]
- Cards processed: [X]/[total]
- Passed: [N]
- Failed: [N] (list card titles)
- Time elapsed: [duration]

4. Handle Failures

Review rejections (Wave 2):

• The reviewer submits a review_note with ## Verdict: FAIL; the server auto-routes the card back to planning. The orchestrator does NOT call agentboard_update_workspace_card to move the card — that path is deprecated.
• A review_note lacking the ## Verdict: PASS|FAIL marker is rejected with HTTP 422 (REVIEW_NOTE_MISSING_VERDICT); the reviewer reads the instructions_for_agents field and resubmits with the marker (the app is not broken).
• Re-run Wave 1 for rejected cards only (max 2 retries per card)
• After 2 failures: report to user, do not retry

Build/lint failure (after Wave 3):

• Stop pipeline — do NOT proceed to Wave 4
• Report which files changed and likely culprit
• Wait for user intervention

Audit failure (Wave 4):

• The audit agent submits the audit_report with ## Verdict: FAIL and does NOT move the card — the server routes on the verdict. A FAIL routes the card to implementation unconditionally, regardless of the audit_blocking setting. The orchestrator does NOT call agentboard_update_workspace_card; that path is deprecated.
• An audit_report lacking a valid ## Verdict: heading (a level-2 heading with value PASS / PASS WITH NOTES / FAIL inline) is rejected with HTTP 422 (AUDIT_REPORT_MISSING_VERDICT); the audit agent reads instructions_for_agents and resubmits with the marker (the app is not broken).
• On a FAIL, re-run Wave 3 (Implementation) for the rejected card against the findings in the audit report. The audit report body carries the full rework context.
• A ## Verdict: PASS or PASS WITH NOTES advances the card to finished only when audit_blocking is OFF; when ON, the card holds in audit for a human checkpoint — report the verdict to the user, who accepts (finish) or reworks (back to implementation).

5. Checkpoint (if applicable)

If this wave requires a pause (per checkpoint logic above):

## Checkpoint: [Wave Name] Complete

[Results table]

Proceed to [next wave]? (waiting for confirmation)

Wait for user confirmation before starting the next wave.

Build Verification

After Wave 3 (Implementation), before Wave 4 (Audit), verify the project builds and lints. Build/lint commands are project-specific — do not hardcode npm, cargo, pytest, etc. into this skill. The implementation-agent runs build and lint as part of executing the plan and reports the result in its submitted implementation_note artifact; the orchestrator reads that artifact's build/lint status field instead of running build commands itself.

If the implementation-agent's submitted artifact reports a build or lint failure, stop the pipeline (do not advance to Wave 4) and report which files changed and the failing command output. Wait for user intervention.

When the build/lint command for the project is not obvious from implementation-agent's context (e.g., a polyglot repo, an unfamiliar project shape), the orchestrator may inspect the repo root for build-system markers (package.json scripts, pyproject.toml/setup.py, Cargo.toml, go.mod, Makefile, .claude-plugin/) and pass a hint to implementation-agent; this is an inspection step, not a hardcoded command.

Retry Policy

Scenario	Action	Max Retries
Review rejects a plan (review_note FAIL)	Server routes card to planning; re-plan with feedback	2 per card
Build fails	Stop, report to user	0 (user intervenes)
Audit fails (audit_report FAIL)	Server routes card to implementation; re-run Wave 3 against the audit findings	2 per card
Agent crashes/times out	Report, card unchanged	1

Status Reporting

Between waves (and at checkpoints), show:

## Orchestration Status — Board: [name]

| Column | Count |
|--------|-------|
| backlog | 0 |
| planning | 0 |
| review | 2 |
| implementation | 0 |
| audit | 3 |
| finished | 5 |

Progress: 5/10 cards finished (50%)

Agents

All wave workers are dedicated agents defined in agents/ at the plugin root:

The model column below shows each agent's model: frontmatter value verbatim. Workspace-pipeline agents use short aliases (opus, sonnet, haiku) to track ongoing model capability improvements; the hooks validate submitted artifact shape at runtime, so a model change that breaks output format is caught immediately. Architecture-pipeline agents pin specific versions for separate reasons that live in their own profile docs.

Agent	Model	Role
planning-research-agent	claude-haiku-4-5-20251001	Wave 1 Phase A — codegraph/RAG discovery, emits FACTS_BUNDLE_V1
plan-compose-agent	opus	Wave 1 Phase B — fetches bundle by ID, writes plan artifact with full Expert Standard rigor
review-agent	opus	Wave 2 — validates plans against constraints
implementation-agent	sonnet	Wave 3 — executes plans, writes code, runs build/lint
audit-research-agent	claude-haiku-4-5-20251001	Wave 4 Phase A — git diff + blast radius, emits AUDIT_FACTS_BUNDLE_V1
audit-compose-agent	opus	Wave 4 Phase B — fetches bundle by ID, writes audit report with a ## Verdict: heading, then stops; the server routes on the verdict

Two-Phase Pipeline (Waves 1 and 4)

Wave 1:

1. Spawn planning-research-agent per card in parallel — runs RAG discovery then codegraph structural analysis, emits FACTS_BUNDLE_V1 artifact
2. Wait for ALL Phase A agents to complete
3. Spawn plan-compose-agent per card in parallel — reads the bundle, writes the plan artifact (no discovery calls)

Wave 4:

1. Spawn audit-research-agent per card in parallel — gathers git diff, blast radius, cross-references the plan artifact, emits AUDIT_FACTS_BUNDLE_V1
2. Wait for ALL Phase A agents to complete
3. Spawn audit-compose-agent per card in parallel — reads the bundle, writes the audit_report artifact with a mandatory ## Verdict: heading; the server routes on the verdict (FAIL → implementation unconditionally; PASS / PASS WITH NOTES → finished when audit_blocking is OFF, else holds in audit for a human checkpoint)