Skip to content

Commit af07e92

Browse files
committed
docs(C5): extract session-protocol template (SPEC §5 C5)
Two near-identical 60-line blocks of session protocol + audit checklist were duplicated between ai-config-kit/docs/SPEC.md and get-installer/docs/SPEC.md. C5 said to factor that out for the third project that adopts the pattern. docs/session-protocol.template.md is the canonical source. It's self-describing: the consumer list lives at the top, and when the protocol changes the workflow is "update template -> propagate to consumer SPECs". Eventually this could live in simtabi/.github as an org-default; staying in ai-config-kit for now since the ecosystem is small (2 consumers). Both consumer SPEC.md files already reference each other in the "identical to" preamble; this template gives that cross-reference a single source of truth.
1 parent 9976632 commit af07e92

1 file changed

Lines changed: 103 additions & 0 deletions

File tree

docs/session-protocol.template.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Session protocol + audit checklist — shared template
2+
3+
This file is the canonical source for the "🔁 Session protocol" +
4+
"🔍 Audit checklist" sections that appear at the top of every
5+
Simtabi project's `docs/SPEC.md`. SPEC §5 issue C5 said to factor
6+
out this duplication; the template lives here in `ai-config-kit`
7+
(the project where the pattern originated) and the other repos
8+
reference it.
9+
10+
When a third Simtabi project adopts this pattern, copy the two
11+
sections below into its SPEC.md unchanged (the project name is
12+
the only variable). When the protocol changes, update this file
13+
first, then propagate to consumer SPECs:
14+
15+
- `simtabi/ai-config-kit/docs/SPEC.md`
16+
- `simtabi/get-installer/docs/SPEC.md`
17+
- _add new consumers here as they appear_
18+
19+
A future cleanup could move this to `simtabi/.github/` as an
20+
org-default; for now keeping it in this repo is fine since the
21+
ecosystem is small.
22+
23+
---
24+
25+
## 🔁 Session protocol (read before everything else)
26+
27+
**Session start**:
28+
29+
1. Read this SPEC end-to-end.
30+
2. Run the audit checklist below (5-line summary at the top of your reply).
31+
3. Read `STATUS.md` if present + `~/.claude/projects/<slug>/memory/MEMORY.md`
32+
+ the latest `CHANGELOG.md` entry.
33+
4. Restate the user's goal in one sentence before any tool call.
34+
35+
**During the work**:
36+
37+
5. **Hallucination guard**: every claim about the codebase comes
38+
from a live `Read` / `Grep` / shell call. Memory tells you what was
39+
true when written, not what's true now. Cite `path:line` where
40+
possible. Phrases that signal you're guessing: "typically",
41+
"usually", "I believe", "around line ~", round numbers, paraphrases
42+
of code you haven't opened.
43+
44+
6. **Track progress**: `TaskCreate` / `TaskUpdate` for anything
45+
beyond 3 steps. Mark `in_progress` before you start; `completed`
46+
the moment it's done, not in a batch.
47+
48+
7. **Watch for regressions**: re-run the audit checklist after every
49+
non-trivial edit; don't accumulate a "tests-at-the-end" debt.
50+
51+
8. **Log failures**: when a step fails, surface it in your reply
52+
immediately: what failed, what you tried, what you'll try next.
53+
54+
9. **Research before guessing**: `WebFetch` the official docs site
55+
first, project README + spec second, reputable blogs third. Skip:
56+
Medium content farms, AI-generated blog spam, paywalled pages.
57+
58+
10. **Clarifying questions**: when the request is ambiguous and the
59+
wrong path costs > 5 minutes to undo, ask once with a numbered
60+
options list. Not Socratic chains.
61+
62+
**Session end**:
63+
64+
11. **Self-improvement loop**: suggest SPEC updates (new findings →
65+
§5; finished phases → `[x]`), prompt updates (this section), test
66+
gaps you noticed.
67+
68+
12. **Hand-off summary**: last paragraph: what changed (paths), what's
69+
still open (issue ids), what the next agent picks up first.
70+
71+
---
72+
73+
## 🔍 Audit checklist: run this FIRST every session
74+
75+
Before writing code, run a status sweep and report the findings inline.
76+
77+
1. **`pytest -q`**: must be green.
78+
2. **`ruff check src tests`**: must be clean.
79+
3. **`mypy --strict <src-package>`**: must be clean.
80+
4. **CLI surface check**: `python -m <package> --help` should list
81+
every subcommand documented in `docs/tools/<package>.md`.
82+
5. **README authority check**: exactly ONE `README.md` at the repo
83+
root + project name + `pip install` line accurate to pyproject.toml.
84+
6. **CHANGELOG check**: `[Unreleased]` section exists; the most
85+
recent dated entry matches the latest tag.
86+
7. **External-URL drift check**: any URL pinned anywhere in the repo
87+
(badges, schema $ref, doc links) responds 200/3xx. If you can't
88+
reach the network, say so.
89+
90+
The 5-line summary at the top of every reply has the form:
91+
92+
```
93+
audit: tests=PASS lint=PASS types=PASS docs=PASS urls=N/A
94+
queue: <one-line description of what I'm about to do>
95+
```
96+
97+
Anything that fails → fix BEFORE the user-facing work, OR flag
98+
explicitly with "blocked on X" and propose a path forward.
99+
100+
---
101+
102+
_The two sections above are kept in lock-step across every
103+
consuming SPEC.md. Source of truth: this file._

0 commit comments

Comments
 (0)