Sessions that must message each other leave a record and a place in a chain

spec:cc-agents.coordination

Use Case / Behavior · epicdefined floor ready

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

Packs: none

Design: no design entries · no pinned declarations · 1 decision

specs/coordination/coordination.sdp.md

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

Most work needs one session. That session has agents and dynamic Workflows, lanes on other providers' models included, and their results return into its own turn. Coordination is for the work that cannot stay in one session, and it adds only what Claude Code's own cross-session messaging lacks. It has four parts: how it is switched on and taken up (spec:cc-agents.coordination.adoption), the record of messages (spec:cc-agents.coordination.record), the chain (spec:cc-agents.coordination.chain) and what the person sees (spec:cc-agents.coordination.view).

Intent

actor: A person who runs Claude Code sessions, and the sessions that start, brief and report to one another.
problem: Work that must cross a session boundary leaves no trace. A message sent while the receiver holds or refuses inbound messages leaves its sender no sign of it. A peer's message reads like the person's own typing in a transcript. A session started by another does not know whom it reports to, and its starter does not know what it left running.
outcome: Where work really needs more than one session, the sessions message through Claude Code's own messaging, each knows its place in a chain, and every message is kept in a record that a person or a later session can read.
value: A part of the work started elsewhere is not mistaken for the person's own words, and where the record has evidence it can be found and its owner known; where the record has none, that is shown as unknown.
assumptions: Claude Code's cross-session messaging behaves as measured on version 2.1.314: with inbound messages accepted a message arrives mid-turn whatever the two sessions' permission modes, and a mod's send wakes an idle session.
With inbound messages not accepted a message is held or refused according to the setting, and the sender is told only through the result of its send. A successful send means queued, not read.
A mod sees every message that reaches or leaves its session through the events session.receive and session.send.
Sessions run by separate applications on one operating system are native peers. A container and its host are not.
risks: Messaging is one vendor's feature with that vendor's defaults. A change there changes what this plugin can observe, so each part states what it needs of the host and the plugin reads it at start.

Open questions

non-blocking · question.bridge line 29 · specs/coordination/coordination.sdp.md:29 · Should messages that cross an operating system boundary by a route outside the host's own messaging be recorded and joined to a chain, and how does a lead on another operating system reach its parent's tree?Decider: ownerLinks: spec:cc-agents.coordination.recordProvisional: This release's tree covers records on the local machine only, and an external parent is shown as an unresolved boundary. Cross-operating-system delivery remains outside this release. The existing cross-machine route stays until a separate bounded measurement shows how a join and a report cross it. No distributed service is built.

Behavior

rule.sessionFirst line 36 · specs/coordination/coordination.sdp.md:36: Work runs as one session with its agents and Workflows, and a result from an agent or a Workflow role returns into that session's turn, with no message, address or record.
no example exercises it
rule.secondSessionAtBoundary line 37 · specs/coordination/coordination.sdp.md:37: A second session starts only where one session cannot reach: another operating system, another repository or permission profile, or a part large or long enough to need a context of its own.
no example exercises it
rule.chainIsParents line 38 · specs/coordination/coordination.sdp.md:38: A chain is the sessions started for one piece of work, each stating its parent, and it is read from those statements in the records on this machine; no service or file holds a chain as a whole.
no example exercises it
rule.threeMessages line 39 · specs/coordination/coordination.sdp.md:39: Inside a chain a message is a brief from a parent to a lead, a report from a lead to its parent, or a correction from a parent to a lead; a message between sessions of no common chain is the exception, and it is recorded like any other.
no example exercises it
rule.nativeDelivery line 40 · specs/coordination/coordination.sdp.md:40: Sessions on one operating system message through Claude Code's own cross-session messaging, and this plugin delivers, queues and retries nothing.
no example exercises it
rule.pluginAddsTwo line 41 · specs/coordination/coordination.sdp.md:41: The plugin adds a record of every message between sessions and a lead's place in a chain, shows both to the person, and works with the job runner off.
no example exercises it

0 unkeyed rules.

Model

session line 45 · specs/coordination/coordination.sdp.md:45: One running Claude Code conversation, addressed by its full session id; an agent or a Workflow role inside it is not a session.
boundary line 46 · specs/coordination/coordination.sdp.md:46: A line one session cannot cross by itself: an operating system, a repository or permission profile, or the size and length of a context.
chain line 47 · specs/coordination/coordination.sdp.md:47: The sessions started for one piece of work, each stating its parent.
top line 48 · specs/coordination/coordination.sdp.md:48: The session of a chain with no parent; it is the one the person talks to.
lead line 49 · specs/coordination/coordination.sdp.md:49: A session that has a parent and owns one part of the work.
part line 50 · specs/coordination/coordination.sdp.md:50: The one line that says what a lead owns.
brief line 51 · specs/coordination/coordination.sdp.md:51: What a parent gives a lead when it starts: the intent of the whole work, the lead's part and how it will know it is done.
record line 52 · specs/coordination/coordination.sdp.md:52: The lasting log of every message between sessions, kept as files on the machine where the sessions ran.

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:cc-agents.coordination

