4bfe5d25cf
Commit the previously-uncommitted current-state.md (left dirty by an interrupted wrap-up), gitignore the heavy context recovery files (screenshot/jsonl/snapshot), and add the consolidated Pi design brief for the shared-state + workflow cleanup. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
64 lines
6.5 KiB
Markdown
64 lines
6.5 KiB
Markdown
# 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`.
|