@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.
- package/README.md +207 -83
- package/dist/cli/index.js +4165 -843
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/harn-canvas.cmd.md +23 -0
- package/dist/commands/{decision.cmd.md → harn-decision.cmd.md} +6 -6
- package/dist/commands/{doc-audit.cmd.md → harn-doc-audit.cmd.md} +7 -7
- package/dist/commands/{drift.cmd.md → harn-drift.cmd.md} +6 -6
- package/dist/commands/{handbook.cmd.md → harn-handbook.cmd.md} +6 -6
- package/dist/commands/harn-improve.cmd.md +20 -0
- package/dist/commands/{intent.cmd.md → harn-intent.cmd.md} +9 -9
- package/dist/commands/{readme.cmd.md → harn-readme.cmd.md} +6 -6
- package/dist/commands/{spec.cmd.md → harn-spec.cmd.md} +6 -6
- package/dist/commands/{test-plan.cmd.md → harn-test-plan.cmd.md} +6 -6
- package/dist/commands/harn-upgrade.cmd.md +22 -0
- package/dist/commands/{workflow.cmd.md → harn-workflow.cmd.md} +6 -6
- package/dist/index.d.ts +32 -3
- package/dist/index.js +533 -96
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +468 -93
- package/dist/init.js.map +1 -1
- package/dist/linters/index.d.ts +3 -34
- package/dist/linters/index.js +996 -554
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +96 -6
- package/dist/parser/index.js +220 -10
- package/dist/parser/index.js.map +1 -1
- package/dist/render-BhUar2gf.d.ts +81 -0
- package/dist/render.d.ts +1 -1
- package/dist/render.js +233 -22
- package/dist/render.js.map +1 -1
- package/dist/skills/harn-canvas-review.skill.md +87 -0
- package/dist/skills/{decision-record-writer.skill.md → harn-decision-record-writer.skill.md} +2 -1
- package/dist/skills/{doc-audit.skill.md → harn-doc-audit.skill.md} +75 -26
- package/dist/skills/{drift-detector.skill.md → harn-drift-detector.skill.md} +15 -14
- package/dist/skills/harn-guide.skill.md +137 -0
- package/dist/skills/{handbook-writer.skill.md → harn-handbook-writer.skill.md} +2 -1
- package/dist/skills/{intent-writer.skill.md → harn-intent-writer.skill.md} +83 -16
- package/dist/skills/{readme-writer.skill.md → harn-readme-writer.skill.md} +4 -4
- package/dist/skills/harn-self-improve.skill.md +84 -0
- package/dist/skills/{spec-writer.skill.md → harn-spec-writer.skill.md} +8 -8
- package/dist/skills/{test-plan-writer.skill.md → harn-test-plan-writer.skill.md} +6 -5
- package/dist/skills/harn-upgrade.skill.md +171 -0
- package/dist/skills/{workflow-writer.skill.md → harn-workflow-writer.skill.md} +6 -5
- package/dist/templates/decisions-index.md.tmpl +11 -0
- package/dist/templates/handbook-index.md.tmpl +8 -0
- package/dist/templates/profile.md.tmpl +30 -0
- package/dist/types-CfUByAIr.d.ts +35 -0
- package/dist/view/index.d.ts +117 -0
- package/dist/view/index.js +3987 -0
- package/dist/view/index.js.map +1 -0
- package/package.json +6 -2
- 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.**
|
|
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.**
|
|
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/` |
|
|
68
|
-
| `docs/skills/` |
|
|
69
|
-
| `docs/intents/` |
|
|
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/
|
|
117
|
+
├── quality/
|
|
107
118
|
│ └── code-quality.md
|
|
108
|
-
├── intents/
|
|
119
|
+
├── intents/
|
|
109
120
|
│ ├── send-an-invoice.md
|
|
110
121
|
│ └── README.md # rendered: the intent tree
|
|
111
|
-
└── skills/
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
334
|
-
2. `/
|
|
335
|
-
3.
|
|
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
|
|
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
|
|
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. `/
|
|
362
|
-
3.
|
|
363
|
-
4. `/
|
|
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.
|
|
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 |
|
|
432
|
-
| Materialized views | What `update .` renders: `AGENTS.md`, the skills per engine, the intents
|
|
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
|
-
|
|
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" |
|
|
713
|
-
| "
|
|
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
|
-
|
|
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
|
-
**
|
|
749
|
-
|
|
750
|
-
| Command
|
|
751
|
-
|
|
|
752
|
-
|
|
|
753
|
-
| `/
|
|
754
|
-
| `/
|
|
755
|
-
| `/
|
|
756
|
-
| `/
|
|
757
|
-
| `/
|
|
758
|
-
| `/
|
|
759
|
-
| `/
|
|
760
|
-
| `/
|
|
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
|
-
**
|
|
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` |
|
|
773
|
-
| `spec-has-content`, `spec-tech-agnostic` |
|
|
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` |
|
|
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
|
-
| `
|
|
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
|
|
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
|
|
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
|
|