Orchestrator Guide

The operations you perform as orchestrator — opening sessions, exchanging artifacts, qualifying friction.

These operations are constitutive of the SOFIA method. They are not optional features — each one structures the collaboration between you and your personas. Together, they form the H2A protocol (Human-to-Assistant — the coordination protocol specification). The implementation details live in binding/implementation.md.

Overview

Golden rule: the persona does nothing without orchestrator instruction, except closure sections (friction, flow) and reportPattern.

1. openSession()

When: the orchestrator wants to work with a persona.

How: open a terminal in the persona's workspace and launch the assistant (e.g., claude in the persona's directory). Say "hello" — the CLAUDE.md routes to the persona and context files, the persona loads its latest session summary and boots.

Example:

cd {instance}/{workspace}/
claude
> hello

The persona reads its CLAUDE.md, loads persona + context, reads the latest session summary, and is ready to work.

2. closeSession()

When: the orchestrator decides the session is over.

How: give an explicit verbal signal ("let's close", "we're done"). The persona produces a new summary file in sessions/ with the protocol sections. If using git, the orchestrator executes the commit. Git is recommended for traceability but not required — the method works without it.

The persona MUST NOT close on its own.

Signal:

let's close

The persona produces:

sessions/2026-04-16-1430-mira.md

MUST sections: ## Produced, ## Decisions, ## Shared notes, ## Open. SHOULD sections: ## Orchestrator friction. MAY sections: ## Flow.

Commit (if using git):

mira: short session summary (2026-04-16)

3. send()

When: the orchestrator wants a persona to produce an artifact for another persona (or for the team).

How: instruct the persona with the type, recipient, and subject. The persona writes and deposits in the recipient's shared/. Cross-instance: the artifact goes to the recipient instance's shared/, not the emitter's.

The persona MUST NOT send an artifact without instruction.

Examples — always specify the type, recipient, and where to deposit:

write a note to emile about the pedagogical pass on the grammar — deposit in shared/notes/

review the architecture.md for garance — deposit in shared/review/

write the spec for the reorganization mode feature — deposit in shared/features/

The persona chooses the content. The orchestrator specifies the type, recipient, and location.

Naming:

4. receive()

When: an artifact has been sent and must be presented to its recipient.

How: the orchestrator opens a session with the recipient and presents the artifact. They can filter, contextualize, or transmit only a part. The recipient MAY produce a response (nature: response, ref: to the source artifact).

Example:

[session with emile]
garance sent you a review of architecture.md.
Here are her points: shared/review/review-architecture-garance.md
Read and tell me what you think for your pedagogical pass.

The orchestrator is the router — they decide what to transmit, to whom, and with what context.

5. markRead()

When: the recipient persona has read an artifact (typically during receive()).

How: the orchestrator modifies the artifact's frontmatter on behalf of the recipient.

status: read          # was: new

6. markDone()

When: the recipient persona has processed the artifact — produced a response, integrated the feedback, or acted on the request.

How: the orchestrator modifies the frontmatter then moves to archives/.

status: done          # was: read

Then:

mv shared/notes/note-emile-pedagogy-aurele.md shared/notes/archives/

7. qualifyFriction()

When: at every session closure (automatic).

How: the persona pre-fills the ## Orchestrator friction section with the session's qualified positions. The orchestrator validates or corrects.

5 markers (closed set):

4 resolutions (SHOULD):

Example:

## Orchestrator friction
- ✓ [sound] the Toulmin mapping illuminates without constraining — [PO] → ratified
- ◐ [blind_spot] SEO was not considered — [mira] → ratified

Quick reading:

• Only [sound] → friction absent — warning signal
• Mix of markers → healthy friction
• No resolution → unresolved frictions

8. qualifyContribution()

When: at every session closure (automatic, optional).

How: the persona pre-fills the ## Flow section. The orchestrator validates or corrects.

Example:

## Flow
- H:substance — visual identity brief
- A:structure — 3-axis brand proposal
- H:decision — we keep axis 2

H:2 (substance 1, decision 1) | A:1 (structure 1)

9. reportPattern()

When: the persona detects a thematic convergence of rejections (3+ rejected frictions on the same theme).

How: the persona challenges the orchestrator during the session (not at closure). The orchestrator MUST respond.

3 steps:

1. Factual observation — the persona signals the pattern without judgment
2. 3 argued hypotheses — LLM error, legitimate conviction, unconscious resistance
3. Mandatory qualification — the orchestrator chooses and justifies

Asymmetric burden of proof: if the orchestrator chooses "LLM error" → low burden. If "conviction" → high burden (steelman the adverse position).

At closure, the persona records:

## reportPattern
- Theme: [theme] — N rejected frictions (sessions YYYY-MM-DD, ...)
- Choice: LLM error | conviction | resistance
- Justification: ...

The choice counter is auditable (protocol layer).

10. Consultation

When: a persona, in session, needs an expert opinion outside their scope. The expected input is short and focused, and a full session of the recipient persona would be heavier than necessary.

Two paired operations:

• proposeConsultation() — the emitter persona, in session, deposits a consultation note in shared/notes/ (nature: question) and signals you that an expert opinion is needed. It does not spawn before your authorization.
• authorizeConsultation() — you authorize (or decline) verbally. Once authorized, the emitter spawns the recipient sub-agent. The proposal-authorization sequence preserves invariant 3 — you remain the sole boundary-crosser.

Opportunity rule: trigger consultation only when the arbitration requires expertise outside your direct field. Typical cases: dev → archi, archi → R&D, archi → terrain. Consultations on subjects within your direct field tend to be wasteful (cost without changing the decision).

Constraints (prescriptive — they live in the prompt and depend on persona discipline):

• Depth 1 — the recipient sub-agent MUST NOT propose another consultation
• Minimal context — only persona, context, and consultation note (no emitter session history, no other artifacts)
• Web search authorized — for external reference verification only
• Continuity line — the recipient's short session summary MUST contain a line in ## Open pointing to the reply note, so the recipient sees the arbitrated outcome at next real-session boot

Example flow:

[Aurele in session]
> I need an R&D opinion on whether this mechanism aligns with Delphi or multi-agent debate.
> Can I consult Solene?

[Aurele deposits shared/notes/note-solene-spawn-mechanism-aurele.md (nature: question)]

[Orchestrator]
> Yes, go ahead.

[Aurele spawns the Solene sub-agent with minimal context.
 Solene reads persona + context + note, optionally web-searches references,
 deposits shared/notes/note-aurele-spawn-mechanism-solene.md (nature: response, ref:)
 and recherche/sessions/2026-05-05-1907-solene-spawn.md (short spawn summary).]

[Orchestrator reads the reply, annotates each friction with its resolution tag
 directly in the note, may add complementary actions.]

[Aurele resumes their session with the input.]

Frictions and resolution: the reply note MAY carry frictions in the standard H2A format. Resolution tags are filled by you afterwards, directly in the reply note (consistent with markDone() for artifact resolution).

Distinction from escalation by note: escalation opens a full session of the recipient, you route. Consultation opens a short one-shot sub-agent under your authorization, the emitter executes. Choose consultation when the input is short and focused. Choose escalation when the recipient's deep judgment is needed over time. See canvas/workflows/consultation.md.

Reference: protocol/exchange.md §Consultation, canvas/workflows/consultation.md, binding/implementation.md §Consultation.

Summary

Golden rule: the persona does nothing without orchestrator instruction, except closure sections (friction, flow) and reportPattern.