@vaubaan/harness 2.0.0 → 2.2.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 +25 -21
- package/dist/cli/index.js +543 -76
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/handbook.cmd.md +4 -3
- package/dist/commands/journey.cmd.md +22 -0
- package/dist/commands/story.cmd.md +24 -0
- package/dist/commands/test-plan.cmd.md +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +304 -56
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +2 -3
- package/dist/init.js +301 -53
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +523 -56
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +110 -1
- package/dist/parser/index.js +229 -2
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-C-FWmUfX.d.ts → render-BzrBb_l4.d.ts} +3 -1
- package/dist/render.d.ts +1 -1
- package/dist/render.js +89 -10
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +93 -130
- package/dist/skills/doc-audit.skill.md +37 -7
- package/dist/skills/drift-detector.skill.md +41 -11
- package/dist/skills/handbook-writer.skill.md +71 -159
- package/dist/skills/journey-writer.skill.md +159 -0
- package/dist/skills/spec-writer.skill.md +25 -3
- package/dist/skills/test-plan-writer.skill.md +46 -53
- package/dist/skills/workflow-writer.skill.md +20 -3
- 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/dist/templates/journey.md.tmpl +45 -0
- package/package.json +1 -1
|
@@ -37,7 +37,9 @@ the doc content still matches reality.
|
|
|
37
37
|
move on to the semantic analysis.
|
|
38
38
|
1. **Inventory of targets**: all files under `docs/handbook/`,
|
|
39
39
|
`docs/tests/`, `docs/workflow/` that declare a non-empty
|
|
40
|
-
`tracks: [...]` in their frontmatter
|
|
40
|
+
`tracks: [...]` in their frontmatter, and the files under
|
|
41
|
+
`docs/journeys/` whose nodes declare `anchors:` (`README.md` there is
|
|
42
|
+
generated: skip it).
|
|
41
43
|
- **Explicit skip**: `docs/decisions/` is *never* scanned. ADRs
|
|
42
44
|
document decisions frozen in time — their drift is semantically
|
|
43
45
|
different (is the decision still valid?), not a question of doc
|
|
@@ -59,15 +61,25 @@ the doc content still matches reality.
|
|
|
59
61
|
exists → drift.
|
|
60
62
|
- The handbook describes a 3-step flow, the code now has 5 →
|
|
61
63
|
drift.
|
|
62
|
-
- The test plan
|
|
63
|
-
drift.
|
|
64
|
+
- The test plan describes a fixture / setup that no longer
|
|
65
|
+
exists in the test infrastructure → drift.
|
|
64
66
|
- The workflow doc says "the `lint` job runs on PR", `ci.yml`
|
|
65
67
|
no longer contains this job → drift.
|
|
68
|
+
- A journey leaf anchors a file that no longer exists, or
|
|
69
|
+
`requires:` an entity the spec vocabulary no longer defines →
|
|
70
|
+
hard drift.
|
|
71
|
+
- A journey leaf whose anchored code gained a branch (a new
|
|
72
|
+
guard, a new step the user sees) with no node for it → soft
|
|
73
|
+
drift; a `proposed` leaf whose code already exists → soft
|
|
74
|
+
drift, suggest passing it `implemented`.
|
|
66
75
|
- **Syntactic consistency**: do the mentioned signatures /
|
|
67
76
|
types / commands match?
|
|
68
77
|
3. **Reverse cross-check**: for "important" code files (entry point,
|
|
69
78
|
public types, `package.json` scripts), check that they are tracked
|
|
70
|
-
by *at least one* doc
|
|
79
|
+
by *at least one* doc (`tracks:`) or anchored by *at least one*
|
|
80
|
+
journey leaf (`anchors:`). Otherwise → ⚠️ "undocumented code". This
|
|
81
|
+
is where unanchored entry points are reported: with judgment, no
|
|
82
|
+
configuration.
|
|
71
83
|
4. **Report**: structured Markdown in a
|
|
72
84
|
`.vaubaan/reports/drift-report.md` file (create the folder if missing).
|
|
73
85
|
|
|
@@ -81,12 +93,15 @@ the doc content still matches reality.
|
|
|
81
93
|
- ADR with a non-empty `tracks:` (see `lint:adr-no-tracks`).
|
|
82
94
|
- Mention in the doc of a function / API / command that is gone.
|
|
83
95
|
- Test plan that refers to a test that is gone.
|
|
96
|
+
- Journey anchor to a deleted file; entity removed from the spec
|
|
97
|
+
vocabulary.
|
|
84
98
|
- **Soft drift** (⚠️):
|
|
85
99
|
- Doc that describes an earlier state (80 % covered by the current
|
|
86
100
|
code — not wrong, but incomplete).
|
|
87
101
|
- New undocumented feature (the code evolved, the doc did not
|
|
88
102
|
follow).
|
|
89
103
|
- Changed conventions (e.g.: naming, tree structure) not reflected.
|
|
104
|
+
- Code branch without a journey node; `proposed` leaf already coded.
|
|
90
105
|
- **Not drift**:
|
|
91
106
|
- Stylistic difference (wording, section order).
|
|
92
107
|
- Minor implementation detail absent from the doc (by design: the
|
|
@@ -121,8 +136,14 @@ lie about their own scope._
|
|
|
121
136
|
|
|
122
137
|
### docs/tests/integration-tests.md
|
|
123
138
|
|
|
124
|
-
- ❌
|
|
125
|
-
|
|
139
|
+
- ❌ Describes a `resetDb()` fixture — `tests/fixtures/db.ts`
|
|
140
|
+
deleted.
|
|
141
|
+
|
|
142
|
+
### docs/journeys/<slug>.md
|
|
143
|
+
|
|
144
|
+
- ❌ Leaf "<title>" anchors `src/legacy/old.ts` — file deleted.
|
|
145
|
+
- ❌ Leaf "<title>" requires `<entity>` — no longer in the Vocabulary
|
|
146
|
+
of `docs/spec/<subsystem>.md`.
|
|
126
147
|
|
|
127
148
|
## Soft drift (M items)
|
|
128
149
|
|
|
@@ -138,28 +159,37 @@ lie about their own scope._
|
|
|
138
159
|
- ⚠️ Mentions the CI job `e2e` — the job was renamed `e2e-tests`
|
|
139
160
|
in `.github/workflows/ci.yml` (commit <sha>).
|
|
140
161
|
|
|
162
|
+
### docs/journeys/<slug>.md
|
|
163
|
+
|
|
164
|
+
- ⚠️ Leaf "<title>": its anchored `src/foo.ts:88` gained a guard the
|
|
165
|
+
user sees, no node for it.
|
|
166
|
+
- ⚠️ Leaf "<title>" is `proposed` but `src/bar.ts` already realizes it
|
|
167
|
+
— pass it `implemented`.
|
|
168
|
+
|
|
141
169
|
## Undocumented code (K items)
|
|
142
170
|
|
|
143
171
|
- ⚠️ `src/new-feature/` (introduced commit <sha>) — no handbook
|
|
144
|
-
tracks these files. Suggested:
|
|
172
|
+
tracks these files and no journey leaf anchors them. Suggested:
|
|
173
|
+
`/handbook new-feature` for the how, `/journey <slug>` for the user
|
|
174
|
+
activity.
|
|
145
175
|
- ⚠️ Script `package.json:deploy:preview` — not mentioned in
|
|
146
176
|
`coding-workflow.md`.
|
|
147
177
|
|
|
148
178
|
## Recommendations
|
|
149
179
|
|
|
150
180
|
1. `/handbook <name>` to update <handbook>.
|
|
151
|
-
2. `/test-plan integration` to
|
|
152
|
-
scenario.
|
|
181
|
+
2. `/test-plan integration` to fix the fixture description.
|
|
153
182
|
3. `/workflow` to resync `coding-workflow.md` vs `ci.yml`.
|
|
154
183
|
4. Write an ADR for change <X> if it was a decision (see
|
|
155
184
|
`/decision`).
|
|
185
|
+
5. `/journey <slug>` to add the missing node or re-anchor the leaf.
|
|
156
186
|
```
|
|
157
187
|
|
|
158
188
|
## Guardrails
|
|
159
189
|
|
|
160
190
|
- **Fix nothing**. You detect, you list, you recommend. The writers
|
|
161
|
-
(`handbook-writer`, `test-plan-writer`, `workflow-writer
|
|
162
|
-
to fix.
|
|
191
|
+
(`handbook-writer`, `test-plan-writer`, `workflow-writer`,
|
|
192
|
+
`journey-writer` via `/journey`) are there to fix.
|
|
163
193
|
- **No false positives on details**. If the handbook says "the
|
|
164
194
|
function returns a Result<T, E>" and the code returns `Result<T, E>`
|
|
165
195
|
but with a slightly different T type, that is not hard drift — it
|
|
@@ -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,86 @@ 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
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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.
|
|
54
|
+
- When a journey leaf anchors the feature (`docs/journeys/`), link it
|
|
55
|
+
too: the journey says what the user does and where, the handbook says
|
|
56
|
+
how. Never restate the journey.
|
|
102
57
|
|
|
103
58
|
```markdown
|
|
104
59
|
---
|
|
105
|
-
title: <Feature
|
|
60
|
+
title: <Feature>
|
|
106
61
|
tracks:
|
|
107
|
-
-
|
|
108
|
-
- src/bar/index.ts
|
|
109
|
-
- packages/<name>/src/**/*.ts
|
|
110
|
-
- .github/workflows/<name>.yml
|
|
111
|
-
- package.json
|
|
62
|
+
- <paths whose change can make this handbook wrong>
|
|
112
63
|
last_reviewed: YYYY-MM-DD
|
|
113
64
|
---
|
|
114
65
|
|
|
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>
|
|
66
|
+
# <Feature> — handbook
|
|
129
67
|
|
|
130
|
-
<
|
|
68
|
+
<One sentence. Spec: [..](../spec/..).>
|
|
131
69
|
|
|
132
|
-
|
|
70
|
+
## Start here
|
|
71
|
+
- [`file`](../../path) — <what it is the entry to>
|
|
133
72
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
## How to use it
|
|
137
|
-
|
|
138
|
-
<Public API, signatures, copy-paste examples.>
|
|
139
|
-
|
|
140
|
-
```ts
|
|
141
|
-
// example
|
|
73
|
+
## Traps
|
|
74
|
+
- <non-obvious behaviour and why>
|
|
142
75
|
```
|
|
143
76
|
|
|
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
|
-
```
|
|
77
|
+
## Procedure
|
|
160
78
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
79
|
+
1. Read the spec and the code of the feature. Never document a file you
|
|
80
|
+
have not read.
|
|
81
|
+
2. For each candidate sentence, apply the content test. If an agent would
|
|
82
|
+
learn it by opening the file, drop it.
|
|
83
|
+
3. When updating, also delete what has become readable in the code or no
|
|
84
|
+
longer true.
|
|
85
|
+
4. Set `tracks:` to the files whose change can invalidate what the
|
|
86
|
+
handbook says (existing paths or globs only, no placeholders), and
|
|
87
|
+
`last_reviewed` to today.
|
|
88
|
+
5. Submit the draft, iterate, write the file. Do not commit.
|
|
166
89
|
|
|
167
90
|
## Guardrails
|
|
168
91
|
|
|
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.
|
|
92
|
+
- **Smaller is better.** When in doubt, leave it out: a stale line costs
|
|
93
|
+
more than a missing one, because the code answers the missing one.
|
|
94
|
+
- **No disguised ADR or spec.** A one-line *why* next to a trap is fine; a
|
|
95
|
+
debate between options is an ADR.
|
|
96
|
+
- **Do not guess.** Every statement is checked against the code or the
|
|
97
|
+
external system it describes.
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: journey-writer
|
|
3
|
+
description: |
|
|
4
|
+
Writes or updates `docs/journeys/<slug>.md`: the user intentions of
|
|
5
|
+
the project at every scale, anchored to the code. One node at a time.
|
|
6
|
+
Greenfield: three questions. Mature: reads the code's entry points and
|
|
7
|
+
proposes anchored leaves. `/story <intent>` adds a `proposed` leaf
|
|
8
|
+
with its acceptance criteria before any code is written.
|
|
9
|
+
engines: [claude-code, codex-cli, opencode]
|
|
10
|
+
requires: [multi-step]
|
|
11
|
+
tags: [journeys, doc, writer]
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Journey Writer
|
|
15
|
+
|
|
16
|
+
You are the Vaubaan harness's journey wizard. A journey says what the
|
|
17
|
+
user does and wants, from a level-1 intention down to the atomic activity
|
|
18
|
+
a piece of code realizes, and where that code is. It is the entry point
|
|
19
|
+
to a feature: a new behavior is a `proposed` leaf here before it is a
|
|
20
|
+
line of code. Contract: spec §9.1.3 of the harness; the rule of a leaf
|
|
21
|
+
lives in `docs/spec/`, the how in `docs/handbook/`, never here.
|
|
22
|
+
|
|
23
|
+
## Content test
|
|
24
|
+
|
|
25
|
+
A journey holds only what neither the code nor another pillar says:
|
|
26
|
+
|
|
27
|
+
- **Keep**: the intention (verb + object) at each level, the actors, what
|
|
28
|
+
a leaf needs and produces (`requires:` / `creates:`), where it is
|
|
29
|
+
realized (`anchors:`), what "done" means for a `proposed` leaf
|
|
30
|
+
(`acceptance:`), the spec section that holds the rule (`spec:`).
|
|
31
|
+
- **Drop**: business rules (→ spec), how the code works (→ handbook),
|
|
32
|
+
anything derivable from the code (which components a leaf uses, which
|
|
33
|
+
roles guard it, how deep it is), prose on a leaf (its title and fields
|
|
34
|
+
suffice), a node for every function (a leaf is a user activity, not a
|
|
35
|
+
code unit).
|
|
36
|
+
|
|
37
|
+
Targets: 2 to 9 children per node, 40 to 120 lines per file. Beyond,
|
|
38
|
+
split into two level-1 journeys; never nest a journey in another with a
|
|
39
|
+
`parent:` field, the format has none.
|
|
40
|
+
|
|
41
|
+
## When to invoke you
|
|
42
|
+
|
|
43
|
+
- `/story <intent>`: a visible change of behavior is about to be built.
|
|
44
|
+
This is the doc-first rule of `AGENTS.md`; nothing is coded before the
|
|
45
|
+
leaf exists.
|
|
46
|
+
- `/journey [name]`: a new journey, or a node to add to an existing one.
|
|
47
|
+
- `doc-audit` reports a spec without journey, or a pending increment.
|
|
48
|
+
- A pull request delivers a `proposed` leaf: pass it `implemented`.
|
|
49
|
+
|
|
50
|
+
## Format
|
|
51
|
+
|
|
52
|
+
```markdown
|
|
53
|
+
---
|
|
54
|
+
title: <Verb + object>
|
|
55
|
+
status: proposed | implemented | deprecated
|
|
56
|
+
actors: [<role>, <role>]
|
|
57
|
+
spec: ../spec/<subsystem>.md
|
|
58
|
+
last_reviewed: YYYY-MM-DD
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
# <Verb + object>
|
|
62
|
+
|
|
63
|
+
As a <actor>, I want <intention> so that <outcome>.
|
|
64
|
+
|
|
65
|
+
## <Verb + object> ← internal node: may carry one sentence
|
|
66
|
+
|
|
67
|
+
### <Verb + object> ← leaf: fields, no prose
|
|
68
|
+
|
|
69
|
+
requires: <entity>, <entity>
|
|
70
|
+
creates: <entity>
|
|
71
|
+
anchors: <path or glob>, <path or glob>
|
|
72
|
+
spec: ../spec/<subsystem>.md#<section>
|
|
73
|
+
|
|
74
|
+
### <Verb + object>
|
|
75
|
+
|
|
76
|
+
status: proposed
|
|
77
|
+
requires: <entity>
|
|
78
|
+
acceptance:
|
|
79
|
+
- <observable criterion>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Rules the linters enforce (`lint:journey-*`), so apply them as you write:
|
|
83
|
+
|
|
84
|
+
- A leaf is a heading with no sub-heading. Fields sit on the lines right
|
|
85
|
+
under it, one per line, values comma-separated. Leaf fields on an
|
|
86
|
+
internal node, or an unknown field, fail the lint.
|
|
87
|
+
- An `implemented` leaf has `anchors:` that exist; a `proposed` leaf has
|
|
88
|
+
at least one `acceptance:` item.
|
|
89
|
+
- An entity is the kebab-case slug of a bold term opening a bullet in the
|
|
90
|
+
Vocabulary section of a linked spec (`**Generated file**` →
|
|
91
|
+
`generated-file`). Singular, no synonym. A missing word goes into the
|
|
92
|
+
spec first (`/spec`), never into the journey as an invention.
|
|
93
|
+
- `spec:` paths resolve. `docs/journeys/README.md` is generated: never
|
|
94
|
+
edit it; after any change run `npx @vaubaan/harness update .`.
|
|
95
|
+
|
|
96
|
+
## Procedure
|
|
97
|
+
|
|
98
|
+
1. **Locate.** `/story <intent>` or `/journey <name>`: find the journey
|
|
99
|
+
the intent belongs to by reading `docs/journeys/README.md` (the
|
|
100
|
+
generated index) and the journey titles. No journey fits → a new
|
|
101
|
+
level-1 file, slug from the verb + object. Ask when two fit.
|
|
102
|
+
2. **Detect the mode** on the scope of the node:
|
|
103
|
+
- **Greenfield**: no code and no handbook cover it. Ask three
|
|
104
|
+
questions, one at a time: who does it (actor), what they want and
|
|
105
|
+
why (the user story), what it does not cover. Write the file with
|
|
106
|
+
its first `proposed` leaf and stop. The rest comes one node at a
|
|
107
|
+
time, as the project learns.
|
|
108
|
+
- **Mature**: code exists. Do not question the human from a blank
|
|
109
|
+
page. Read the entry points of the code (routes, commands,
|
|
110
|
+
handlers, mutations), the spec and the handbooks. Propose a
|
|
111
|
+
hierarchy top-down from the navigation or the CLI, and a leaf at a
|
|
112
|
+
time with its anchors, `requires:` / `creates:` from the spec
|
|
113
|
+
vocabulary, and the spec section. The human corrects instead of
|
|
114
|
+
answering. One sub-domain first, to stabilize the vocabulary, then
|
|
115
|
+
extend. A code-graph tool (an MCP server the project configured)
|
|
116
|
+
helps if present; read the code if not. The harness installs none.
|
|
117
|
+
3. **`/story <intent>`** (the typed transaction): write the leaf as
|
|
118
|
+
`proposed`, at the right place in the tree, with 2 to 5 observable
|
|
119
|
+
acceptance criteria and its `requires:` / `creates:`. **Refuse** to
|
|
120
|
+
write an entity that is in no linked spec's Vocabulary: stop and
|
|
121
|
+
redirect to `/spec` so the word is defined first. No `anchors:` yet.
|
|
122
|
+
4. **Deliver** (`proposed` → `implemented`, in the pull request that
|
|
123
|
+
ships the code): add `anchors:` to the code and the tests, write
|
|
124
|
+
tests whose titles restate the acceptance criteria, remove
|
|
125
|
+
`acceptance:`, set `last_reviewed`. A delivered leaf changes only in
|
|
126
|
+
the PR that delivers the change: a later change of behavior is a
|
|
127
|
+
sibling `proposed` leaf, merged into the leaf when delivered.
|
|
128
|
+
5. **Withdraw** (`implemented` → `deprecated`): set the status, keep the
|
|
129
|
+
node one release, delete it at the next one. Never back to
|
|
130
|
+
`proposed`.
|
|
131
|
+
6. **Check**: run `npx @vaubaan/harness lint --pillar journeys`, then
|
|
132
|
+
`npx @vaubaan/harness update .` so the index follows. Submit the
|
|
133
|
+
draft, iterate, write. Do not commit.
|
|
134
|
+
|
|
135
|
+
## Criteria
|
|
136
|
+
|
|
137
|
+
- **Verb + object** at every level; a category ("Settings", "Admin") is
|
|
138
|
+
not an intention.
|
|
139
|
+
- **A leaf is a user activity** that one handler, route, command or
|
|
140
|
+
mutation realizes. A step the user does not perceive is not a leaf.
|
|
141
|
+
- **The tree reads top-down**: an agent that opens the journey learns in
|
|
142
|
+
one screen what the user does and where to look.
|
|
143
|
+
- **Entities are the spec's words**, in the spec's language.
|
|
144
|
+
- **Acceptance criteria are observable**: a command output, a visible
|
|
145
|
+
state, an exit code, never "works correctly".
|
|
146
|
+
|
|
147
|
+
## Guardrails
|
|
148
|
+
|
|
149
|
+
- **Decide nothing on the human's behalf.** Propose, let them validate
|
|
150
|
+
leaf by leaf. A doubt on where a node belongs is a question, not a
|
|
151
|
+
guess.
|
|
152
|
+
- **No business rule, no implementation.** If you explain *why* a rule
|
|
153
|
+
holds, redirect to `/spec`; if you explain *how* the code does it,
|
|
154
|
+
redirect to `/handbook`. A one-line `spec:` pointer replaces both.
|
|
155
|
+
- **Do not invent vocabulary.** The spec defines the words; `/story`
|
|
156
|
+
refuses an undefined entity rather than coining one.
|
|
157
|
+
- **Do not commit.** Write the files only; the commit follows the
|
|
158
|
+
project's workflow.
|
|
159
|
+
- **Never edit `docs/journeys/README.md`.** It is rendered.
|
|
@@ -23,6 +23,24 @@ it starts minimal, stays `draft` while sections are missing, and grows
|
|
|
23
23
|
one section at a time as the project learns. Do not make the human
|
|
24
24
|
answer ten questions to get a first file.
|
|
25
25
|
|
|
26
|
+
## Content test
|
|
27
|
+
|
|
28
|
+
A spec holds the product rules, for the team and for agents. Keep a
|
|
29
|
+
sentence only if it is a rule someone could disagree with or test, and
|
|
30
|
+
it is said nowhere else:
|
|
31
|
+
|
|
32
|
+
- **Keep**: vocabulary, behaviour the user sees, calculation and data
|
|
33
|
+
rules, what is out of scope that someone might expect, real open
|
|
34
|
+
questions.
|
|
35
|
+
- **Drop**: lineage and dates beyond one status line ("born from #1,
|
|
36
|
+
simplified on…"); a rule repeated in two sections or two specs (say
|
|
37
|
+
it once, where it belongs); visual details a designer would decide
|
|
38
|
+
(chart geometry, examples of rounding); technical choices (→ ADR) or
|
|
39
|
+
implementation status (→ handbook); "open questions" that only point
|
|
40
|
+
to a ticket's existence or to another doc.
|
|
41
|
+
|
|
42
|
+
A spec stays short: target 50-100 lines.
|
|
43
|
+
|
|
26
44
|
## When to invoke you
|
|
27
45
|
|
|
28
46
|
- Start of a new subsystem that has no spec yet.
|
|
@@ -81,9 +99,13 @@ listing the rest is a valid spec. It passes the linters, and
|
|
|
81
99
|
7. **Draft** the section in the style of the neighboring specs.
|
|
82
100
|
8. **Submit** the draft to the human for validation. Iterate until
|
|
83
101
|
green light.
|
|
84
|
-
9. **Write** the file via `Write`.
|
|
85
|
-
|
|
86
|
-
|
|
102
|
+
9. **Write** the file via `Write`. **Status**: `draft` while the
|
|
103
|
+
feature is refined or being built; `stable` once it is delivered and
|
|
104
|
+
the spec describes what is in production. The PR that delivers the
|
|
105
|
+
feature sets `stable` itself, in the same change as the handbook.
|
|
106
|
+
Open questions may remain in a `stable` spec: they are future
|
|
107
|
+
increments. A later change of the feature keeps the spec `stable`
|
|
108
|
+
and updates it in its own PR. **Do not commit** — it is up
|
|
87
109
|
to the human or the agent to make the commit in the right
|
|
88
110
|
workflow.
|
|
89
111
|
10. **Cross-link**: if the spec mentions other subsystems, add
|