Orchestration lives in one plugin, apart from infra and HQ

spec:hq.orchestration

Use Case / Behavior · featuredefined floor ready

Next rung ready: nothing blocks; it waits only for the author's statement.

Packs: none

Design: no design entries · no pinned declarations · 3 decisions

design/hq/hq/orchestration.sdp.md

No open questions and no blocking questions; implementation binding none, verifier binding none, and expected-outcome oracle none.

The owner has already paid for the hard part: harnesses behave differently, and glue was built to manage that, and with mods the differences are handled. Relay already carries multi-day protocol executions on mission-critical work, and it runs properly inside T3 Code because it runs in the actual Claude harness. What is left is the separation of concerns: the inbox was built into infra only because the attempt at bootstrapping HQ needed it there.

Intent

actor: Agents that delegate work, and the owner who watches them.
problem: Generic coordination sits in infra because a bootstrap needed it, so every project's orchestration depends on the repository that should know least about it.
outcome: The inbox, the chain and the other generic orchestration live in cc-agents, Relay's rewrite, which infra deploys to projects as an extension.
value: Models with complementary characteristics, each with its own taste and approach, work together on one task.

Behavior

rule.genericInPlugin line 31 · design/hq/hq/orchestration.sdp.md:31: The inbox, the chain and similar generic orchestration live in cc-agents, not in infra and not in HQ.
no example exercises it
rule.relayUntilTrusted line 32 · design/hq/hq/orchestration.sdp.md:32: Relay runs the harness jobs until cc-agents' job runner earns the owner's trust, and that runner stays off on every machine until then.
no example exercises it
rule.coordinationSwitchesAlone line 33 · design/hq/hq/orchestration.sdp.md:33: Coordination in cc-agents can be on where its job runner is off, because infra gives up the inbox before the runner has earned trust.
no example exercises it
rule.nativeMessaging line 34 · design/hq/hq/orchestration.sdp.md:34: Inside one operating system, sessions message each other through Claude Code's own cross-session messaging, and cc-agents adds only a lasting record and each session's role and parent.
no example exercises it
rule.boundaryCrossing line 35 · design/hq/hq/orchestration.sdp.md:35: A message between operating systems crosses through the T3 MCP route, and nothing inside one operating system depends on that route.
no example exercises it
rule.complementaryModels line 36 · design/hq/hq/orchestration.sdp.md:36: Complex scope runs as workflows that mix Claude with other providers' models through Relay.
no example exercises it
rule.infraDeploysExtension line 37 · design/hq/hq/orchestration.sdp.md:37: Infra deploys the orchestration extension and its templates to projects.
no example exercises it
rule.sessionScanning line 38 · design/hq/hq/orchestration.sdp.md:38: Session scanning moves into cc-agents before the current vault is deleted, with the extraction of the owner's words it depends on, because that record is what lets a scan trace each direction to its outcome.
no example exercises it
rule.scanFilters line 39 · design/hq/hq/orchestration.sdp.md:39: A scan's prompt names the context it filters out, so that it reads pure context from the repositories and not the orchestration noise that vault sessions repeat.
no example exercises it
rule.templates line 40 · design/hq/hq/orchestration.sdp.md:40: Templates for end users, private templates and project-specific templates are scope for cc-agents.
no example exercises it
rule.skillsPerSession line 41 · design/hq/hq/orchestration.sdp.md:41: Infra prepares the list of skills for each session, so that a session loads only what its task needs.
no example exercises it
rule.contextForPeers line 42 · design/hq/hq/orchestration.sdp.md:42: A lane on another provider receives the Claude Code skills and documentation its task needs.
no example exercises it

0 unkeyed rules.

Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

Declared verifying examples: no declared verifying example.
Satisfying or referencing units: no recorded binding.
Test or oracle bindings: no recorded binding.

Requirement drawing for spec:hq.orchestration

Arrows: refines (declared).

The diagram as text

spec:hq.orchestration: Orchestration lives in one plugin, apart from infra and HQ · declared Spec · no satisfying binding
spec:cc-agents.hq-links: The one tie between this repository's Specs and HQ's design · declared Spec · no satisfying binding
spec:decisions.coordination-native-first: Coordination is built on Claude Code's own messaging, and cc-agents adds only what that lacks · declared Spec
spec:decisions.orchestration-leaves-infra: Generic orchestration moves from infra to cc-agents, and Relay runs jobs until cc-agents earns trust · declared Spec
spec:architecture.cc-agents: cc-agents · declared Spec
spec:hq.headquarters: HQ plans and designs across every project, and starts the engineering work · declared Spec
spec:cc-agents.hq-links refines spec:architecture.cc-agents · declared — the job runner and the coordination design are the parts of this component that exist in this repository
spec:cc-agents.hq-links refines spec:hq.orchestration · declared — this repository's coordination design answers the rules that HQ's orchestration states
spec:decisions.coordination-native-first refines spec:hq.orchestration · declared — settles what coordination is built from once it leaves infra
spec:decisions.orchestration-leaves-infra refines spec:hq.orchestration · declared — settles where generic orchestration lives and what runs jobs until then
spec:hq.orchestration refines spec:hq.headquarters · declared — names how work moves between harnesses, models and machines

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

