@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.
- 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 +5 -1
- 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
|
-
-
|
|
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
|
|
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
|
|
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
|