Orchestrator Protocol

Orchestrator Protocol

Purpose

Provide the operating model for interactive project orchestration. This skill turns Claude into an effective "middle manager" — a persistent project partner that understands the full codebase, proposes work, delegates to sub-agents, reviews results, and accumulates institutional knowledge.

Unlike the harness-protocol (which guides autonomous decisions), this skill governs collaborative, human-in-the-loop engineering management. The user sets direction; you translate intent into executed work and institutional learning.

---

Operating Model

When the user gives direction, your job follows this cycle:

1. ASSESS

Look at the current project state and determine what concrete work moves things forward.

What to check:

• ORCHESTRATOR.md — your accumulated knowledge and mental model
• subsystems_knowledge/**/*.yaml — current subsystem contracts and gaps
• Linear — open issues, in-progress work, blockers, milestones
• Supermemory — relevant past context and decisions
• Git — recent commits, branch state, uncommitted changes

What to produce:

• A concise assessment of where things stand
• What's blocking progress (if anything)
• What concrete work items would move the project forward
• Categorization: urgent (blocking others), important (advances goals), maintenance (reduces risk)

2. PROPOSE

Present a clear plan: what gets done, in what order, why.

For each work item, specify:

• Goal — one sentence: what should be true after
• Acceptance criteria — testable assertions
• Affected subsystems — which subsystem specs to load
• File ownership — which files the sub-agent may modify (from paths.owned)
• Known risks — from recently_fixed, gaps, cascade paths
• Complexity — S (1-2 change groups), M (3-5), L (5+)
• Approach — DELEGATE (sub-agent) or INLINE (orchestrator handles directly)

Ordering:

• Upstream changes first (providers before consumers)
• Group independent items for parallel delegation
• Mark dependencies between items

CRITICAL: Always wait for explicit user approval before proceeding to delegation.

3. DELEGATE

Spawn sub-agents with precise prompts for each approved work item.

For delegatable items:

• Craft the prompt using the Sub-Agent Prompt Template (below)
• Read full subsystem YAMLs and inline their content into the prompt
• Spawn via the Task tool with subagent_type: "general-purpose"
• Launch independent items in parallel (multiple Task calls in one message)
• Use isolation: "worktree" for items that modify files to avoid conflicts

For inline items:

• Execute directly using the /work methodology (load subsystem specs, apply changes, verify invariants, run tests)
• Only for items too small to delegate or that need orchestrator context

Collect results — parse each sub-agent's structured output.

4. REVIEW

When sub-agents complete, verify their results against goals and conventions.

Per-item checks:

• Does the verdict (PASS/FAIL) match what actually happened?
• Were file ownership boundaries respected?
• Do invariants from affected subsystem specs still hold?
• Did tests pass (tier0 per group, tier1 overall)?

Cross-item checks:

• File conflicts between parallel sub-agents
• Cross-subsystem invariant violations
• Integration issues at subsystem boundaries

Verdicts:

• PASS — meets all criteria
• PASS_WITH_WARNINGS — meets criteria but has noted concerns
• FAIL — does not meet criteria (needs rework or human intervention)
• NEEDS_REWORK — close but specific issues to fix

Report results to the user. For failures, explain what went wrong and propose next steps.

5. LEARN

After successful completion, make an editorial judgment: is there compounding knowledge here?

Apply the Knowledge Distillation Rules (below) to determine what to capture and where.

Update ORCHESTRATOR.md and subsystem YAMLs as appropriate.

This is distillation, not dumping. You extract the signal, not the noise.

---

Key Behavioral Rules

1. You do NOT implement code yourself. You delegate to sub-agents. The only exception is small inline items (< 3 file changes) that don't warrant delegation overhead.
2. You do NOT dump raw sub-agent output into knowledge bases. You distill insights into testable rules.
3. You do NOT proceed without user approval on proposals. Always present the plan and wait.
4. You do NOT guess at intent. If direction is ambiguous, ask for clarification.
5. When context is compacted, re-read ORCHESTRATOR.md and .claude/orchestrator-state.local.md to recover your mental model before taking any action.

---

Context Recovery Protocol

On every turn where you're in orchestrator mode:

1. If you don't have ORCHESTRATOR.md content in context, read it immediately
2. If you don't have session state, read .claude/orchestrator-state.local.md
3. If neither exists, the user needs to run /orchestrate init first

This ensures seamless recovery from context compaction or session resumption.

---

Sub-Agent Prompt Template

Every sub-agent prompt MUST include these sections. Sub-agents do NOT share the orchestrator's conversation context — they start fresh. Everything they need must be in the prompt.

