@vaubaan/harness 2.1.0 → 2.3.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 CHANGED
@@ -17,39 +17,61 @@ npx -y @vaubaan/harness init . --engines=claude-code
17
17
 
18
18
  A few Markdown files hold what the code cannot say and point to the code and configs for everything else. The harness renders them into the native layout of Claude Code, Codex or OpenCode, and lints them so context and code never drift apart.
19
19
 
20
- - **One context, every engine.** Eight skills, one per pillar plus an audit and a drift detector, each with a slash command. Written once for Claude Code, Codex and OpenCode.
21
- - **Pointers that stay true.** Handbooks and test plans declare the files they describe in a `tracks:` field. When that code moves and the doc does not, the linter says so.
22
- - **Checks with zero tokens.** Fifteen mechanical linters run in CI and in your pre-commit hook. No engine hook, no injected turn, no loop. The agent sees a failed command and fixes it.
23
-
24
- **Contents:**
25
- [The problem](#the-problem) · [A context database with pointers](#a-context-database-with-pointers) · [What it looks like](#what-it-looks-like) · [Quick start](#quick-start) ·
26
- [How it works](#how-it-works) · [What is included](#what-is-included) · [Adopting it on an existing project](#adopting-it-on-an-existing-project) · [Commands](#commands) ·
27
- [Configuration](#configuration) · [FAQ](#faq) · [Where this is going](#where-this-is-going) · [Documentation](#documentation)
20
+ - **One context, every engine.** Nine skills, one per pillar plus an audit and a drift detector, each with a slash command. Written once for Claude Code, Codex and OpenCode.
21
+ - **Pointers that stay true.** Handbooks, test plans and intents declare the files they describe. When that code moves and the doc does not, the linter says so.
22
+ - **Checks with zero tokens.** Nineteen mechanical linters run in CI and in your pre-commit hook. No engine hook, no injected turn, no loop. The agent sees a failed command and fixes it.
23
+
24
+ **Contents**
25
+
26
+ 1. [Two personas, one codebase, two databases](#two-personas-one-codebase-two-databases)
27
+ 2. [What it looks like](#what-it-looks-like)
28
+ 3. [Quick start](#quick-start)
29
+ 4. [Set up](#set-up): [start from scratch](#start-from-scratch) · [adopt an existing project](#adopt-it-on-an-existing-project) · [update the harness](#update-the-harness) · [back out](#back-out)
30
+ 5. [How it works](#how-it-works)
31
+ 6. [Day to day](#day-to-day): specify a change [without](#specify-a-change-without-a-ticketing-tool) or [from a ticket](#specify-a-change-from-a-ticket) · [deliver](#deliver-a-change) · [reassure yourself](#reassure-yourself) · [compact the docs](#compact-the-docs) · [fix or refactor](#fix-a-bug-refactor) · [decide](#take-a-structural-decision) · [come back](#come-back-to-a-project) · [change the workflow](#change-the-workflow)
32
+ 7. [For your agent](#for-your-agent): [reading order](#before-any-task-the-reading-order) · [decision tree](#the-decision-tree) · [what the user says, what the agent does](#what-the-user-says-what-the-agent-does) · [refusals](#the-refusals-the-agent-holds) · [end of task](#at-the-end-of-a-task-always)
33
+ 8. [What is included](#what-is-included): [skills](#skills) · [linters](#linters) · [engines](#engines)
34
+ 9. [Commands](#commands) · [Configuration](#configuration)
35
+ 10. [FAQ](#faq) · [Where this is going](#where-this-is-going)
36
+ 11. [Documentation](#documentation) · [Contributing](#contributing) · [License](#license)
28
37
 
29
38
  ---
30
39
 
31
- ## The problem
32
-
33
- A coding agent is fast and knows nothing about your project. So you repeat the same instructions in every session. You maintain a `CLAUDE.md`, an `AGENTS.md` and an OpenCode config that slowly disagree. The agent changes a behavior, the doc still describes the old one, and nobody notices until a teammate ships against the wrong assumption.
34
-
35
- The context of a project is real information: what you want, why it is built this way, how it actually works today, what "done" means, how you ship. It deserves a home, a shape, and a check.
36
-
37
- ## A context database with pointers
38
-
39
- The harness does one thing. It keeps your project's context in a small, fixed set of Markdown files, gives every agent the same entry point into it, and refuses to let it go stale.
40
+ ## Two personas, one codebase, two databases
41
+
42
+ You and your coding agents share a codebase. It holds two databases.
43
+
44
+ The **code database** is `src/`, the tests, the configs: what the machine runs. The **meta database** is `docs/`: what the code cannot say, kept in a small fixed set of Markdown files that point to the code for everything else. Both personas read and write both. You decide, validate and merge; the agent writes docs and code with judgment; the harness is the schema of the meta database, its integrity constraints and its views.
45
+
46
+ ```mermaid
47
+ flowchart LR
48
+ H["You<br/>decide, validate, merge"]
49
+ A["Your coding agents<br/>write docs and code"]
50
+ subgraph CB["one repository"]
51
+ direction TB
52
+ CODE["code database<br/>src · tests · configs"]
53
+ META["meta database<br/>docs/ and its rendered views"]
54
+ META -- "tracks · anchors · realized by" --> CODE
55
+ end
56
+ X["harness<br/>schema · 19 constraints · views"]
57
+ H <--> CB
58
+ A <--> CB
59
+ X -. "keeps the meta database consistent<br/>with itself and with the code" .-> META
60
+ ```
40
61
 
41
62
  Each pillar stores one kind of information the code cannot carry, and links to the code or config that carries the rest. Nothing is written twice: if a paragraph could be deleted without losing anything that is not in the files it points to, it does not belong in the doc.
42
63
 
43
- | Pillar | What the doc says (the code cannot) | What it points to in the repo |
44
- | ----------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
45
- | `README.md` | What this is, how to run it. | `package.json` scripts, the quick start. |
46
- | `docs/spec/` | What we want, for whom, what we refuse to do. Vocabulary. Tech-agnostic. | The modules and entry points that realize each requirement. A requirement with no pointer is a todo or dead. |
47
- | `docs/decisions/` | The structural choices in force: why, and what was rejected. | The config files and commits that embody the decision: `tsconfig.json`, `ci.yml`, a sha. |
48
- | `docs/handbook/` | The map: where to look, the invariants the code assumes, the gotchas. | The files it describes, declared in `tracks:`. A map, not a retelling. |
49
- | `docs/tests/` | Test scope, stack, conventions, known gaps. Never the covered scenarios. | The test files: their titles say what is covered. A spec with no test is a known gap. |
50
- | `docs/workflow/` | What lives outside the repo: approvals, protections, secrets, languages. | `ci.yml`, build scripts, pre-commit hook. |
51
- | `docs/quality/` | Optional. The code rules this team holds, and the deviations it accepts. | The linter and formatter configs that enforce the mechanical part. |
52
- | `docs/skills/` | Optional. Domain know-how the agent should load. | Whatever the skill needs. |
64
+ | Pillar | What the doc says (the code cannot) | What it points to in the repo |
65
+ | ----------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
66
+ | `README.md` | What this is, how to run it. | `package.json` scripts, the quick start. |
67
+ | `docs/spec/` | What we want, for whom, what we refuse to do. Vocabulary. Tech-agnostic. | The modules and entry points that realize each requirement. A requirement with no pointer is a todo or dead. |
68
+ | `docs/decisions/` | The structural choices in force: why, and what was rejected. | The config files and commits that embody the decision: `tsconfig.json`, `ci.yml`, a sha. |
69
+ | `docs/handbook/` | The map: where to look, the invariants the code assumes, the gotchas. | The files it describes, declared in `tracks:`. A map, not a retelling. |
70
+ | `docs/tests/` | Test scope, stack, conventions, known gaps. Never the covered scenarios. | The test files: their titles say what is covered. A spec with no test is a known gap. |
71
+ | `docs/workflow/` | What lives outside the repo: approvals, protections, secrets, languages. | `ci.yml`, build scripts, pre-commit hook. |
72
+ | `docs/quality/` | Optional. The code rules this team holds, and the deviations it accepts. | The linter and formatter configs that enforce the mechanical part. |
73
+ | `docs/skills/` | Optional. Domain know-how the agent should load. | Whatever the skill needs. |
74
+ | `docs/intents/` | Optional. What the user wants, at every scale, as one tree of intents anchored to the code. An OKR tree the repo keeps true. | Each terminal intent's `anchors:`; `requires:` / `creates:` name the spec vocabulary. |
53
75
 
54
76
  > [!IMPORTANT]
55
77
  > **One rule.** The only working rule the harness imposes, written into `AGENTS.md` for every engine: **understand the context, fill the gaps, code, update the context, commit.**
@@ -65,22 +87,40 @@ acme-billing/
65
87
  ├── README.md
66
88
  ├── AGENTS.md # rendered: the one rule, the map, the checks
67
89
  ├── CLAUDE.md # rendered: @AGENTS.md
68
- ├── .claude/ .agents/ .opencode/ # rendered: skills and commands per engine
90
+ ├── .claude/ # rendered: for Claude Code
91
+ │ ├── skills/
92
+ │ └── commands/
93
+ ├── .agents/
94
+ │ └── skills/ # rendered: for Codex
95
+ ├── .opencode/ # rendered: for OpenCode
96
+ │ ├── skills/
97
+ │ └── commands/
69
98
  ├── .harness-manifest.json # rendered: what the harness owns
70
99
  └── docs/
71
- ├── spec/invoicing.md
72
- ├── decisions/postgres-over-sqlite.md
73
- ├── handbook/invoice-pipeline.md
74
- ├── tests/integration-tests.md
75
- ├── tests/e2e-tests.md
76
- ├── workflow/coding-workflow.md
77
- ├── quality/code-quality.md # optional
78
- └── skills/tax-rules.skill.md # optional
100
+ ├── spec/
101
+ │ └── invoicing.md
102
+ ├── decisions/
103
+ │ └── postgres-over-sqlite.md
104
+ ├── handbook/
105
+ │ └── invoice-pipeline.md
106
+ ├── tests/
107
+ │ ├── integration-tests.md
108
+ │ └── e2e-tests.md
109
+ ├── workflow/
110
+ │ └── coding-workflow.md
111
+ ├── quality/ # optional
112
+ │ └── code-quality.md
113
+ ├── intents/ # optional
114
+ │ ├── send-an-invoice.md
115
+ │ └── README.md # rendered: the intent tree
116
+ └── skills/ # optional
117
+ └── tax-rules.skill.md
79
118
  ```
80
119
 
81
120
  Each file says what the code cannot, and points to the code for the rest.
82
121
 
83
- **`docs/spec/invoicing.md`**: intent and vocabulary, no technology, each requirement realized by something.
122
+ <details>
123
+ <summary><code>docs/spec/invoicing.md</code>: intent and vocabulary, no technology, each requirement realized by something.</summary>
84
124
 
85
125
  ```markdown
86
126
  ---
@@ -102,8 +142,10 @@ status: draft
102
142
  ## N. Open questions
103
143
  - Multi-currency: not before a customer asks.
104
144
  ```
145
+ </details>
105
146
 
106
- **`docs/decisions/postgres-over-sqlite.md`**: one structural decision in force, about 40 lines: the why and the rejected options. When you change your mind, a new file replaces it; git holds the rest.
147
+ <details>
148
+ <summary><code>docs/decisions/postgres-over-sqlite.md</code>: one structural decision in force, about 40 lines: the why and the rejected options. When you change your mind, a new file replaces it; git holds the rest.</summary>
107
149
 
108
150
  ```markdown
109
151
  # Postgres over SQLite for the invoice store
@@ -122,8 +164,10 @@ Local setup needs Docker. Migrations live in `db/migrations/`.
122
164
  ### SQLite
123
165
  Where it started; its single-writer lock lost a write under two workers.
124
166
  ```
167
+ </details>
125
168
 
126
- **`docs/handbook/invoice-pipeline.md`**: the map, declared with `tracks:` so the linter notices when the code moves.
169
+ <details>
170
+ <summary><code>docs/handbook/invoice-pipeline.md</code>: the map, declared with <code>tracks:</code> so the linter notices when the code moves.</summary>
127
171
 
128
172
  ```markdown
129
173
  ---
@@ -143,8 +187,10 @@ enforced in `src/invoicing/guards.ts#assertOwner`, not in the database.
143
187
  Gotcha: `void.ts` keeps the row and flips `status`; reports must filter
144
188
  on it (`src/reports/monthly.ts`).
145
189
  ```
190
+ </details>
146
191
 
147
- **`docs/tests/integration-tests.md`**: scope, stack, conventions and known gaps. The covered scenarios are the test titles, never copied here.
192
+ <details>
193
+ <summary><code>docs/tests/integration-tests.md</code>: scope, stack, conventions and known gaps. The covered scenarios are the test titles, never copied here.</summary>
148
194
 
149
195
  ```markdown
150
196
  ---
@@ -157,8 +203,10 @@ One database per worker (`fixtures/db.ts`); never share a draft across tests.
157
203
  ## Known gaps
158
204
  - ⚠️ Two workers issuing the same draft (spec invoicing §3) — not tested yet.
159
205
  ```
206
+ </details>
160
207
 
161
- **`docs/workflow/coding-workflow.md`**: what lives outside the repo, and pointers to what lives in it.
208
+ <details>
209
+ <summary><code>docs/workflow/coding-workflow.md</code>: what lives outside the repo, and pointers to what lives in it.</summary>
162
210
 
163
211
  ```markdown
164
212
  ---
@@ -173,8 +221,10 @@ Tag `v*` triggers `publish.yml`. Secrets live in the GitHub environment `prod`.
173
221
  ## Languages
174
222
  Docs and code in English. Domain vocabulary in spec §0, French-speaking team.
175
223
  ```
224
+ </details>
176
225
 
177
- **`docs/quality/code-quality.md`** (optional): the rules a tool cannot check, and the deviations you accept.
226
+ <details>
227
+ <summary><code>docs/quality/code-quality.md</code> (optional): the rules a tool cannot check, and the deviations you accept.</summary>
178
228
 
179
229
  ```markdown
180
230
  ## Mechanical checks
@@ -184,8 +234,10 @@ No business logic in route handlers; it lives in `src/invoicing/`.
184
234
  ## Accepted deviations
185
235
  `any` allowed in `src/legacy/csv-import.ts` until it is rewritten.
186
236
  ```
237
+ </details>
187
238
 
188
- **`docs/skills/tax-rules.skill.md`** (optional): know-how the agent loads, rendered like the built-in skills.
239
+ <details>
240
+ <summary><code>docs/skills/tax-rules.skill.md</code> (optional): know-how the agent loads, rendered like the built-in skills.</summary>
189
241
 
190
242
  ```markdown
191
243
  ---
@@ -195,6 +247,7 @@ description: How VAT rates are chosen and where they live.
195
247
  Rates are in `config/vat.json`, keyed by country. Never hardcode a rate;
196
248
  add a key and a fixture in `tests/fixtures/vat/`.
197
249
  ```
250
+ </details>
198
251
 
199
252
  ## Quick start
200
253
 
@@ -254,36 +307,460 @@ jobs:
254
307
  /doc-audit # what is missing or stale
255
308
  /spec # write the spec of a subsystem, guided
256
309
  /decision # turn an implicit choice into an ADR
310
+ /intent <what> # a proposed intent with acceptance criteria, before the code
257
311
  ```
258
312
 
259
313
  > [!NOTE]
260
314
  > Already have a hand-written `AGENTS.md` or `CLAUDE.md`? `init` never overwrites a file it did not write. See [adopting it on an existing project](#adopting-it-on-an-existing-project).
261
315
 
262
- ## How it works
316
+ ## Set up
317
+
318
+ Four situations that happen once per project. The quick start above is the shortest path; this is what each path looks like in full, with what the harness checks and what you see at the end.
319
+
320
+ <a name="start-from-scratch"></a>
321
+ <details>
322
+ <summary><strong>Start from scratch</strong></summary>
323
+
324
+ **When.** No code yet. The docs precede the code, and that is where they are cheapest.
325
+
326
+ **What you say.** `init`, then `/readme`, `/spec`, `/intent`, then `/intent <verb + object>` for each proposal.
327
+
328
+ **What happens.**
263
329
 
330
+ 1. `/spec` in greenfield mode: three questions to start, then one section at a time. The Vocabulary first: it will constrain the intents.
331
+ 2. `/intent` in greenfield mode: who does it, what they want and why, what it does not cover. The file is born with its first `proposed` intent.
332
+ 3. `/workflow` as soon as CI exists. `/decision` for the stack.
333
+ 4. Then the cycle specify → deliver for each feature.
334
+
335
+ **What the harness checks.** That the cardinal files exist, that the spec has content and no technology word, that each intent is well formed.
336
+
337
+ **What you see at the end.** A repo where the first code commit arrives with its spec, its intent and its ADR. Each following feature costs ten more lines.
338
+
339
+ </details>
340
+
341
+ <a name="adopt-it-on-an-existing-project"></a>
342
+ <details>
343
+ <summary><strong>Adopt it on an existing project</strong></summary>
344
+
345
+ **When.** A repo with code, perhaps a hand-written `CLAUDE.md`, no structured docs.
346
+
347
+ **What you say.**
348
+
349
+ ```bash
350
+ npx -y @vaubaan/harness init . --engines=claude-code
264
351
  ```
265
- docs/ your context, versioned, reviewed in PRs
266
- │ spec · decisions · handbook · tests · workflow · quality · skills
267
- │
268
- ▼ init / update
269
- AGENTS.md .claude/ .codex/ .opencode/ rendered for your engines, committed
270
- │
271
- ▼
272
- Claude Code · Codex · OpenCode read the same context, write the code
273
- │
274
- ▼ pre-commit, CI
275
- vaubaan-harness lint 15 linters: shape, links, drift, freshness
352
+
353
+ then `/doc-audit`.
354
+
355
+ **What happens.**
356
+
357
+ 1. `init` renders the engine files without touching anything it did not write. A hand-written `AGENTS.md` or `CLAUDE.md` stops it with a list: move the content into `docs/`, or keep the file as yours with `--preserve AGENTS.md`. It never merges a configuration file and never touches `.claude/settings.json`, `.codex/hooks.json` or any MCP configuration. You commit everything, and wire the lint in pre-commit and CI.
358
+ 2. `/doc-audit` says what is missing. In useful order: `/spec` by extraction from the code (the agent proposes, you correct), `/workflow` from `.github/workflows/`, `/handbook` for the modules with traps.
359
+ 3. `/intent` with no argument, in mature mode: the agent reads routes, commands and handlers, proposes a hierarchy, one terminal intent at a time with its anchors. One sub-domain first, to stabilize the vocabulary.
360
+ 4. `/decision` for the implicit choices the `git log` betrays.
361
+
362
+ **What the harness checks.** From the first commit: the shape of the pillars present, the gitignore, the freshness of the render. Optional pillars that are absent report nothing.
363
+
364
+ **What you see at the end.** A `docs/` that says what the code does not, and agents that start from the same place. Count half a day for a medium project, in several short sessions. `npx @vaubaan/harness uninstall .` backs out anytime and leaves your own files in place.
365
+
366
+ </details>
367
+
368
+ <a name="update-the-harness"></a>
369
+ <details>
370
+ <summary><strong>Update the harness</strong></summary>
371
+
372
+ **When.** A new version is published.
373
+
374
+ **What you say.**
375
+
376
+ ```bash
377
+ npm i -D @vaubaan/harness@latest && npx vaubaan-harness update .
378
+ ```
379
+
380
+ **What happens.** `update` re-renders the engine files and the manifest, leaves untouched the generated files you modified by hand (it refuses to overwrite them: delete and rerun if you want the new version), and tells you to commit.
381
+
382
+ **What the harness checks.** `generated-fresh`: the committed render is the one of the installed version.
383
+
384
+ **What you see at the end.** A commit of generated files, and the harness changelog for what changed. Known traps: a prettier pre-commit that reformats the generated files (add them to `.prettierignore`); a pnpm `minimumReleaseAge` that refuses a version published less than 24 hours ago.
385
+
386
+ </details>
387
+
388
+ <a name="back-out"></a>
389
+ <details>
390
+ <summary><strong>Back out</strong></summary>
391
+
392
+ **When.** You stop using the harness, or you want to start over from a clean render.
393
+
394
+ **What you say.**
395
+
396
+ ```bash
397
+ npx @vaubaan/harness uninstall .
398
+ ```
399
+
400
+ **What happens.** `uninstall` removes exactly what `init` and `update` wrote, as recorded in `.harness-manifest.json`: `AGENTS.md`, `CLAUDE.md`, the engine folders, the intents index, the manifest itself. Your `docs/`, your own skills, settings and hooks are left in place. A generated file you had modified is preserved and listed.
401
+
402
+ **What the harness checks.** Nothing afterwards: without the harness there is no linter. Your context stays in `docs/`, readable by anyone.
403
+
404
+ **What you see at the end.** A repo with its docs and without the render. `init` brings it back in one command.
405
+
406
+ </details>
407
+
408
+ ## How it works
409
+
410
+ ```mermaid
411
+ flowchart LR
412
+ D["docs/<br/>your context, in Markdown"]
413
+ R["AGENTS.md · .claude/ · .agents/ · .opencode/<br/>rendered for each engine, committed"]
414
+ E["Claude Code · Codex · OpenCode<br/>read the same context, write the code"]
415
+ L["vaubaan-harness lint<br/>pre-commit and CI, zero tokens"]
416
+ D -- "init · update" --> R --> E -- "code and docs" --> L
417
+ L -. "fails when context and code disagree" .-> D
276
418
  ```
277
419
 
278
420
  1. **Your docs are the context.** A small, fixed layout under `docs/`. Every file has a template and a writer skill, so you rarely start from a blank page.
279
421
  2. **One pivot format, rendered per engine.** Skills and commands land where Claude Code, Codex and OpenCode look for them. `AGENTS.md` is the shared entry point; `CLAUDE.md` just imports it.
280
422
  3. **Linters keep context and code in sync.** They run before each commit and on every pull request. The semantic part, contradictions, stale prose, missing pieces, is a skill the agent runs: `/doc-audit`.
281
423
 
424
+ In database terms:
425
+
426
+ | Database notion | In the meta database |
427
+ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
428
+ | Schema | The pillars below: one per kind of information. A rule goes to the spec, a why to a decision, a how to a handbook. |
429
+ | Foreign keys | `tracks:`, `anchors:`, `spec:`, the "realized by" arrows. They point into the code database, and the linter refuses one that does not resolve. |
430
+ | Integrity constraints | Nineteen linters: shape, pointers, vocabulary, freshness. Run on every commit and pull request, at zero token cost. |
431
+ | Materialized views | What `update .` renders: `AGENTS.md`, the skills per engine, the intents index. Committed, never edited by hand, refreshed from their source. |
432
+ | Transactions | `/intent <verb + object>`: a typed write that adds a `proposed` intent with its acceptance criteria and leaves the base consistent. |
433
+ | Join table | The intents pillar: the one table that joins both databases, to the code through `anchors:` and to the spec vocabulary through `requires:` / `creates:`. |
434
+
435
+ ## Day to day
436
+
437
+ Eight things you will do with a harnessed project, again and again. Each one is a conversation with your agent, not a form: the slash command is the moment the conversation lands in the repo. Every section follows the same grid: when, what you say, what happens, what the harness checks, what you see at the end.
438
+
439
+ One word first. In the intents pillar, every heading is an **intent**: what the user wants, verb + object, at every level. The file is the level-1 intent, its headings are sub-intents. An intent with no sub-intent is **terminal**: it carries the fields. Terminal and `proposed`, it is decided and not delivered, the backlog item; terminal and `implemented`, it is delivered and points to its code.
440
+
441
+ <a name="specify-a-change-without-a-ticketing-tool"></a>
442
+ <details>
443
+ <summary><strong>Specify a change, without a ticketing tool</strong></summary>
444
+
445
+ **When.** A change visible to the user is decided, and the repo is the only source of truth.
446
+
447
+ **What you say.** You describe what you want, the agent asks its questions, you converge. Then `go`, or directly:
448
+
449
+ ```
450
+ /intent the customer receives the invoice by email
451
+ ```
452
+
453
+ **What happens.**
454
+
455
+ 1. The agent opens `docs/intents/README.md`, the rendered index, and finds the level-1 intent this belongs to. None fits: it creates a file.
456
+ 2. It checks that every word of the new intent is in the Vocabulary section of the spec. A word is missing: it stops and offers `/spec` to define it first.
457
+ 3. It writes the `proposed` intent with two to five observable acceptance criteria, then runs `update .` so the index follows.
458
+ 4. It shows you the intent. You correct, you validate. Not one line of code.
459
+
460
+ **What the harness checks.** The shape of the intent, words known to the spec, a `spec:` link that resolves, a fresh index. Zero tokens.
461
+
462
+ **What you see at the end.** Ten lines of Markdown in a commit or pull request, and one `— proposed` line in the index. This is the persistent todo: if the session stops here, the next agent knows exactly what to deliver.
463
+
464
+ ```markdown
465
+ ### Email the invoice
466
+
467
+ status: proposed
468
+ requires: invoice
469
+ acceptance:
470
+ - the customer receives a PDF within a minute of issue
471
+ - a bounced address is visible on the invoice
472
+ - no email is sent for a draft
473
+ ```
474
+
475
+ </details>
476
+
477
+ <a name="specify-a-change-from-a-ticket"></a>
478
+ <details>
479
+ <summary><strong>Specify a change, from a ticket</strong></summary>
480
+
481
+ **When.** The team plans in a board such as GitHub Projects. The issue carries the work: priority, sprint, discussion. The intent carries the contract: acceptance, vocabulary, anchors.
482
+
483
+ **What you say.** Planning ends in an issue, as today, with draft criteria in its body. Later, when the work is picked up:
484
+
485
+ ```
486
+ /intent #123
487
+ ```
488
+
489
+ **What happens.**
490
+
491
+ 1. The agent reads the issue with `gh`, finds the level-1 intent, copies and cleans the criteria, checks the vocabulary.
492
+ 2. It writes the `proposed` intent citing the issue. Today the reference lives in the pull request; an optional `issue:` field on the intent is proposed in [vaubaan/harness#12](https://github.com/vaubaan/harness/pull/12).
493
+ 3. It comments the issue with the path of the intent: "contract: `docs/intents/<file>.md#<heading>`". From here the intent is the source of truth for the criteria.
494
+
495
+ **What the harness checks.** The same as above. The ticket reference will only be checked in form: `#123`, `owner/repo#123` or a URL.
496
+
497
+ **What you see at the end.** An issue on the board that points to an intent in the repo, and an intent that points to the issue. The delivery pull request says `Closes #123` and closes both.
498
+
499
+ Write the rule in your `docs/workflow/coding-workflow.md`: intents are born in the board, the intent is written when the work is picked up, the pull request closes the issue and delivers the intent. Your agents read it in `AGENTS.md`.
500
+
501
+ </details>
502
+
503
+ <a name="deliver-a-change"></a>
504
+ <details>
505
+ <summary><strong>Deliver a change</strong></summary>
506
+
507
+ **When.** A `proposed` intent exists and you start the code.
508
+
509
+ **What you say.** `deliver "Email the invoice"`, or `go on #123`.
510
+
511
+ **What happens.**
512
+
513
+ 1. The agent reads the intent, the spec section it cites, the handbook of the module. That is its whole brief.
514
+ 2. It codes, and writes tests whose titles restate the acceptance criteria, one for one.
515
+ 3. In the same pull request the intent turns `implemented`: it adds `anchors:` to the code and the tests, removes `acceptance:`, sets `last_reviewed`.
516
+ 4. If the "how" changed, `/handbook`. If a structural choice slipped into the diff, `/decision`. Then `update .`.
517
+
518
+ **What the harness checks.** The anchors exist, the index is fresh, the docs that `tracks:` the touched code are not older than it. Pre-commit, then CI.
519
+
520
+ **What you see at the end.** A pull request with the code, the tests, and the diff of the intent: three lines of criteria replaced by three paths. The tests carry the criteria from now on. The intent never goes back to `proposed`: a later change is a sibling `proposed` intent.
521
+
522
+ </details>
523
+
524
+ <a name="reassure-yourself"></a>
525
+ <details>
526
+ <summary><strong>Reassure yourself</strong></summary>
527
+
528
+ **When.** Before a release, after a large pull request, or when you feel the docs and the code have drifted. Three levels, from free to costly.
529
+
530
+ **What you say.** `state of things, change nothing`
531
+
532
+ **What happens.**
533
+
534
+ 1. **Mechanical, zero tokens.** `npx @vaubaan/harness lint`. Shape, pointers, drift, freshness of the render. Green means the structure is sound.
535
+ 2. **Code ↔ doc drift.** `/drift`. For each doc that declares code, the agent reads the code and judges whether the doc still tells the truth. Hard and soft drift, listed.
536
+ 3. **Completeness.** `/doc-audit`. Pillar by pillar: in place, missing, stale. It also spots implicit decisions in the `git log` that have no ADR. Report in `.vaubaan/reports/doc-audit.md`, gitignored.
537
+ 4. **Where we stand.** The intents index. `proposed` intents are what remains; `deprecated` ones leave at the next release.
538
+
539
+ **What the harness checks.** Level 1 entirely. Levels 2 and 3 are judgment: the harness ships the skill and the report format, the agent does the work.
540
+
541
+ **What you see at the end.** A report, no change. Each item names the skill that fixes it. You choose what to treat, and in which order.
542
+
543
+ </details>
544
+
545
+ <a name="compact-the-docs"></a>
546
+ <details>
547
+ <summary><strong>Compact the docs</strong></summary>
548
+
549
+ **When.** Pillars repeat each other, contradict each other, or a file has grown past what an agent reads well. The content test: if a paragraph can go without losing anything that is not in the files it points to, it should go.
550
+
551
+ **What you say.** `compact the docs: list the contradictions first, then we rewrite pillar by pillar`
552
+
553
+ **What happens.**
554
+
555
+ 1. `/doc-audit` in contradiction mode: where the spec and a handbook disagree, where an ADR is contradicted by a config, where two handbooks describe the same code.
556
+ 2. For each pillar, its writer rewrites with the content test: the rule stays in the spec, the why in the ADR, the how in the handbook, the rest is a pointer. One pull request per pillar, so the review stays readable.
557
+ 3. `/drift` at the end, to check the rewrite lost no rule in force.
558
+
559
+ **What the harness checks.** That every pointer still resolves and the cross-links hold. It does not judge loss of meaning: that is your review.
560
+
561
+ **What you see at the end.** Shorter files that each say one thing, and red diffs you read with care: the only rule is that no rule in force disappears.
562
+
563
+ A dedicated `/compact` is decided and not shipped: it is a `proposed` intent, "Rewrite a context that has grown contradictions", under *Keep the docs honest*. Until then the recipe above is manual.
564
+
565
+ </details>
566
+
567
+ <a name="fix-a-bug-refactor"></a>
568
+ <details>
569
+ <summary><strong>Fix a bug, refactor</strong></summary>
570
+
571
+ **When.** The visible behavior does not change. No intent: you code.
572
+
573
+ **What you say.** `fix the rounding on credit notes`, or `move src/invoicing/ to packages/billing/`.
574
+
575
+ **What happens.**
576
+
577
+ 1. The agent reads the handbook of the module before touching it: invariants and traps are there.
578
+ 2. It codes, adds a regression test.
579
+ 3. If an invariant or a trap changed: `/handbook`. If files moved: it updates the `tracks:` and `anchors:` that cited them, or the lint fails.
580
+
581
+ **What the harness checks.** That every declared path still exists after the move, and that the handbook is not older than the code it tracks.
582
+
583
+ **What you see at the end.** A code pull request, and sometimes one line of handbook or intent updated. Nothing else.
584
+
585
+ </details>
586
+
587
+ <a name="take-a-structural-decision"></a>
588
+ <details>
589
+ <summary><strong>Take a structural decision</strong></summary>
590
+
591
+ **When.** A choice is costly to reverse, a real alternative was weighed, and it will outlive the ticket. Database, framework, package layout, CI policy.
592
+
593
+ **What you say.** `we move from SQLite to Postgres`, or after the fact, `/decision` on a diff that holds an implicit choice.
594
+
595
+ **What happens.**
596
+
597
+ 1. The agent applies the admission test. It fails: the agent says so and puts the justification in the handbook or the spec instead.
598
+ 2. It writes `docs/decisions/<slug>.md`: context, decision, consequences, rejected alternatives. About forty lines, and the files that embody the decision.
599
+ 3. Then, and only then, the code. When you change your mind, a new ADR replaces this one; git keeps the history.
600
+
601
+ **What the harness checks.** The four sections, no `tracks:` on an ADR, and that the ADR is referenced somewhere, otherwise it is orphaned.
602
+
603
+ **What you see at the end.** A file you can reread in a year to know why, and what else was considered.
604
+
605
+ </details>
606
+
607
+ <a name="come-back-to-a-project"></a>
608
+ <details>
609
+ <summary><strong>Come back to a project</strong></summary>
610
+
611
+ **When.** You, a new agent, or a colleague, after weeks. The goal: in ten minutes, know what the product does, where the work stands, what drifted.
612
+
613
+ **What you say.** `give me the tour and tell me what is left`
614
+
615
+ **What happens.**
616
+
617
+ 1. The agent reads `AGENTS.md`: the map and the rule.
618
+ 2. The intents index: what the user does, where in the code, and the `proposed` intents as the remaining work.
619
+ 3. The ADRs: the choices in force.
620
+ 4. `/drift` if the last `last_reviewed` is old.
621
+
622
+ **What the harness checks.** Nothing beyond the usual. Its work here was done before: everything is in the repo, no external tool and no token needed to resume.
623
+
624
+ **What you see at the end.** A summary in three parts: what it does, what is left, what moved. You pick up the conversation where it stopped.
625
+
626
+ </details>
627
+
628
+ <a name="change-the-workflow"></a>
629
+ <details>
630
+ <summary><strong>Change the workflow</strong></summary>
631
+
632
+ **When.** A new CI job, a move to trunk-based, an automated release, a team rule such as "intents are born in GitHub Projects".
633
+
634
+ **What you say.** `/workflow`, after changing `.github/workflows/`, or to write a team rule.
635
+
636
+ **What happens.** The agent reads the workflows, the scripts, the pre-commit hook, and updates `docs/workflow/coding-workflow.md`: what triggers what, what lives outside the repo (protections, secrets, approvals), the release. It is the one pillar where the team describes its own organization; the harness imposes none.
637
+
638
+ **What the harness checks.** That the file `tracks:` the workflows and is not older than them.
639
+
640
+ **What you see at the end.** A procedure the agent follows to the letter next time, instead of guessing.
641
+
642
+ </details>
643
+
644
+ ## For your agent
645
+
646
+ How a coding agent should react to what the user asks, in a harnessed project. It does not replace `docs/workflow/`, which says how the team organizes itself, nor the skills, which say how to write each pillar. It says which reflex to trigger, and when to trigger none.
647
+
648
+ <a name="before-any-task-the-reading-order"></a>
649
+ <details>
650
+ <summary><strong>Before any task: the reading order</strong></summary>
651
+
652
+ 1. `AGENTS.md`: the rule, the map, the checks.
653
+ 2. `docs/intents/README.md`: what the product does, where in the code, what is `proposed`.
654
+ 3. The intent and the spec section the request touches.
655
+ 4. The handbook of the module before opening the code: the invariants and traps are there.
656
+ 5. `docs/workflow/coding-workflow.md` before committing, branching or opening a pull request.
657
+
658
+ Never:
659
+
660
+ - Edit `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.agents/`, `.opencode/`, `.harness-manifest.json` or `docs/intents/README.md` by hand. Their source is in `docs/` or `.harness-overrides/`; then `update .`.
661
+ - Invent a vocabulary word. The spec defines the words; a missing word goes into the spec first.
662
+ - Disable a linter to get a commit through. The message names the skill that fixes it.
663
+ - Commit when the project's workflow does not say so. The skills write files; the commit follows the team's procedure.
664
+
665
+ </details>
666
+
667
+ <a name="the-decision-tree"></a>
668
+ <details>
669
+ <summary><strong>The decision tree</strong></summary>
670
+
671
+ The first question is always the same: does the behavior visible to the user change?
672
+
673
+ ```mermaid
674
+ flowchart TB
675
+ Q0["The user asks for something"]
676
+ Q5{"A question, not a<br/>request for change?"}
677
+ Q1{"Does the behavior visible<br/>to the user change?"}
678
+ Q2{"Does a proposed intent<br/>already exist?"}
679
+ Q3{"Are the words in the<br/>spec Vocabulary?"}
680
+ Q4{"A structural choice,<br/>costly to reverse?"}
681
+ X{"An intent to deliver?"}
682
+ R["Answer from the docs and the code<br/>Report the gap, invent nothing"]
683
+ S["/intent: a proposed intent with<br/>acceptance criteria, no code"]
684
+ SP["/spec first: define the word<br/>then back to /intent"]
685
+ D["/decision before the code"]
686
+ C["Code + tests titled after the criteria<br/>intent → implemented with anchors"]
687
+ F["Code + regression test<br/>handbook if an invariant changed<br/>tracks and anchors if files moved"]
688
+ E["update . → lint → follow docs/workflow"]
689
+ Q0 --> Q5
690
+ Q5 -- yes --> R
691
+ Q5 -- no --> Q1
692
+ Q1 -- yes --> Q2
693
+ Q2 -- no --> Q3
694
+ Q3 -- yes --> S
695
+ Q3 -- no --> SP --> S
696
+ S -- "the user validates" --> Q4
697
+ Q2 -- yes --> Q4
698
+ Q1 -- no --> Q4
699
+ Q4 -- yes --> D --> X
700
+ Q4 -- no --> X
701
+ X -- yes --> C --> E
702
+ X -- no --> F --> E
703
+ ```
704
+
705
+ </details>
706
+
707
+ <a name="what-the-user-says-what-the-agent-does"></a>
708
+ <details>
709
+ <summary><strong>What the user says, what the agent does</strong></summary>
710
+
711
+ | The user says | Reflex | Never |
712
+ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
713
+ | "I want the user to be able to…", "add a feature" | Talk until you converge, then `/intent`. Show the intent, wait for validation, and only then code. | Open the code first. Write the intent after the code "to document". |
714
+ | "Go", after a planning discussion | Summarize the decisions in a short list and land them: `/intent` for behavior, `/decision` for a structural choice. Then code. | Treat the conversation as the spec. It dies with the session. |
715
+ | "Take issue #123" | Read the issue with `gh`. `/intent` citing the issue. Comment the issue with the path of the intent. The pull request says `Closes #123`. | Copy the issue's criteria into the code without the intent. Keep two diverging versions of the criteria. |
716
+ | "Deliver the intent X" | Read the intent, its spec section, the handbook. Code. Tests titled after the criteria. Intent → `implemented` with `anchors:`, `acceptance:` removed, `last_reviewed` set. `update .`. | Deliver without touching the intent. Leave `acceptance:` on a delivered intent. Move an intent back to `proposed`. |
717
+ | "Fix this bug" | Read the handbook of the module. Code, regression test. If an invariant or a trap changed, `/handbook`. | Open an intent: the expected behavior does not change. Fix without a test. |
718
+ | "Refactor", "rename", "move" | Code. Update every `tracks:` and `anchors:` that cited the old paths. `/handbook` if the map changed. | Let the lint fail on dead paths. Open an intent. |
719
+ | "We move to Postgres", "we change framework" | Admission test. If it passes: `/decision` before the code, with the files that embody the choice. Then the code, then `/handbook` and `/workflow` if CI changes. | Make the change and leave the why in a commit message. Write an ADR for a choice reversible in one pull request. |
720
+ | "Why is it done this way?" | Look for the ADR, the handbook, the spec. Answer by citing. If none answers and it is structural: say so, offer `/decision`. | Invent a plausible justification. Write the ADR before the user confirms the reason. |
721
+ | "Is it fine?", "reassure me", "where do we stand?" | Read-only mode: `lint`, then `/drift`, then `/doc-audit`, then the intents index. Report in three parts: healthy, drifted, missing. Each item names the skill that fixes it. | Fix things on the way. The user asked for a state, not changes. |
722
+ | "Compact the docs", "clean up", "too long" | `/doc-audit` to list the contradictions first. Then one pillar at a time, with the pillar's writer and the content test. One pull request per pillar. `/drift` at the end. | Delete a rule in force because it looks redundant. Rewrite everything in one pull request. |
723
+ | "Document this" | Pick the pillar by nature: a rule → spec; a why → ADR; where and how, traps → handbook; test scope → test plan; team procedure → workflow; what the user wants → intent. A pointer over a retelling. | Write into `AGENTS.md` or `CLAUDE.md`. Create `docs/notes.md`. Paraphrase the code. |
724
+ | "Change AGENTS.md / CLAUDE.md" | Explain they are rendered. Find the source: `docs/`, a project skill in `docs/skills/`, or `.harness-overrides/` for a local trial. `update .`, commit the render. | Edit the file: `generated-fresh` fails on the next commit. |
725
+ | "The lint fails" | Read the message: it names the file and the skill. Fix the cause. If it is drift, reread the code and update the doc, not only the date. | Touch `last_reviewed` without rereading. Disable the linter. Reformat a generated file. |
726
+ | "Release", "tag" | Follow `docs/workflow/coding-workflow.md` § Release, to the letter. Changelog, version, tag, verification. A snag in the procedure goes back into the file the same day. | Improvise the order of steps. Skip verifying the publication. |
727
+ | "Update the harness" | Bump the dependency, `update .`, read the changelog and its Migration section, commit the generated files. Report the preserved files that will not be refreshed. | Overwrite a file the user had modified. Ignore the Migration section. |
728
+ | "Give me the tour" | `AGENTS.md`, the intents index, the ADRs, then `/drift` if `last_reviewed` is old. Summarize: what it does, what is left (`proposed`), what moved. | Read all the code to retell it. The docs exist to avoid that. |
729
+
730
+ </details>
731
+
732
+ <a name="the-refusals-the-agent-holds"></a>
733
+ <details>
734
+ <summary><strong>The refusals the agent holds</strong></summary>
735
+
736
+ Four cases where the agent says no, explains, and offers the path. They are the only ones.
737
+
738
+ - **Coding before the intent.** "This change is visible to the user. I write the `proposed` intent with its criteria first, you validate, then I code." If the user insists, it is their call: say so, do it, and write the intent in the same pull request.
739
+ - **Inventing a word.** "The word *email* is not in the spec Vocabulary. I add it to the spec with `/spec` before using it in the intent." No synonym, no plural.
740
+ - **Editing a generated file.** "`AGENTS.md` is rendered from `docs/`. I change the source and rerun `update .`." Same for the intents index.
741
+ - **Coding without a spec.** "The subsystem I touch has no spec. I stop and report the gap." It is the rule of `AGENTS.md`: missing spec, do not code, report the gap.
742
+
743
+ </details>
744
+
745
+ <a name="at-the-end-of-a-task-always"></a>
746
+ <details>
747
+ <summary><strong>At the end of a task, always</strong></summary>
748
+
749
+ 1. The docs touched by the change are current: intent, handbook, test plan, workflow. No more.
750
+ 2. `npx @vaubaan/harness update .` if an intent, a project skill or an override changed.
751
+ 3. `npx @vaubaan/harness lint`. Green, or fix with the named skill.
752
+ 4. Commit and open the pull request as `docs/workflow/coding-workflow.md` says, never as habit says.
753
+ 5. Report in three lines: what was done, what was verified, what is left or was set aside and why.
754
+
755
+ Warning sign: if finishing requires touching a generated file, disabling a linter or inventing a word, stop. A step was skipped upstream.
756
+
757
+ </details>
758
+
282
759
  ## What is included
283
760
 
284
761
  ### Skills
285
762
 
286
- **8 skills**, each with a slash command. A skill never says *when* to do something. It says *how* to write or check one pillar.
763
+ **9 skills**, nine slash commands. A skill never says *when* to do something. It says *how* to write or check one pillar.
287
764
 
288
765
  | Command | Skill | What it does |
289
766
  | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
@@ -295,10 +772,11 @@ jobs:
295
772
  | `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
296
773
  | `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release, languages. |
297
774
  | `/readme` | `readme-writer` | Keeps the README in sync with the code. |
775
+ | `/intent` | `intent-writer` | `/intent <verb + object>` proposes an intent with its acceptance criteria before any code; with no argument, maps or extends the intent tree: three questions on a greenfield scope, extraction from the code on a mature one. |
298
776
 
299
777
  ### Linters
300
778
 
301
- **15 linters**, fast enough to run on every commit.
779
+ **19 linters**, fast enough to run on every commit.
302
780
 
303
781
  <details>
304
782
  <summary>See the list</summary>
@@ -315,6 +793,7 @@ jobs:
315
793
  | `gitignore-harness` | Overrides and reports are ignored; generated files are not. |
316
794
  | `generated-fresh` | Committed generated files match the current render. |
317
795
  | `quality-schema` | `docs/quality/code-quality.md` has its sections, if you use it. |
796
+ | `intent-schema`, `intent-anchors`, `intent-vocabulary`, `intent-graph` | Optional `docs/intents/`: node grammar, anchors exist, entities are spec vocabulary, nothing requires what nothing creates. |
318
797
 
319
798
  </details>
320
799
 
@@ -328,15 +807,6 @@ jobs:
328
807
 
329
808
  You name your engines; nothing is rendered for a tool you don't use. Add one later with `init . --engines=...` again.
330
809
 
331
- ## Adopting it on an existing project
332
-
333
- You don't have to write all the docs on day one.
334
-
335
- - **See where you stand.** `npx @vaubaan/harness lint` lists what's missing, with the skill that fixes each item.
336
- - **Let the agent do the first pass.** `/doc-audit`, then `/spec`, `/handbook` and `/decision` on the parts you touch. The rest fills in over time.
337
- - **Keep what you had.** Your own skills, settings and hooks are never touched. A hand-written `AGENTS.md` or `CLAUDE.md` stops `init` with a list: move the content into `docs/`, or keep the file as yours with `--preserve AGENTS.md`. It never merges a configuration file either, and it never touches `.claude/settings.json`, `.codex/hooks.json` or any MCP configuration.
338
- - **Back out anytime.** `npx @vaubaan/harness uninstall .` removes what `init` wrote. Your own files are left in place.
339
-
340
810
  ## Commands
341
811
 
342
812
  | Command | What it does |
@@ -418,7 +888,7 @@ npx @vaubaan/harness update . # then commit the result
418
888
 
419
889
  ## Where this is going
420
890
 
421
- Decided, not shipped yet: typed context transactions (`/story`, `/decide`, `/refactor`, `/fix`), an optional `docs/todo/` pillar for increments that fold into the spec when delivered, pointer checks per section, a token budget per file, and `/compact` to rewrite a context that has grown contradictions. The [spec](./docs/spec/coding-agent-harness.md) and the [decisions](./docs/decisions/) say what exists today.
891
+ Shipped: the optional `docs/intents/` pillar and its typed context transaction, `/intent <verb + object>`, which writes an increment as a `proposed` intent before the code and passes it `implemented` when delivered. Read it as an OKR tree: intents are objectives, acceptance criteria are key results, anchors are the initiatives, and progress is the share of `implemented` intents, computed from the repo. Decided, not shipped yet: the other transactions (`/refactor`, `/fix`), pointer checks per section, a token budget per file, and `/compact` to rewrite a context that has grown contradictions. The [spec](./docs/spec/coding-agent-harness.md) and the [decisions](./docs/decisions/) say what exists today.
422
892
 
423
893
  ## Documentation
424
894