Signal/docs/workflow-consolidation-brief-2026-06-23.md

Pi Design Brief — Workflow Consolidation

Date: 2026-06-23 Designs: Pi (full design) · Builds: Claude Code · Approves: Kisa Goal: Stop spending build time on plumbing. Convert every recurring manual protocol that drifts into a skill or hook, so the workflow self-maintains and we get back to building Signal and Shield. Principle: Anywhere a protocol drifts, the fix is a skill or a hook, not a human reminder.

---

Findings (grounded — do not re-discover)

• Skills are already shared. Claude and Pi both read from ~/.claude/skills/SKILL_NAME/SKILL.md. Pi has no separate skills directory. Add a skill once → both tools have it. The only drift is a hand-maintained skill table inside ~/.pi/agent/AGENTS.md (a stale ~9-skill subset) and separate MCP configs (~/.pi/agent/mcp.json vs Claude's). graphify and use-railway are Claude-only.
• The wrap-up commit+push exists but is a fragile manual chain. It is Step 5 of navaigate-session-brain ("runs automatically every session"), but it only fires if a human triggers the wrap-up and the session does not crash first. Evidence: context/current-state.md was left uncommitted and a terminal-freeze-screenshot.png sits beside it — a session updated state (Step 3B) but died before pushing (Step 5). The skill also swallows push failures silently ("note and continue").
• State is triplicated and drifts. context/current-state.md (freshest, auto-written) vs the embedded "Current State" block in signal/CLAUDE.md (already disagreeing today) vs project_next_steps.md in Claude memory. The harness auto-injects whole CLAUDE.md files into context, so stale state in that block keeps loading even when nobody reads it on purpose.

Decisions already locked — do not re-litigate

• State source of truth = one git-versioned file per repo: context/current-state.md. signal origin = Forgejo (canonical), github = mirror.
• Both agents read from git: git pull --rebase then read the file. Write = write → commit → push. Matched pair; reading from git is only fresh if every wrap-up pushes.
• The embedded "Current State" block in CLAUDE.md is demoted to a one-line pointer (zero rolling fields). Required because the harness auto-injects CLAUDE.md.
• Skills stay in the shared ~/.claude/skills/ directory. No skill-sync system to build.
• Not an API, not TriLane-as-live-store. TriLane stays the searchable archive.
• Housekeeping done this session: context/*.png, context/*.jsonl, context/recovery-snapshot-*.md added to .gitignore; current-state.md committed clean.

---

What Pi designs (five workstreams)

1. The state contract

Format for current-state.md: fixed sections, a v:1 schema marker, an Updated: timestamp line, author tags ([Pi]/[CC]) on every Decisions-log line, and a hard size budget (whole file reads in well under ~2k tokens). Provide a fill-in template. Plus:

• De-duplication map — one home per info type. Starting boundary: volatile working state → current-state.md; stable project facts (what Signal is, PHI rules, run commands, checklists) → CLAUDE.md; Kisa/CC operating notes → Claude memory; history/insights → TriLane. Rule of thumb: changes every session → current-state.md; true for months → CLAUDE.md; "what happened" → TriLane.
• Read protocol (start): git pull --rebase, read the file, surface a staleness signal ("state is N days old" from the Updated: line). Kisa opens the same file; no separate human path.
• Write protocol (wrap): single mutable ACTIVE/NEXT head; append-only, author-stamped Decisions log; pull --rebase → write → commit → push; before writing, re-check the Updated: line and rebase-reconcile if it moved.
• Concurrency: on a rare ACTIVE/NEXT conflict, last writer hand-merges (never -X ours, never a lock file).
• Disagreement rule: while the old block still exists, current-state.md wins; demote it in the same change.

2. Reliable wrap-up commit + push (the real fix)

Make state-to-git automatic so a crash or a skipped wrap-up cannot lose state. Pi weighs and recommends:

• A Stop hook in settings.json (the harness runs it when a session ends, with no human trigger) that commits + pushes current-state.md — the strongest option because it fires regardless of whether anyone says "wrap up."
• and/or a lightweight launchd safety-net that commits + pushes any dirty current-state.md on a timer.
• Either way: make push failures visible (stop silently swallowing them) and keep the existing session-brain Step 5 as the rich path. Pi specifies the exact mechanism, where it lives, and how it behaves for both Claude and Pi.

3. Skills + MCP parity (Claude ↔ Pi)

Keep the shared ~/.claude/skills/ directory as the single skill library. Then:

• Eliminate or auto-generate the hand-maintained skill table in ~/.pi/agent/AGENTS.md so it cannot drift from the real directory (e.g., a one-line "read any skill from ~/.claude/skills/ by name" plus an optional generated index).
• Decide MCP parity: one source of truth for MCP servers, or a sync step, so adding a server to one tool reaches the other. Note graphify/use-railway stay Claude-only.

4. Drift-to-skill governance

A standing rule plus a short catalog: list the recurring manual protocols that currently rely on a human remembering (session start reads, wrap-up, git-push, content-calendar pull, KG queries, etc.) and say which should become a skill, a hook, or stay manual. Output is a small decision table Claude can build from.

5. Cleanup / smoother workflow

The broader housekeeping: collapse the triplicated state into the de-dup map above, retire stale rolling sections from the mission brief and CLAUDE.md, and define one coherent start/wrap protocol shared by both agents. Keep one current-state.md per repo, not a global file.

---

Constraints

• Lean and token-conscious above all — net startup reads go DOWN.
• Plain-text, human-readable. One file per repo. No PHI in state files.
• No new running services beyond (optionally) one Stop hook and/or one launchd safety-net.
• Schema versioning is a single v:1 marker — no migration tooling.

Deliverable

A short design doc (2–3 pages): the current-state.md schema + filled template; the read/write protocol steps ready to drop into the shared skill; the de-dup map; the recommended wrap-up automation mechanism (hook and/or launchd) with exact placement; the skills/MCP parity fix; the drift-to-skill decision table; and the exact startup edits for both CLAUDE.md and ~/.pi/agent/AGENTS.md.