Orchestration system — overview

This is the fuller reference behind the two per-client-tier orchestration digests. It explains how the HCS estate is orchestrated across every AI coding client — not just Claude Code — and documents the Tier A (subagent-capable) mechanics in depth.

What a client should fetch each session

A client does not read this whole page every session. At session start any client calls the MCP bootstrap(repo, client) tool, which returns the tier-appropriate digest automatically (see MCP's role below). This page is for humans and for deep reference when a digest is not enough. See clients for the two capability tiers.

---

Two client tiers

Orchestration adapts to what the connected client can actually do, not to which scope the repo belongs to (see clients):

Tier	Clients	Model of work	Digest
A — subagent-capable	Claude Code (and any future client that can spawn parallel subagents, run lifecycle hooks, load skills)	Orchestrated pipelines with fan-out to specialised subagents, wave-packing, and a hard security gate	digests/tier-a.md
B — single-agent	Codex CLI, Gemini CLI, Cursor, VS Code Copilot	The same workstream logic, run sequentially by one agent, leaning on MCP deterministic tools instead of fan-out	digests/tier-b.md

The rest of this page documents the Tier A engine — wave-packing, the validator roster, and the security-waf-caf gate. These mechanics are specific to Claude Code because they depend on parallel subagent spawning and a hook system that Tier B clients do not have. Tier B clients run the same seven workstreams one step at a time and validate through the MCP; see the Tier B digest for their flow.

---

The MCP's role (bootstrap)

The HCS Governance MCP server (mcp-server/) and this orchestration engine are complementary layers, not duplicates.

• bootstrap(repo, client) is the recommended session-start call for ANY client. It returns one compact payload — scope, hard rules, standards index, the tier-appropriate orchestration digest, the .ai/ session protocol, and model policy — replacing three or four separate calls. A client fetches this, not this whole page.
• Shared source of truth. The MCP serves the same master-registry.db, profiles/*, and docs/standards/* that Tier A orchestration consumes — one source, two consumers.
• Tier A orchestration = the Claude Code autonomous layer. Wave-packing, parallel fan-out, and the security-waf-caf gate are Claude Code behaviours an MCP cannot initiate — so this engine stays.
• MCP = the portable capability layer. It exposes registry, standards, profiles, validate, check_drift, and auth to any client (Codex, Cursor, Gemini, Copilot) that cannot spawn a Claude-native agent.

The deterministic agents fold into the MCP: the five validators → MCP validate; triage-lookup/router/platform-standards-keeper → MCP tools/resources. Retiring those ~8 requires one rewire — orchestration-pm calls the MCP validate tool instead of spawning validators. Full plan: mcp-server/docs/HCS-Platform-MCP-Design.md §6.

---

Tier A — rules a Claude Code session MUST follow before orchestrating

These are not guidelines — they are enforced by the MCP orchestration_rules and agent_selection prompts. They are Tier A behaviour; a Tier B client follows the sequential flow in its digest instead.

1. Consult guidance first. Call get_guidance("orchestration") from the MCP (or read the tier-a digest) before dispatching. Do not improvise the dispatch flow.
2. Shared agents first. Check the shared HCS roster (orchestration-pm, validators, security-waf-caf) before creating any new agent. See the agent roster for the full decision procedure.
3. Wave-packing is hard. Max 8 concurrent spawns per wave. Max 1 agent per repo at a time. These limits exist to prevent resource exhaustion.
4. Security gate is non-overridable. security-waf-caf verdict block is final. No PM, no orchestrator, no human can bypass it — escalate instead.
5. HARD COST RULE: no metered API. Agents MUST run under the Claude Code subscription/harness. Never call the Anthropic API directly (no SDK / ANTHROPIC_API_KEY in any agent or script). Direct API calls incur per-token charges outside the plan.
6. Pilot scope only. The current active scope is pilot repos (7 repos, one per type). Full estate dispatch is deferred until all pilots are green.

---

What Tier A does

The system takes a task — "validate all Terraform pilot repos", "sweep for CAF naming drift", "get a second opinion on this Bicep file" — and resolves it into the right agents, running them in parallel waves against the right repos.

The orchestration PM coordinates. Validators run. The security gate makes the final call. Nothing passes without it.

---

Key components

Component	Location	Purpose
orchestration-pm agent	.claude/agents/orchestration-pm.md	Coordinator — reads the registry, builds waves, spawns agents, aggregates results
security-waf-caf agent	.claude/agents/security-waf-caf.md	Hard gate — WAF five-pillar + CAF naming. Merge blocker. Opus model.
Validator agents	.claude/agents/*-validator.md + *-linter.md	Run the tools defined in each validation profile; report pass/fail
master-registry.db	D:\git\platform\master-registry.db	All 157 repos: name, type, local path, validation profile, pilot flag
profiles/*.yaml	D:\git\platform\profiles\	8 validation profiles, one per repo type
Commands	.claude/commands/	/dispatch, /sweep, /second-opinion, /persona

---

How a dispatch works (Tier A)

/dispatch [type|repo|--dry-run]
       │
       â–¼
orchestration-pm reads master-registry.db
       │
       â–¼
For each target repo → look up validation_profile → read profiles/<type>.yaml
       │
       â–¼
Group into waves (max 8 concurrent, max 1 per repo)
       │
       â–¼
Wave N: spawn validator agents in parallel
       │
       ├── all structural checks PASS → spawn security-waf-caf
       │                                     │
       │                                     ├── PASS → repo marked green
       │                                     └── BLOCK → repo marked blocked; human escalation
       │
       └── any structural check FAILS → skip security gate; report failure
       │
       â–¼
Status report: X passed / Y failed / Z blocked

A Tier B client runs the same profile checks through the MCP validate tool, one repo at a time, reading each result itself — no waves, no fan-out.

---

Wave-packing rules (Tier A)

• Max 8 concurrent agent spawns per wave. This is a hard limit, not a guideline.
• Max 1 agent per repo at a time. Repos are never processed in parallel with themselves.
• Repos are grouped by type first, then by platform (GitHub / GitLab / ADO) to minimize context-switching.
• security-waf-caf always runs after all structural validators for a repo, never in parallel with them.
• If a structural validator fails, security-waf-caf is not spawned for that repo.

---

Security gate — security-waf-caf

The security gate is a hard merge blocker. Its verdict: block cannot be overridden by the orchestration PM or any other agent. It is a Tier A agent; a Tier B client performs the equivalent self-review against the WAF/CAF standards through get_standard and which_standards_apply, and still gates security-sensitive changes on human approval.

It checks:

Dimension	What it checks
WAF Reliability	Redundancy, failover design, single points of failure
WAF Security	Least privilege, network isolation, encryption at rest/in transit
WAF Cost Optimization	Right-sizing, idle resource detection, commitment discounts
WAF Operational Excellence	Tagging, monitoring, alerting, runbook coverage
WAF Performance Efficiency	Tier selection, autoscale, load distribution
CAF Naming	Azure resource naming against Microsoft Cloud Adoption Framework conventions

The gate uses the Microsoft Learn MCP tools for live documentation lookups. Model: opus.

---

Pilot scope

The current active scope is pilot repos only — 7 repos, one per type. Full estate dispatch is deferred until all pilots are green end-to-end.

See Registry for the pilot list.

---

Orchestration commands

Command	Purpose
/dispatch	Run validators + security gate across target repos
/sweep	Cross-repo read-only scan
/second-opinion	Send an artifact to Gemini for independent analysis
/persona	Switch the PM's active persona

See Commands for full reference. These commands are Claude-native (Tier A); Tier B clients invoke the equivalent MCP tools directly.