|
| 1 | +# Specsmith Session Governance Skill |
| 2 | + |
| 3 | +This skill describes the **mandatory session protocol** for any agent working |
| 4 | +in a specsmith-governed project. It prevents silent drift and keeps governance |
| 5 | +state alive across context summarization without modifying the agent runtime. |
| 6 | + |
| 7 | +## Why agents drift |
| 8 | +When a conversation gets long, any chat application (Warp, Cursor, Claude, |
| 9 | +GPT) summarizes the history. That summary discards: the current work item ID, |
| 10 | +the last preflight decision, the project phase, and any uncommitted changes. |
| 11 | +The agent then operates on stale or invented governance state. |
| 12 | + |
| 13 | +## The fix: three rules |
| 14 | + |
| 15 | +### Rule 1 — Initialization (every session start) |
| 16 | +```bash |
| 17 | +specsmith kill-session 2>/dev/null || true # kill orphaned processes |
| 18 | +specsmith audit --project-dir . # verify governance health |
| 19 | +specsmith sync --project-dir . # confirm machine state |
| 20 | +specsmith checkpoint --project-dir . # emit and display the anchor |
| 21 | +``` |
| 22 | +Output the checkpoint verbatim as your first response. This establishes the |
| 23 | +governance baseline that all subsequent work traces back to. |
| 24 | + |
| 25 | +### Rule 2 — Preflight gate (before EVERY proposed code change) |
| 26 | +```bash |
| 27 | +specsmith preflight "<describe the change you intend to make>" --json |
| 28 | +``` |
| 29 | +- If `decision == "accepted"`: proceed with the work item ID in scope. |
| 30 | +- If `decision == "needs_clarification"`: surface the instruction to the user |
| 31 | + before making any changes. |
| 32 | +- Never make a code change without an accepted preflight. |
| 33 | + |
| 34 | +### Rule 3 — Heartbeat (every 8-10 turns, or when context > 60%) |
| 35 | +```bash |
| 36 | +specsmith checkpoint --project-dir . |
| 37 | +``` |
| 38 | +Output the GOVERNANCE ANCHOR block verbatim in your response. Tag it clearly: |
| 39 | + |
| 40 | +``` |
| 41 | +⎠ GOVERNANCE ANCHOR (output of `specsmith checkpoint`): |
| 42 | +╔═════... |
| 43 | +║ GOVERNANCE ANCHOR 2026-05-19T22:43:04Z |
| 44 | +║ Project : specsmith |
| 45 | +... |
| 46 | +╚═════... |
| 47 | +``` |
| 48 | + |
| 49 | +**When producing any context summary, ALWAYS include the most recent |
| 50 | +GOVERNANCE ANCHOR verbatim at the top of the summary.** The anchor is the |
| 51 | +minimum viable governance state that must survive summarization. |
| 52 | + |
| 53 | +## End of session |
| 54 | +```bash |
| 55 | +specsmith save --project-dir . # ESDB backup + commit + push |
| 56 | +specsmith kill-session # clean up processes |
| 57 | +``` |
| 58 | +Never end a session with uncommitted governance changes. |
| 59 | + |
| 60 | +## Detecting drift (self-check) |
| 61 | +If you notice you cannot answer any of these from memory, you have drifted |
| 62 | +and MUST re-anchor immediately: |
| 63 | +- What is the current AEE phase? |
| 64 | +- What work item is active? |
| 65 | +- What was the last preflight decision? |
| 66 | +- Is the audit currently healthy? |
| 67 | + |
| 68 | +Run `specsmith checkpoint` and copy the output into your response. |
| 69 | + |
| 70 | +## Quick reference |
| 71 | +| When | Command | |
| 72 | +|---|---| |
| 73 | +| Session start | `specsmith audit && specsmith sync && specsmith checkpoint` | |
| 74 | +| Before any code change | `specsmith preflight "<intent>" --json` | |
| 75 | +| Every 8-10 turns | `specsmith checkpoint` (output verbatim) | |
| 76 | +| Context summary | Include checkpoint output at top | |
| 77 | +| Session end | `specsmith save && specsmith kill-session` | |
| 78 | +| Drift detected | `specsmith checkpoint` immediately | |
0 commit comments