Orchestration digest — Tier A (subagent-capable clients)

Who this is for: Claude Code and any future client that can spawn parallel subagents, run lifecycle hooks, and load reusable skills. If you are a single-agent client (Codex, Gemini, Cursor, VS Code Copilot), read the Tier B digest instead.

This is the compact, session-start digest. The full reference is get_guidance("orchestration") and the agents standard.

How you work

You run workstreams as orchestrated pipelines with fan-out to specialised subagents and human approval gates. The Claude-native layer lives under .claude/ (agents/, skills/, commands/, hooks/, settings.json).

• Workstreams: build, review, refactor, test, document, investigate, operate. Each is a skill that sequences the right agents (planner → coder → reviewer → documenter, etc.) with a human approve gate.
• Dispatch: resolve a task through master-registry.db → per-repo validation_profile → profiles/<type>.yaml, then pack into waves.

Hard orchestration rules (non-negotiable)

1. Consult guidance first. Call get_guidance("orchestration") before dispatching. Do not improvise the flow.
2. Shared agents first. Check the shared HCS roster (orchestration-pm, validators, security-waf-caf) before creating any agent. Follow the agent-selection procedure.
3. Wave-packing limits: max 8 concurrent spawns per wave; max 1 agent per repo at a time.
4. Security gate is final. security-waf-caf runs after all structural validators, never in parallel. Its verdict: block cannot be overridden — escalate.
5. No metered API. All agents run under the Claude Code subscription/harness. Never call a model API directly. The only sanctioned external-model path is gemini-runner / /second-opinion.
6. Never launch subagents without explicit opt-in when doing so spends metered budget outside the harness.

Deterministic checks are MCP tools

Prefer the MCP's deterministic tools over spawning an agent to eyeball a repo:

• validate(path, profile) — run a profile's tool checks.
• check_drift(repo=… | path=…) — canonical-layout conformance (AGENTS.md, CLAUDE.md shim, .ai/, secrets).
• which_standards_apply(repo) and get_standard(domain, scope) — the rules to review against.

Fold the mechanical validators into validate; reserve subagents for work that genuinely needs model reasoning.

Session protocol

Read .ai/state/ then .ai/memory/ at session start; summarise believed state before changing anything; update .ai/state/HANDOFF.md before ending. Full contract: ai-workspace standard.