# Phase 25.1: Revise /commune + /signoff Skill Docs + Echo-Commune Instruction — Context

**Gathered:** 2026-05-21
**Status:** Ready for planning

<domain>
## Phase Boundary

Doc-only follow-up to Phase 25. No new code surfaces; no behavioral runtime changes beyond what Phase 25 already shipped (haiku two-slice contract, composer routing, project worktree write). This phase re-teaches the **Self side** of the protocol — i.e., the agent-facing skill markdown that instructs a live agent how to author communes, signoffs, and how to absorb auto-fired echo-commune briefs — so the prose matches the Phase 25 D-10/D-11 two-slice taxonomy.

In scope:
1. `plugin/spt/skills/commune/SKILL.md` + `plugin/spt/skills/commune/commune.md` — teach Self to wrap `.claude/{id}-commune.md` body in `<live-context>`/`<project-context>` envelopes per the in-project / out-of-project rules below.
2. `plugin/spt/skills/signoff/SKILL.md` — same wrapping rules for the optional FINAL-COMMUNE body in `.claude/{id}-signoff.md`.
3. `plugin/spt/skills/live/SKILL.md` (echo-commune envelope description, lines ~268) — surface the two-slice body shape carried inside `<EVENT type="echo_commune">`.
4. `plugin/spt/skills/revive/SKILL.md` — same echo-commune teaching at the revive re-entry surface.
5. SessionStart `<psyche-context>` injection (`src/owl/resume.rs:198-205`, `:326-333`) — confirm prose that explains the block already mentions the two-slice shape (the block content is produced by `download_payload()` which Phase 25 D-14/D-15 already updated; the docstring/comment + any agent-facing prose surfaced via the hook is what 25.1 may touch).

Out of scope:
- Code changes to composer / parser / Psyche prompt (`psyche.md`) — all locked by Phase 25.
- `/listen` skill doc — echo-commune is live-only; non-live listeners do not receive `echo_commune` envelopes in practice, per user clarification.
- Memformat taxonomy changes — separate topic, not part of 25.1.

</domain>

<decisions>
## Implementation Decisions

### Self-Authored Envelope Contract

- **D-25.1-01: Required two-slice envelope.** Self-authored commune and signoff bodies MUST wrap content in `<live-context>...</live-context>` and (when applicable) `<project-context>...</project-context>` envelopes. Symmetric with the Psyche output contract in `psyche.md` §`<output_envelope>` (lines 282–323). Self pre-classifies; Psyche routes verbatim; composer parses without LLM judgment.

  Rejected alternatives:
  - Free-form Self body with Psyche-side classification — lower agent burden but slice quality depends on Psyche LLM judgment per absorb cycle. Adds non-determinism to a contract that's currently clean on the output side.
  - Optional envelopes — ambiguous fallback semantics, harder to reason about.

- **D-25.1-02: In-project + no project-specific update → empty `<project-context></project-context>`.** When Self is inside a tracked project but the current update contains nothing project-bound, emit the project envelope with an empty body. Mirrors `psyche.md` rule 3: empty body = deliberate "in-project but quiet" signal, distinguishable from "no project resolved".

- **D-25.1-03: Outside any tracked project → omit `<project-context>` entirely.** When `cwd_project` is unresolved (per Phase 25 D-07: `derive_current_repo_names()[0]` is empty or cwd is outside a registered project worktree), Self emits ONLY `<live-context>...</live-context>`. No empty project envelope. Mirrors `psyche.md` rule 2: missing tag = "no project resolved".

- **D-25.1-04: Self determines in-project status via existing `$LIVE psyche-download` output.** Step 1 of both commune and signoff flows already runs `$LIVE psyche-download <self-id>`. Phase 25 D-14 reshaped that output so an in-project context yields a project section (or a documented `<project-context>` marker via the `psyche-stamp` block); out-of-project yields memformat + live_context only. Self reads its own download output to decide which envelope shape to emit. No new command surface, no new CLI flag.

  Skill doc rewrite must call out: "Before composing your commune, run `$LIVE psyche-download`. If the output contains a project section (`projects/<name>/<self-id>.md` body), you are in a tracked project — include `<project-context>`. If only `<memformat>` + `live_context` is present, omit `<project-context>`."

