@vaubaan/harness 2.3.1 → 3.0.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 (53) hide show
  1. package/README.md +207 -83
  2. package/dist/cli/index.js +4165 -843
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/harn-canvas.cmd.md +23 -0
  5. package/dist/commands/{decision.cmd.md → harn-decision.cmd.md} +6 -6
  6. package/dist/commands/{doc-audit.cmd.md → harn-doc-audit.cmd.md} +7 -7
  7. package/dist/commands/{drift.cmd.md → harn-drift.cmd.md} +6 -6
  8. package/dist/commands/{handbook.cmd.md → harn-handbook.cmd.md} +6 -6
  9. package/dist/commands/harn-improve.cmd.md +20 -0
  10. package/dist/commands/{intent.cmd.md → harn-intent.cmd.md} +9 -9
  11. package/dist/commands/{readme.cmd.md → harn-readme.cmd.md} +6 -6
  12. package/dist/commands/{spec.cmd.md → harn-spec.cmd.md} +6 -6
  13. package/dist/commands/{test-plan.cmd.md → harn-test-plan.cmd.md} +6 -6
  14. package/dist/commands/harn-upgrade.cmd.md +22 -0
  15. package/dist/commands/{workflow.cmd.md → harn-workflow.cmd.md} +6 -6
  16. package/dist/index.d.ts +32 -3
  17. package/dist/index.js +533 -96
  18. package/dist/index.js.map +1 -1
  19. package/dist/init.d.ts +1 -1
  20. package/dist/init.js +468 -93
  21. package/dist/init.js.map +1 -1
  22. package/dist/linters/index.d.ts +3 -34
  23. package/dist/linters/index.js +996 -554
  24. package/dist/linters/index.js.map +1 -1
  25. package/dist/parser/index.d.ts +96 -6
  26. package/dist/parser/index.js +220 -10
  27. package/dist/parser/index.js.map +1 -1
  28. package/dist/render-BhUar2gf.d.ts +81 -0
  29. package/dist/render.d.ts +1 -1
  30. package/dist/render.js +233 -22
  31. package/dist/render.js.map +1 -1
  32. package/dist/skills/harn-canvas-review.skill.md +87 -0
  33. package/dist/skills/{decision-record-writer.skill.md → harn-decision-record-writer.skill.md} +2 -1
  34. package/dist/skills/{doc-audit.skill.md → harn-doc-audit.skill.md} +75 -26
  35. package/dist/skills/{drift-detector.skill.md → harn-drift-detector.skill.md} +15 -14
  36. package/dist/skills/harn-guide.skill.md +137 -0
  37. package/dist/skills/{handbook-writer.skill.md → harn-handbook-writer.skill.md} +2 -1
  38. package/dist/skills/{intent-writer.skill.md → harn-intent-writer.skill.md} +83 -16
  39. package/dist/skills/{readme-writer.skill.md → harn-readme-writer.skill.md} +4 -4
  40. package/dist/skills/harn-self-improve.skill.md +84 -0
  41. package/dist/skills/{spec-writer.skill.md → harn-spec-writer.skill.md} +8 -8
  42. package/dist/skills/{test-plan-writer.skill.md → harn-test-plan-writer.skill.md} +6 -5
  43. package/dist/skills/harn-upgrade.skill.md +171 -0
  44. package/dist/skills/{workflow-writer.skill.md → harn-workflow-writer.skill.md} +6 -5
  45. package/dist/templates/decisions-index.md.tmpl +11 -0
  46. package/dist/templates/handbook-index.md.tmpl +8 -0
  47. package/dist/templates/profile.md.tmpl +30 -0
  48. package/dist/types-CfUByAIr.d.ts +35 -0
  49. package/dist/view/index.d.ts +117 -0
  50. package/dist/view/index.js +3987 -0
  51. package/dist/view/index.js.map +1 -0
  52. package/package.json +6 -2
  53. package/dist/render-CTx7VNOK.d.ts +0 -45
package/README.md CHANGED
@@ -20,16 +20,18 @@ npx -y @vaubaan/harness init . --engines=claude-code
20
20
 
21
21
  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.
22
22
 
23
- - **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.
23
+ - **One context, every engine.** Thirteen skills: one per pillar, an audit, a drift detector, a review canvas, a self-improvement loop, and two about the harness itself. Written once for Claude Code, Codex and OpenCode.
24
+ - **As much context as the project needs, no more.** A project that starts needs a README. Every other pillar is added the day it helps, with one command, and costs nothing until then: no check, no skill, no line of context.
24
25
  - **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.
25
- - **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.
26
+ - **Checks with zero tokens.** Twenty-one 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.
27
+ - **A view to review it.** `vaubaan-harness view` draws the whole context on one offline canvas. `/harn-canvas` keeps it live while you talk to the agent or comment a card, and nothing is committed until you say so. `/harn-improve` turns the patches reviews keep asking for into rules.
26
28
 
27
29
  **Contents**
28
30
 
