@vaubaan/harness 2.0.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 +13 -15
- package/dist/cli/index.js +3 -3
- 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 +1 -1
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -2
- package/dist/init.js +3 -3
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +2 -2
- package/dist/linters/index.js.map +1 -1
- package/dist/render.js +2 -2
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +93 -130
- package/dist/skills/doc-audit.skill.md +3 -3
- package/dist/skills/drift-detector.skill.md +5 -6
- package/dist/skills/handbook-writer.skill.md +68 -159
- 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/package.json +1 -1
|
@@ -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.
|
|
@@ -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
|
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
id: test-plan-writer
|
|
3
3
|
description: |
|
|
4
4
|
Updates `docs/tests/integration-tests.md` and/or
|
|
5
|
-
`docs/tests/e2e-tests.md
|
|
6
|
-
|
|
7
|
-
`tracks: [...]` frontmatter for drift detection.
|
|
5
|
+
`docs/tests/e2e-tests.md` (scope, stack, conventions, known gaps).
|
|
6
|
+
Never lists the covered scenarios: the test code is their source of
|
|
7
|
+
truth. Maintains the `tracks: [...]` frontmatter for drift detection.
|
|
8
8
|
engines: [claude-code, codex-cli, opencode]
|
|
9
9
|
requires: [multi-step]
|
|
10
10
|
tags: [tests, doc, writer]
|
|
@@ -17,12 +17,25 @@ You are the Vaubaan harness's test plan writing wizard. The
|
|
|
17
17
|
required files: `integration-tests.md` and `e2e-tests.md`. Unit tests
|
|
18
18
|
live next to the code and do not need a separate plan.
|
|
19
19
|
|
|
20
|
+
The plans do **not** list the covered scenarios: the `describe()` /
|
|
21
|
+
`it()` titles of the test files already say what is tested, and a copy
|
|
22
|
+
in the docs only drifts. A plan documents what the code cannot tell:
|
|
23
|
+
the scope of the level, the stack, the conventions, and the known gaps.
|
|
24
|
+
|
|
25
|
+
The same rule applies to everything else: keep a sentence only if an
|
|
26
|
+
agent would not get it quickly from the code or another doc. Do not
|
|
27
|
+
restate what the runner config says (browsers, reporters, web server,
|
|
28
|
+
timeouts), what `docs/quality/code-quality.md` already says (file naming),
|
|
29
|
+
or placeholders ("to be defined"). Keep the *why* of a non-obvious choice,
|
|
30
|
+
the conventions that protect shared state, and the known gaps. Target 20-50
|
|
31
|
+
lines per plan, in bullets.
|
|
32
|
+
|
|
20
33
|
## When to invoke you
|
|
21
34
|
|
|
22
35
|
- The agent adds / modifies an integration or E2E test →
|
|
23
36
|
update the corresponding test plan.
|
|
24
|
-
- `doc-audit` shows that a spec has no associated test
|
|
25
|
-
|
|
37
|
+
- `doc-audit` shows that a spec has no associated test → add it to
|
|
38
|
+
the known gaps.
|
|
26
39
|
- `/test-plan [integration|e2e]` invoked by the human.
|
|
27
40
|
- Overhaul of the test scope: re-split integration vs e2e.
|
|
28
41
|
|
|
@@ -39,16 +52,14 @@ live next to the code and do not need a separate plan.
|
|
|
39
52
|
`**/*.int.test.ts`, or defined by the `package.json` scripts).
|
|
40
53
|
- For e2e: list `tests/e2e/`, `e2e/`, `playwright/`, or the
|
|
41
54
|
equivalent.
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
3. **Read the existing plan** if it exists.
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
- Scenarios in the plan but not in the code → mark as a "known
|
|
48
|
-
gap" or remove (ask the human).
|
|
55
|
+
- Use them to check that the documented stack and conventions
|
|
56
|
+
still match, not to copy the scenarios into the plan.
|
|
57
|
+
3. **Read the existing plan** if it exists. Flag the stack /
|
|
58
|
+
conventions statements the code contradicts, and known gaps that
|
|
59
|
+
are now covered by a test (→ remove, ask the human).
|
|
49
60
|
4. **Read the specs** under `docs/spec/` to identify the
|
|
50
|
-
subsystems/features
|
|
51
|
-
|
|
61
|
+
subsystems/features without any test at this level → known gap.
|
|
62
|
+
Spec neither tested nor listed as a gap = `doc-audit` warning.
|
|
52
63
|
5. **Load the appropriate template**.
|
|
53
64
|
6. **Draft** the required sections:
|
|
54
65
|
- **Scope**: what is tested at this level vs what is not
|
|
@@ -57,13 +68,11 @@ live next to the code and do not need a separate plan.
|
|
|
57
68
|
fixtures.
|
|
58
69
|
- **Conventions**: naming, file structure, shared fixtures,
|
|
59
70
|
cleanup.
|
|
60
|
-
- **
|
|
61
|
-
its source spec or handbook (`tracks` cross-link).
|
|
62
|
-
- **Known gaps**: scenarios identified as to be added, with
|
|
71
|
+
- **Known gaps**: what is not tested yet, with the linked spec,
|
|
63
72
|
priority and the reason for postponing.
|
|
64
|
-
7. **`tracks:` frontmatter**:
|
|
65
|
-
|
|
66
|
-
CI
|
|
73
|
+
7. **`tracks:` frontmatter**: the configs and test infrastructure the
|
|
74
|
+
plan describes (runner configs, shared fixtures, setup scripts, E2E
|
|
75
|
+
CI workflow) — not the individual test files.
|
|
67
76
|
8. **Submit** to the human. Iterate.
|
|
68
77
|
9. **Validate the `tracks:` before writing.** For each entry, check
|
|
69
78
|
that the path exists (file or matching glob). If not — it is
|
|
@@ -76,12 +85,11 @@ live next to the code and do not need a separate plan.
|
|
|
76
85
|
- **Clear integration vs E2E distinction**. Integration tests test the
|
|
77
86
|
interaction between several modules of the same process, with mocks
|
|
78
87
|
or in-memory DBs. E2E tests launch the full system (browser + live
|
|
79
|
-
backend + test DB) on golden paths.
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
- **Explicit known gaps**. Listing what we *do not test yet* is as
|
|
88
|
+
backend + test DB) on golden paths.
|
|
89
|
+
- **No covered-scenario list**. Not even a summary table: point to the
|
|
90
|
+
test files' location / naming convention instead.
|
|
91
|
+
- **Explicit known gaps**, each linked to its spec
|
|
92
|
+
(`docs/spec/<name>.md`). Listing what we *do not test yet* is as
|
|
85
93
|
important as listing what we test. Avoids false confidence.
|
|
86
94
|
- **E2E-specific conventions** (see harness spec §9.2): for
|
|
87
95
|
`e2e-tests.md`, document the e2e org (dedicated Stripe org /
|
|
@@ -96,7 +104,6 @@ live next to the code and do not need a separate plan.
|
|
|
96
104
|
---
|
|
97
105
|
title: Integration Tests Plan # or: E2E Tests Plan
|
|
98
106
|
tracks:
|
|
99
|
-
- packages/<name>/**/*.int.test.ts
|
|
100
107
|
- vitest.config.ts
|
|
101
108
|
- package.json
|
|
102
109
|
last_reviewed: YYYY-MM-DD
|
|
@@ -126,19 +133,6 @@ or e2e).>
|
|
|
126
133
|
- Dedicated test org / project: `<name>`
|
|
127
134
|
- Orphaned resource sweeper: `<script>`
|
|
128
135
|
|
|
129
|
-
## Covered scenarios
|
|
130
|
-
|
|
131
|
-
### <Subsystem / feature 1>
|
|
132
|
-
> Covers: docs/spec/<name>.md §X
|
|
133
|
-
|
|
134
|
-
- **scenario-name** — <1-line description>
|
|
135
|
-
- File: `path/to/test.int.test.ts`
|
|
136
|
-
- Setup: <precondition>
|
|
137
|
-
- Assert: <what is checked>
|
|
138
|
-
|
|
139
|
-
### <Subsystem / feature 2>
|
|
140
|
-
...
|
|
141
|
-
|
|
142
136
|
## Known gaps
|
|
143
137
|
|
|
144
138
|
- ⚠️ **<scenario-name>** (spec `<name>.md`) — not tested yet.
|
|
@@ -154,26 +148,25 @@ or e2e).>
|
|
|
154
148
|
|
|
155
149
|
Finish by:
|
|
156
150
|
- Listing the updated files.
|
|
157
|
-
- Listing the added / removed
|
|
151
|
+
- Listing the added / removed known gaps.
|
|
158
152
|
- Listing the specs still without tests (suggest a `/test-plan`
|
|
159
153
|
follow-up).
|
|
160
154
|
|
|
161
155
|
## Guardrails
|
|
162
156
|
|
|
163
|
-
- **Do not
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
- **No integration ↔ e2e duplication**. A scenario belongs to a
|
|
157
|
+
- **Do not duplicate the tests**. Scenarios live in the test code
|
|
158
|
+
only; the plan never lists them (only the untested ones, under
|
|
159
|
+
"Known gaps").
|
|
160
|
+
- **No integration ↔ e2e duplication**. A known gap belongs to a
|
|
168
161
|
single file. If you hesitate, ask the human.
|
|
169
162
|
- **No unit docs here**. Unit tests live next to the code and speak
|
|
170
163
|
for themselves. If someone asks to document them here, push back:
|
|
171
164
|
this is not the pillar.
|
|
172
|
-
- **Exhaustive `tracks:`**. Include
|
|
173
|
-
the
|
|
174
|
-
workflow). Without that,
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
165
|
+
- **Exhaustive `tracks:`**. Include every config and piece of test
|
|
166
|
+
infrastructure the plan describes (`vitest.config.ts`,
|
|
167
|
+
`playwright.config.ts`, fixtures, E2E CI workflow). Without that,
|
|
168
|
+
drift detection misses changes.
|
|
169
|
+
- **Do not remove a known gap without confirmation**. If a gap now
|
|
170
|
+
seems covered by a test, propose its removal and let the human
|
|
171
|
+
decide.
|
|
179
172
|
- **No auto-commit**.
|
|
@@ -17,6 +17,23 @@ You are the Vaubaan harness's workflow writing wizard. The
|
|
|
17
17
|
environment variants, PR process, branch model, release. One required
|
|
18
18
|
file in v1: `coding-workflow.md`.
|
|
19
19
|
|
|
20
|
+
## Content test
|
|
21
|
+
|
|
22
|
+
The doc is read by an agent about to change CI, deploy or the process.
|
|
23
|
+
Keep a sentence only if the agent would not get it quickly from the
|
|
24
|
+
configs or another doc:
|
|
25
|
+
|
|
26
|
+
- **Keep**: team conventions (PR, branches, commits), what lives outside
|
|
27
|
+
the repo (Vercel / Supabase / GitHub settings, integrations, secrets),
|
|
28
|
+
their traps, rollback, and the rules nobody can enforce mechanically.
|
|
29
|
+
- **Drop**: CI job steps, path lists, triggers or secrets readable in
|
|
30
|
+
`.github/workflows/`; rules already in `AGENTS.md` (language,
|
|
31
|
+
doc-first); architecture (→ ADR); feature config (→ handbook);
|
|
32
|
+
placeholders ("to be defined", "to be measured").
|
|
33
|
+
|
|
34
|
+
Target 60-100 lines, in bullets. The 5 required sections stay, even
|
|
35
|
+
short.
|
|
36
|
+
|
|
20
37
|
## When to invoke you
|
|
21
38
|
|
|
22
39
|
- The agent modifies a CI workflow, a deployment config, or a
|
|
@@ -45,9 +62,9 @@ file in v1: `coding-workflow.md`.
|
|
|
45
62
|
then confirm with the human.
|
|
46
63
|
3. **Load the template** `coding-workflow.md.tmpl`.
|
|
47
64
|
4. **Draft** the 5 required sections:
|
|
48
|
-
- **CI pipeline**:
|
|
49
|
-
|
|
50
|
-
|
|
65
|
+
- **CI pipeline**: link the workflows; state only which checks are
|
|
66
|
+
required, how to reproduce them locally, and the non-obvious
|
|
67
|
+
behaviours (conditional jobs, why a filter sits where it does).
|
|
51
68
|
- **Env variants**: `prod` / `staging` / `preview` / `local` —
|
|
52
69
|
where they run, which env vars distinguish them, how to switch
|
|
53
70
|
locally.
|
|
@@ -1,60 +1,33 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
---
|
|
2
|
+
title: <The decision in one sentence>
|
|
3
|
+
status: <accepted | proposed>
|
|
4
|
+
date: <DATE>
|
|
5
|
+
author: <AUTHOR>
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# <The decision in one sentence>
|
|
9
|
+
|
|
10
|
+
<!--
|
|
11
|
+
Only a structural decision: costly to reverse, a real alternative was
|
|
12
|
+
weighed, it outlives the ticket. About 40 lines, 60 at most. A decision
|
|
13
|
+
that changes is rewritten as a new file and the old one is deleted; the
|
|
14
|
+
old option goes to Rejected alternatives.
|
|
15
|
+
-->
|
|
7
16
|
|
|
8
17
|
## Context
|
|
9
18
|
|
|
10
|
-
|
|
11
|
-
are we solving? What constraints apply (technical, organizational,
|
|
12
|
-
time-related)? What signals triggered the discussion?
|
|
13
|
-
|
|
14
|
-
This section must be readable on its own: a reader discovering the
|
|
15
|
-
ADR six months later must understand why the question came up.
|
|
19
|
+
<2-4 sentences: the forces that made the choice necessary. No chronology.>
|
|
16
20
|
|
|
17
21
|
## Decision
|
|
18
22
|
|
|
19
|
-
|
|
20
|
-
"we will probably" — it is settled.
|
|
21
|
-
|
|
22
|
-
Then detail the conditions of application: scope, exceptions,
|
|
23
|
-
thresholds, effective dates.
|
|
23
|
+
<1-3 sentences in the present tense, stated as a rule.>
|
|
24
24
|
|
|
25
25
|
## Consequences
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
**Positive:**
|
|
30
|
-
|
|
31
|
-
- <POSITIVE_CONSEQUENCE_1>
|
|
32
|
-
- <POSITIVE_CONSEQUENCE_N>
|
|
33
|
-
|
|
34
|
-
**Negative:**
|
|
35
|
-
|
|
36
|
-
- <NEGATIVE_CONSEQUENCE_1>
|
|
37
|
-
- <NEGATIVE_CONSEQUENCE_N>
|
|
38
|
-
|
|
39
|
-
**Neutral / to watch:**
|
|
40
|
-
|
|
41
|
-
- <NEUTRAL_CONSEQUENCE_1>
|
|
27
|
+
- <constraint on future work>
|
|
42
28
|
|
|
43
29
|
## Rejected alternatives
|
|
44
30
|
|
|
45
|
-
|
|
46
|
-
with the reason for rejecting each one. This section is as important
|
|
47
|
-
as the decision itself — it avoids re-debating the same
|
|
48
|
-
alternatives later.
|
|
49
|
-
|
|
50
|
-
### Alternative A — <ALTERNATIVE_A_NAME>
|
|
51
|
-
|
|
52
|
-
<DESCRIPTION_A>
|
|
53
|
-
|
|
54
|
-
Rejected because: <REJECTION_REASON_A>.
|
|
55
|
-
|
|
56
|
-
### Alternative B — <ALTERNATIVE_B_NAME>
|
|
57
|
-
|
|
58
|
-
<DESCRIPTION_B>
|
|
31
|
+
### <Alternative>
|
|
59
32
|
|
|
60
|
-
|
|
33
|
+
<1-2 sentences: what it is, why not in this project.>
|