@vaubaan/harness 2.4.0 → 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 +5 -1
  53. package/dist/render-CTx7VNOK.d.ts +0 -45
@@ -1,5 +1,5 @@
1
1
  ---
2
- id: drift-detector
2
+ id: harn-drift-detector
3
3
  description: |
4
4
  Detects code ↔ doc drift. For each doc file that declares a
5
5
  `tracks: [...]`, checks that the doc still reflects the current
@@ -7,6 +7,7 @@ description: |
7
7
  cannot see (linters count commits, you read the content).
8
8
  engines: [claude-code, codex-cli, opencode]
9
9
  requires: [multi-step]
10
+ pillars: [handbook, tests, workflow, intents]
10
11
  tags: [drift, doc, audit]
11
12
  ---
12
13
 
@@ -19,9 +20,9 @@ the doc content still matches reality.
19
20
 
20
21
  ## When to invoke you
21
22
 
22
- - After `doc-audit`, during a review, to dig into the flagged
23
+ - After `harn-doc-audit`, during a review, to dig into the flagged
23
24
  `⚠️ stale` items.
24
- - `/drift` or `/drift <handbook-name>` invoked by the human.
25
+ - `/harn-drift` or `/harn-drift <handbook-name>` invoked by the human.
25
26
  - Before a major release: full drift audit.
26
27
 
27
28
  ## Procedure
@@ -32,7 +33,7 @@ the doc content still matches reality.
32
33
  - non-existent tracked paths (forgotten placeholders, deleted
33
34
  files);
34
35
  - ADRs carrying a `tracks:` (forbidden — see the
35
- `decision-record-writer` guardrail).
36
+ `harn-decision-record-writer` guardrail).
36
37
  Include these results in the "Hard drift" section of the report and
37
38
  move on to the semantic analysis.
38
39
  1. **Inventory of targets**: all files under `docs/handbook/`,
@@ -123,7 +124,7 @@ lie about their own scope._
123
124
  - ❌ `docs/handbook/foo.md` tracks `feature/p7-mcp-config-regen` —
124
125
  non-existent path (planning placeholder never replaced?).
125
126
  - ❌ `docs/decisions/stack.md` carries `tracks: [package.json, ...]` —