29
31
  1. [Two personas, one codebase, two databases](#two-personas-one-codebase-two-databases)
30
32
  2. [What it looks like](#what-it-looks-like)
31
33
  3. [Quick start](#quick-start)
32
- 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)
34
+ 4. [Set up](#set-up): [start from scratch](#start-from-scratch) · [adopt an existing project](#adopt-it-on-an-existing-project) · [add a pillar](#add-a-pillar) · [update the harness](#update-the-harness) · [back out](#back-out)
33
35
  5. [How it works](#how-it-works)
34
36
  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)
35
37
  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)
@@ -64,14 +66,23 @@ Each pillar stores one kind of information the code cannot carry, and links to t
64
66
  | `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. |
65
67
  | `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. |
66
68
  | `docs/workflow/` | What lives outside the repo: approvals, protections, secrets, languages. | `ci.yml`, build scripts, pre-commit hook. |
67
- | `docs/quality/` | Optional. The code rules this team holds, and the deviations it accepts. | The linter and formatter configs that enforce the mechanical part. |
68
- | `docs/skills/` | Optional. Domain know-how the agent should load. | Whatever the skill needs. |
69
- | `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. |
69
+ | `docs/quality/` | The code rules this team holds, and the deviations it accepts. | The linter and formatter configs that enforce the mechanical part. |
70
+ | `docs/skills/` | Domain know-how the agent should load. | Whatever the skill needs. |
71
+ | `docs/intents/` | 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. |
72
+ | `docs/profiles/` | Who the project serves: each kind of user, what hurts them, what they hope for, and the evidence behind it. | The intents: their `actors:` are profiles, `relieves:` / `delivers:` name the pain or gain they serve. A generated index shows the fit. |
73
+
74
+ **Only the README is required.** `README.md` and `docs/spec/` are the core. Every other row is a pillar you add when the project needs it:
75
+
76
+ ```bash
77
+ npx @vaubaan/harness add decisions # or handbook, tests, workflow, quality, intents, profiles
78
+ ```
79
+
80
+ A pillar is active when its folder exists. Inactive, it leaves no trace: its linters report nothing, its skill and command are not rendered, `AGENTS.md` holds no rule for it. You are never asked for a release workflow before you have a release. The agent is told which pillars are missing and proposes one when the work calls for it; you decide.
70
81
 
71
82
  > [!IMPORTANT]
72
83
  > **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.**
73
84
  >
74
- > How your team organizes itself around that, branches, review, release, is yours. You write it in `docs/workflow/` and the agents follow it. The harness ships no roles, no personas, no phases.
85
+ > How your team organizes itself around that, branches, review, release, is yours. You write it in `docs/workflow/` and the agents follow it. The harness ships no roles, no agent personas, no phases, and no maturity level to reach.
75
86
 
76
87
  ## What it looks like
77
88
 
@@ -103,16 +114,16 @@ acme-billing/
103
114
  │ └── e2e-tests.md
104
115
  ├── workflow/
105
116
  │ └── coding-workflow.md
106
- ├── quality/ # optional
117
+ ├── quality/
107
118
  │ └── code-quality.md
108
- ├── intents/ # optional
119
+ ├── intents/
109
120
  │ ├── send-an-invoice.md
110
121
  │ └── README.md # rendered: the intent tree
111
- └── skills/ # optional
122
+ └── skills/
112
123
  └── tax-rules.skill.md
113
124
  ```
114
125
 
115
- Each file says what the code cannot, and points to the code for the rest.
126
+ Each file says what the code cannot, and points to the code for the rest. This is a project that has been running for a while: on its first day it had `README.md` and nothing under `docs/`, and each folder was added when it was needed.
116
127
 
117
128
  <details>
118
129
  <summary><code>docs/spec/invoicing.md</code>: intent and vocabulary, no technology, each requirement realized by something.</summary>
@@ -219,7 +230,7 @@ Docs and code in English. Domain vocabulary in spec §0, French-speaking team.
219
230
  </details>
220
231
 
221
232
  <details>
222
- <summary><code>docs/quality/code-quality.md</code> (optional): the rules a tool cannot check, and the deviations you accept.</summary>
233
+ <summary><code>docs/quality/code-quality.md</code>: the rules a tool cannot check, and the deviations you accept.</summary>
223
234
 
224
235
  ```markdown
225
236
  ## Mechanical checks
@@ -232,7 +243,7 @@ No business logic in route handlers; it lives in `src/invoicing/`.
232
243
  </details>
233
244
 
234
245
  <details>
235
- <summary><code>docs/skills/tax-rules.skill.md</code> (optional): know-how the agent loads, rendered like the built-in skills.</summary>
246
+ <summary><code>docs/skills/tax-rules.skill.md</code>: know-how the agent loads, rendered like the built-in skills.</summary>
236
247
 
237
248
  ```markdown
238
249
  ---
@@ -307,10 +318,10 @@ jobs:
307
318
  **4. Open your agent and let it fill the gaps.**
308
319
 
309
320
  ```
310
- /doc-audit # what is missing or stale
311
- /spec # write the spec of a subsystem, guided
312
- /decision # turn an implicit choice into an ADR
313
- /intent <what> # a proposed intent with acceptance criteria, before the code
321
+ /harn-doc-audit # what is missing or stale
322
+ /harn-spec # write the spec of a subsystem, guided
323
+ /harn-decision # turn an implicit choice into an ADR
324
+ /harn-intent <what> # a proposed intent with acceptance criteria, before the code
314
325
  ```
315
326
 
316
327
  > [!NOTE]
@@ -326,18 +337,17 @@ Four situations that happen once per project. The quick start above is the short
326
337
 
327
338
  **When.** No code yet. The docs precede the code, and that is where they are cheapest.
328
339
 
329
- **What you say.** `init`, then `/readme`, `/spec`, `/intent`, then `/intent <verb + object>` for each proposal.
340
+ **What you say.** `init`, then `/harn-readme` and `/harn-spec`. Nothing else is asked of you on day one.
330
341
 
331
342
  **What happens.**
332
343
 
333
- 1. `/spec` in greenfield mode: three questions to start, then one section at a time. The Vocabulary first: it will constrain the intents.
334
- 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.
335
- 3. `/workflow` as soon as CI exists. `/decision` for the stack.
336
- 4. Then the cycle specify → deliver for each feature.
344
+ 1. `init` renders seven skills and `AGENTS.md`. The lint passes with a README alone; it warns that there is no spec yet.
345
+ 2. `/harn-spec` in greenfield mode: three questions to start, then one section at a time. The Vocabulary first: it will constrain the intents.
346
+ 3. The rest comes when the project calls for it, one pillar at a time: `add intents` before the first feature you want specified before it is coded, `add decisions` the day you pick a database, `add workflow` when CI exists, `add tests` with the second kind of test. The agent proposes each one at the moment it would help; see [add a pillar](#add-a-pillar).
337
347
 
338
- **What the harness checks.** That the cardinal files exist, that the spec has content and no technology word, that each intent is well formed.
348
+ **What the harness checks.** That the README exists. Then, for each pillar you added, its own contract and nothing more.
339
349
 
340
- **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.
350
+ **What you see at the end.** A repo whose docs grew at the pace of the code, with no placeholder written to satisfy a linter.
341
351
 
342
352
  </details>
343
353
 
@@ -353,34 +363,67 @@ Four situations that happen once per project. The quick start above is the short
353
363
  npx -y @vaubaan/harness init . --engines=claude-code
354
364
  ```
355
365
 
356
- then `/doc-audit`.
366
+ then `/harn-doc-audit`.
357
367
 
358
368
  **What happens.**
359
369
 
360
370
  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.
361
- 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.
362
- 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.
363
- 4. `/decision` for the implicit choices the `git log` betrays.
371
+ 2. `/harn-spec` by extraction from the code: the agent proposes, you correct.
372
+ 3. Add the pillars the project is ready for, in useful order: `add workflow`, then `/harn-workflow` from `.github/workflows/`; `add handbook`, then `/harn-handbook` for the modules with traps; `add decisions`, then `/harn-decision` for the implicit choices the `git log` betrays.
373
+ 4. `add intents`, then `/harn-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.
374
+ 5. `/harn-doc-audit` says what is missing or stale in the pillars you activated. It never reports a pillar you did not add.
364
375
 
365
- **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.
376
+ **What the harness checks.** From the first commit: the shape of the pillars present, the gitignore, the freshness of the render. Pillars that are absent report nothing.
366
377
 
367
378
  **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.
368
379
 
369
380
  </details>
370
381
 
382
+ <a name="add-a-pillar"></a>
383
+ <details>
384
+ <summary><strong>Add a pillar</strong></summary>
385
+
386
+ **When.** The project has outgrown its docs: a decision nobody will remember, a trap you explained twice, a first release, user research worth keeping. Or the agent says "this would go into a `decisions` pillar, which this project does not have yet".
387
+
388
+ **What you say.**
389
+
390
+ ```bash
391
+ npx @vaubaan/harness add decisions
392
+ ```
393
+
394
+ or "add the decisions pillar" to the agent.
395
+
396
+ **What happens.** `add` creates the folder, writes the pillar's starter files without overwriting anything, and re-renders: the pillar's skill, its slash command and its lines of `AGENTS.md` appear. It ends with the next step, the skill that fills the starter files.
397
+
398
+ | Pillar | Add it when | Starter files | Brings |
399
+ | ----------- | --------------------------------------------------------------------------- | -------------------------------------- | --------------------------- |
400
+ | `decisions` | A choice is costly to reverse, or someone asks "why is it done this way?" | `README.md`, the index | `/harn-decision` |
401
+ | `handbook` | An invariant or a trap took several files to learn | `README.md`, the index | `/harn-handbook`, `/harn-drift` |
402
+ | `tests` | A second kind of test, a shared fixture, a known gap | `integration-tests.md`, `e2e-tests.md` | `/harn-test-plan`, `/harn-drift` |
403
+ | `workflow` | CI, a second contributor, a release | `coding-workflow.md` | `/harn-workflow`, `/harn-drift` |
404
+ | `quality` | The same review remark comes back | `code-quality.md` | a line in `AGENTS.md` |
405
+ | `intents` | You want a change specified before it is coded, and a backlog the repo keeps | the generated index | `/harn-intent`, `/harn-drift` |
406
+ | `profiles` | You know, or want to find out, who the product is for and what hurts them | the generated index | profiles in `harn-intent-writer` |
407
+
408
+ **What the harness checks.** Once added, the pillar's contract: `add tests` leaves two files with placeholders, and the lint fails on them until `/harn-test-plan` has filled them. That is the point of adding it. An empty pillar folder fails the lint too: git would not record it.
409
+
410
+ **What you see at the end.** One more folder under `docs/`, one more skill, and a project map in `AGENTS.md` that says so. To remove a pillar, delete its folder and run `update .`.
411
+
412
+ </details>
413
+
371
414
  <a name="update-the-harness"></a>
372
415
  <details>
373
416
  <summary><strong>Update the harness</strong></summary>
374
417
 
375
418
  **When.** A new version is published.
376
419
 
377
- **What you say.**
420
+ **What you say.** `/harn-upgrade`, or by hand:
378
421
 
379
422
  ```bash
380
423
  npm i -D @vaubaan/harness@latest && npx vaubaan-harness update .
381
424
  ```
382
425
 
383
- **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.
426
+ **What happens.** The `harn-upgrade` skill pins the version wherever your project pins it, previews the update, resolves what it reports, applies it, then applies the migration notes of every version you cross: what a version asks of your own files, which no command can do for you. `update` itself 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.
384
427
 
385
428
  **What the harness checks.** `generated-fresh`: the committed render is the one of the installed version.
386
429
 
@@ -420,7 +463,7 @@ npx @vaubaan/harness uninstall .
420
463
 
421
464
  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.
422
465
  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.
423
- 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`.
466
+ 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: `/harn-doc-audit`.
424
467
 
425
468
  In database terms:
426
469
 
@@ -428,14 +471,14 @@ In database terms:
428
471
  | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
429
472
  | 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. |
430
473
  | Foreign keys | `tracks:`, `anchors:`, `spec:`, the "realized by" arrows. They point into the code database, and the linter refuses one that does not resolve. |
431
- | Integrity constraints | Nineteen linters: shape, pointers, vocabulary, freshness. Run on every commit and pull request, at zero token cost. |
432
- | Materialized views | What `update .` renders: `AGENTS.md`, the skills per engine, the intents index. Committed, never edited by hand, refreshed from their source. |
433
- | Transactions | `/intent <verb + object>`: a typed write that adds a `proposed` intent with its acceptance criteria and leaves the base consistent. |
474
+ | Integrity constraints | Twenty-one linters: shape, pointers, vocabulary, freshness. Run on every commit and pull request, at zero token cost. |
475
+ | Materialized views | What `update .` renders: `AGENTS.md`, the skills per engine, the intents and profiles indexes. Committed, never edited by hand, refreshed from their source. And what `view` derives on demand, never committed: the context graph and its canvas. |
476
+ | Transactions | `/harn-intent <verb + object>`: a typed write that adds a `proposed` intent with its acceptance criteria and leaves the base consistent. |
434
477
  | 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:`. |
435
478
 
436
479
  ## Day to day
437
480
 
438
- 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.
481
+ Eleven 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.
439
482
 
440
483
  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.
441
484
 
@@ -456,13 +499,13 @@ One word first. In the intents pillar, every heading is an **intent**: what the
456
499
  **What you say.** You describe what you want, the agent asks its questions, you converge. Then `go`, or directly:
457
500
 
458
501
  ```
459
- /intent the customer receives the invoice by email
502
+ /harn-intent the customer receives the invoice by email
460
503
  ```
461
504
 
462
505
  **What happens.**
463
506
 
464
507
  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.
465
- 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.
508
+ 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 `/harn-spec` to define it first.
466
509
  3. It writes the `proposed` intent with two to five observable acceptance criteria, then runs `update .` so the index follows.
467
510
  4. It shows you the intent. You correct, you validate. Not one line of code.
468
511
 
@@ -492,7 +535,7 @@ acceptance:
492
535
  **What you say.** Planning ends in an issue, as today, with draft criteria in its body. Later, when the work is picked up:
493
536
 
494
537
  ```
495
- /intent #123
538
+ /harn-intent #123
496
539
  ```
497
540
 
498
541
  **What happens.**
@@ -522,7 +565,7 @@ Write the rule in your `docs/workflow/coding-workflow.md`: intents are born in t
522
565
  1. The agent reads the intent, the spec section it cites, the handbook of the module. That is its whole brief.
523
566
  2. It codes, and writes tests whose titles restate the acceptance criteria, one for one.
524
567
  3. In the same pull request the intent turns `implemented`: it adds `anchors:` to the code and the tests, removes `acceptance:`, sets `last_reviewed`.
525
- 4. If the "how" changed, `/handbook`. If a structural choice slipped into the diff, `/decision`. Then `update .`.
568
+ 4. If the "how" changed, `/harn-handbook`. If a structural choice slipped into the diff, `/harn-decision`. Then `update .`.
526
569
 
527
570
  **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.
528
571
 
@@ -541,8 +584,8 @@ Write the rule in your `docs/workflow/coding-workflow.md`: intents are born in t
541
584
  **What happens.**
542
585
 
543
586
  1. **Mechanical, zero tokens.** `npx @vaubaan/harness lint`. Shape, pointers, drift, freshness of the render. Green means the structure is sound.
544
- 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.
545
- 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.
587
+ 2. **Code ↔ doc drift.** `/harn-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.
588
+ 3. **Completeness.** `/harn-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.
546
589
  4. **Where we stand.** The intents index. `proposed` intents are what remains; `deprecated` ones leave at the next release.
547
590
 
548
591
  **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.
@@ -551,6 +594,48 @@ Write the rule in your `docs/workflow/coding-workflow.md`: intents are born in t
551
594
 
552
595
  </details>
553
596
 
597
+ <a name="review-the-docs-on-a-canvas"></a>
598
+ <details>
599
+ <summary><strong>Review the docs on a canvas</strong></summary>
600
+
601
+ **When.** You want to read the context as a whole, or change several docs while seeing what each change touches: before a release, after a large pull request, when a new teammate joins.
602
+
603
+ **What you say.** `/harn-canvas`, then you talk as usual: `the handbook of the CLI is wrong about…`, `add an intent for…`. Or you comment cards in the page and click **Hand over to the agent**.
604
+
605
+ **What happens.**
606
+
607
+ 1. `vaubaan-harness review start` copies `docs/` and `README.md` aside, serves the view on your machine behind a token, and prints its URL.
608
+ 2. The page is a map of the context: one card per document, grouped by pillar, the links between documents drawn. A click on a card gathers its neighbours around it: what it cites, what cites it, the code it tracks, the words it uses, the linters that check it.
609
+ 3. Each edit the agent makes appears within a second, with **Before / Now / Differences** and the lint issues the change added or removed.
610
+ 4. A comment lands in its thread; the agent applies it with the writer rules of the pillar and answers with the file and line it changed, or with a question. A comment on a linter or a shipped skill becomes an upstream issue draft, never an edit of a generated file.
611
+ 5. At the end you choose: `review keep` leaves the changes in place, uncommitted; `review discard` restores `docs/` and `README.md` byte for byte, untracked drafts included.
612
+
613
+ **What the harness checks.** The same linters, live, on every change. The server listens on your machine only and writes nothing in `docs/`.
614
+
615
+ **What you see at the end.** A diff of docs you watched being written, and nothing committed. Without a session, `npx @vaubaan/harness view` writes the same map as one offline page, `.vaubaan/view/index.html`.
616
+
617
+ </details>
618
+
619
+ <a name="teach-the-harness-from-your-reviews"></a>
620
+ <details>
621
+ <summary><strong>Teach the harness from your reviews</strong></summary>
622
+
623
+ **When.** Reviews keep asking for the same small patches: a changelog line, a test cleanup, a word the spec does not define. Every few weeks, or after a release.
624
+
625
+ **What you say.** `/harn-improve`
626
+
627
+ **What happens.**
628
+
629
+ 1. The agent fetches the recent pull requests with your platform's CLI, then runs `vaubaan-harness lessons collect`: review comments, commits pushed after a review, fix-up commits, the threads of past review sessions and, only if you enabled it, your conversations with the agent. One line per piece of evidence, secrets masked.
630
+ 2. It groups the patches that came back at least twice and proposes, for each, the rule that would have prevented it and where it goes: `docs/quality/`, the workflow, a handbook, a test plan, a skill of yours. A rule that already exists but is not followed is reported as such.
631
+ 3. You accept, edit or reject each one. Accepted rules are written with the pillar's writer rules; rejected ones are kept so they do not come back. A rule that holds for every project becomes an issue draft for the harness, never an edit of a shipped skill.
632
+
633
+ **What the harness checks.** Nothing new: the rules land in pillars the linters already watch.
634
+
635
+ **What you see at the end.** A few lines added to your docs, each with the patches that justified it. The next run tells you whether the patch came back anyway.
636
+
637
+ </details>
638
+
554
639
  <a name="compact-the-docs"></a>
555
640
  <details>
556
641
  <summary><strong>Compact the docs</strong></summary>
@@ -561,9 +646,9 @@ Write the rule in your `docs/workflow/coding-workflow.md`: intents are born in t
561
646
 
562
647
  **What happens.**
563
648
 
564
- 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.
649
+ 1. `/harn-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.
565
650
  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.
566
- 3. `/drift` at the end, to check the rewrite lost no rule in force.
651
+ 3. `/harn-drift` at the end, to check the rewrite lost no rule in force.
567
652
 
568
653
  **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.
569
654
 
@@ -585,7 +670,7 @@ A dedicated `/compact` is decided and not shipped: it is a `proposed` intent, "R
585
670
 
586
671
  1. The agent reads the handbook of the module before touching it: invariants and traps are there.
587
672
  2. It codes, adds a regression test.
588
- 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.
673
+ 3. If an invariant or a trap changed: `/harn-handbook`. If files moved: it updates the `tracks:` and `anchors:` that cited them, or the lint fails.
589
674
 
590
675
  **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.
591
676
 
@@ -599,7 +684,7 @@ A dedicated `/compact` is decided and not shipped: it is a `proposed` intent, "R
599
684
 
600
685
  **When.** A choice is costly to reverse, a real alternative was weighed, and it will outlive the ticket. Database, framework, package layout, CI policy.
601
686
 
602
- **What you say.** `we move from SQLite to Postgres`, or after the fact, `/decision` on a diff that holds an implicit choice.
687
+ **What you say.** `we move from SQLite to Postgres`, or after the fact, `/harn-decision` on a diff that holds an implicit choice.
603
688
 
604
689
  **What happens.**
605
690
 
@@ -626,7 +711,7 @@ A dedicated `/compact` is decided and not shipped: it is a `proposed` intent, "R
626
711
  1. The agent reads `AGENTS.md`: the map and the rule.
627
712
  2. The intents index: what the user does, where in the code, and the `proposed` intents as the remaining work.
628
713
  3. The ADRs: the choices in force.
629
- 4. `/drift` if the last `last_reviewed` is old.
714
+ 4. `/harn-drift` if the last `last_reviewed` is old.
630
715
 
631
716
  **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.
632
717
 
@@ -640,7 +725,7 @@ A dedicated `/compact` is decided and not shipped: it is a `proposed` intent, "R
640
725
 
641
726
  **When.** A new CI job, a move to trunk-based, an automated release, a team rule such as "intents are born in GitHub Projects".
642
727
 
643
- **What you say.** `/workflow`, after changing `.github/workflows/`, or to write a team rule.
728
+ **What you say.** `/harn-workflow`, after changing `.github/workflows/`, or to write a team rule.
644
729
 
645
730
  **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.
646
731
 
@@ -654,6 +739,8 @@ A dedicated `/compact` is decided and not shipped: it is a `proposed` intent, "R
654
739
 
655
740
  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.
656
741
 
742
+ Your agent does not need this page: the `harn-guide` skill, rendered into every project, carries the same reflexes, plus the signs that the project is ready for a pillar it does not have yet. A step below that names a pillar the project has not added is skipped, or the agent proposes the pillar.
743
+
657
744
  <a name="before-any-task-the-reading-order"></a>
658
745
  <details>
659
746
  <summary><strong>Before any task: the reading order</strong></summary>
@@ -695,22 +782,25 @@ The first question is always the same: does the behavior visible to the user cha
695
782
 
696
783
  | The user says | Reflex | Never |
697
784
  | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
698
- | "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". |
699
- | "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. |
700
- | "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. |
785
+ | "I want the user to be able to…", "add a feature" | Talk until you converge, then `/harn-intent`. Show the intent, wait for validation, and only then code. | Open the code first. Write the intent after the code "to document". |
786
+ | "Go", after a planning discussion | Summarize the decisions in a short list and land them: `/harn-intent` for behavior, `/harn-decision` for a structural choice. Then code. | Treat the conversation as the spec. It dies with the session. |
787
+ | "Take issue #123" | Read the issue with `gh`. `/harn-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. |
701
788
  | "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`. |
702
- | "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. |
703
- | "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. |
704
- | "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. |
705
- | "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. |
706
- | "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. |
707
- | "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. |
789
+ | "Fix this bug" | Read the handbook of the module. Code, regression test. If an invariant or a trap changed, `/harn-handbook`. | Open an intent: the expected behavior does not change. Fix without a test. |
790
+ | "Refactor", "rename", "move" | Code. Update every `tracks:` and `anchors:` that cited the old paths. `/harn-handbook` if the map changed. | Let the lint fail on dead paths. Open an intent. |
791
+ | "We move to Postgres", "we change framework" | Admission test. If it passes: `/harn-decision` before the code, with the files that embody the choice. Then the code, then `/harn-handbook` and `/harn-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. |
792
+ | "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 `/harn-decision`. | Invent a plausible justification. Write the ADR before the user confirms the reason. |
793
+ | "Is it fine?", "reassure me", "where do we stand?" | Read-only mode: `lint`, then `/harn-drift`, then `/harn-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. |
794
+ | "Compact the docs", "clean up", "too long" | `/harn-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. `/harn-drift` at the end. | Delete a rule in force because it looks redundant. Rewrite everything in one pull request. |
708
795
  | "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. |
709
796
  | "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. |
710
797
  | "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. |
711
798
  | "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. |
712
- | "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. |
713
- | "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. |
799
+ | "Update the harness" | `/harn-upgrade`: pin the version, preview, `update .`, apply the migration notes of every version crossed, lint, commit the generated files. Report the preserved files that will not be refreshed. | Overwrite a file the user had modified. Skip a version's migration notes. |
800
+ | "Who is this for?", "here is our user research" | `add profiles` if the human agrees, then `harn-intent-writer` writes the profile from the research. Each intent then names the pain it relieves. | Invent a persona. Copy interview notes into the repo. |
801
+ | "Give me the tour" | `AGENTS.md`, the intents index, the ADRs, then `/harn-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. |
802
+ | "Show me the docs", "let's review the context together" | `/harn-canvas`: a review session. Give the URL, apply what the user says or comments with the pillar's writer rules, answer each thread with the file and line changed. End with keep or discard, as the user chooses. | Commit during the session. Edit a generated file or a shipped skill because a comment points at it. |
803
+ | "Reviews keep asking for the same thing" | `/harn-improve`: collect the patch events, propose one rule per recurring patch with its evidence and its pillar; write only what the user accepts. | Write a rule from one occurrence. Enable conversation histories without the user. |
714
804
 
715
805
  </details>
716
806
 
@@ -718,12 +808,13 @@ The first question is always the same: does the behavior visible to the user cha
718
808
  <details>
719
809
  <summary><strong>The refusals the agent holds</strong></summary>
720
810
 
721
- Four cases where the agent says no, explains, and offers the path. They are the only ones.
811
+ Five cases where the agent says no, explains, and offers the path. They are the only ones.
722
812
 
723
813
  - **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.
724
- - **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.
814
+ - **Inventing a word.** "The word *email* is not in the spec Vocabulary. I add it to the spec with `/harn-spec` before using it in the intent." No synonym, no plural.
725
815
  - **Editing a generated file.** "`AGENTS.md` is rendered from `docs/`. I change the source and rerun `update .`." Same for the intents index.
726
816
  - **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.
817
+ - **Adding a pillar unasked.** "This decision would go into a `decisions` pillar, which this project does not have. Shall I add it?" The agent proposes once, at the moment the work shows the need; it never creates the folder itself.
727
818
 
728
819
  </details>
729
820
 
@@ -745,23 +836,27 @@ Warning sign: if finishing requires touching a generated file, disabling a linte
745
836
 
746
837
  ### Skills
747
838
 
748
- **9 skills**, nine slash commands. A skill never says *when* to do something. It says *how* to write or check one pillar.
749
-
750
- | Command | Skill | What it does |
751
- | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
752
- | `/doc-audit` | `doc-audit` | Audits completeness and freshness of every pillar. |
753
- | `/drift` | `drift-detector` | Finds where docs no longer match the code. |
754
- | `/spec` | `spec-writer` | Writes a tech-agnostic spec, progressively: three questions to start, one section at a time after. |
755
- | `/decision` | `decision-record-writer` | Writes an ADR, spotting implicit decisions in your diff. |
756
- | `/handbook` | `handbook-writer` | Documents how a feature is actually implemented. |
757
- | `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
758
- | `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release, languages. |
759
- | `/readme` | `readme-writer` | Keeps the README in sync with the code. |
760
- | `/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. |
839
+ **13 skills**, twelve slash commands. A skill is rendered into your project while a pillar it serves is active; seven are always there. A doc-skill never says *when* your team does something. It says *how* to write or check one pillar.
840
+
841
+ | Command | Skill | Rendered with | What it does |
842
+ | ------------------ | ------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------- |
843
+ | — | `harn-guide` | always | How to work in a harnessed project: reading order, which skill for which request, what to refuse, and when to propose a pillar the project does not have yet. |
844
+ | `/harn-upgrade` | `harn-upgrade` | always | Moves the project to a newer harness version, with the migration notes of every version crossed. |
845
+ | `/harn-doc-audit` | `harn-doc-audit` | always | Audits completeness and freshness of the active pillars. |
846
+ | `/harn-spec` | `harn-spec-writer` | always | Writes a tech-agnostic spec, progressively: three questions to start, one section at a time after. |
847
+ | `/harn-readme` | `harn-readme-writer` | always | Keeps the README in sync with the code. |
848
+ | `/harn-canvas` | `harn-canvas-review` | always | Opens the live view of the context; you talk or comment cards, the agent changes the docs and answers in the thread. Ends with keep or discard, never a commit. |
849
+ | `/harn-improve` | `harn-self-improve` | always | Finds the patches reviews keep asking for and proposes the rule that prevents each, with its evidence, in the right pillar. |
850
+ | `/harn-decision` | `harn-decision-record-writer` | `decisions` | Writes an ADR, spotting implicit decisions in your diff. |
851
+ | `/harn-handbook` | `harn-handbook-writer` | `handbook` | Documents how a feature is actually implemented. |
852
+ | `/harn-test-plan` | `harn-test-plan-writer` | `tests` | Keeps integration and e2e test plans up to date. |
853
+ | `/harn-workflow` | `harn-workflow-writer` | `workflow` | Documents CI, environments, PR process, branches, release, languages. |
854
+ | `/harn-drift` | `harn-drift-detector` | `handbook`, `tests`, `workflow` or `intents` | Finds where docs no longer match the code. |
855
+ | `/harn-intent` | `harn-intent-writer` | `intents` or `profiles` | `/harn-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. Writes the user profiles and names, on each intent, the pain it relieves. |
761
856
 
762
857
  ### Linters
763
858
 
764
- **19 linters**, fast enough to run on every commit.
859
+ **21 linters**, fast enough to run on every commit. A linter of a pillar you have not added reports nothing.
765
860
 
766
861
  <details>
767
862
  <summary>See the list</summary>
@@ -769,8 +864,8 @@ Warning sign: if finishing requires touching a generated file, disabling a linte
769
864
  | Linter | Checks |
770
865
  | ------------------------------------ | ------------------------------------------------------------------- |
771
866
  | `readme-presence`, `readme-sections` | `README.md` exists and has a title and a quick start. |
772
- | `doc-layout`, `cardinal-files` | The `docs/` folders and required files exist. |
773
- | `spec-has-content`, `spec-tech-agnostic` | Specs exist and don't name frameworks or vendors. |
867
+ | `doc-layout`, `cardinal-files` | No pillar folder is empty; an active pillar has its required files. |
868
+ | `spec-has-content`, `spec-tech-agnostic` | A warning while there is no spec; specs don't name frameworks or vendors. |
774
869
  | `decision-schema` | Each ADR has its four sections. |
775
870
  | `adr-no-tracks`, `orphan-decisions` | ADRs carry no `tracks:` and are referenced somewhere. |
776
871
  | `frontmatter-tracks`, `tracks-drift` | Tracked paths exist; docs aren't older than the code they track. |
@@ -778,7 +873,8 @@ Warning sign: if finishing requires touching a generated file, disabling a linte
778
873
  | `gitignore-harness` | Overrides and reports are ignored; generated files are not. |
779
874
  | `generated-fresh` | Committed generated files match the current render. |
780
875
  | `quality-schema` | `docs/quality/code-quality.md` has its sections, if you use it. |
781
- | `intent-schema`, `intent-anchors`, `intent-vocabulary`, `intent-graph` | Optional `docs/intents/`: node grammar, anchors exist, entities are spec vocabulary, nothing requires what nothing creates. |
876
+ | `intent-schema`, `intent-anchors`, `intent-vocabulary`, `intent-graph` | `docs/intents/`: node grammar, anchors exist, entities are spec vocabulary, nothing requires what nothing creates. |
877
+ | `profile-schema`, `intent-profiles` | `docs/profiles/`: a profile names its pains and gains, a validated one has evidence; an intent's actors are profiles and what it relieves is one of their pains. |
782
878
 
783
879
  </details>
784
880
 
@@ -797,10 +893,14 @@ You name your engines; nothing is rendered for a tool you don't use. Add one lat
797
893
  | Command | What it does |
798
894
  | ------------------------------------- | -------------------------------------------------------------------------------------------- |
799
895
  | `init <dir> --engines=<list>` | Render the harness into a project. Re-run it to change engines. |
896
+ | `add <pillar> [dir]` | Activate a pillar: starter files, its skill, its command. Never overwrites a file. |
800
897
  | `update [dir]` | Re-render with the installed version, keeping your engines. `--dry-run --json` previews. |
801
898
  | `uninstall <dir>` | Remove what `init` wrote, leaving your own files in place. |
802
899
  | `lint` | Run the linters. `--format json`, `--pillar <name>`, `--only <ids>`. |
803
- | `check <dir>` | Quick layout check: doc folders and `.gitignore`. |
900
+ | `view [dir]` | Write the context graph (`.vaubaan/graph.json`) and its offline canvas (`.vaubaan/view/index.html`). |
901
+ | `review start \| next \| reply \| keep \| discard` | A review session: the canvas served locally and live, comments handed to the agent; `discard` restores `docs/` as it was. |
902
+ | `lessons collect [dir]` | Extract the patch events `/harn-improve` turns into rules (`.vaubaan/lessons/events.json`). |
903
+ | `check <dir>` | Quick layout check: the README and `.gitignore`. |
804
904
  | `render --engines=<list> --out <dir>` | Preview the render somewhere harmless. |
805
905
 
806
906
  Run them with `npx @vaubaan/harness <command>`. Install the package in the project (`npm i -D @vaubaan/harness`) so CI, pre-commit and your teammates render with the same version.
@@ -833,13 +933,29 @@ Try a custom skill or command without forking, in a gitignored `.harness-overrid
833
933
  .harness-overrides/
834
934
  skills/ *.skill.md
835
935
  commands/ *.cmd.md
836
- disable.yaml # disable: [readme-writer, workflow-writer]
936
+ disable.yaml # disable: [harn-readme-writer, harn-workflow-writer]
837
937
  ```
838
938
 
839
939
  Overrides are personal and disposable. Skills meant for the whole team go in `docs/skills/`, which is versioned. See [overrides loading](./docs/handbook/overrides-loading.md).
840
940
 
841
941
  </details>
842
942
 
943
+ <details>
944
+ <summary><b>Lessons from your agent conversations</b></summary>
945
+
946
+ `/harn-improve` reads the history, your pull requests and the comments of past review sessions. Agent conversations are often where corrections happen, but they are private: they are read only if you list the source, and quoted one line at a time.
947
+
948
+ ```json
949
+ {
950
+ "lessons": {
951
+ "sources": ["claude-code"],
952
+ "threshold": 2
953
+ }
954
+ }
955
+ ```
956
+
957
+ </details>
958
+
843
959
  <details>
844
960
  <summary><b>Updating</b></summary>
845
961
 
@@ -859,21 +975,29 @@ npx @vaubaan/harness update . # then commit the result
859
975
 
860
976
  **Why commit the generated files?** So a clone has the whole context without installing the harness, and so the context survives a teammate who has never heard of it. `lint` fails when a committed file no longer matches the render, which is how it stays honest.
861
977
 
978
+ **Do I have to write all of this before I can code?** No. A README is enough to start, and the lint passes on it. The spec comes next; every other pillar waits until you add it. The harness never asks for a document about something your project does not have yet.
979
+
980
+ **How does the agent know when to suggest a pillar?** `AGENTS.md` names the pillars the project has not added, in one line, and the `harn-guide` skill holds the sign for each: a choice costly to reverse for `decisions`, a trap explained twice for `handbook`, a first release for `workflow`. The agent proposes once, when it sees the sign; you say yes or no.
981
+
982
+ **Are profiles the same as personas?** A profile is a kind of *user* your product serves, with pains and gains backed by research. The personas the harness does not ship are *agent roles* (reviewer, planner). Different things; hence the different word.
983
+
862
984
  **Why no agents or personas?** Because how a team works is the team's decision. The harness imposes one rule, doc-first, and asks you to write the rest in `docs/workflow/`. A persona you like belongs in `docs/skills/`, versioned with your project.
863
985
 
864
986
  **Why no engine hook?** A hook that re-injects a report at the end of every turn costs tokens you don't see, and every engine does it differently. A pre-commit hook and CI cost nothing and work the same everywhere.
865
987
 
866
- **Can I write my docs in another language?** Prose, yes. The linters look for English section headings (`## Context`, `## Decision`…); French headings are also accepted. `/workflow` records which languages you use for docs, code and domain.
988
+ **Can I write my docs in another language?** Prose, yes. The linters look for English section headings (`## Context`, `## Decision`…); French headings are also accepted. `/harn-workflow` records which languages you use for docs, code and domain.
867
989
 
868
990
  **Does it work in a monorepo?** Run it at the repository root and use `lint.ignore` for sub-projects you don't want checked.
869
991
 
870
- **Coming from 1.x?** `--with-mcp`, the Stop hook and the four personas are gone. Run `update .`, remove the old Stop hook entry from your engine settings if you had one, un-ignore the generated files, and commit. The [changelog](./CHANGELOG.md) has the full list.
992
+ **Coming from 2.x?** Nothing breaks: your six pillars exist, so they stay active. `/harn-upgrade` walks through the rest; a pillar you kept only to satisfy the lint can now be deleted.
993
+
994
+ **Coming from 1.x?** `--with-mcp`, the Stop hook and the four personas are gone. Go to the last 2.x first: run `update .`, remove the old Stop hook entry from your engine settings if you had one (in 3.0 it fails instead of doing nothing), un-ignore the generated files, and commit. The [changelog](./CHANGELOG.md) has the full list.
871
995
 
872
996
  **Is this tied to Vaubaan?** No. Vaubaan builds it and uses it on its own projects, including this one, which is harnessed by itself.
873
997
 
874
998
  ## Where this is going
875
999
 
876
- 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.
1000
+ Shipped: the context view and review sessions (`view`, `/harn-canvas`) and lessons from reviews (`/harn-improve`); pillars on demand (`add <pillar>`), the `docs/profiles/` pillar that says who the product serves and which intent relieves which pain, the `docs/intents/` pillar and its typed context transaction, `/harn-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.
877
1001
 
878
1002
  ## Documentation
879
1003