@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
@@ -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 Next.js, no Supabase, no code blocks. The technical *how* lives in
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 (a `packages/<name>/` that does not have a
24
- spec yet).
46
+ - Start of a new subsystem that has no spec yet.
25
47
  - `/spec <name>` invoked by the human.
26
- - `planning` agent that detects (via `doc-audit`) a missing spec.
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. **Read**: if the file already exists, read it in full and identify
35
- the sections that deserve an update (vs starting from scratch).
36
- 3. **Read neighboring specs** under `docs/spec/` to draw on the house
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
- 4. **Load the template** `@vaubaan/harness/templates/spec.md.tmpl` if
85
+ 5. **Load the template** `@vaubaan/harness/templates/spec.md.tmpl` if
39
86
  it is a new file.
40
- 5. **Core questions** to ask the human (one at a time or in a batch,
41
- depending on the complexity of the subject):
42
- - What is the subsystem's *one-liner*?
43
- - What are the **3-9 vocabulary words** specific to this domain?
44
- Define them.
45
- - What is the **vision** (3-5 bullets): what must the subsystem
46
- do, for whom, at what level of abstraction?
47
- - What is **explicitly out of scope**? (very important — the "what
48
- we don't do" section prevents later drift).
49
- - What is the **domain hierarchy** (core entities, their
50
- relations, their states if they are stateful)?
51
- - What is the expected **filesystem / API layout** (without
52
- implementation details — just the external shape)?
53
- - What **cross-cutting constraints** (security, perf, compat)?
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
- 8. **Write** the final file via `Write`. **Do not commit** — it is up
69
- to the human or the `coding` agent to make the commit in the right
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
- 9. **Cross-link**: if the spec mentions other subsystems, add relative
72
- links (`../spec/<other>.md`).
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**. None of these words in the spec:
77
- `Next.js`, `Supabase`, `Vercel`, `React`, `TypeScript`, `npm`,
78
- `Docker`, `PostgreSQL`, lib names, code file paths, code blocks. If
79
- a technical notion is central to the design, abstract it: "isolated
80
- container" rather than naming the runtime, "relational store" rather
81
- than "PostgreSQL".
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 can (and should)
90
- declare its uncertainties in an "Open questions" section rather than
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 complete `docs/spec/<name>.md` file, minimal frontmatter:
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 — what the subsystem does, for whom, under what core
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
- ### 2.3 States (if applicable)
167
+ ## 3. Format / Layout (optional while draft)
130
168
 
131
- ## 3. Format / Layout
169
+ ## 4. Composition (optional while draft)
132
170
 
133
- ## 4. Composition
171
+ ## 5. Security (optional while draft)
134
172
 
135
- ## 5. Security
173
+ ## 6. Tests (optional while draft)
136
174
 
137
- ## 6. Tests
175
+ ## 7. Open questions
138
176
 
139
- ## 7. v1 decisions & open questions
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
- `coding` or `planning` agent that invokes you.
156
- - **No technology**. If the exchange converges on a technology choice
157
- (`Next.js`, `Supabase`, …), stop the wizard and redirect to
158
- `decision-record-writer` (`/decision`). A technology choice is an
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`. Detects scenarios not yet listed from the
6
- existing test code and offers to document them. Maintains the
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 `coding` agent adds / modifies an integration or E2E test →
35
+ - The agent adds / modifies an integration or E2E test →
23
36
  update the corresponding test plan.
24
- - The `planning` agent detects (via `doc-audit`) that a spec has no
25
- associated test scenario → add the missing scenario.
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
- - Parse the `describe()` / `test()` / `it()` titles to extract the
43
- covered scenarios.
44
- 3. **Read the existing plan** if it exists. Compare the list extracted
45
- from the code vs the documented list. Flag:
46
- - Scenarios in the code but not in the plan → add.
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 that should be covered by at least one
51
- scenario. Spec without a test plan = `doc-audit` warning.
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
- - **Covered scenarios**: structured list. Each scenario mentions
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**: for `integration-tests.md`, typically
65
- the test file paths; for `e2e-tests.md`, the Playwright files + E2E
66
- CI configs.
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. No scenario appears in both
80
- files.
81
- - **Each scenario traced to a spec or a handbook**. Format:
82
- `> Covers: docs/spec/<name>.md §X` or `[[spec-<name>]]`. Without a
83
- cross-link, `doc-audit` flags the spec as "without a test plan".
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 scenarios.
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 reinvent the tests**. You document what *exists* in the
164
- test code, plus the identified gaps. You do not pre-write scenarios
165
- that have no corresponding code (except in the "Known gaps"
166
- section).
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 *all* test files in scope, plus
173
- the configs (`vitest.config.ts`, `playwright.config.ts`, E2E CI
174
- workflow). Without that, drift detection misses changes.
175
- - **Do not remove a scenario without confirmation**. If you detect
176
- that a documented scenario no longer exists in the code, propose two
177
- options: (a) remove it; (b) mark it "Known gap — regression to
178
- investigate". Let the human decide.
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 `coding` or `merge` agent modifies a CI workflow, a deployment
23
- config, or a `package.json` script → update the workflow doc.
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**: which workflows run on which events (`push`,
45
- `pull_request`, `schedule`), which jobs are required to merge,
46
- typical duration, rejection points.
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). The code audit (`/clean-code`)
6
- reads it before any other context.
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
- # <DECISION_TITLE>
2
-
3
- - **Date:** <DATE>
4
- - **Author:** <AUTHOR>
5
- - **Status:** <PROPOSED | ACCEPTED | SUPERSEDED | DEPRECATED>
6
- - **Supersedes:** <PREVIOUS_ADR_SLUG | none>
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
- Describe the situation that makes this decision necessary. What problem
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
- State the chosen decision in one to three clear sentences. No
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
- List the expected effects of the decision, positive **and** negative.
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
- List the options seriously considered that were not chosen,
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
- Rejected because: <REJECTION_REASON_B>.
33
+ <1-2 sentences: what it is, why not in this project.>