# 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`.