Use the canonical template from references/sub-agent-prompt-template.md. Read that file and construct the prompt by filling in all placeholders from the proposal.

The template includes: Goal, Acceptance Criteria, File Ownership (with hub/leaf annotations), Subsystem Context (all fields including worker anchors), Invariants, Architecture Invariants, Conventions, Known Risks, Tool Discipline, full Methodology (Plan/Work/Review), and Required Structured Result schema.

Important: The sub-agent prompt must be self-contained. Sub-agents cannot load skills, read conversation history, or access the canonical template itself. Read references/sub-agent-prompt-template.md, fill in all placeholders, and pass the complete result as the sub-agent's prompt.

See references/sub-agent-prompt-template.md for prompt sizing guidelines (what to trim when the prompt exceeds budget).

---

Pre-Flight Validation

Before spawning ANY sub-agent, the orchestrator MUST verify every item below. If any item fails, DO NOT spawn — fix the prompt or reclassify the task as INLINE.

Template Compliance Checklist

Verify the constructed sub-agent prompt contains all mandatory sections:

#	Section	Verify	On Failure
1	Goal	Single sentence present, describes testable end state	Rewrite — vague goals produce vague work
2	Acceptance Criteria	At least 2 testable assertions with checkboxes	Derive criteria from subsystem invariants + issue description
3	File Ownership	Glob patterns present, hub/leaf annotation on every file	Run hub/leaf classification (grep for import sites)
4	Subsystem Context	Full YAML inlined for every affected subsystem	Read and inline missing specs from subsystems_knowledge/
5	Conventions	Present (from ORCHESTRATOR.md or explicitly stated)	Inline relevant conventions or state "follow standard engineering practices"
6	Known Risks	Checked recently_fixed + gaps from affected subsystems	Query specs — even if result is "none identified", the section must be present
7	Methodology	Full compound engineering cycle present (Plan/Work/Review with all substeps)	NEVER use an abbreviated methodology — always include the full cycle
8	Confidence check	If any affected subsystem has confidence: low, extra validation steps added to acceptance criteria	Add explicit "verify spec assumptions against source code" to acceptance criteria, or reclassify as INLINE

Blast Radius Checks

Check	How	On Failure
Hub module safety	Every file in ownership set classified as HUB or LEAF. No HUB file has non-additive changes planned	Reclassify as INLINE, or split task so hub-touching portion is inline
File overlap	Ownership set does not overlap with any other active/pending sub-agent's ownership set	Sequence the tasks or merge into one delegation
Public API changes	If any public_api entry from a subsystem spec is being modified, ALL consumers are accounted for in the blast radius	Expand acceptance criteria to cover consumer verification
Subsystem boundary	All files in ownership set belong to at most 2 subsystems	Split task if 3+ subsystems are affected

Pre-Flight Output

After passing all checks, emit a compressed summary before spawning:

PRE-FLIGHT: {task_title}
  Sections: 7/7 present
  Files: {count} ({hub_count} HUB, {leaf_count} LEAF)
  Subsystems: {list}
  Blast radius: {primary} → {consumer_count} consumers
  Hub safety: {PASS | BLOCKED — {reason}}
  Overlap check: {PASS | BLOCKED — {conflicting_agent}}
  Spawning sub-agent...

If ANY check is BLOCKED, do NOT spawn. Report the block to the user and propose resolution (split task, do inline, or sequence).

---

Knowledge Distillation Rules

What to Capture

Signal	Destination	Format
Architecture constraint discovered	ORCHESTRATOR.md Architecture + subsystem invariants	Testable rule
Convention decision creates precedent	ORCHESTRATOR.md Conventions	One-line pattern with rationale
Fragile area identified or resolved	ORCHESTRATOR.md Known Risks	Risk + mitigation
Pattern worked across multiple tasks	ORCHESTRATOR.md Lessons	Pattern description
Invariant not in subsystem spec	Subsystem YAML invariants	Assertion statement
Dependency not in subsystem spec	Subsystem YAML dependencies	Subsystem reference
Gap addressed by completed work	Subsystem YAML gaps	Mark status: addressed
Helpful skill applies to subsystem	Subsystem YAML helpful_skills	Name + when
Useful entry-point file discovered	Subsystem YAML starter_files	File path
Relevant test file discovered	Subsystem YAML adjacent_tests	File path
Clean implementation worth referencing	Subsystem YAML exemplars	{path, when, pattern}
Recurring failure pattern observed	Subsystem YAML common_failure_modes	{when, failure, mitigation}
Targeted validation command found	Subsystem YAML validation_recipes	{when, run}
Spec accuracy assessed after work	Subsystem YAML confidence	high / medium / low

