| name | workspace-orchestration |
| description | Use when orchestrating parallel subagents across workspace board cards for planning, review, implementation, and audit waves |
Workspace Orchestration
Orchestrate parallel subagents through workspace board columns: planning → review → implementation → audit → finished.
Prerequisites
- AgentBoard server running (call
agentboard_health_check)
- A workspace board with cards in
backlog (created via /foundation)
- 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
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.
2. Spawn Parallel Subagents
Launch one Agent per card using run_in_background: true. Use the prompt template from prompts/{wave}-agent.md, substituting:
{{card_id}} — the card's UUID
{{board_id}} — the board UUID
{{agent_id}} — use the orchestrator's agent_id (e.g., claude-opus-4-6)
{{spec_path}} — path to the spec document (for planning/review agents)
{{card_title}} — the card's title (for artifact headers)
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):
- Card sent back to
planning with rejection notes
- 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):
- Card stays in
audit with audit report
- Report findings to user
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):
npm run build
npm run lint --prefix client
Both must pass. If either fails, stop and report.
Retry Policy
| Scenario | Action | Max Retries |
|---|
| Review rejects a plan | Re-plan with feedback | 2 per card |
| Build fails | Stop, report to user | 0 (user intervenes) |
| Audit fails | Report, card stays in audit | 0 (user reviews) |
| 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%)
Prompt Templates
Located in prompts/ directory within this skill:
planning-agent.md — produces implementation plans
review-agent.md — validates plans against constraints
implementation-agent.md — executes plans, writes code
audit-agent.md — read-only verification of implementation