@vaubaan/harness 1.4.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +301 -167
- package/dist/cli/index.js +886 -1882
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/handbook.cmd.md +4 -3
- package/dist/commands/test-plan.cmd.md +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +277 -1064
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +8 -23
- package/dist/init.js +270 -1036
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +687 -31
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +1 -26
- package/dist/parser/index.js +1 -17
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-Cu2XrkkY.d.ts → render-C-FWmUfX.d.ts} +8 -15
- package/dist/render.d.ts +1 -1
- package/dist/render.js +18 -280
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +93 -131
- package/dist/skills/doc-audit.skill.md +10 -10
- package/dist/skills/drift-detector.skill.md +6 -7
- package/dist/skills/handbook-writer.skill.md +68 -159
- package/dist/skills/readme-writer.skill.md +3 -3
- package/dist/skills/spec-writer.skill.md +111 -71
- package/dist/skills/test-plan-writer.skill.md +47 -54
- package/dist/skills/workflow-writer.skill.md +40 -6
- package/dist/templates/code-quality.md.tmpl +2 -2
- package/dist/templates/coding-workflow.md.tmpl +10 -0
- package/dist/templates/decision.md.tmpl +20 -47
- package/dist/templates/e2e-tests.md.tmpl +16 -45
- package/dist/templates/handbook.md.tmpl +20 -38
- package/dist/templates/integration-tests.md.tmpl +16 -34
- package/package.json +1 -1
- package/dist/agents/coding.agent.md +0 -182
- package/dist/agents/merge.agent.md +0 -139
- package/dist/agents/planning.agent.md +0 -194
- package/dist/agents/review.agent.md +0 -176
- package/dist/commands/clean-code.cmd.md +0 -26
- package/dist/skills/clean-code-guardian.skill.md +0 -391
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
id: decision-record-writer
|
|
3
3
|
description: |
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
Consequences, Rejected alternatives.
|
|
4
|
+
Writes an ADR under `docs/decisions/<slug>.md`, only for a structural
|
|
5
|
+
decision that passes the admission test below. Everything else goes to
|
|
6
|
+
the spec, the handbook, the test plans or the workflow. ADRs are short:
|
|
7
|
+
one decision, four sections, about 40 lines.
|
|
9
8
|
engines: [claude-code, codex-cli, opencode]
|
|
10
9
|
requires: [multi-step]
|
|
11
10
|
tags: [decisions, doc, writer, adr]
|
|
@@ -13,154 +12,117 @@ tags: [decisions, doc, writer, adr]
|
|
|
13
12
|
|
|
14
13
|
# Decision Record Writer
|
|
15
14
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
##
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
line for the new ADR.
|
|
72
|
-
|
|
73
|
-
## Criteria
|
|
74
|
-
|
|
75
|
-
- **4 mandatory required sections**: `## Context`, `## Decision`,
|
|
76
|
-
`## Consequences`, `## Rejected alternatives` (the French headings
|
|
77
|
-
`## Contexte` / `## Décision` / `## Conséquences` / `## Alternatives
|
|
78
|
-
rejetées` are also accepted for backward compatibility). Without
|
|
79
|
-
Rejected alternatives, the `lint:decision-schema` linter breaks CI.
|
|
80
|
-
- **Concise but complete**. An ADR is typically 50-150 lines. Not an
|
|
81
|
-
essay, not a sticky note.
|
|
82
|
-
- **Dated**. The date in the frontmatter is the date the decision was
|
|
83
|
-
*made*, not the date the ADR was written (often retrospective).
|
|
84
|
-
- **Immutable**. An accepted ADR is no longer modified — if the
|
|
85
|
-
decision changes, create a new ADR that *supersedes* the old one. No
|
|
86
|
-
rewrite.
|
|
87
|
-
|
|
88
|
-
## Expected output
|
|
89
|
-
|
|
90
|
-
A `docs/decisions/<slug>.md` file:
|
|
15
|
+
The decision log holds **only the structural decisions in force**: the few
|
|
16
|
+
choices a newcomer must know so they don't undo them, and that would cost a
|
|
17
|
+
lot to reverse. It is not a journal of the project, nor a place to justify
|
|
18
|
+
every choice. Most choices do not get an ADR.
|
|
19
|
+
|
|
20
|
+
## Admission test
|
|
21
|
+
|
|
22
|
+
Write an ADR only if **all three** answers are yes. Otherwise, do not write
|
|
23
|
+
it: say which test fails and where the content goes instead.
|
|
24
|
+
|
|
25
|
+
1. **Costly to reverse.** Changing it later takes more than one ordinary PR:
|
|
26
|
+
it touches the code structure, the data model, a module boundary, the
|
|
27
|
+
security model, or a vendor/platform the code depends on.
|
|
28
|
+
2. **A real alternative was weighed.** Someone could reasonably propose the
|
|
29
|
+
other option again; the ADR exists to stop that debate from restarting.
|
|
30
|
+
No rejected alternative worth one sentence → no ADR.
|
|
31
|
+
3. **It outlives the ticket.** It constrains future work across the
|
|
32
|
+
codebase, not just the feature that triggered it.
|
|
33
|
+
|
|
34
|
+
## Not an ADR — where it goes
|
|
35
|
+
|
|
36
|
+
| Content | Goes to |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| Product rule (who can sign in, which channels, what is out of scope) | `docs/spec/` |
|
|
39
|
+
| Implementation detail: config values, file layout, env variables | the code (traps and settings outside the repo: `docs/handbook/`) |
|
|
40
|
+
| Test strategy and tooling (runner, target env, what is E2E) | `docs/tests/` |
|
|
41
|
+
| CI, branches, deploy, harness and tooling upgrades | `docs/workflow/` |
|
|
42
|
+
| Review rules and conventions | `docs/quality/code-quality.md` |
|
|
43
|
+
| Temporary choice with a planned end (stub, demo data until ticket X) | the ticket, plus a line in the handbook |
|
|
44
|
+
| Library choice that a single PR can swap | the PR description |
|
|
45
|
+
| Dependency upgrade | the commit message |
|
|
46
|
+
|
|
47
|
+
A one-sentence *why* may sit in the handbook or test plan next to the fact
|
|
48
|
+
it explains. Do not create an ADR just to hold it.
|
|
49
|
+
|
|
50
|
+
## Format
|
|
51
|
+
|
|
52
|
+
Hard limits — an ADR that exceeds them is rewritten, not accepted:
|
|
53
|
+
|
|
54
|
+
- **One decision per ADR.** If the Decision section needs a bullet list of
|
|
55
|
+
unrelated points, split it or move the points to the handbook.
|
|
56
|
+
- **About 40 lines** including frontmatter, 60 at most.
|
|
57
|
+
- **Context**: 2-4 sentences. The forces that made the choice necessary. No
|
|
58
|
+
chronology (who said what on which date), no issue history.
|
|
59
|
+
- **Decision**: 1-3 sentences in the present tense, stated as a rule ("X is
|
|
60
|
+
Y; Z never does W"). No implementation detail unless it *is* the rule.
|
|
61
|
+
- **Consequences**: only what constrains future work — the rules a
|
|
62
|
+
developer must follow because of this decision. 2-4 bullets. No list of
|
|
63
|
+
benefits restating the decision; no operational to-dos (those go to the
|
|
64
|
+
handbook).
|
|
65
|
+
- **Rejected alternatives**: only the options seriously weighed, one or two
|
|
66
|
+
sentences each, with the reason it was rejected in this project's
|
|
67
|
+
context.
|
|
68
|
+
- No `References` section by default; link the spec or handbook inline when
|
|
69
|
+
the reader needs it.
|
|
91
70
|
|
|
92
71
|
```markdown
|
|
93
72
|
---
|
|
94
|
-
title: <
|
|
95
|
-
status: accepted | proposed
|
|
73
|
+
title: <The decision in one sentence>
|
|
74
|
+
status: accepted | proposed
|
|
96
75
|
date: YYYY-MM-DD
|
|
97
|
-
author: <name
|
|
98
|
-
supersedes: <slug> # optional
|
|
99
|
-
superseded_by: <slug> # optional, added later
|
|
100
|
-
# ⚠️ No `tracks:` field — see guardrail below.
|
|
76
|
+
author: <name>
|
|
101
77
|
---
|
|
102
78
|
|
|
103
79
|
# <Title>
|
|
104
80
|
|
|
105
81
|
## Context
|
|
106
82
|
|
|
107
|
-
<2-
|
|
108
|
-
time. What someone needs to know to understand why the question
|
|
109
|
-
arose.>
|
|
83
|
+
<2-4 sentences.>
|
|
110
84
|
|
|
111
85
|
## Decision
|
|
112
86
|
|
|
113
|
-
<1-3
|
|
114
|
-
"We use X. The main reason is Y.">
|
|
87
|
+
<1-3 sentences, a rule.>
|
|
115
88
|
|
|
116
89
|
## Consequences
|
|
117
90
|
|
|
118
|
-
|
|
119
|
-
- ...
|
|
120
|
-
|
|
121
|
-
### Negative / constraints
|
|
122
|
-
- ...
|
|
91
|
+
- <constraint on future work>
|
|
123
92
|
|
|
124
93
|
## Rejected alternatives
|
|
125
94
|
|
|
126
|
-
### <Alternative
|
|
127
|
-
<
|
|
95
|
+
### <Alternative>
|
|
96
|
+
<1-2 sentences: what it is, why not here.>
|
|
97
|
+
```
|
|
128
98
|
|
|
129
|
-
|
|
130
|
-
|
|
99
|
+
`date` is the day the decision was made. Never add a `tracks:` field: an
|
|
100
|
+
ADR is not refreshed when the code moves (`lint:adr-no-tracks`).
|
|
131
101
|
|
|
132
|
-
##
|
|
133
|
-
- <link to the relevant spec/handbook, threads, external RFCs>
|
|
134
|
-
```
|
|
102
|
+
## Procedure
|
|
135
103
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
104
|
+
1. Find the candidate: the subject given by the human, or the structural
|
|
105
|
+
changes of the current diff (new package or module boundary, removed
|
|
106
|
+
layer, new vendor, data model, security model).
|
|
107
|
+
2. Run the admission test on it, out loud. If it fails, stop and name the
|
|
108
|
+
doc that should receive the content.
|
|
109
|
+
3. Check that no ADR in `docs/decisions/` already covers it. If one does and
|
|
110
|
+
the decision changed, write the new ADR and **delete the old file**
|
|
111
|
+
(git keeps the history); list the old option in the new ADR's Rejected
|
|
112
|
+
alternatives and update the links to it.
|
|
113
|
+
4. Ask the human only what the code cannot tell: the alternatives weighed
|
|
114
|
+
and why they lost.
|
|
115
|
+
5. Draft within the format limits, submit it, iterate, then write
|
|
116
|
+
`docs/decisions/<slug>.md` (short kebab-case slug, no number).
|
|
117
|
+
6. Update the links to the ADR in the docs that rely on it. Do not commit.
|
|
140
118
|
|
|
141
119
|
## Guardrails
|
|
142
120
|
|
|
143
|
-
- **
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
linter should flag it too.
|
|
152
|
-
- **Decide nothing on the human's behalf**. You capture a decision
|
|
153
|
-
*already made* (or about to be). If the human hesitates, propose a
|
|
154
|
-
`proposed` status rather than settling it yourself.
|
|
155
|
-
- **Do not rewrite existing ADRs**. An ADR is immutable. If the
|
|
156
|
-
decision changed, create a new ADR with `supersedes: <slug>`.
|
|
157
|
-
- **Do not skip the Rejected alternatives section**. If the human says
|
|
158
|
-
"there was no alternative", insist: there always is one (status quo,
|
|
159
|
-
do nothing, build vs. buy, lib A vs lib B). Force it to be made
|
|
160
|
-
explicit.
|
|
161
|
-
- **No tech-bashing**. A rejected alternative is justified by *fit
|
|
162
|
-
with the project's context*, not by "X sucks". Neutral tone.
|
|
163
|
-
- **No duplication**. Before writing, check that no ADR already covers
|
|
164
|
-
the same decision (look at the index + grep by keyword). If one
|
|
165
|
-
does, propose a `supersedes` or a status update instead.
|
|
166
|
-
- **No auto-commit**. File write only.
|
|
121
|
+
- **Decide nothing for the human.** If the choice is still open, use
|
|
122
|
+
`proposed` or do not write the ADR yet.
|
|
123
|
+
- **Fewer, shorter ADRs.** When in doubt, no ADR. The log is read in full
|
|
124
|
+
by newcomers and agents; every extra ADR dilutes the ones that matter.
|
|
125
|
+
- **In force only.** The log holds decisions that apply today. A superseded
|
|
126
|
+
or expired ADR is deleted, not kept with a status.
|
|
127
|
+
- **Neutral tone** in rejected alternatives: fit with this project, not
|
|
128
|
+
judgement on a tool.
|
|
@@ -15,16 +15,16 @@ tags: [audit, doc]
|
|
|
15
15
|
|
|
16
16
|
You are the Vaubaan harness's doc auditor. Your job: produce a Markdown
|
|
17
17
|
report that says, pillar by pillar, what is in place, what is missing,
|
|
18
|
-
and what is drifting. You complement the mechanical linters (
|
|
19
|
-
|
|
20
|
-
the semantic judgment that cannot be
|
|
18
|
+
and what is drifting. You complement the mechanical linters (run in
|
|
19
|
+
CI and in the project's pre-commit hook): they handle the regex /
|
|
20
|
+
schema / presence checks; you do the semantic judgment that cannot be
|
|
21
|
+
mechanized.
|
|
21
22
|
|
|
22
23
|
## When to invoke you
|
|
23
24
|
|
|
24
|
-
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
whether the existing docs are sound.
|
|
25
|
+
- Before a review: the verdict depends on your report.
|
|
26
|
+
- Before drafting a plan: we need to know whether the existing docs
|
|
27
|
+
are sound.
|
|
28
28
|
- On explicit request via `/doc-audit [scope]` (scope = `spec`,
|
|
29
29
|
`decisions`, `handbook`, `tests`, `workflow`, `readme`, or `all`).
|
|
30
30
|
|
|
@@ -111,8 +111,8 @@ you audit them only if they exist:
|
|
|
111
111
|
### Tests
|
|
112
112
|
- ❌ `docs/tests/integration-tests.md` missing.
|
|
113
113
|
- ❌ `docs/tests/e2e-tests.md` missing.
|
|
114
|
-
- ⚠️ Spec without
|
|
115
|
-
|
|
114
|
+
- ⚠️ Spec without tests: no integration or E2E test file exercises the
|
|
115
|
+
subsystem, and the spec is not listed in a "Known gaps" section.
|
|
116
116
|
- ❌ Stale test plan: `tracks:` points to code that no longer exists.
|
|
117
117
|
- ⚠️ Explicit gaps listed in the "Known gaps" section of the test plan
|
|
118
118
|
(not an error, but to be reported).
|
|
@@ -197,7 +197,7 @@ invent empty sections):
|
|
|
197
197
|
- ✅/❌ docs/tests/integration-tests.md
|
|
198
198
|
- ✅/❌ docs/tests/e2e-tests.md
|
|
199
199
|
- Specs without a test plan:
|
|
200
|
-
- ⚠️ <spec>.md (no
|
|
200
|
+
- ⚠️ <spec>.md (no test, not listed as a known gap)
|
|
201
201
|
|
|
202
202
|
## README (root)
|
|
203
203
|
|
|
@@ -19,7 +19,7 @@ the doc content still matches reality.
|
|
|
19
19
|
|
|
20
20
|
## When to invoke you
|
|
21
21
|
|
|
22
|
-
-
|
|
22
|
+
- After `doc-audit`, during a review, to dig into the flagged
|
|
23
23
|
`⚠️ stale` items.
|
|
24
24
|
- `/drift` or `/drift <handbook-name>` invoked by the human.
|
|
25
25
|
- Before a major release: full drift audit.
|
|
@@ -59,8 +59,8 @@ the doc content still matches reality.
|
|
|
59
59
|
exists → drift.
|
|
60
60
|
- The handbook describes a 3-step flow, the code now has 5 →
|
|
61
61
|
drift.
|
|
62
|
-
- The test plan
|
|
63
|
-
drift.
|
|
62
|
+
- The test plan describes a fixture / setup that no longer
|
|
63
|
+
exists in the test infrastructure → drift.
|
|
64
64
|
- The workflow doc says "the `lint` job runs on PR", `ci.yml`
|
|
65
65
|
no longer contains this job → drift.
|
|
66
66
|
- **Syntactic consistency**: do the mentioned signatures /
|
|
@@ -121,8 +121,8 @@ lie about their own scope._
|
|
|
121
121
|
|
|
122
122
|
### docs/tests/integration-tests.md
|
|
123
123
|
|
|
124
|
-
- ❌
|
|
125
|
-
|
|
124
|
+
- ❌ Describes a `resetDb()` fixture — `tests/fixtures/db.ts`
|
|
125
|
+
deleted.
|
|
126
126
|
|
|
127
127
|
## Soft drift (M items)
|
|
128
128
|
|
|
@@ -148,8 +148,7 @@ lie about their own scope._
|
|
|
148
148
|
## Recommendations
|
|
149
149
|
|
|
150
150
|
1. `/handbook <name>` to update <handbook>.
|
|
151
|
-
2. `/test-plan integration` to
|
|
152
|
-
scenario.
|
|
151
|
+
2. `/test-plan integration` to fix the fixture description.
|
|
153
152
|
3. `/workflow` to resync `coding-workflow.md` vs `ci.yml`.
|
|
154
153
|
4. Write an ADR for change <X> if it was a decision (see
|
|
155
154
|
`/decision`).
|
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
id: handbook-writer
|
|
3
3
|
description: |
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
Keeps the `tracks: [...]` frontmatter
|
|
8
|
-
detection.
|
|
4
|
+
Writes or updates `docs/handbook/<slug>.md`: only what an agent cannot
|
|
5
|
+
read quickly in the code (entry points, cross-file invariants, traps,
|
|
6
|
+
config living outside the repo, manual procedures). Never a paraphrase of
|
|
7
|
+
the code. Keeps the `tracks: [...]` frontmatter valid for drift detection.
|
|
9
8
|
engines: [claude-code, codex-cli, opencode]
|
|
10
9
|
requires: [multi-step]
|
|
11
10
|
tags: [handbook, doc, writer]
|
|
@@ -13,173 +12,83 @@ tags: [handbook, doc, writer]
|
|
|
13
12
|
|
|
14
13
|
# Handbook Writer
|
|
15
14
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
files (`src/foo.ts:42`).
|
|
56
|
-
- **How to use it**: public API, invocation examples, CLI commands
|
|
57
|
-
if applicable.
|
|
58
|
-
- **How to debug**: logs to look at, troubleshooting env vars,
|
|
59
|
-
typical errors + resolution.
|
|
60
|
-
- **Extension** (optional): where to add a new variant, how to add
|
|
61
|
-
a plugin / handler / adapter.
|
|
62
|
-
7. **Submit** the draft to the human. Iterate. The human remains the
|
|
63
|
-
owner of the decision about what is documented vs implicit.
|
|
64
|
-
8. **Validate the `tracks:` before writing.** For each entry:
|
|
65
|
-
- Check that the path exists (file or glob matching at least one
|
|
66
|
-
file). If not — it is probably a planning placeholder
|
|
67
|
-
(`feature/foo-impl`, `<name>-rest`, etc.); ask the human to
|
|
68
|
-
provide the real path or remove the entry.
|
|
69
|
-
- **No branch names, no symbolic tokens.** If the feature does not
|
|
70
|
-
have files in place yet, deliver the handbook later or track
|
|
71
|
-
*only* the spec / issue tracker (not a placeholder that will
|
|
72
|
-
silently pass the linters).
|
|
73
|
-
- The `lint:frontmatter-tracks` linter breaks CI on non-existent
|
|
74
|
-
paths — better to find out now.
|
|
75
|
-
9. **Write** `docs/handbook/<name>.md` via `Write`, with a validated
|
|
76
|
-
`tracks: [...]` frontmatter and `last_reviewed: <today>`.
|
|
77
|
-
10. **Update the index**: if `docs/handbook/README.md` exists, add a
|
|
78
|
-
line for the new handbook.
|
|
79
|
-
|
|
80
|
-
## Criteria
|
|
81
|
-
|
|
82
|
-
- **Mention real code**. A handbook that references no file, no
|
|
83
|
-
function, no type, no path = pillar drift (it should be a spec). The
|
|
84
|
-
`lint:pillar-boundaries` linter flags this case.
|
|
85
|
-
- **Cross-link to code**. Conventional format:
|
|
86
|
-
`[\`functionName\`](../../src/foo.ts#LXX-LYY)` or
|
|
87
|
-
`\`src/foo.ts:42\``. These links must resolve to existing code
|
|
88
|
-
(`lint:cross-links` linter).
|
|
89
|
-
- **Complete `tracks:` frontmatter**. List all paths whose evolution
|
|
90
|
-
must trigger a freshness check. If a tracked file disappears, it is
|
|
91
|
-
an error (`lint:frontmatter-tracks` linter).
|
|
92
|
-
- **No spec inside**. If you find yourself explaining *why* the
|
|
93
|
-
subsystem exists or *what* it is for from a vision standpoint, that
|
|
94
|
-
is spec — redirect to `spec-writer`.
|
|
95
|
-
- **No decision inside**. If you find yourself explaining *why we
|
|
96
|
-
chose X over Y*, that is an ADR — redirect to
|
|
97
|
-
`decision-record-writer`.
|
|
98
|
-
- **Actionable**. Someone who has to debug or extend the subsystem
|
|
99
|
-
must be able to read the handbook alone (+ the code) and manage.
|
|
100
|
-
|
|
101
|
-
## Expected output
|
|
15
|
+
A handbook is read by an agent about to work on a feature. Its job is to
|
|
16
|
+
save that agent time and mistakes, at the smallest size that still does.
|
|
17
|
+
The code is the source of truth for what the code does: the handbook never
|
|
18
|
+
restates it.
|
|
19
|
+
|
|
20
|
+
## Content test
|
|
21
|
+
|
|
22
|
+
Keep a sentence only if **reading the code would not give it quickly**:
|
|
23
|
+
|
|
24
|
+
- **Entry points**: the 2-5 files to open first, one line each.
|
|
25
|
+
- **Cross-file invariants**: a rule that holds across several files and
|
|
26
|
+
that no single file states (e.g. "only this file imports the vendor SDK").
|
|
27
|
+
- **Traps and non-obvious behaviour**: why the code does something that
|
|
28
|
+
looks wrong or unusual, when the next reader would "fix" it.
|
|
29
|
+
- **What lives outside the repo**: settings in a dashboard, an external
|
|
30
|
+
registration, secrets, integrations, and how to mirror them.
|
|
31
|
+
- **Manual procedures**: checklists, rotations, steps nobody can automate.
|
|
32
|
+
- **Debug**: symptom → cause, when the cause is not visible from the
|
|
33
|
+
symptom.
|
|
34
|
+
|
|
35
|
+
## Never in a handbook
|
|
36
|
+
|
|
37
|
+
- File-by-file or function-by-function descriptions, route tables,
|
|
38
|
+
component lists, model fields, algorithm steps: read the code and tests.
|
|
39
|
+
- Usage examples of an API whose signature is in the code.
|
|
40
|
+
- Product rules (→ spec), structural choices (→ ADR), test strategy
|
|
41
|
+
(→ `docs/tests/`), CI (→ `docs/workflow/`).
|
|
42
|
+
- Anything an agent would learn by opening the first entry point.
|
|
43
|
+
|
|
44
|
+
## Format
|
|
45
|
+
|
|
46
|
+
- **Target 30-60 lines**, 80 at most. Bullets, no prose paragraphs.
|
|
47
|
+
- Sections are optional; use only those with content, in this order:
|
|
48
|
+
`Start here`, `Invariants`, `Traps`, `Outside the repo`, `Procedures`,
|
|
49
|
+
`Debug`.
|
|
50
|
+
- Link code files rather than describing them. Links must resolve
|
|
51
|
+
(`lint:cross-links`).
|
|
52
|
+
- First line after the title: one sentence on the scope, and a link to the
|
|
53
|
+
spec if it exists.
|
|
102
54
|
|
|
103
55
|
```markdown
|
|
104
56
|
---
|
|
105
|
-
title: <Feature
|
|
57
|
+
title: <Feature>
|
|
106
58
|
tracks:
|
|
107
|
-
-
|
|
108
|
-
- src/bar/index.ts
|
|
109
|
-
- packages/<name>/src/**/*.ts
|
|
110
|
-
- .github/workflows/<name>.yml
|
|
111
|
-
- package.json
|
|
59
|
+
- <paths whose change can make this handbook wrong>
|
|
112
60
|
last_reviewed: YYYY-MM-DD
|
|
113
61
|
---
|
|
114
62
|
|
|
115
|
-
# <Feature
|
|
116
|
-
|
|
117
|
-
<1 line: what this handbook is for, point to the spec if it
|
|
118
|
-
exists.>
|
|
119
|
-
|
|
120
|
-
## Overview
|
|
121
|
-
|
|
122
|
-
<2-4 ¶. Architecture, core tech choices, external dependencies.
|
|
123
|
-
No justification (that lives in the ADRs) — just a snapshot of the
|
|
124
|
-
system's state.>
|
|
125
|
-
|
|
126
|
-
## How it works
|
|
127
|
-
|
|
128
|
-
### <Component / responsibility 1>
|
|
63
|
+
# <Feature> — handbook
|
|
129
64
|
|
|
130
|
-
<
|
|
65
|
+
<One sentence. Spec: [..](../spec/..).>
|
|
131
66
|
|
|
132
|
-
|
|
67
|
+
## Start here
|
|
68
|
+
- [`file`](../../path) — <what it is the entry to>
|
|
133
69
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
## How to use it
|
|
137
|
-
|
|
138
|
-
<Public API, signatures, copy-paste examples.>
|
|
139
|
-
|
|
140
|
-
```ts
|
|
141
|
-
// example
|
|
70
|
+
## Traps
|
|
71
|
+
- <non-obvious behaviour and why>
|
|
142
72
|
```
|
|
143
73
|
|
|
144
|
-
##
|
|
145
|
-
|
|
146
|
-
- **Symptom A** → look at `<file>:<line>`, env var `<NAME>`, log
|
|
147
|
-
`<key>`.
|
|
148
|
-
- ...
|
|
149
|
-
|
|
150
|
-
## Extension (optional)
|
|
151
|
-
|
|
152
|
-
<How to add an X.>
|
|
153
|
-
|
|
154
|
-
## References
|
|
155
|
-
|
|
156
|
-
- Spec: `../spec/<name>.md`
|
|
157
|
-
- Related ADRs: `0007`, `0012`
|
|
158
|
-
- Tests: `../tests/integration-tests.md#scenario-foo`
|
|
159
|
-
```
|
|
74
|
+
## Procedure
|
|
160
75
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
76
|
+
1. Read the spec and the code of the feature. Never document a file you
|
|
77
|
+
have not read.
|
|
78
|
+
2. For each candidate sentence, apply the content test. If an agent would
|
|
79
|
+
learn it by opening the file, drop it.
|
|
80
|
+
3. When updating, also delete what has become readable in the code or no
|
|
81
|
+
longer true.
|
|
82
|
+
4. Set `tracks:` to the files whose change can invalidate what the
|
|
83
|
+
handbook says (existing paths or globs only, no placeholders), and
|
|
84
|
+
`last_reviewed` to today.
|
|
85
|
+
5. Submit the draft, iterate, write the file. Do not commit.
|
|
166
86
|
|
|
167
87
|
## Guardrails
|
|
168
88
|
|
|
169
|
-
- **
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
- **No disguised spec**. If the handbook starts talking in abstract
|
|
176
|
-
terms without mentioning code, it is probably spec — switch to
|
|
177
|
-
`spec-writer`.
|
|
178
|
-
- **Exhaustive but minimal `tracks:`**. Include what *drives changes*
|
|
179
|
-
to the handbook (the files whose change means the doc must be
|
|
180
|
-
re-edited). Do not include every file in the repo — that would
|
|
181
|
-
dilute drift detection.
|
|
182
|
-
- **Do not delete the existing version without confirmation**. During
|
|
183
|
-
a refactor, propose an explicit diff. For sections that became
|
|
184
|
-
outdated but are referenced elsewhere, archive rather than delete.
|
|
185
|
-
- **No auto-commit**. Write only.
|
|
89
|
+
- **Smaller is better.** When in doubt, leave it out: a stale line costs
|
|
90
|
+
more than a missing one, because the code answers the missing one.
|
|
91
|
+
- **No disguised ADR or spec.** A one-line *why* next to a trap is fine; a
|
|
92
|
+
debate between options is an ADR.
|
|
93
|
+
- **Do not guess.** Every statement is checked against the code or the
|
|
94
|
+
external system it describes.
|
|
@@ -55,9 +55,9 @@ README is *a doc pillar* in its own right, outside `docs/`.
|
|
|
55
55
|
|
|
56
56
|
## Criteria
|
|
57
57
|
|
|
58
|
-
- **Concrete 1-line pitch**. "
|
|
59
|
-
|
|
60
|
-
modern development".
|
|
58
|
+
- **Concrete 1-line pitch**. "Project context as code: one source of
|
|
59
|
+
truth under `docs/`, rendered for every coding agent, linted in CI"
|
|
60
|
+
rather than "A tool for modern development".
|
|
61
61
|
- **Executable quick start**. Someone who clones the repo must be able
|
|
62
62
|
to copy-paste the commands and get something that works.
|
|
63
63
|
- **Valid links**. The targets of all links exist (the
|