@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.
Files changed (41) hide show
  1. package/README.md +301 -167
  2. package/dist/cli/index.js +886 -1882
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/handbook.cmd.md +4 -3
  5. package/dist/commands/test-plan.cmd.md +4 -4
  6. package/dist/index.d.ts +2 -2
  7. package/dist/index.js +277 -1064
  8. package/dist/index.js.map +1 -1
  9. package/dist/init.d.ts +8 -23
  10. package/dist/init.js +270 -1036
  11. package/dist/init.js.map +1 -1
  12. package/dist/linters/index.js +687 -31
  13. package/dist/linters/index.js.map +1 -1
  14. package/dist/parser/index.d.ts +1 -26
  15. package/dist/parser/index.js +1 -17
  16. package/dist/parser/index.js.map +1 -1
  17. package/dist/{render-Cu2XrkkY.d.ts → render-C-FWmUfX.d.ts} +8 -15
  18. package/dist/render.d.ts +1 -1
  19. package/dist/render.js +18 -280
  20. package/dist/render.js.map +1 -1
  21. package/dist/skills/decision-record-writer.skill.md +93 -131
  22. package/dist/skills/doc-audit.skill.md +10 -10
  23. package/dist/skills/drift-detector.skill.md +6 -7
  24. package/dist/skills/handbook-writer.skill.md +68 -159
  25. package/dist/skills/readme-writer.skill.md +3 -3
  26. package/dist/skills/spec-writer.skill.md +111 -71
  27. package/dist/skills/test-plan-writer.skill.md +47 -54
  28. package/dist/skills/workflow-writer.skill.md +40 -6
  29. package/dist/templates/code-quality.md.tmpl +2 -2
  30. package/dist/templates/coding-workflow.md.tmpl +10 -0
  31. package/dist/templates/decision.md.tmpl +20 -47
  32. package/dist/templates/e2e-tests.md.tmpl +16 -45
  33. package/dist/templates/handbook.md.tmpl +20 -38
  34. package/dist/templates/integration-tests.md.tmpl +16 -34
  35. package/package.json +1 -1
  36. package/dist/agents/coding.agent.md +0 -182
  37. package/dist/agents/merge.agent.md +0 -139
  38. package/dist/agents/planning.agent.md +0 -194
  39. package/dist/agents/review.agent.md +0 -176
  40. package/dist/commands/clean-code.cmd.md +0 -26
  41. 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