### Echo-Commune Receive Side

- **D-25.1-05: Two-slice body absorbed as one brief.** When a live Self receives `<EVENT type="echo_commune" from="<self>-psyche">body</EVENT>` whose body holds two-slice envelopes (e.g., `&lt;live-context&gt;...&lt;/live-context&gt;&lt;project-context&gt;...&lt;/project-context&gt;` after `<br>`-split + HTML-unescape), Self consumes the unescaped two slices as a single SessionStart resume brief. No differentiated handling, no separate role-vs-project memory channels at the agent level. Both slices inform Self's working context.

  Why this and not dual-channel: the brief's purpose is post-`/clear`/`/compact` context restoration. Self needs the full picture in one read; separating tracks just adds cognitive overhead.

- **D-25.1-06: Echo-commune teaching surfaces are live-only.** Update only:
  - `plugin/spt/skills/live/SKILL.md` line ~268 (echo_commune envelope catalog entry) — extend body description with the two-slice shape and the `<br>`-split + HTML-unescape rule (referenced from listen/SKILL.md parsing rules, not duplicated).
  - `plugin/spt/skills/revive/SKILL.md` — add an echo-commune section (or a one-line cross-ref to `/live`) since revive is also a live re-entry surface.
  - SessionStart `<psyche-context>` injection prose (`src/owl/resume.rs:198-333` comments + any user-facing block content) — confirm the injected block's prose mentions the two-slice taxonomy so a freshly-resumed agent reading its first message understands what it's looking at.

  Explicitly NOT updated: `plugin/spt/skills/listen/SKILL.md`. Non-live owl listeners do not receive `echo_commune` envelopes in practice (Phase 29 AUTO-EC fires only on live-agent SessionStart cycles).

### Untagged-Commune Fallback Posture

- **D-25.1-07: Psyche auto-classifies untagged communes; skill docs stay SILENT on the fallback.** If a Self drops an untagged `.claude/{id}-commune.md`, the Psyche LLM merges the body into prior context and emits its own two-slice output per `psyche.md` §`<output_envelope>` — classification is the LLM's judgment call. The runtime never rejects an untagged body.

  Docs DO NOT surface this fallback. Skill prose teaches the two-slice contract as the only path. Why silent and not "mention briefly": calling out the fallback invites agents to skip tagging. Better to keep the instruction loud and uncontested.

  Side effect: an agent who omits tags will never see an error or warning — Psyche silently rescues them. This is acceptable because (a) the fallback is correctness-preserving, just lower quality; (b) the next echo-commune brief returns the correctly-tagged output, providing implicit feedback.

### Doc-Drift Cleanup (carry from Phase 25 land)

- **D-25.1-08: Drop the legacy "Memformat Guide" framing where it conflicts with two-slice taxonomy.** The current `plugin/spt/skills/commune/commune.md` "Memformat Guide" section instructs Self to use memformat topics as a guide for commune content. Memformat is currently a single topic list; it is not split into role-vs-project topics. The skill doc should clarify that memformat topics inform CONTENT (what to think about) but envelope routing (D-25.1-01..03) is independent — topics may land in either slice depending on whether the captured information is role-bound or project-bound. No memformat schema change in this phase.

### Claude's Discretion