Arrows: refines (declared).

The diagram as text

spec:cc-agents.coordination: Sessions that must message each other leave a record and a place in a chain · declared Spec · no satisfying binding
spec:cc-agents.coordination.adoption: Coordination switches on alone, and a project takes it up with one setting and its own boundaries · declared Spec · no satisfying binding
spec:cc-agents.coordination.boundary-only: A second session exists only across a boundary one session cannot cross · declared Spec
spec:cc-agents.coordination.chain: A lead states its parent once, and the chain is read from what leads stated · declared Spec · no satisfying binding
spec:cc-agents.coordination.record: Messages between sessions this session saw are kept whole, with what is known of who sent them and what came of them · declared Spec · no satisfying binding
spec:cc-agents.coordination.session-scanning: A scan reads a project's sessions and traces each direction to its outcome · declared Spec · no satisfying binding
spec:cc-agents.coordination.view: The person sees the chain and the traffic without asking a model · declared Spec · no satisfying binding
spec:cc-agents.coordination.adoption refines spec:cc-agents.coordination · declared — how coordination is switched on alone and taken up by a project
spec:cc-agents.coordination.boundary-only refines spec:cc-agents.coordination · declared — settles what a chain still has to be when agents and Workflows carry most work
spec:cc-agents.coordination.chain refines spec:cc-agents.coordination · declared — the second thing the plugin adds to the host's messaging
spec:cc-agents.coordination.record refines spec:cc-agents.coordination · declared — the first thing the plugin adds to the host's messaging
spec:cc-agents.coordination.session-scanning refines spec:cc-agents.coordination · declared — reads what sessions leave behind, so that work is not lost between them
spec:cc-agents.coordination.view refines spec:cc-agents.coordination · declared — what the person sees of coordination

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:cc-agents.coordination

requirementDiagram
  requirement n0 {
    text: "Sessions that must message each other leave a record and a place in a chain · declared Spec · no satisfying binding · spec:cc-agents.coordination"
  }
  requirement n1 {
    text: "Coordination switches on alone, and a project takes it up with one setting and its own boundaries · declared Spec · no satisfying binding · spec:cc-agents.coordination.adoption"
  }
  requirement n2 {
    text: "A second session exists only across a boundary one session cannot cross · declared Spec · spec:cc-agents.coordination.boundary-only"
  }
  requirement n3 {
    text: "A lead states its parent once, and the chain is read from what leads stated · declared Spec · no satisfying binding · spec:cc-agents.coordination.chain"
  }
  requirement n4 {
    text: "Messages between sessions this session saw are kept whole, with what is known of who sent them and what came of them · declared Spec · no satisfying binding · spec:cc-agents.coordination.record"
  }
  requirement n5 {
    text: "A scan reads a project's sessions and traces each direction to its outcome · declared Spec · no satisfying binding · spec:cc-agents.coordination.session-scanning"
  }
  requirement n6 {
    text: "The person sees the chain and the traffic without asking a model · declared Spec · no satisfying binding · spec:cc-agents.coordination.view"
  }
  %% claim: declared; reason: how coordination is switched on alone and taken up by a project
  n1 - refines -> n0
  %% claim: declared; reason: settles what a chain still has to be when agents and Workflows carry most work
  n2 - refines -> n0
  %% claim: declared; reason: the second thing the plugin adds to the host's messaging
  n3 - refines -> n0
  %% claim: declared; reason: the first thing the plugin adds to the host's messaging
  n4 - refines -> n0
  %% claim: declared; reason: reads what sessions leave behind, so that work is not lost between them
  n5 - refines -> n0
  %% claim: declared; reason: what the person sees of coordination
  n6 - refines -> n0

Decisions

A second session exists only across a boundary one session cannot cross
A second session is started only for one of three boundaries: another operating system, another repository or permission profile, or a part large or long enough to need a context of its own. The sessions started for one piece of work form a chain, in which the top has no parent and every other session is a lead with exactly one parent. A chain has no roles beyond top and lead. Inside a chain a message is a brief down, a report up or a correction down. A message between two sessions of no common chain is allowed, rare and recorded, and it gives neither side a role.

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:cc-agents.coordination

The diagram as text