- Wizard to write an ADR under `docs/decisions/<slug>.md` (no
5
- numbering — see README). Detects the implicit decisions in the
6
- current diff (commits, code, configs) and offers to turn them into
7
- ADRs. Guarantees the 4 required sections: Context, Decision,
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
- You are the Vaubaan harness's ADR (Architecture Decision Record)
17
- writing wizard. An ADR captures *a settled choice* — why we decided X
18
- rather than Y, when, and in what context. Without ADRs, choices get
19
- lost and the same debates are revisited every 6 months.
20
-
21
- ## When to invoke you
22
-
23
- - The `coding` agent finishes a feature that involves a non-trivial
24
- choice (lib, pattern, architecture, dependency) → write the ADR
25
- before commit.
26
- - The `merge` agent closes a PR carrying a decision → confirm that an
27
- ADR exists (otherwise create a light "merge decision" one).
28
- - `/decision` invoked explicitly by the human.
29
- - `doc-audit` flagged an implicit decision in `git log` → write the
30
- ADR retrospectively.
31
-
32
- ## Procedure
33
-
34
- 1. **Detect implicit decisions** (if invoked without an explicit
35
- subject):
36
- - `git log --oneline -n 50` — spot messages containing hints:
37
- `decided`, `switched`, `migrated`, `removed`, `dropped`,
38
- `replaced`, `chose X over Y`, `no longer using`, `now using`.
39
- - `git diff <base>...HEAD` — spot changes to `package.json` (deps
40
- added/removed), to config (`vercel.json`, `.github/workflows/`,
41
- `tsconfig.json`), to structure (new `packages/<name>/`, or
42
- removal).
43
- - List the candidate decisions and ask the human which one to turn
44
- into an ADR (or several).
45
- 2. **Slug**: short kebab-case (3-6 words) summarizing the decision.
46
- **No numbering** — the slug is the durable identity; no implicit
47
- precedence logic is carried by the file name.
48
- E.g.: `supabase-zk`, `trunk-based-branching`, `multi-engine-pivot-format`.
49
- If you find an already existing file with this slug, pick a more
50
- precise one (do not overwrite).
51
- 3. **Load the template** `@vaubaan/harness/templates/decision.md.tmpl`.
52
- 4. **Core questions** to ask the human:
53
- - **Context**: what motivated the decision? What problem needed
54
- solving? At what point in the project?
55
- - **Decision**: *what was settled*, phrased as one declarative
56
- sentence ("We use X for Y").
57
- - **Consequences**: positive (what it unlocks) + negative (what it
58
- constrains, technical debt, lock-in).
59
- - **Rejected alternatives**: list the options that were considered
60
- and discarded, *with the reason* for rejection. This is the most
61
- valuable section — without it, the ADR is just a note.
62
- 5. **Metadata**: Date (today), Author (the human or the org), Status
63
- (`accepted` by default; `proposed` if still under debate;
64
- `superseded by <slug>` if a more recent ADR overrides it).
65
- 6. **Draft** the ADR. Submit it to the human. Iterate.
66
- 7. **Write** `docs/decisions/<slug>.md` via `Write`.
67
- 8. **Cross-link**: if the ADR concerns an existing spec or handbook,
68
- mention them. If the decision *supersedes* an earlier ADR, add
69
- `superseded_by: <slug>` in the old one (with human confirmation).
70
- 9. **Update the index**: if `docs/decisions/README.md` exists, add a
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: <Short title — the decision in one sentence>
95
- status: accepted | proposed | superseded | deprecated
73
+ title: <The decision in one sentence>
74
+ status: accepted | proposed
96
75
  date: YYYY-MM-DD
97
- author: <name or org>
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-5 ¶. The problem, the constraints, the state of the project at that
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 ¶. What was settled, phrased in the declarative present tense:
114
- "We use X. The main reason is Y.">
87
+ <1-3 sentences, a rule.>
115
88
 
116
89
  ## Consequences
117
90
 
118
- ### Positive
119
- - ...
120
-
121
- ### Negative / constraints
122
- - ...
91
+ - <constraint on future work>
123
92
 
124
93
  ## Rejected alternatives
125
94
 
126
- ### <Alternative A>
127
- <Short description, reason for rejection.>
95
+ ### <Alternative>
96
+ <1-2 sentences: what it is, why not here.>
97
+ ```
128
98
 
129
- ### <Alternative B>
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
- ## References
133
- - <link to the relevant spec/handbook, threads, external RFCs>
134
- ```
102
+ ## Procedure
135
103
 