Mermaid source for Requirement drawing for spec:hq.orchestration

requirementDiagram
  requirement n0 {
    text: "The one tie between this repository's Specs and HQ's design · declared Spec · no satisfying binding · spec:cc-agents.hq-links"
  }
  requirement n1 {
    text: "Coordination is built on Claude Code's own messaging, and cc-agents adds only what that lacks · declared Spec · spec:decisions.coordination-native-first"
  }
  requirement n2 {
    text: "Generic orchestration moves from infra to cc-agents, and Relay runs jobs until cc-agents earns trust · declared Spec · spec:decisions.orchestration-leaves-infra"
  }
  requirement n3 {
    text: "Orchestration lives in one plugin, apart from infra and HQ · declared Spec · no satisfying binding · spec:hq.orchestration"
  }
  requirement n4 {
    text: "cc-agents · declared Spec · spec:architecture.cc-agents"
  }
  requirement n5 {
    text: "HQ plans and designs across every project, and starts the engineering work · declared Spec · spec:hq.headquarters"
  }
  %% claim: declared; reason: the job runner and the coordination design are the parts of this component that exist in this repository
  n0 - refines -> n4
  %% claim: declared; reason: this repository's coordination design answers the rules that HQ's orchestration states
  n0 - refines -> n3
  %% claim: declared; reason: settles what coordination is built from once it leaves infra
  n1 - refines -> n3
  %% claim: declared; reason: settles where generic orchestration lives and what runs jobs until then
  n2 - refines -> n3
  %% claim: declared; reason: names how work moves between harnesses, models and machines
  n3 - refines -> n5

Decisions

Coordination is built on Claude Code's own messaging, and cc-agents adds only what that lacks
Most work stays in one session with its agents and Workflows, and needs no messaging. Where work must cross a boundary inside one operating system, sessions find and message each other through Claude Code's own cross-session messaging, with every session accepting inbound messages. cc-agents adds only what that lacks: a lasting record of every message, and each session's place in a chain. Between operating systems, a message crosses through the T3 MCP route.
Generic orchestration moves from infra to cc-agents, and Relay runs jobs until cc-agents earns trust
The inbox, the chain and similar generic orchestration move from infra to cc-agents. Until cc-agents' job runner earns trust it stays off on every machine and Relay runs the harness jobs, while its coordination can already be on. Infra deploys the result to projects as an extension.
The recovery chain stops and this corpus replaces its master plan
The recovery chain stops and this SDP corpus replaces its master plan. The scan items' purpose, recovering valid owner directions and sufficient evidence for rollback and takeover, remains with the context and infra Specs. Existing evidence is used first; any remaining investigation is bounded detailed work, not a revival of the recovery chain.

Runtime

No implementation neighborhood recorded.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact

Relations of spec:hq.orchestration

The diagram as text

spec:cc-agents.hq-links: The one tie between this repository's Specs and HQ's design
spec:decisions.coordination-native-first: Coordination is built on Claude Code's own messaging, and cc-agents adds only what that lacks
spec:decisions.orchestration-leaves-infra: Generic orchestration moves from infra to cc-agents, and Relay runs jobs until cc-agents earns trust
spec:decisions.recovery-closed: The recovery chain stops and this corpus replaces its master plan
spec:hq.headquarters: HQ plans and designs across every project, and starts the engineering work
spec:hq.infra: Infra delivers configuration by projection, under HQ's plan
spec:hq.orchestration: Orchestration lives in one plugin, apart from infra and HQ
spec:hq.orchestration decidedBy spec:decisions.coordination-native-first · declared — settles what coordination is built from
spec:hq.orchestration decidedBy spec:decisions.orchestration-leaves-infra · declared — the ruling places generic orchestration in Relay's rewrite
spec:hq.orchestration decidedBy spec:decisions.recovery-closed · declared — items 7 and 8 of the master plan continue here
spec:hq.orchestration refines spec:hq.headquarters · declared — names how work moves between harnesses, models and machines
spec:hq.infra dependsOn spec:hq.orchestration · declared — the owner's order takes over Relay and cc-agents before infra, and the inbox leaves infra first
spec:cc-agents.hq-links refines spec:hq.orchestration · declared — this repository's coordination design answers the rules that HQ's orchestration states
spec:decisions.coordination-native-first refines spec:hq.orchestration · declared — settles what coordination is built from once it leaves infra
spec:decisions.orchestration-leaves-infra refines spec:hq.orchestration · declared — settles where generic orchestration lives and what runs jobs until then

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Mermaid source for Relations of spec:hq.orchestration

