etylsarin/orchestration-protocols

Orchestration Protocols

Runtime patterns for managing delegated agents.

Active Steering

Intervene early when you spot:

| 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 and 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 can save an hour). Background agents: Steer post-hoc — invest in prompt specificity and 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, and acceptance criteria checklists upfront

Parallel Research Protocol

Spawn multiple research sub-agents in parallel when 3+ independent questions must be answered before implementation. Spawn if: ≥3 independent questions AND answers span multiple codebase areas — otherwise handle sequentially.

Spawn Strategy

| Rule | Detail | |------|--------| | Divide by topic/area | Each researcher owns a coherent domain | | Max 3–5 researchers | More creates diminishing returns and 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

1. Collect all results into single context
2. Checkpoint: verify every researcher returned a result (no timeout or error); re-run any that failed before proceeding.
3. Deduplicate (same file/pattern counts once)
4. Resolve conflicts — specific evidence beats general observations
5. Synthesize into concise context block for implementation prompts
6. Checkpoint: confirm synthesized block covers every original question; mark any unanswered questions as blockers.

Batch Reviews

• Group by domain (UI, data); run fast reviews in parallel for independent outputs
• Review sequentially when outputs share the same partition boundary
• Combine related artifacts into one panel question when they share acceptance criteria

Context Compaction

Summarize prior phase output before passing to the 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

Detailed Agent Health Monitoring, Error Recovery Playbook, and Agent Circuit Breaker tables have been moved to REFERENCE.md to keep this skill concise. See REFERENCE.md in this directory for thresholds, recovery steps, and escalation flows.

CLI examples (spawn & monitor)

These use the 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) |