126
- an ADR must not have `tracks:` (see the `decision-record-writer`
127
+ an ADR must not have `tracks:` (see the `harn-decision-record-writer`
127
128
  guardrail).
128
129
 
129
130
  ## Hard drift (N items)
@@ -170,32 +171,32 @@ lie about their own scope._
170
171
 
171
172
  - ⚠️ `src/new-feature/` (introduced commit <sha>) — no handbook
172
173
  tracks these files and no intent anchors them. Suggested:
173
- `/handbook new-feature` for the how, `/intent` to map the user
174
+ `/harn-handbook new-feature` for the how, `/harn-intent` to map the user
174
175
  activity.
175
176
  - ⚠️ Script `package.json:deploy:preview` — not mentioned in
176
177
  `coding-workflow.md`.
177
178
 
178
179
  ## Recommendations
179
180
 
180
- 1. `/handbook <name>` to update <handbook>.
181
- 2. `/test-plan integration` to fix the fixture description.
182
- 3. `/workflow` to resync `coding-workflow.md` vs `ci.yml`.
181
+ 1. `/harn-handbook <name>` to update <handbook>.
182
+ 2. `/harn-test-plan integration` to fix the fixture description.
183
+ 3. `/harn-workflow` to resync `coding-workflow.md` vs `ci.yml`.
183
184
  4. Write an ADR for change <X> if it was a decision (see
184
- `/decision`).
185
- 5. `/intent` to add the missing node or re-anchor the intent.
185
+ `/harn-decision`).
186
+ 5. `/harn-intent` to add the missing node or re-anchor the intent.
186
187
  ```
187
188
 
188
189
  ## Guardrails
189
190
 
190
191
  - **Fix nothing**. You detect, you list, you recommend. The writers
191
- (`handbook-writer`, `test-plan-writer`, `workflow-writer`,
192
- `intent-writer` via `/intent`) are there to fix.
192
+ (`harn-handbook-writer`, `harn-test-plan-writer`, `harn-workflow-writer`,
193
+ `harn-intent-writer` via `/harn-intent`) are there to fix.
193
194
  - **No false positives on details**. If the handbook says "the
194
195
  function returns a Result<T, E>" and the code returns `Result<T, E>`
195
196
  but with a slightly different T type, that is not hard drift — it
196
197
  is normal evolution. Stay reasonable.
197
198
  - **Cross-link to the writers**. Each reported drift must point to the
198
- skill that can fix it (`/handbook`, `/test-plan`, etc.).
199
+ skill that can fix it (`/harn-handbook`, `/harn-test-plan`, etc.).
199
200
  - **Do not re-implement `lint:tracks-drift`**. The linter counts
200
201
  commits; you *read* the content. If a doc file has 3 commits of
201
202
  drift but the content is still correct, do not flag it.
@@ -0,0 +1,137 @@
1
+ ---
2
+ id: harn-guide
3
+ description: |
4
+ How to work in a project harnessed by @vaubaan/harness: the reading
5
+ order, which skill answers which request, what to refuse, how to end a
6
+ task, and when to propose a pillar the project does not have yet
7
+ (`npx @vaubaan/harness add <pillar>`). Load it at the start of any
8
+ task when you do not know the project's docs, when a doc you would
9
+ need is missing, or when the project outgrows its current docs.
10
+ engines: [claude-code, codex-cli, opencode]
11
+ tags: [harness, onboarding]
12
+ ---
13
+
14
+ # Harness Guide
15
+
16
+ You work in a project harnessed by `@vaubaan/harness`. The repo holds two
17
+ databases: the **code** (sources, tests, configs) and the **context**
18
+ (`README.md` and `docs/`): what the code cannot say, in a few Markdown
19
+ files that point to the code for everything else. The harness is the
20
+ schema of the context, its linters and the skills that write it. This
21
+ skill is the one to read before the others: it says which reflex a
22
+ request calls for, and when to call for none.
23
+
24
+ `AGENTS.md` holds the working rule and the project map; the team's
25
+ procedure is in `docs/workflow/` when that pillar exists. Neither is
26
+ repeated here.
27
+
28
+ ## The project decides how much context it keeps
29
+
30
+ A pillar is one kind of information with its place, its form and its
31
+ writer skill. **README and spec are always there. Every other pillar is
32
+ active only when its folder under `docs/` exists.** The project map of
33
+ `AGENTS.md` lists the active ones and names the others in one line.
34
+
35
+ An inactive pillar is not a gap. A project that started this week does
36
+ not need a release workflow or test plans; it needs a README and, soon, a
37
+ spec. Do not report a missing pillar as an error, do not write files for
38
+ a pillar that is not active, and never create its folder yourself.
39
+
40
+ ## When a pillar becomes worth adding
41
+
42
+ Propose a pillar when the work in front of you shows the sign below, at
43
+ the moment it shows, in one sentence: what you saw, which pillar would
44
+ hold it, the command. Then continue the task; the human decides.
45
+
46
+ | Sign in the work | Pillar | Command |
47
+ |---|---|---|
48
+ | A choice that is costly to reverse is being made (a database, a framework, a protocol), or the human asks "why is it done this way?" and nothing answers | `decisions` | `npx @vaubaan/harness add decisions` |
49
+ | You had to read several files to learn an invariant, a trap or a manual step; or you are about to explain one in a commit message | `handbook` | `npx @vaubaan/harness add handbook` |
50
+ | The project has a second kind of test, a shared fixture, or a behavior nobody tests on purpose | `tests` | `npx @vaubaan/harness add tests` |
51
+ | A CI file, a second contributor, a release, a branch rule the human just told you | `workflow` | `npx @vaubaan/harness add workflow` |
52
+ | The same review remark about code style or structure comes back, or the team accepts a deviation from a common rule | `quality` | `npx @vaubaan/harness add quality` |
53
+ | Behavior visible to the user is about to change and the decision would otherwise live only in this conversation; or the human asks what the product does or what is left to build | `intents` | `npx @vaubaan/harness add intents` |
54
+ | The human talks about who the users are, what hurts them, interviews, personas, a value proposition; or you cannot say for whom a feature is built | `profiles` | `npx @vaubaan/harness add profiles` |
55
+ | A domain procedure you would otherwise re-learn each session (a tax rule, a migration runbook) | `skills` | create `docs/skills/<id>.skill.md`, then `update .` |
56
+
57
+ Rules of the proposal:
58
+
59
+ - **One pillar at a time, the one the current task needs.** Never a
60
+ list, never "you should also".
61
+ - **Propose once.** If the human declines, do not raise it again in the
62
+ session; do the task with what exists.
63
+ - **Until it is added, put nothing elsewhere.** No `docs/notes.md`, no
64
+ decision hidden in a handbook, no rule in `AGENTS.md`.
65
+ - **`add` writes starter files with placeholders.** The lint fails on
66
+ them until you fill them with the pillar's writer skill: do it in the
67
+ same change, or do not add the pillar.
68
+ - **Removing** a pillar is deleting its folder, then
69
+ `npx @vaubaan/harness update .`.
70
+
71
+ ## Before a task: the reading order
72
+
73
+ 1. `AGENTS.md`: the rule, the map, the checks.
74
+ 2. `docs/intents/README.md`, when it exists: what the product does,
75
+ where in the code, what is `proposed`. `docs/profiles/README.md`,
76
+ when it exists: for whom, and which pain nothing relieves yet.
77
+ 3. The spec section the request touches, and its intent.
78
+ 4. The handbook of the module, when there is one, before opening the
79
+ code: the invariants and the traps are there.
80
+ 5. The workflow, when there is one, before committing, branching or
81
+ opening a pull request.
82
+
83
+ ## What the user says, what you do
84
+
85
+ The first question is always: does the behavior visible to the user
86
+ change? Skip a step whose pillar is inactive, or propose the pillar when
87
+ the table above says so.
88
+
89
+ | The user says | Reflex | Never |
90
+ |---|---|---|
91
+ | "I want the user to be able to…", "add a feature" | Talk until you converge, then `/harn-intent`. Show the intent, wait for validation, then code. | Open the code first. Write the intent after the code. |
92
+ | "Go", after a planning discussion | Land the decisions: `/harn-intent` for behavior, `/harn-decision` for a structural choice, `/harn-spec` for a rule or a word. Then code. | Treat the conversation as the spec: it dies with the session. |
93
+ | "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. |
94
+ | "Refactor", "rename", "move" | Code. Update every `tracks:` and `anchors:` that cited the old paths. | Let the lint fail on dead paths. |
95
+ | "We move to X", "we change framework" | Is it costly to reverse, with a real alternative? Then `/harn-decision` before the code. | Leave the why in a commit message. |
96
+ | "Why is it done this way?" | Look for the ADR, the handbook, the spec. Answer by citing. If nothing answers, say so. | Invent a plausible justification. |
97
+ | "Who is this for?", "here is our user research" | The `harn-intent-writer` skill writes or updates a profile; then each intent names the pain it relieves. | Invent a persona. Copy interview notes into the repo. |
98
+ | "Is it fine?", "where do we stand?" | Read-only: `npx @vaubaan/harness lint`, then `/harn-drift`, then `/harn-doc-audit`. Report: healthy, drifted, missing. | Fix things on the way. |
99
+ | "Show me the docs", "let's review the context", "I want to see the changes as you make them" | `/harn-canvas`: start a review session, give the URL, apply what the human says or comments with the pillar's writer rules, answer each thread. End with keep or discard. | Commit during the session. Edit a generated file or a shipped skill because a comment points at it. |
100
+ | "Reviews keep asking for the same thing", "learn from our reviews" | `/harn-improve`: collect the patch events, propose one rule per recurring patch with its evidence; write only the accepted ones. | Write a rule from one occurrence. Enable conversation histories without the human. |
101
+ | "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; who the user is → profile. | Write into `AGENTS.md`. Create `docs/notes.md`. Paraphrase the code. |
102
+ | "Change AGENTS.md / CLAUDE.md" | They are rendered. Change the source in `docs/` or `docs/skills/`, then `update .`. | Edit the file. |
103
+ | "The lint fails" | The message names the file and the skill. Fix the cause; for drift, reread the code and update the doc, not only the date. | Disable the linter. Touch `last_reviewed` without rereading. |
104
+ | "Update the harness" | The `harn-upgrade` skill (`/harn-upgrade`). | Bump the package and stop there. |
105
+
106
+ ## The refusals you hold
107
+
108
+ Say no, explain in one sentence, offer the path:
109
+
110
+ - **Coding without a spec.** The subsystem you touch has no spec: stop
111
+ and report the gap, or write its minimum with `/harn-spec`.
112
+ - **Coding before the intent**, when `docs/intents/` is active and the
113
+ change is visible to the user. If the human insists, it is their call:
114
+ do it, and write the intent in the same change.
115
+ - **Inventing a word.** A word missing from the spec's Vocabulary goes
116
+ into the spec first. The same for a pain: it goes into the profile
117
+ first.
118
+ - **Editing a generated file**: `AGENTS.md`, `CLAUDE.md`, the engine
119
+ folders, `.harness-manifest.json`, `docs/intents/README.md`,
120
+ `docs/profiles/README.md`. Change the source, run `update .`.
121
+ - **Adding a pillar unasked.** You propose; the human decides.
122
+
123
+ ## At the end of a task
124
+
125
+ 1. The docs the change touches are current, in the active pillars. No
126
+ more.
127
+ 2. `npx @vaubaan/harness update .` if an intent, a profile, a project
128
+ skill or a pillar changed.
129
+ 3. `npx @vaubaan/harness lint`: green, or fixed with the skill the
130
+ message names.
131
+ 4. Commit and open the pull request as the project's workflow says.
132
+ 5. Report in three lines: what was done, what was verified, what is left
133
+ and why. A pillar you proposed and the human declined is not "left".
134
+
135
+ Warning sign: if finishing requires editing a generated file, disabling
136
+ a linter, inventing a word or creating a pillar folder by hand, stop: a
137
+ step was skipped upstream.
@@ -1,5 +1,5 @@
1
1
  ---
2
- id: handbook-writer
2
+ id: harn-handbook-writer
3
3
  description: |
4
4
  Writes or updates `docs/handbook/<slug>.md`: only what an agent cannot
5
5
  read quickly in the code (entry points, cross-file invariants, traps,
@@ -7,6 +7,7 @@ description: |
7
7
  the code. Keeps the `tracks: [...]` frontmatter valid for drift detection.
8
8
  engines: [claude-code, codex-cli, opencode]
9
9
  requires: [multi-step]
10
+ pillars: [handbook]
10
11
  tags: [handbook, doc, writer]
11
12
  ---
12
13
 
@@ -1,14 +1,17 @@
1
1
  ---
2
- id: intent-writer
2
+ id: harn-intent-writer
3
3
  description: |
4
4
  Writes or updates `docs/intents/<slug>.md`: the user intents of
5
5
  the project at every scale, one tree, anchored to the code. One node at
6
6
  a time. Greenfield: three questions. Mature: reads the code's entry
7
- points and proposes anchored terminal intents. `/intent <verb + object>`
7
+ points and proposes anchored terminal intents. `/harn-intent <verb + object>`
8
8
  adds a `proposed` intent with its acceptance criteria before any code
9
- is written.
9
+ is written. Also writes the user profiles under `docs/profiles/` (who
10
+ the project serves, their pains and gains) and names, on an intent,
11
+ the profile it serves and the pain it relieves.
10
12
  engines: [claude-code, codex-cli, opencode]
11
13
  requires: [multi-step]
14
+ pillars: [intents, profiles]
12
15
  tags: [intents, doc, writer]
13
16
  ---
14
17
 
@@ -51,12 +54,15 @@ split into two level-1 intents; never nest a file in another with a
51
54
 
52
55
  ## When to invoke you
53
56
 
54
- - `/intent <verb + object>`: a visible change of behavior is about to be
57
+ - The human points to user research (interviews, a synthesis, a value
58
+ proposition canvas) or asks who the project is for: write or update a
59
+ profile (see *Profiles* below).
60
+ - `/harn-intent <verb + object>`: a visible change of behavior is about to be
55
61
  built. This is the doc-first rule of `AGENTS.md`; nothing is coded
56
62
  before the intent exists.
57
- - `/intent` without argument: map the tree or extend it, a new level-1
63
+ - `/harn-intent` without argument: map the tree or extend it, a new level-1
58
64
  intent or a node to add to an existing one.
59
- - `doc-audit` reports a spec without intents, or a pending increment.
65
+ - `harn-doc-audit` reports a spec without intents, or a pending increment.
60
66
  - A pull request delivers a `proposed` intent: pass it `implemented`.
61
67
 
62
68
  ## Format
@@ -80,6 +86,8 @@ As a <actor>, I want <intent> so that <outcome>. ← intent statement
80
86
 
81
87
  requires: <entity>, <entity>
82
88
  creates: <entity>
89
+ relieves: <pain> ← only with docs/profiles/
90
+ delivers: <gain> ← only with docs/profiles/
83
91
  anchors: <path or glob>, <path or glob>
84
92
  spec: ../spec/<subsystem>.md#<section>
85
93
 
@@ -98,16 +106,71 @@ Rules the linters enforce (`lint:intent-*`), so apply them as you write:
98
106
  on an internal node, or an unknown field, fail the lint.
99
107
  - An `implemented` intent has `anchors:` that exist; a `proposed` intent has
100
108
  at least one `acceptance:` item.
101
- - An entity is the kebab-case slug of a bold term opening a bullet in the
102
- Vocabulary section of a linked spec (`**Generated file**` →
109
+ - An entity is the kebab-case slug of a bold term opening a bullet, or of
110
+ the first cell of a table row, in the Vocabulary section of a linked spec (`**Generated file**` →
103
111
  `generated-file`). Singular, no synonym. A missing word goes into the
104
- spec first (`/spec`), never into the intent file as an invention.
112
+ spec first (`/harn-spec`), never into the intent file as an invention.
105
113
  - `spec:` paths resolve. `docs/intents/README.md` is generated: never
106
114
  edit it; after any change run `npx @vaubaan/harness update .`.
107
115
 
116
+ ## Profiles
117
+
118
+ Only when `docs/profiles/` exists (spec §9.1.4 of the harness). A profile
119
+ is a kind of user the project serves, never an agent role. One file
120
+ `docs/profiles/<slug>.md`; the slug is the name the intents use in
121
+ `actors:`.
122
+
123
+ ```markdown
124
+ ---
125
+ title: <Who they are, in a few words>
126
+ status: hypothesis | validated
127
+ evidence: <relative path or URL> ← required when validated
128
+ last_reviewed: YYYY-MM-DD
129
+ ---
130
+
131
+ # <Who they are>
132
+
133
+ <One paragraph: who, in what situation.>
134
+
135
+ ## Pains
136
+
137
+ - **<Name of the pain>** — <what hurts, in the user's terms>
138
+
139
+ ## Gains
140
+
141
+ - **<Name of the gain>** — <the outcome they hope for>
142
+ ```
143
+
144
+ - **Write from evidence, never from imagination.** Read the research the
145
+ human points to and propose the profile; they correct. With no
146
+ research, write a `hypothesis` and say what would validate it. Never
147
+ set `validated` without an `evidence:` you have read or the human
148
+ vouches for.
149
+ - **Do not copy the research.** Interview notes hold personal data: the
150
+ profile links to them, or to their synthesis, and keeps only the pain.
151
+ - **A pain is what the user lives**, not the absence of a feature:
152
+ "cannot tell which invoices are late", never "no dashboard".
153
+ - **The order is the rank**: the most severe pain first. Ask the human
154
+ when the research does not say.
155
+ - **3 to 7 pains, 3 to 7 gains, 20 to 40 lines.** A longer list has not
156
+ been ranked yet.
157
+ - **No jobs section.** What the profile is trying to do is its intents:
158
+ the level-1 intents that name it in `actors:`.
159
+ - **On every intent you write**, while the pillar is active: `actors:`
160
+ holds profile slugs, and you ask which pain the intent relieves or
161
+ which gain it delivers, then write `relieves:` / `delivers:` on the
162
+ terminal intent with the slugs (`**Context rot**` → `context-rot`).
163
+ "None" is an answer: say that the intent then serves nobody yet and
164
+ let the human decide. A pain the research does not hold goes into the
165
+ profile first, never into the intent as an invention.
166
+ - **Check** with `npx @vaubaan/harness lint --pillar profiles`, then
167
+ `npx @vaubaan/harness update .`: the generated
168
+ `docs/profiles/README.md` shows which intent serves which pain, and
169
+ which pain nothing relieves yet. Never edit it.
170
+
108
171
  ## Procedure
109
172
 
110
- 1. **Locate.** With `/intent <verb + object>`: find the level-1 intent
173
+ 1. **Locate.** With `/harn-intent <verb + object>`: find the level-1 intent
111
174
  it belongs to by reading `docs/intents/README.md` (the generated
112
175
  index) and the file titles. None fits → a new level-1 file, slug from
113
176
  the verb + object. Ask when two fit. Without an argument: read the
@@ -128,11 +191,11 @@ Rules the linters enforce (`lint:intent-*`), so apply them as you write:
128
191
  answering. One sub-domain first, to stabilize the vocabulary, then
129
192
  extend. A code-graph tool (an MCP server the project configured)
130
193
  helps if present; read the code if not. The harness installs none.
131
- 3. **`/intent <verb + object>`** (the typed transaction): write the intent as
194
+ 3. **`/harn-intent <verb + object>`** (the typed transaction): write the intent as
132
195
  `proposed`, at the right place in the tree, with 2 to 5 observable
133
196
  acceptance criteria and its `requires:` / `creates:`. **Refuse** to
134
197
  write an entity that is in no linked spec's Vocabulary: stop and
135
- redirect to `/spec` so the word is defined first. No `anchors:` yet.
198
+ redirect to `/harn-spec` so the word is defined first. No `anchors:` yet.
136
199
  4. **Deliver** (`proposed` → `implemented`, in the pull request that
137
200
  ships the code): add `anchors:` to the code and the tests, write
138
201
  tests whose titles restate the acceptance criteria, remove
@@ -165,10 +228,14 @@ Rules the linters enforce (`lint:intent-*`), so apply them as you write:
165
228
  intent by intent. A doubt on where a node belongs is a question, not a
166
229
  guess.
167
230
  - **No business rule, no implementation.** If you explain *why* a rule
168
- holds, redirect to `/spec`; if you explain *how* the code does it,
169
- redirect to `/handbook`. A one-line `spec:` pointer replaces both.
170
- - **Do not invent vocabulary.** The spec defines the words; `/intent`
231
+ holds, redirect to `/harn-spec`; if you explain *how* the code does it,
232
+ redirect to `/harn-handbook`. A one-line `spec:` pointer replaces both.
233
+ - **Do not invent vocabulary.** The spec defines the words; `/harn-intent`
171
234
  refuses an undefined entity rather than coining one.
172
235
  - **Do not commit.** Write the files only; the commit follows the
173
236
  project's workflow.
174
- - **Never edit `docs/intents/README.md`.** It is rendered.
237
+ - **Never edit `docs/intents/README.md` or `docs/profiles/README.md`.**
238
+ They are rendered.
239
+ - **Never create `docs/profiles/` yourself.** Without the pillar, actors
240
+ are free strings and `relieves:` / `delivers:` fail the lint. Adding
241
+ it is the human's decision: `npx @vaubaan/harness add profiles`.
@@ -1,5 +1,5 @@
1
1
  ---
2
- id: readme-writer
2
+ id: harn-readme-writer
3
3
  description: |
4
4
  Maintains `README.md` at the repo root. Syncs the links to the other
5
5
  doc pillars, checks that pitch + quick start stay up to date with
@@ -19,8 +19,8 @@ README is *a doc pillar* in its own right, outside `docs/`.
19
19
 
20
20
  - Bootstrap of a new repo: create the initial README.
21
21
  - Change of project pitch / scope → update.
22
- - `doc-audit` flags broken links or missing sections.
23
- - `/readme` invoked by the human.
22
+ - `harn-doc-audit` flags broken links or missing sections.
23
+ - `/harn-readme` invoked by the human.
24
24
  - Refactor of the `package.json` scripts → check that the Quick start
25
25
  commands match.
26
26
 
@@ -63,7 +63,7 @@ README is *a doc pillar* in its own right, outside `docs/`.
63
63
  - **Valid links**. The targets of all links exist (the
64
64
  `lint:cross-links` linter checks).
65
65
  - **Links to the 3 core pillars** at minimum (spec, handbook,
66
- workflow). Otherwise → ⚠️ `doc-audit`.
66
+ workflow). Otherwise → ⚠️ `harn-doc-audit`.
67
67
  - **Not too long**. A good README is 50-200 lines. Beyond that, split
68
68
  it into `docs/`.
69
69
 
@@ -0,0 +1,84 @@
1
+ ---
2
+ id: harn-self-improve
3
+ description: |
4
+ Finds the small patches that reviews keep asking for, in the repo
5
+ history, pull requests, review threads and, when the project enables
6
+ it, agent conversations; proposes for each the rule that would have
7
+ prevented it, with its evidence, and writes the accepted ones in the
8
+ right project pillar.
9
+ engines: [claude-code, codex-cli, opencode]
10
+ requires: [multi-step, inline-exec]
11
+ tags: [review, quality, workflow, doc]
12
+ ---
13
+
14
+ # Self-Improve
15
+
16
+ A review almost always ends in small patches: a changelog line, a test
17
+ that forgot to clean up, a word the spec did not define. Each one that
18
+ comes back is a rule written nowhere. You find them, group them, and
19
+ propose the rule, so the next change does not need the patch (spec §10.5
20
+ of the harness).
21
+
22
+ ## Domains
23
+
24
+ - The **harness** ships this procedure, never a rule.
25
+ - An accepted lesson is **project** data: it lands in the project's
26
+ pillars, written with that pillar's writer rules.
27
+ - A lesson valid for every project (a missing linter, a gap of a shipped
28
+ skill) becomes an upstream issue draft in `.vaubaan/reports/upstream.md`;
29
+ never a local edit of a shipped skill or a generated file.
30
+ - Candidates and refusals are **local**: `.vaubaan/lessons/`.
31
+
32
+ ## Procedure
33
+
34
+ 1. **Fetch the pull requests** when the project uses a hosting platform
35
+ and its CLI is available (for example `gh`): the last 30 merged pull
36
+ requests with their review comments and their commits (sha, message,
37
+ files, date). Save them as `.vaubaan/lessons/prs.json`:
38
+ `[{ "number", "url", "comments": [{ "body", "path", "line", "createdAt" }], "commits": [{ "sha", "message", "files", "date" }] }]`.
39
+ Squash merges erase review patches from the main branch: the pull
40
+ requests are where they live.
41
+ 2. **Collect**: `npx @vaubaan/harness lessons collect`. It reads the
42
+ history, `prs.json`, the archived review threads and, only for the
43
+ sources the project enabled in `.harnessrc` (`lessons.sources`), the
44
+ agent conversations. It writes `.vaubaan/lessons/events.json` and
45
+ prints what it skipped. Never enable a conversation source yourself:
46
+ ask the human.
47
+ 3. **Group** the events by meaning: the same kind of patch, on the same
48
+ kind of file, asked for again. Keep a group seen at least `threshold`
49
+ times (in `events.json`, default 2). Read the rules in force first
50
+ (`docs/quality/`, `docs/workflow/`, the handbooks, the test plans,
51
+ `docs/skills/`): a group that a rule already covers is reported as
52
+ **rule present, not followed**, with the rule's file and line, never
53
+ proposed again.
54
+ 4. **Propose** one lesson per group, in `.vaubaan/lessons/lessons.json`:
55
+ `[{ "id", "rule", "evidence": [refs], "seen", "domain": "project" | "harness", "pillar": "<file § section>", "status": "proposed" }]`.
56
+ One sentence per rule, stated so it can be checked. Where it goes:
57
+ - checkable by a tool: the tool's config, cited in `docs/quality/`
58
+ § Mechanical checks;
59
+ - judgment on code: `docs/quality/code-quality.md` § Project rules;
60
+ - a forgotten process step: `docs/workflow/coding-workflow.md`;
61
+ - a trap of a module: the handbook that tracks it;
62
+ - a test convention: the test plan § Conventions;
63
+ - how the agent should work in this team: a skill in `docs/skills/`;
64
+ - every project: `harness` domain, upstream draft.
65
+ Run `npx @vaubaan/harness view`: the Lessons view shows them. Present
66
+ them to the human, most seen first, with one line of evidence each.
67
+ 5. **Apply** the accepted ones with the pillar's writer rules; mark them
68
+ `accepted`. Mark the refused ones `rejected` and keep them: they must
69
+ not come back. Run `npx @vaubaan/harness lint`.
70
+ 6. **Measure** on the next run: a patch that came back after the date of
71
+ an accepted rule is reported as **rule not followed**, with the new
72
+ evidence.
73
+
74
+ ## Guardrails
75
+
76
+ - **Propose, never decide.** Nothing lands in a pillar without the human.
77
+ - **Never create a pillar to hold a lesson.** When the pillar a lesson
78
+ belongs to is not active in the project, say so in the proposal with
79
+ its command (`npx @vaubaan/harness add quality`); the human adds it
80
+ first, or the lesson waits.
81
+ - **Quote, do not copy.** One line per piece of evidence, secrets masked;
82
+ conversation histories stay on the machine.
83
+ - **No rule from one occurrence.** Below the threshold, it waits.
84
+ - **Never commit.** The commit follows `docs/workflow/`.
@@ -1,5 +1,5 @@
1
1
  ---
2
- id: spec-writer
2
+ id: harn-spec-writer
3
3
  description: |
4
4
  Human-guided wizard to write or update a `docs/spec/<name>.md`
5
5
  file. Asks the core questions (vision, vocabulary, out of scope,
@@ -44,8 +44,8 @@ A spec stays short: target 50-100 lines.
44
44
  ## When to invoke you
45
45
 
46
46
  - Start of a new subsystem that has no spec yet.
47
- - `/spec <name>` invoked by the human.
48
- - `doc-audit` reports a missing or stale spec.
47
+ - `/harn-spec <name>` invoked by the human.
48
+ - `harn-doc-audit` reports a missing or stale spec.
49
49
  - Major overhaul: the existing spec no longer describes the current
50
50
  vision.
51
51
 
@@ -61,7 +61,7 @@ Three things make a spec exist. Everything else is optional while the
61
61
 
62
62
  A file with only these three sections and an "Open questions" section
63
63
  listing the rest is a valid spec. It passes the linters, and
64
- `doc-audit` reports it as `draft`, not as a gap.
64
+ `harn-doc-audit` reports it as `draft`, not as a gap.
65
65
 
66
66
  ## Procedure
67
67
 
@@ -179,7 +179,7 @@ status: draft | stable | deprecated
179
179
 
180
180
  Finish by recapping:
181
181
  - The path of the written file and the sections filled today.
182
- - The open questions that deserve a later ADR (suggest `/decision`
182
+ - The open questions that deserve a later ADR (suggest `/harn-decision`
183
183
  for each one).
184
184
  - The sections still missing, so the next session can pick one.
185
185
  - The neighboring subsystems to update for cross-linking (suggest a
@@ -193,11 +193,11 @@ Finish by recapping:
193
193
  - **Do not commit the file**. Write only. The commit belongs to the
194
194
  agent or the human running the project's workflow.
195
195
  - **No technology**. If the exchange converges on a technology choice,
196
- stop the wizard and redirect to `decision-record-writer`
197
- (`/decision`). A technology choice is an ADR, not a spec element.
196
+ stop the wizard and redirect to `harn-decision-record-writer`
197
+ (`/harn-decision`). A technology choice is an ADR, not a spec element.
198
198
  - **No implementation details**. If you find yourself explaining
199
199
  *how* something works (algorithms, concrete schemas, files), that is
200
- handbook — redirect to `handbook-writer`.
200
+ handbook — redirect to `harn-handbook-writer`.
201
201
  - **Do not fill sections nobody asked for**. One section at a time;
202
202
  a spec that grows by increments stays true.
203
203
  - **Do not delete the existing spec without confirmation**. During an
@@ -1,5 +1,5 @@
1
1
  ---
2
- id: test-plan-writer
2
+ id: harn-test-plan-writer
3
3
  description: |
4
4
  Updates `docs/tests/integration-tests.md` and/or
5
5
  `docs/tests/e2e-tests.md` (scope, stack, conventions, known gaps).
@@ -7,6 +7,7 @@ description: |
7
7
  truth. Maintains the `tracks: [...]` frontmatter for drift detection.
8
8
  engines: [claude-code, codex-cli, opencode]
9
9
  requires: [multi-step]
10
+ pillars: [tests]
10
11
  tags: [tests, doc, writer]
11
12
  ---
12
13
 
@@ -34,9 +35,9 @@ lines per plan, in bullets.
34
35
 
35
36
  - The agent adds / modifies an integration or E2E test →
36
37
  update the corresponding test plan.
37
- - `doc-audit` shows that a spec has no associated test → add it to
38
+ - `harn-doc-audit` shows that a spec has no associated test → add it to
38
39
  the known gaps.
39
- - `/test-plan [integration|e2e]` invoked by the human.
40
+ - `/harn-test-plan [integration|e2e]` invoked by the human.
40
41
  - Overhaul of the test scope: re-split integration vs e2e.
41
42
 
42
43
  ## Procedure
@@ -59,7 +60,7 @@ lines per plan, in bullets.
59
60
  are now covered by a test (→ remove, ask the human).
60
61
  4. **Read the specs** under `docs/spec/` to identify the
61
62
  subsystems/features without any test at this level → known gap.
62
- Spec neither tested nor listed as a gap = `doc-audit` warning.
63
+ Spec neither tested nor listed as a gap = `harn-doc-audit` warning.
63
64
  5. **Load the appropriate template**.
64
65
  6. **Draft** the required sections:
65
66
  - **Scope**: what is tested at this level vs what is not
@@ -149,7 +150,7 @@ or e2e).>
149
150
  Finish by:
150
151
  - Listing the updated files.
151
152
  - Listing the added / removed known gaps.
152
- - Listing the specs still without tests (suggest a `/test-plan`
153
+ - Listing the specs still without tests (suggest a `/harn-test-plan`
153
154
  follow-up).
154
155
 
155
156
  ## Guardrails