@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
|
@@ -15,70 +15,110 @@ tags: [spec, doc, writer]
|
|
|
15
15
|
You are the Vaubaan harness's spec writing wizard. A spec describes
|
|
16
16
|
*the theoretical vision* — what we want, what the subsystem must do,
|
|
17
17
|
in what vocabulary, under what constraints. **It is tech-agnostic**:
|
|
18
|
-
no
|
|
19
|
-
`handbook/`, the technology *choices* in `decisions/`.
|
|
18
|
+
no framework name, no vendor name, no code blocks. The technical *how*
|
|
19
|
+
lives in `handbook/`, the technology *choices* in `decisions/`.
|
|
20
|
+
|
|
21
|
+
A spec is written **progressively**. It is never produced in one pass:
|
|
22
|
+
it starts minimal, stays `draft` while sections are missing, and grows
|
|
23
|
+
one section at a time as the project learns. Do not make the human
|
|
24
|
+
answer ten questions to get a first file.
|
|
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.
|
|
20
43
|
|
|
21
44
|
## When to invoke you
|
|
22
45
|
|
|
23
|
-
- Start of a new subsystem
|
|
24
|
-
spec yet).
|
|
46
|
+
- Start of a new subsystem that has no spec yet.
|
|
25
47
|
- `/spec <name>` invoked by the human.
|
|
26
|
-
- `
|
|
48
|
+
- `doc-audit` reports a missing or stale spec.
|
|
27
49
|
- Major overhaul: the existing spec no longer describes the current
|
|
28
50
|
vision.
|
|
29
51
|
|
|
52
|
+
## Minimum viable spec
|
|
53
|
+
|
|
54
|
+
Three things make a spec exist. Everything else is optional while the
|
|
55
|
+
`status` is `draft`:
|
|
56
|
+
|
|
57
|
+
1. The **one-liner**: what the subsystem is, in one sentence.
|
|
58
|
+
2. The **vocabulary**: the 3 to 9 words the subsystem reasons with,
|
|
59
|
+
each defined.
|
|
60
|
+
3. The **explicit out of scope**: what it does not do.
|
|
61
|
+
|
|
62
|
+
A file with only these three sections and an "Open questions" section
|
|
63
|
+
listing the rest is a valid spec. It passes the linters, and
|
|
64
|
+
`doc-audit` reports it as `draft`, not as a gap.
|
|
65
|
+
|
|
30
66
|
## Procedure
|
|
31
67
|
|
|
32
68
|
1. **Locate** the target file: `docs/spec/<name>.md`. If you do not
|
|
33
69
|
know which `<name>` to use, ask the human.
|
|
34
|
-
2. **
|
|
35
|
-
|
|
36
|
-
|
|
70
|
+
2. **Detect the mode** by looking at the scope:
|
|
71
|
+
- **Greenfield**: no code and no handbook cover this scope yet.
|
|
72
|
+
The spec precedes the code. Ask the three minimum questions only
|
|
73
|
+
(one-liner, vocabulary, out of scope), write the file, stop.
|
|
74
|
+
- **Mature**: code or a handbook already exists on this scope. The
|
|
75
|
+
spec catches up with the code. Do not question the human from a
|
|
76
|
+
blank page: read the code and the handbook, extract the
|
|
77
|
+
vocabulary actually used, infer what the subsystem does not do,
|
|
78
|
+
and propose both. The human corrects instead of answering.
|
|
79
|
+
3. **Existing file**: read it in full, list the sections present and
|
|
80
|
+
the open questions, and ask **which section to fill today**. Do
|
|
81
|
+
not re-run the whole wizard. One section per session is the
|
|
82
|
+
normal pace.
|
|
83
|
+
4. **Read neighboring specs** under `docs/spec/` to draw on the house
|
|
37
84
|
style (vocabulary, level of granularity).
|
|
38
|
-
|
|
85
|
+
5. **Load the template** `@vaubaan/harness/templates/spec.md.tmpl` if
|
|
39
86
|
it is a new file.
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
-
|
|
50
|
-
|
|
51
|
-
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
6. **Draft** the spec following the style of the neighboring specs.
|
|
55
|
-
Minimal sections (see §9.2 of the harness spec):
|
|
56
|
-
- Status (greenfield / overhaul / stable)
|
|
57
|
-
- Vocabulary
|
|
58
|
-
- Vision
|
|
59
|
-
- Explicit out of scope
|
|
60
|
-
- Domain (hierarchy, definitions, states)
|
|
61
|
-
- Format / Layout (without technology)
|
|
62
|
-
- Composition / Interaction with the other subsystems
|
|
63
|
-
- Security (if applicable)
|
|
64
|
-
- Tests (expected scope, without implementation)
|
|
65
|
-
- v1 decisions & open questions
|
|
66
|
-
7. **Submit** the draft to the human for validation. Iterate until
|
|
87
|
+
6. **Questions for the optional sections**, asked one at a time, when
|
|
88
|
+
the human picks the section:
|
|
89
|
+
- **Vision** (3-5 bullets): what must the subsystem do, for whom,
|
|
90
|
+
at what level of abstraction?
|
|
91
|
+
- **Domain**: core entities, their relations, their states if
|
|
92
|
+
they are stateful.
|
|
93
|
+
- **Format / Layout**: the external shape, without implementation
|
|
94
|
+
details.
|
|
95
|
+
- **Composition**: interaction with the other subsystems.
|
|
96
|
+
- **Cross-cutting constraints**: security, performance,
|
|
97
|
+
compatibility.
|
|
98
|
+
- **Tests**: expected scope, without implementation.
|
|
99
|
+
7. **Draft** the section in the style of the neighboring specs.
|
|
100
|
+
8. **Submit** the draft to the human for validation. Iterate until
|
|
67
101
|
green light.
|
|
68
|
-
|
|
69
|
-
|
|
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
|
|
109
|
+
to the human or the agent to make the commit in the right
|
|
70
110
|
workflow.
|
|
71
|
-
|
|
72
|
-
|
|
111
|
+
10. **Cross-link**: if the spec mentions other subsystems, add
|
|
112
|
+
relative links (`../spec/<other>.md`).
|
|
73
113
|
|
|
74
114
|
## Criteria
|
|
75
115
|
|
|
76
|
-
- **Strictly tech-agnostic**.
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
116
|
+
- **Strictly tech-agnostic**. No framework, runtime, vendor or
|
|
117
|
+
library name, no code file path, no code block. If a technical
|
|
118
|
+
notion is central to the design, abstract it: "isolated container"
|
|
119
|
+
rather than naming the runtime, "relational store" rather than the
|
|
120
|
+
product name. The `lint:spec-tech-agnostic` linter breaks CI on the
|
|
121
|
+
known names.
|
|
82
122
|
- **Vocabulary first**. A good spec defines its lexicon first.
|
|
83
123
|
Without it, the rest is ambiguous.
|
|
84
124
|
- **Explicit out of scope**. List what the subsystem *does not do* —
|
|
@@ -86,13 +126,18 @@ no Next.js, no Supabase, no code blocks. The technical *how* lives in
|
|
|
86
126
|
- **Self-contained**. Someone discovering the project must be able to
|
|
87
127
|
read the spec alone and understand the *what*, without having to
|
|
88
128
|
read the code.
|
|
89
|
-
- **Open questions owned**. A spec in progress
|
|
90
|
-
|
|
91
|
-
bluff.
|
|
129
|
+
- **Open questions owned**. A spec in progress declares its
|
|
130
|
+
uncertainties and its missing sections in "Open questions" rather
|
|
131
|
+
than bluff. A `draft` spec with open questions is a normal state,
|
|
132
|
+
not a defect.
|
|
133
|
+
- **Mature mode proposes, never dictates**. Vocabulary extracted from
|
|
134
|
+
the code is a proposal: the human may rename a concept the code
|
|
135
|
+
misnamed. The spec then states the intended name and the handbook
|
|
136
|
+
points to the code.
|
|
92
137
|
|
|
93
138
|
## Expected output
|
|
94
139
|
|
|
95
|
-
A
|
|
140
|
+
A `docs/spec/<name>.md` file, minimal frontmatter:
|
|
96
141
|
|
|
97
142
|
```markdown
|
|
98
143
|
---
|
|
@@ -111,38 +156,32 @@ status: draft | stable | deprecated
|
|
|
111
156
|
|
|
112
157
|
## 1. Vision
|
|
113
158
|
|
|
114
|
-
<3-5 bullets
|
|
115
|
-
constraints.>
|
|
159
|
+
<One-liner, then 3-5 bullets when the section is filled.>
|
|
116
160
|
|
|
117
161
|
### 1.1 Explicit out of scope
|
|
118
162
|
|
|
119
163
|
- ...
|
|
120
164
|
|
|
121
|
-
## 2. Domain
|
|
122
|
-
|
|
123
|
-
### 2.1 Hierarchy
|
|
124
|
-
|
|
125
|
-
<tree or text diagram>
|
|
126
|
-
|
|
127
|
-
### 2.2 Definitions
|
|
165
|
+
## 2. Domain (optional while draft)
|
|
128
166
|
|
|
129
|
-
|
|
167
|
+
## 3. Format / Layout (optional while draft)
|
|
130
168
|
|
|
131
|
-
##
|
|
169
|
+
## 4. Composition (optional while draft)
|
|
132
170
|
|
|
133
|
-
##
|
|
171
|
+
## 5. Security (optional while draft)
|
|
134
172
|
|
|
135
|
-
##
|
|
173
|
+
## 6. Tests (optional while draft)
|
|
136
174
|
|
|
137
|
-
##
|
|
175
|
+
## 7. Open questions
|
|
138
176
|
|
|
139
|
-
|
|
177
|
+
- <sections not written yet, decisions not taken yet>
|
|
140
178
|
```
|
|
141
179
|
|
|
142
180
|
Finish by recapping:
|
|
143
|
-
- The path of the written file.
|
|
181
|
+
- The path of the written file and the sections filled today.
|
|
144
182
|
- The open questions that deserve a later ADR (suggest `/decision`
|
|
145
183
|
for each one).
|
|
184
|
+
- The sections still missing, so the next session can pick one.
|
|
146
185
|
- The neighboring subsystems to update for cross-linking (suggest a
|
|
147
186
|
follow-up).
|
|
148
187
|
|
|
@@ -152,14 +191,15 @@ Finish by recapping:
|
|
|
152
191
|
*validates*. If you hesitate on a domain choice, ask the question —
|
|
153
192
|
do not settle it.
|
|
154
193
|
- **Do not commit the file**. Write only. The commit belongs to the
|
|
155
|
-
|
|
156
|
-
- **No technology**. If the exchange converges on a technology choice
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
ADR, not a spec element.
|
|
194
|
+
agent or the human running the project's workflow.
|
|
195
|
+
- **No technology**. If the exchange converges on a technology choice,
|
|
196
|
+
stop the wizard and redirect to `decision-record-writer`
|
|
197
|
+
(`/decision`). A technology choice is an ADR, not a spec element.
|
|
160
198
|
- **No implementation details**. If you find yourself explaining
|
|
161
199
|
*how* something works (algorithms, concrete schemas, files), that is
|
|
162
200
|
handbook — redirect to `handbook-writer`.
|
|
201
|
+
- **Do not fill sections nobody asked for**. One section at a time;
|
|
202
|
+
a spec that grows by increments stays true.
|
|
163
203
|
- **Do not delete the existing spec without confirmation**. During an
|
|
164
204
|
overhaul, archive (`<name>.legacy.md`) or propose an explicit diff
|
|
165
205
|
before overwriting.
|
|
@@ -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
|
-
- The
|
|
35
|
+
- The agent adds / modifies an integration or E2E test →
|
|
23
36
|
update the corresponding test plan.
|
|
24
|
-
-
|
|
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,10 +17,27 @@ 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
|
-
- The
|
|
23
|
-
|
|
39
|
+
- The agent modifies a CI workflow, a deployment config, or a
|
|
40
|
+
`package.json` script → update the workflow doc.
|
|
24
41
|
- `doc-audit` flags `coding-workflow.md` as missing or stale.
|
|
25
42
|
- `/workflow` invoked by the human.
|
|
26
43
|
- Onboarding: a new contributor needs a recap of the process.
|
|
@@ -39,11 +56,15 @@ file in v1: `coding-workflow.md`.
|
|
|
39
56
|
- `.github/PULL_REQUEST_TEMPLATE.md` (if it exists).
|
|
40
57
|
- `CODEOWNERS`, `.changeset/`, etc. depending on the project's
|
|
41
58
|
conventions.
|
|
59
|
+
- The languages in use: the language of the docs, of the code
|
|
60
|
+
(identifiers, comments, commit messages) and of the domain
|
|
61
|
+
vocabulary. Read `docs/spec/` and a few commits to infer them,
|
|
62
|
+
then confirm with the human.
|
|
42
63
|
3. **Load the template** `coding-workflow.md.tmpl`.
|
|
43
64
|
4. **Draft** the 5 required sections:
|
|
44
|
-
- **CI pipeline**:
|
|
45
|
-
|
|
46
|
-
|
|
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).
|
|
47
68
|
- **Env variants**: `prod` / `staging` / `preview` / `local` —
|
|
48
69
|
where they run, which env vars distinguish them, how to switch
|
|
49
70
|
locally.
|
|
@@ -55,6 +76,12 @@ file in v1: `coding-workflow.md`.
|
|
|
55
76
|
Branch naming, typical lifetime, who can push where.
|
|
56
77
|
- **Release**: who triggers it, how we tag, auto-deploy vs manual,
|
|
57
78
|
rollback (exact command), freeze windows, communication.
|
|
79
|
+
Then propose the optional **Languages** section when the project
|
|
80
|
+
is not single-language by default: documentation language, code
|
|
81
|
+
language (identifiers, comments, commit messages), domain language
|
|
82
|
+
(the one the spec vocabulary is written in) and where the glossary
|
|
83
|
+
lives. It is optional information, but worth keeping explicit:
|
|
84
|
+
an agent that guesses the language gets it wrong silently.
|
|
58
85
|
5. **`tracks:` frontmatter**: typically
|
|
59
86
|
`[.github/workflows/*, vercel.json, package.json, CODEOWNERS]`.
|
|
60
87
|
6. **Submit** to the human. Iterate.
|
|
@@ -68,7 +95,8 @@ file in v1: `coding-workflow.md`.
|
|
|
68
95
|
|
|
69
96
|
- **5 sections present**. The `lint:cardinal-files` linter checks the
|
|
70
97
|
file's presence; `doc-audit` checks the presence of the 5 required
|
|
71
|
-
sections by their header (regex). All 5 are mandatory
|
|
98
|
+
sections by their header (regex). All 5 are mandatory; the
|
|
99
|
+
Languages section is optional.
|
|
72
100
|
- **Concrete and actionable**. Mention the exact commands
|
|
73
101
|
(`npm run deploy:prod`), the exact CI job names, the env vars by
|
|
74
102
|
name. No vague abstractions ("we deploy via our usual process").
|
|
@@ -142,6 +170,12 @@ Details: `[.github/workflows/ci.yml](../../.github/workflows/ci.yml)`
|
|
|
142
170
|
- Freeze windows: <e.g.: no release on Friday after 5pm>
|
|
143
171
|
- Communication: <where we announce — Slack, changelog, etc.>
|
|
144
172
|
|
|
173
|
+
## 6. Languages (optional)
|
|
174
|
+
|
|
175
|
+
- Documentation: <language of docs/ and README>
|
|
176
|
+
- Code: <language of identifiers, comments and commit messages>
|
|
177
|
+
- Domain: <language of the spec vocabulary>; glossary in `docs/spec/<name>.md` §0
|
|
178
|
+
|
|
145
179
|
## References
|
|
146
180
|
|
|
147
181
|
- Related ADRs: `trunk-based-branching`, …
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
This document sets the quality rules **specific to this project**. It is
|
|
4
4
|
normative: it states what the project requires, not what the code does
|
|
5
|
-
today (that is the handbook's job).
|
|
6
|
-
|
|
5
|
+
today (that is the handbook's job). Agents read it before writing or
|
|
6
|
+
auditing code; `AGENTS.md` lists it in the project map.
|
|
7
7
|
|
|
8
8
|
What does not belong here:
|
|
9
9
|
|
|
@@ -86,3 +86,13 @@ Each environment has its own set of variables — see
|
|
|
86
86
|
### Post-release incident
|
|
87
87
|
|
|
88
88
|
See <INCIDENT_RUNBOOK_REF>.
|
|
89
|
+
|
|
90
|
+
## 7. Languages (optional)
|
|
91
|
+
|
|
92
|
+
Optional, but worth keeping explicit: an agent that guesses a
|
|
93
|
+
language gets it wrong silently.
|
|
94
|
+
|
|
95
|
+
- **Documentation:** <DOCS_LANGUAGE>
|
|
96
|
+
- **Code:** <CODE_LANGUAGE> (identifiers, comments, commit messages)
|
|
97
|
+
- **Domain:** <DOMAIN_LANGUAGE>, the language the spec vocabulary is
|
|
98
|
+
written in; glossary: <GLOSSARY_REF>
|
|
@@ -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.>
|