spec:cc-agents.coordination: Sessions that must message each other leave a record and a place in a chain
spec:cc-agents.coordination.adoption: Coordination switches on alone, and a project takes it up with one setting and its own boundaries
spec:cc-agents.coordination.boundary-only: A second session exists only across a boundary one session cannot cross
spec:cc-agents.coordination.chain: A lead states its parent once, and the chain is read from what leads stated
spec:cc-agents.coordination.record: Messages between sessions this session saw are kept whole, with what is known of who sent them and what came of them
spec:cc-agents.coordination.session-scanning: A scan reads a project's sessions and traces each direction to its outcome
spec:cc-agents.coordination.view: The person sees the chain and the traffic without asking a model
spec:cc-agents.hq-links: The one tie between this repository's Specs and HQ's design
spec:cc-agents.coordination decidedBy spec:cc-agents.coordination.boundary-only · declared — settles when work needs a second session at all
spec:cc-agents.hq-links dependsOn spec:cc-agents.coordination · declared — the tie holds only while the coordination design states what it answers
spec:cc-agents.coordination.adoption refines spec:cc-agents.coordination · declared — how coordination is switched on alone and taken up by a project
spec:cc-agents.coordination.boundary-only refines spec:cc-agents.coordination · declared — settles what a chain still has to be when agents and Workflows carry most work
spec:cc-agents.coordination.chain refines spec:cc-agents.coordination · declared — the second thing the plugin adds to the host's messaging
spec:cc-agents.coordination.record refines spec:cc-agents.coordination · declared — the first thing the plugin adds to the host's messaging
spec:cc-agents.coordination.session-scanning refines spec:cc-agents.coordination · declared — reads what sessions leave behind, so that work is not lost between them
spec:cc-agents.coordination.view refines spec:cc-agents.coordination · declared — what the person sees of coordination

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:cc-agents.coordination

flowchart TB
  n0["Sessions that must message each other leave a record and a place in a chain · spec:cc-agents.coordination"]
  n1["Coordination switches on alone, and a project takes it up with one setting and its own boundaries · spec:cc-agents.coordination.adoption"]
  n2["A second session exists only across a boundary one session cannot cross · spec:cc-agents.coordination.boundary-only"]
  n3["A lead states its parent once, and the chain is read from what leads stated · spec:cc-agents.coordination.chain"]
  n4["Messages between sessions this session saw are kept whole, with what is known of who sent them and what came of them · spec:cc-agents.coordination.record"]
  n5["A scan reads a project's sessions and traces each direction to its outcome · spec:cc-agents.coordination.session-scanning"]
  n6["The person sees the chain and the traffic without asking a model · spec:cc-agents.coordination.view"]
  n7["The one tie between this repository's Specs and HQ's design · spec:cc-agents.hq-links"]
  n0 -->|"decidedBy · declared — settles when work needs a second session at all"| n2
  n1 -->|"refines · declared — how coordination is switched on alone and taken up by a project"| n0
  n2 -->|"refines · declared — settles what a chain still has to be when agents and Workflows carry most work"| n0
  n3 -->|"refines · declared — the second thing the plugin adds to the host's messaging"| n0
  n4 -->|"refines · declared — the first thing the plugin adds to the host's messaging"| n0
  n5 -->|"refines · declared — reads what sessions leave behind, so that work is not lost between them"| n0
  n6 -->|"refines · declared — what the person sees of coordination"| n0
  n7 -->|"dependsOn · declared — the tie holds only while the coordination design states what it answers"| n0

Rests on

decidedBy · spec:cc-agents.coordination.boundary-only · stated defined, floor ready

Rested on by

Distance 1

spec:cc-agents.coordination.adoption
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: pack:cc-agents-coordination
spec:cc-agents.coordination.boundary-only
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
spec:cc-agents.coordination.chain
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: pack:cc-agents-coordination
spec:cc-agents.coordination.record
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: pack:cc-agents-coordination
spec:cc-agents.coordination.session-scanning
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: pack:cc-agents-coordination
spec:cc-agents.coordination.view
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: pack:cc-agents-coordination
spec:cc-agents.hq-links
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Relations

Relation and direction	Other end	Claim	Reason	Exercised keys
decidedBy · outgoing	A second session exists only across a boundary one session cannot cross `spec:cc-agents.coordination.boundary-only` · resolves	declared	settles when work needs a second session at all	None
dependsOn · incoming	The one tie between this repository's Specs and HQ's design `spec:cc-agents.hq-links` · resolves	declared	the tie holds only while the coordination design states what it answers	None
refines · incoming	Coordination switches on alone, and a project takes it up with one setting and its own boundaries `spec:cc-agents.coordination.adoption` · resolves	declared	how coordination is switched on alone and taken up by a project	None
refines · incoming	A second session exists only across a boundary one session cannot cross `spec:cc-agents.coordination.boundary-only` · resolves	declared	settles what a chain still has to be when agents and Workflows carry most work	None
refines · incoming	A lead states its parent once, and the chain is read from what leads stated `spec:cc-agents.coordination.chain` · resolves	declared	the second thing the plugin adds to the host's messaging	None
refines · incoming	Messages between sessions this session saw are kept whole, with what is known of who sent them and what came of them `spec:cc-agents.coordination.record` · resolves	declared	the first thing the plugin adds to the host's messaging	None
refines · incoming	A scan reads a project's sessions and traces each direction to its outcome `spec:cc-agents.coordination.session-scanning` · resolves	declared	reads what sessions leave behind, so that work is not lost between them	None
refines · incoming	The person sees the chain and the traffic without asking a model `spec:cc-agents.coordination.view` · resolves	declared	what the person sees of coordination	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.