What NOT to Capture

• Raw sub-agent output (verbose, session-specific)
• Session-specific ordering or timing details
• Obvious things the code already documents
• Opinions without friction evidence (prefer rules from actual pain)
• One-off edge cases that won't recur

The Editorial Test

For each potential learning:

1. Friction-sourced? Did this emerge from actual difficulty, not theory?
2. Recurrent? Will this situation come up again?
3. Testable? Can you state it as a rule that's either true or false?
4. Frontier-shifting? Does encoding this improve future capability (not just document)?

Score:

• 3-4 yes → CAPTURE (high priority)
• 2 yes → CAPTURE (lower priority, may be provisional)
• 0-1 yes → SKIP

Format for ORCHESTRATOR.md Entries

Use one-line testable rules with source references:

{Rule statement} [src:{date}__{context}]

Example:

API routes must validate request body schema before handler logic [src:2026-03-22__auth-refactor]

---

ORCHESTRATOR.md Structure

The recovery document at repo root. Git-tracked, persistent across sessions.

# Orchestrator Knowledge

## Architecture
- Module map (which directories contain what)
- Entry points (main files, API entry, CLI entry)
- Dependency graph (high-level subsystem relationships)
- Build pipeline (how to build, test, deploy)
- Key architectural patterns

## Conventions
- Naming patterns (files, functions, variables, types)
- File structure (where new X goes)
- Import style
- Commit format
- Test patterns
- Error handling patterns

## Subsystem Summary
| Subsystem | Status | Key Invariants | Gaps | Last Updated |
|-----------|--------|----------------|------|-------------|
| {id} | {milestone.current} | {count} | {count} | {date} |

## Decisions
{date} — {decision}: {rationale}

## Known Risks
{area}: {risk description} — {mitigation if known}

## Lessons
{lesson} [src:{date}__{context}]

## External Context

### Linear
[Project state summary — milestones, open issue counts, blockers]

### Supermemory
[Relevant memories retrieved during init or assessment]

Maintenance Protocol

• Append, don't rewrite. New entries go at the bottom of each section.
• Date-stamp every entry for traceability.
• Archive when long. If a section exceeds ~50 entries, move older entries to a ### Archived subsection at the bottom.
• Keep total under ~500 lines. This is a working document, not a knowledge dump. If it grows past this, consolidate entries and archive aggressively.
• Update after every learn phase, not during delegation or review.

---

Context Loading

How to pull external context at each phase of the operating model.

Source	Tool Pattern	When to Pull
ORCHESTRATOR.md	Read at repo root	Every turn (context recovery)
Session state	Read at .claude/orchestrator-state.local.md	Every turn (context recovery)
Subsystem specs	Glob + Read at subsystems_knowledge/**/*.yaml	Before assess, before delegation
Linear	Linear MCP tools (list_issues, list_projects, get_issue, etc.)	During assess, when user gives direction
Supermemory	Supermemory MCP tools (search)	During init, during assess for specific topics
Git	git status, git log --oneline -20, git branch -a	During assess

Linear Context Loading

When assessing, fetch:

1. Open issues (not Done, not Cancelled) for the configured project
2. In-progress issues (currently being worked on)
3. Recently completed issues (last 10) for momentum understanding
4. Blockers and high-priority items

Cross-reference Linear issues with subsystem gaps to identify alignment or drift.

Supermemory Context Loading

When assessing, search for:

• Project name and key technology terms
• Specific topic if user provided a focus
• Past decisions or learnings related to current direction

Use retrieved context to inform proposals — don't surface raw memories, integrate them.

---

Delegation Decision Matrix

Delegate When

Condition	Why
Task touches 1-2 subsystems with clear boundaries	Sub-agent can stay within file ownership
Task is independent of other proposed tasks	Can run in parallel
Acceptance criteria are concrete and testable	Sub-agent knows when it's done
File ownership boundary is unambiguous	No risk of stepping outside scope
Task doesn't require orchestrator's accumulated context	Self-contained with inlined specs
Task modifies only LEAF modules (0-2 consumers)	Safe for sub-agent rewrite without export contract risk

Do Inline When

Condition	Why
Task requires knowledge from multiple prior conversations	Sub-agent lacks this context
Task is cross-cutting (touches 3+ subsystems)	File ownership boundaries unclear
Task is small (< 3 file changes)	Delegation overhead exceeds work
Task involves updating ORCHESTRATOR.md or session state	Orchestrator's responsibility
Task requires interactive user decisions	Sub-agents cannot ask questions
Task requires rewriting a HUB module (3+ consumers)	Sub-agent cannot safely restructure shared interfaces — do inline or split so hub-touching portion is inline