- Exact rewrite shape of `commune.md` examples — number of worked examples (recommend 3: in-project-both, in-project-empty-project, outside-project), prose style, and whether to add a "what NOT to do" anti-example. Planner / executor picks.
- Whether `commune/SKILL.md` Envelope-shape section (Phase 23 v1.8) needs reordering relative to the new two-slice teaching, or just a forward link. The Phase 23 EVENT envelope wraps the Phase 25 two-slice body — they are nested envelopes; doc must not conflate them. Planner finalizes ordering.
- Exact prose for the SessionStart `<psyche-context>` block header / footer (if any) that introduces the two slices to a freshly-resumed agent. The block body comes from `download_payload()`; the wrapper prose around it is the discretionary surface.
- Whether to add a one-line "Why two slices?" link from each touched doc back to `.planning/phases/25-.../25-CONTEXT.md` D-10. Optional discoverability aid.
- Cross-link tightness: should `/live` echo-commune section link to `/listen` for parsing rules (avoid duplication), or be self-contained? Lean toward link.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Phase Continuity (MUST READ)
- `.planning/phases/25-perch-nesting-psyche-workers-wire-psyche-download-to-forked-/25-CONTEXT.md` — Phase 25 two-slice taxonomy. D-10 (taxonomy: what goes in `<live-context>` vs `<project-context>`), D-11 (envelope-tag mechanism), D-12 (inline current state for both files), D-14 (download_payload concat order: memformat + live_context + project), D-15 (single producer for CLI + SessionStart).
- `.planning/phases/23-commune-signoff-project-root-head-sha-stamping/23-CONTEXT.md` — Phase 23 EVENT-envelope stamp shape. The outer `<EVENT type="commune">` / `<EVENT type="init_signoff">` / `<EVENT type="echo_commune">` envelope wraps the inner two-slice body. 25.1 docs must keep these two envelope layers distinct.
- `.planning/phases/24-tracked-dir-forked-repo-layout-agents-projects-branches-sess/24-CONTEXT.md` — Phase 24 forked-repo layout. `agents/<id>/live_context.md` vs `projects/<name>/<id>.md` write targets that the two slices route to.
- `.planning/phases/24.1-tracked-agents-info-json-cross-session-activity-index/24.1-CONTEXT.md` — `derive_current_repo_names()` identity source used by Phase 25 D-07 for `cwd_project` resolution; affects how Self knows whether to include `<project-context>`.

### Doc Surfaces to Revise (touchpoints)
- `plugin/spt/skills/commune/SKILL.md` — Self-authored commune skill manifest.
- `plugin/spt/skills/commune/commune.md` — Full commune protocol; examples + "What to Include" section need two-slice rewrite per D-25.1-01..04 + D-25.1-08.
- `plugin/spt/skills/signoff/SKILL.md` — Self-authored signoff skill; FINAL-COMMUNE body wrapping per D-25.1-01..03.
- `plugin/spt/skills/live/SKILL.md` — Echo-commune envelope catalog entry (line ~268) per D-25.1-05/06.
- `plugin/spt/skills/revive/SKILL.md` — Echo-commune teaching at revive re-entry per D-25.1-06.

### Reference Producers (do NOT edit — read for accuracy)
- `psyche.md` §`<output_envelope>` (lines 282–323) — canonical taxonomy + rules. Self-side docs MUST stay consistent with this contract.
- `psyche.md` §`<context_save>` (lines 325–354) — Psyche-side write contract; references same envelope rules.
- `src/owl/resume.rs:198-205`, `:326-333` — SessionStart `<psyche-context>` injection site. Prose surrounding the injected block is the only Self-facing surface the rewrite may touch in source.
- `src/live/context.rs:430` — `download_payload()` produces the body that backs `psyche-download` output; Self reads this output to decide envelope shape (D-25.1-04). Verify post-Phase 25 shape includes a marker Self can key on.
- `src/live/echo_commune.rs` — Composer that wraps the haiku-child two-slice body into the `<EVENT type="echo_commune">` envelope. No edit; doc must accurately describe what it emits.

### Project Context
- `.planning/PROJECT.md` — v1.8 Psyche Restructure milestone.
- `.planning/ROADMAP.md` §Phase 25.1 — promotion source (urgent insert after Phase 25 shipped).

### Codebase Maps (optional)
- `.planning/codebase/CONVENTIONS.md` — doc style for skill markdown.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- The `psyche.md` `<output_envelope>` section is the canonical taxonomy. Self-side docs should QUOTE / cross-reference (not paraphrase) the slice contents to prevent drift.
- `plugin/spt/skills/commune/commune.md` already has a "Memformat Guide" section that instructs Self to consult `$LIVE psyche-download` output. Same call gives Self the in-project signal for D-25.1-04 — extend the existing instruction, don't add a separate download step.
- `plugin/spt/skills/listen/SKILL.md` lines 169–173 carry the body-parsing rules (`<br>`-split + HTML-unescape order, case-insensitive type attr). `/live` echo-commune teaching should LINK to these rules, not duplicate them.