flowchart TB
  n0["HQ plans and designs across every project, and starts the engineering work · spec:hq.headquarters"]
  n1["The recovery chain stops and this corpus replaces its master plan · spec:decisions.recovery-closed"]
  n2["Orchestration lives in one plugin, apart from infra and HQ · spec:hq.orchestration"]
  n3["The one tie between this repository's Specs and HQ's design · spec:cc-agents.hq-links"]
  n4["Coordination is built on Claude Code's own messaging, and cc-agents adds only what that lacks · spec:decisions.coordination-native-first"]
  n5["Generic orchestration moves from infra to cc-agents, and Relay runs jobs until cc-agents earns trust · spec:decisions.orchestration-leaves-infra"]
  n6["Infra delivers configuration by projection, under HQ's plan · spec:hq.infra"]
  n3 -->|"refines · declared — this repository's coordination design answers the rules that HQ's orchestration states"| n2
  n4 -->|"refines · declared — settles what coordination is built from once it leaves infra"| n2
  n5 -->|"refines · declared — settles where generic orchestration lives and what runs jobs until then"| n2
  n6 -->|"dependsOn · declared — the owner's order takes over Relay and cc-agents before infra, and the inbox leaves infra first"| n2
  n2 -->|"decidedBy · declared — settles what coordination is built from"| n4
  n2 -->|"decidedBy · declared — the ruling places generic orchestration in Relay's rewrite"| n5
  n2 -->|"decidedBy · declared — items 7 and 8 of the master plan continue here"| n1
  n2 -->|"refines · declared — names how work moves between harnesses, models and machines"| n0

Rests on

refines · spec:hq.headquarters · stated defined, floor ready
decidedBy · spec:decisions.coordination-native-first · stated defined, floor ready
decidedBy · spec:decisions.orchestration-leaves-infra · stated defined, floor ready
decidedBy · spec:decisions.recovery-closed · stated defined, floor ready

Rested on by

Distance 1

spec:cc-agents.hq-links
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:decisions.coordination-native-first
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:decisions.orchestration-leaves-infra
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:hq.infra
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Distance 2

spec:decisions.isolated-infra-manages-hq
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:hq.context
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Distance 3

spec:decisions.client-material-deferred
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:hq.environment
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:hq.isolation
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Distance 4

spec:hq.engineering-environment
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:hq.session-handoff
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Distance 5

spec:decisions.design-locked-by-projection
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:hq.delivery-planning
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Distance 6

spec:decisions.sdp-holds-the-plan
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Distance 7

spec:hq.headquarters
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Distance 8

spec:architecture.cc-agents
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:architecture.inbox
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:architecture.relay
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:decisions.hq-starts-engineering
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:decisions.recovery-closed
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:decisions.separate-repositories
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:hq.model
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Relations

Relation and direction	Other end	Claim	Reason	Exercised keys
decidedBy · outgoing	Coordination is built on Claude Code's own messaging, and cc-agents adds only what that lacks `spec:decisions.coordination-native-first` · resolves	declared	settles what coordination is built from	None
decidedBy · outgoing	Generic orchestration moves from infra to cc-agents, and Relay runs jobs until cc-agents earns trust `spec:decisions.orchestration-leaves-infra` · resolves	declared	the ruling places generic orchestration in Relay's rewrite	None
decidedBy · outgoing	The recovery chain stops and this corpus replaces its master plan `spec:decisions.recovery-closed` · resolves	declared	items 7 and 8 of the master plan continue here	None
refines · outgoing	HQ plans and designs across every project, and starts the engineering work `spec:hq.headquarters` · resolves	declared	names how work moves between harnesses, models and machines	None
dependsOn · incoming	Infra delivers configuration by projection, under HQ's plan `spec:hq.infra` · resolves	declared	the owner's order takes over Relay and cc-agents before infra, and the inbox leaves infra first	None
refines · incoming	The one tie between this repository's Specs and HQ's design `spec:cc-agents.hq-links` · resolves	declared	this repository's coordination design answers the rules that HQ's orchestration states	None
refines · incoming	Coordination is built on Claude Code's own messaging, and cc-agents adds only what that lacks `spec:decisions.coordination-native-first` · resolves	declared	settles what coordination is built from once it leaves infra	None
refines · incoming	Generic orchestration moves from infra to cc-agents, and Relay runs jobs until cc-agents earns trust `spec:decisions.orchestration-leaves-infra` · resolves	declared	settles where generic orchestration lives and what runs jobs until then	None

Bindings

Implementation binding: none

Design reference: none

Verifier binding: none

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.