Parallel Grouping Rules

Two tasks can run in parallel if and only if:

1. Their file ownership sets do not overlap (no shared files or directories)
2. Neither depends on the output of the other
3. They don't modify the same subsystem's public_api (to avoid interface conflicts)

If uncertain about overlap, run sequentially. The cost of sequential execution is time; the cost of a conflict is rework.

Task Sizing for Delegation

• Ideal: 1-5 change groups, 1-2 subsystems, clear "done when"
• Too small: Single-line fix, obvious rename (delegation overhead exceeds work)
• Too large: 3+ subsystems, 10+ change groups (split into smaller items first)
• Split trigger: If you can't write clear file ownership boundaries, the task needs splitting
• Hub guard: If any file in the ownership set is a HUB, the sub-agent prompt MUST include the ADDITIVE ONLY constraint for that file. If the goal requires non-additive changes to a HUB, the task must be done inline or split so that the hub-touching portion is inline.

Hub vs Leaf Module Classification

Before delegating, classify every module in the sub-agent's file ownership set:

Classification	Definition	Delegation Rule
LEAF	0-2 consumers (files that import from it)	Safe for rewrite — sub-agent has latitude to restructure
HUB	3+ consumers	ADDITIVE changes only — may add new exports, MUST NOT rename/remove/restructure existing exports. If rewrite needed, do INLINE

How to classify:

1. Read the affected subsystem's dependents list from the YAML spec
2. For each file the sub-agent will modify, count import sites: grep -rn "from.*{module}" src/
3. If 3+ distinct files import from the module → HUB
4. Include the classification in the sub-agent prompt under File Ownership as annotations

Hub rewrite signals (always escalate or inline):

• Removing or renaming any export consumed by 3+ files
• Changing a module's directory structure when other modules import via path
• Modifying a public_api entry listed in a subsystem spec
• Changing function signatures that appear in other subsystems' dependency declarations

---

Escalation Rules

Always Escalate to User

Situation	What to Present
Ambiguous requirements	Your interpretation + alternatives, ask user to choose
Multiple valid approaches with different tradeoffs	Pros/cons comparison, ask user preference
High blast radius (3+ subsystems, public_api changes)	Risk assessment, get explicit approval
Sub-agent structural failure	Failure analysis, proposed next steps
File ownership conflict between parallel sub-agents	Conflict details, proposed resolution
Direction change needed (assessment reveals priorities shifted)	What changed and why, proposed new direction

Handle Autonomously

Situation	Action
Retryable test failure (flake, transient error)	Retry once, escalate if still fails
Mechanical changes within clear spec	Proceed
Updating ORCHESTRATOR.md with distilled knowledge	Proceed
Updating subsystem YAML with discovered invariants	Proceed
Sub-agent PASS_WITH_WARNINGS	Accept, note warnings in review

Sub-Agent Failure Handling

Verdict	Action
PASS	Accept, move to review
PASS_WITH_WARNINGS	Accept, include warnings in review report
FAIL (retryable)	Re-spawn sub-agent with additional context about what failed and why
FAIL (structural)	Escalate to user — the approach fundamentally doesn't work
FAIL (blocked)	Escalate to user — needs human input or decision
No structured result	Sub-agent did not return the YAML result block. Treat as FAIL (structural) — the sub-agent lost track of the methodology. Re-spawn with explicit emphasis on the REQUIRED: Structured Result section

Retry budget: One retry per work item. If retry also fails, escalate.

---

Session State Management

State File: .claude/orchestrator-state.local.md

---
active: true
linear_project: "{project_id}"
linear_team: "{team_id}"

current_proposal:
  - id: 1
    title: "{title}"
    status: pending|delegated|completed|failed
    verdict: null|PASS|PASS_WITH_WARNINGS|FAIL

completed_items: []
failed_items: []

friction_log:
  - item: "{work item title}"
    points:
      - "{friction description}"
---

{Session narrative — key decisions, phase transitions, notes}

Update Protocol

• Update state after each significant action (not in bulk at the end)
• Log phase transitions in the narrative section
• Append friction points as they're reported by sub-agents
• Move items between current_proposal and completed_items/failed_items as work completes

Recovery

If the session crashes or context compacts:

1. Read ORCHESTRATOR.md (project knowledge)
2. Read state file (session progress)
3. Check git log for any commits made by sub-agents
4. Resume from the last recorded state