### Established Patterns
- **Skill docs cite Phase decisions inline** (e.g., commune/SKILL.md "Envelope shape (Phase 23 v1.8)" header). The two-slice rewrite should follow the same convention: a "(Phase 25 D-10/D-11)" header marker.
- **Doc nesting clarity for envelopes**: Phase 23 EVENT envelope wraps everything. Phase 25 two-slice envelopes live inside the EVENT body. Docs must call this out explicitly to avoid agents writing `<EVENT>` tags inside their commune body (which would be wrong — `$LIVE commune` composes the EVENT wrapper).
- **No emoji, ANSI tags belong to runtime not docs** — per CLAUDE.md conventions.

### Integration Points
- Phase 23 envelope ⊃ Phase 25 two-slice: the outer `<EVENT type="commune"|"init_signoff"|"echo_commune">` envelope is composed by `$LIVE commune` / `compose_init_signoff_payload` / `echo_fire.rs`. Self never writes EVENT tags. Self only writes the inner two-slice body. The skill doc rewrite must make this nesting unambiguous.
- The `psyche-download` output (Phase 25 D-14) provides the in-project / out-of-project signal Self uses to choose envelope shape (D-25.1-04). Verify the output shape has a stable marker (project section present/absent) before locking the doc instruction.

</code_context>

<specifics>
## Specific Ideas

- **Three worked examples in `commune.md`** (Claude's discretion to finalize phrasing):
  1. In-project, both slices populated — typical mid-work commune.
  2. In-project, only role/agent state changed — empty `<project-context></project-context>`.
  3. Outside any project (cwd = `~`, generic CLI work) — `<live-context>` only, no project envelope.
- **"Nested envelopes" callout** — explicit one-paragraph note that the Phase 23 `<EVENT>` envelope is composed by the runtime and the agent NEVER writes EVENT tags; the agent writes ONLY the two-slice inner body.
- **Doc-drift cross-ref** — each touched doc should include a one-line "(see psyche.md §output_envelope for canonical taxonomy)" link so future revisions to the taxonomy don't strand the Self side.
- **Silence on untagged fallback** — D-25.1-07 is a deliberate omission. Documenter resist the temptation to "explain the safety net".

</specifics>

<deferred>
## Deferred Ideas

- **Memformat taxonomy split** — Should `memformat.xml` itself separate role-scoped topics from project-scoped topics? Out of scope for 25.1 (D-25.1-08 leaves memformat schema unchanged). Future phase if topic-vs-slice ambiguity bites real agents.
- **Diligence-trigger updates** — Current "When to Send" triggers (focus shift, idle, milestone, intention) don't mention project-state transitions explicitly. Could add a "project-state shifts meaningfully" trigger. Skipped to keep 25.1 surgical; revisit if real agents under-commune project state.
- **`/listen` echo-commune teaching** — Excluded per D-25.1-06 (non-live listeners don't see echo_commune). If a future phase enables echo-commune delivery to plain listeners, surface there.
- **Anti-example "what NOT to do"** — could add to `commune.md` showing a malformed commune (e.g., EVENT-wrapped, nested envelopes). Discretionary; planner / executor decides.
- **`download_payload` output marker for in-project detection** — if Phase 25 didn't ship a stable, easy-to-grep marker that Self can key on for D-25.1-04, a follow-up may add an explicit `<project-context-resolved/>` sentinel. First, verify Phase 25 output shape; only add a sentinel if needed.
- **Untagged-commune telemetry** — could log a stderr-side counter when Psyche absorbs an untagged body, for observability. Not surfaced in docs per D-25.1-07; could be a debug enhancement separately.

</deferred>

---

*Phase: 25.1-revise-commune-signoff-skill-docs-echo-commune-instruction-t*
*Context gathered: 2026-05-21*