| name | orchestration-protocols |
| description | Coordinate multiple agents: parallel spawning, health monitoring, circuit breakers, escalation. Use for parallel agents, agent timeouts, fan-out tasks, multi-agent delegation. |
Orchestration Protocols
Runtime patterns for delegated agents.
Active Steering
Intervene early on:
| Signal | Action |
|---|
| Failing tests/builds | Check dependency resolution; revert if builds break |
| Unexpected file changes | Revert; enforce partition |
| Scope creep | Redirect to scoped files only |
| Circular behavior | Halt; switch approach |
| Intent misunderstanding | Clarify prompt; re-delegate |
When redirecting, explain why + how:
"Don't modify libs/data/src/lib/product.ts — shared across features. Add the new query in libs/data/src/lib/reviews.ts."
Sub-agents: Catch problems early (5 min in saves an hour). Background agents: Steer post-hoc — invest in prompt specificity, partition constraints upfront.
Background Agents
Run autonomously in isolated Git worktrees. Reserve for well-scoped tasks >5 min with clear acceptance criteria.
- Spawn: Delegate Session → Background → Select agent → Enter prompt
- Auto-compaction: At 95% token limit; use
--resume to continue
- No real-time monitoring: Invest in specific prompts, strict partition constraints, acceptance criteria checklists upfront
Parallel Research Protocol
Spawn multiple research sub-agents in parallel when 3+ independent questions need answers before implementation. Spawn if: ≥3 independent questions AND answers span multiple codebase areas — else handle sequentially.
Spawn Strategy
| Rule | Detail |
|---|
| Divide by topic/area | Each researcher owns a coherent domain |
| Max 3–5 researchers | More: diminishing returns, token waste |
| Focused scope per agent | Explicit dirs, file patterns, or questions |
| Economy/Standard tier | Manage cost for research sub-agents |
Prompt template:
Research: [specific question]
Scope: [files/directories to search]
Return: key findings, relevant file paths (with line numbers), patterns, unanswered questions
Result Merge Protocol
- Collect all results into single context
- Checkpoint: verify every researcher returned a result (no timeout/error); re-run failures before proceeding.
- Deduplicate (same file/pattern counts once)
- Resolve conflicts — specific evidence beats general observations
- Synthesize into concise context block for implementation prompts
- Checkpoint: confirm synthesized block covers every original question; mark unanswered as blockers.
Batch Reviews
- Group by domain (UI, data); run fast reviews in parallel for independent outputs
- Review sequentially when outputs share partition boundary
- Combine related artifacts into one panel question when sharing acceptance criteria
Context Compaction
Summarize prior phase output before passing to next agent. Extract: files changed, key decisions, verification (pass/fail), blockers. Discard: raw tool output, reasoning traces, failed attempts.
Template:
### Prior Phase Output
**Phase [N] — [Agent Name] — [Task Title]**
- Files changed: [list]
- Decisions: [key decisions affecting downstream work]
- Verification: [lint ✅ | types ✅ | tests ✅]
- Blockers: [none | list]
Concrete example:
### Prior Phase Output
**Phase 2 — Researcher A — Find usages of `calculateTotal()`**
- Files changed: none (read-only research)
- Decisions: `calculateTotal` lives in `libs/cart/src/lib/total.ts`; new logic should live in `libs/cart/src/lib/discounts.ts`
- Verification: lint ✅ | types ✅ | unit smoke test (cart total) ✅
- Blockers: design question on rounding behavior (see `docs/rounding.md`)
Health & Recovery Reference
Agent Health Monitoring, Error Recovery Playbook, Circuit Breaker tables moved to REFERENCE.md. See REFERENCE.md for thresholds, recovery steps, escalation flows.
CLI examples (spawn & monitor)
Use OpenCastle CLI (npx opencastle or bin/cli.mjs):
opencastle run --file convoy.yml --dry-run
opencastle run --file convoy.yml --verbose
opencastle run --resume
opencastle run --status
opencastle run --retry-failed
Post-run verification (copy-paste checks):
if [ $? -ne 0 ]; then
echo "opencastle run failed — inspect .opencastle/convoy.log" \
&& tail -n 200 .opencastle/convoy.log && exit 1
fi
npx opencastle run --status
grep -i "error\|failed" .opencastle/convoy.log || echo "no obvious errors in logs"
Validation & Verification Checkpoints
| Phase | Check | Command / Action |
|---|
| Pre-spawn | Inputs present (task, scope, ACs) | test -s convoy.yml || exit 1 |
| During-run | Tail for fatal errors | tail -F .opencastle/convoy.log | grep -i "fatal|error" |
| Pre-merge | All agents exited 0 | jq -e '.agents[] | .exit_code == 0' .opencastle/results.json |
| Output schema | Required fields present | jq -e '.agents[] | (.findings and .file_paths)' .opencastle/results.json |
| Post-merge | Lint + smoke tests pass | npm run lint && npm test -- -t "smoke" |
| Blocker | Any failure | Block merge; reopen to original researcher(s) |