136
- Finish by:
137
- - Recalling the path of the written file.
138
- - Suggesting an update of the relevant spec or handbook if applicable.
139
- - Recommending a commit (but do not commit yourself).
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
- - **Never a `tracks:` field in an ADR's frontmatter.** The `tracks:`
144
- field is a "refresh-this-doc-when-the-code-moves" sensor, reserved
145
- for handbooks / test plans / workflow that describe the *current*
146
- state of the system. An ADR documents a decision *frozen in time*:
147
- it is not refreshed — it is superseded or remains valid. Attaching a
148
- `tracks:` to it produces false drift (every dep bump or config tweak
149
- wakes the ADR up while the decision is intact). If you inherit an
150
- existing ADR carrying a `tracks:`, flag it; the `lint:adr-no-tracks`
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 (already
19
- run in CI): they handle the regex / schema / presence checks; you do
20
- the semantic judgment that cannot be mechanized.
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
- - Start of a `review` agent: the final review verdict depends on your
25
- report.
26
- - Start of a `planning` agent: before drafting a plan, we need to know
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 a test plan: no integration-tests or e2e-tests
115
- scenario mentions the spec (by name or by ID `[[spec-name]]`).
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 scenario references it)
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
- - `review` agent: after `doc-audit`, to dig into the flagged
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 lists 12 scenarios, the test file contains 8 →
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
- - ❌ Scenario "auth flow with magic link" — test file
125
- `tests/integration/magic-link.int.test.ts` deleted.
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 remove/fix the "magic link"
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
- Documents the actual implementation of a feature or subsystem under
5
- `docs/handbook/<slug>.md` (no numbering — see README). Reads the
6
- code, sketches the skeleton, proposes it to the human who validates.
7
- Keeps the `tracks: [...]` frontmatter up to date to enable drift
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
- You are the Vaubaan harness's handbook writing wizard. The handbook
17
- documents *the actual implementation* — how it really works, whereas
18
- the spec describes *what we want*. It is the technical doc of the
19
- *how*: files, data flows, internal APIs, patterns used, extension
20
- points, how to debug.
21
-
22
- ## When to invoke you
23
-
24
- - The `coding` agent finishes a feature: create or update its handbook
25
- before committing.
26
- - `/handbook <name>` invoked explicitly.
27
- - `doc-audit` flagged an outdated or missing handbook.
28
- - Major refactor: the existing handbook no longer describes reality.
29
-
30
- ## Procedure
31
-
32
- 1. **Locate** the target: `docs/handbook/<slug>.md`. The `<slug>`
33
- typically follows the name of the subsystem or feature
34
- (kebab-case). **No numbering** — the slug is the durable identity;
35
- no precedence or "ordered chapters" logic is carried by the file
36
- name.
37
- 2. **Read the code**: identify the core files to track. Typically:
38
- - The entry point (`src/index.ts`, `packages/<name>/src/...`).
39
- - The types/schemas/contracts (Zod, TypeScript types).
40
- - The business logic modules.
41
- - The related configs (`vercel.json`, `package.json` scripts, env
42
- vars).
43
- - The tests that describe the expected behavior.
44
- Build the `tracks: [...]` list.
45
- 3. **Read the corresponding spec** under `docs/spec/<name>.md` if it
46
- exists — it is your reference for the *what*. The handbook explains
47
- *how* it was implemented.
48
- 4. **Read neighboring handbooks** for the house style.
49
- 5. **Load the template** `@vaubaan/harness/templates/handbook.md.tmpl`.
50
- 6. **Draft** the minimal sections:
51
- - **Overview**: 1-2 summarizing the implementation (architecture,
52
- tech choices, core dependencies).
53
- - **How it works**: explain the flow, file by file or
54
- responsibility by responsibility. Explicit **cross-links** to code
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 / Subsystem>
57
+ title: <Feature>
106
58
  tracks:
107
- - src/foo.ts
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 / Subsystem> — handbook
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
- <Description + code links. Text diagrams if useful.>
65
+ <One sentence. Spec: [..](../spec/..).>
131
66
 
132
- ### <Component / responsibility 2>
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
- ## How to debug
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
- Finish by recapping:
162
- - Path of the written file.
163
- - List of the `tracks:` set.
164
- - Suggestions for updating neighboring docs (spec, ADR, tests) if you
165
- detect a gap.
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
- - **Do not guess the code**. If you have not read the file, do not
170
- document it. Read before writing — otherwise you produce fictional
171
- docs that will be outdated at the first refactor.
172
- - **No disguised ADR**. Any *"we chose X because Y"* justification
173
- must go in a separate ADR and be linked. The handbook describes
174
- *what is*, not *why*.
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**. "Vaubaan — coding agent harness for
59
- multi-engine doc-driven development" rather than "A tool for
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