@vaubaan/harness 2.1.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +537 -67
- package/dist/cli/index.js +582 -83
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/intent.cmd.md +33 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +343 -63
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +340 -60
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +536 -62
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +143 -1
- package/dist/parser/index.js +235 -4
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-C-FWmUfX.d.ts → render-CTx7VNOK.d.ts} +3 -1
- package/dist/render.d.ts +1 -1
- package/dist/render.js +98 -14
- package/dist/render.js.map +1 -1
- package/dist/skills/doc-audit.skill.md +35 -4
- package/dist/skills/drift-detector.skill.md +36 -5
- package/dist/skills/handbook-writer.skill.md +3 -0
- package/dist/skills/intent-writer.skill.md +174 -0
- package/dist/templates/e2e-tests.md.tmpl +1 -1
- package/dist/templates/integration-tests.md.tmpl +1 -1
- package/dist/templates/intent.md.tmpl +46 -0
- package/package.json +3 -7
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: intent-writer
|
|
3
|
+
description: |
|
|
4
|
+
Writes or updates `docs/intents/<slug>.md`: the user intents of
|
|
5
|
+
the project at every scale, one tree, anchored to the code. One node at
|
|
6
|
+
a time. Greenfield: three questions. Mature: reads the code's entry
|
|
7
|
+
points and proposes anchored terminal intents. `/intent <verb + object>`
|
|
8
|
+
adds a `proposed` intent with its acceptance criteria before any code
|
|
9
|
+
is written.
|
|
10
|
+
engines: [claude-code, codex-cli, opencode]
|
|
11
|
+
requires: [multi-step]
|
|
12
|
+
tags: [intents, doc, writer]
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Intent Writer
|
|
16
|
+
|
|
17
|
+
You are the Vaubaan harness's intent wizard. The intents pillar is one
|
|
18
|
+
tree of intents: what the user does and wants, from a level-1 intent
|
|
19
|
+
down to the atomic activity a piece of code realizes, and where that
|
|
20
|
+
code is. It is the entry point to a feature: a new behavior is a
|
|
21
|
+
`proposed` intent here before it is a line of code. Every heading is an
|
|
22
|
+
intent (verb + object, for an actor); a file is a level-1 intent with
|
|
23
|
+
its sub-intents; an intent with no sub-intent is terminal. Contract:
|
|
24
|
+
spec §9.1.3 of the harness; the
|
|
25
|
+
rule of an intent lives in `docs/spec/`, the how in `docs/handbook/`,
|
|
26
|
+
never here.
|
|
27
|
+
|
|
28
|
+
Think OKR tree: every intent is an objective (verb + object, for an
|
|
29
|
+
actor), the acceptance criteria of a terminal intent are its key
|
|
30
|
+
results, its anchors are the initiatives. Write an objective, not a
|
|
31
|
+
category; write a key result you can observe, not one you can argue
|
|
32
|
+
about.
|
|
33
|
+
|
|
34
|
+
## Content test
|
|
35
|
+
|
|
36
|
+
An intent file holds only what neither the code nor another pillar says:
|
|
37
|
+
|
|
38
|
+
- **Keep**: the intent (verb + object) at each level, the actors, what
|
|
39
|
+
a terminal intent needs and produces (`requires:` / `creates:`), where it is
|
|
40
|
+
realized (`anchors:`), what "done" means for a `proposed` intent
|
|
41
|
+
(`acceptance:`), the spec section that holds the rule (`spec:`).
|
|
42
|
+
- **Drop**: business rules (→ spec), how the code works (→ handbook),
|
|
43
|
+
anything derivable from the code (which components an intent uses,
|
|
44
|
+
which roles guard it, how deep it is), prose on a terminal intent (its
|
|
45
|
+
title and fields suffice), a node for every function (a terminal intent
|
|
46
|
+
is a user activity, not a code unit).
|
|
47
|
+
|
|
48
|
+
Targets: 2 to 9 children per node, 40 to 120 lines per file. Beyond,
|
|
49
|
+
split into two level-1 intents; never nest a file in another with a
|
|
50
|
+
`parent:` field, the format has none.
|
|
51
|
+
|
|
52
|
+
## When to invoke you
|
|
53
|
+
|
|
54
|
+
- `/intent <verb + object>`: a visible change of behavior is about to be
|
|
55
|
+
built. This is the doc-first rule of `AGENTS.md`; nothing is coded
|
|
56
|
+
before the intent exists.
|
|
57
|
+
- `/intent` without argument: map the tree or extend it, a new level-1
|
|
58
|
+
intent or a node to add to an existing one.
|
|
59
|
+
- `doc-audit` reports a spec without intents, or a pending increment.
|
|
60
|
+
- A pull request delivers a `proposed` intent: pass it `implemented`.
|
|
61
|
+
|
|
62
|
+
## Format
|
|
63
|
+
|
|
64
|
+
```markdown
|
|
65
|
+
---
|
|
66
|
+
title: <Verb + object>
|
|
67
|
+
status: proposed | implemented | deprecated
|
|
68
|
+
actors: [<role>, <role>]
|
|
69
|
+
spec: ../spec/<subsystem>.md
|
|
70
|
+
last_reviewed: YYYY-MM-DD
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
# <Verb + object>
|
|
74
|
+
|
|
75
|
+
As a <actor>, I want <intent> so that <outcome>. ← intent statement
|
|
76
|
+
|
|
77
|
+
## <Verb + object> ← internal node: may carry one sentence
|
|
78
|
+
|
|
79
|
+
### <Verb + object> ← terminal intent: fields, no prose
|
|
80
|
+
|
|
81
|
+
requires: <entity>, <entity>
|
|
82
|
+
creates: <entity>
|
|
83
|
+
anchors: <path or glob>, <path or glob>
|
|
84
|
+
spec: ../spec/<subsystem>.md#<section>
|
|
85
|
+
|
|
86
|
+
### <Verb + object>
|
|
87
|
+
|
|
88
|
+
status: proposed
|
|
89
|
+
requires: <entity>
|
|
90
|
+
acceptance:
|
|
91
|
+
- <observable criterion>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Rules the linters enforce (`lint:intent-*`), so apply them as you write:
|
|
95
|
+
|
|
96
|
+
- A terminal intent is a heading with no sub-heading. Fields sit on the
|
|
97
|
+
lines right under it, one per line, values comma-separated. Its fields
|
|
98
|
+
on an internal node, or an unknown field, fail the lint.
|
|
99
|
+
- An `implemented` intent has `anchors:` that exist; a `proposed` intent has
|
|
100
|
+
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**` →
|
|
103
|
+
`generated-file`). Singular, no synonym. A missing word goes into the
|
|
104
|
+
spec first (`/spec`), never into the intent file as an invention.
|
|
105
|
+
- `spec:` paths resolve. `docs/intents/README.md` is generated: never
|
|
106
|
+
edit it; after any change run `npx @vaubaan/harness update .`.
|
|
107
|
+
|
|
108
|
+
## Procedure
|
|
109
|
+
|
|
110
|
+
1. **Locate.** With `/intent <verb + object>`: find the level-1 intent
|
|
111
|
+
it belongs to by reading `docs/intents/README.md` (the generated
|
|
112
|
+
index) and the file titles. None fits → a new level-1 file, slug from
|
|
113
|
+
the verb + object. Ask when two fit. Without an argument: read the
|
|
114
|
+
index, list the level-1 intents and ask which one to extend or
|
|
115
|
+
whether to map a new one.
|
|
116
|
+
2. **Detect the mode** on the scope of the node:
|
|
117
|
+
- **Greenfield**: no code and no handbook cover it. Ask three
|
|
118
|
+
questions, one at a time: who does it (actor), what they want and
|
|
119
|
+
why (the intent statement), what it does not cover. Write the file with
|
|
120
|
+
its first `proposed` intent and stop. The rest comes one node at a
|
|
121
|
+
time, as the project learns.
|
|
122
|
+
- **Mature**: code exists. Do not question the human from a blank
|
|
123
|
+
page. Read the entry points of the code (routes, commands,
|
|
124
|
+
handlers, mutations), the spec and the handbooks. Propose a
|
|
125
|
+
hierarchy top-down from the navigation or the CLI, and a terminal
|
|
126
|
+
intent at a time with its anchors, `requires:` / `creates:` from the spec
|
|
127
|
+
vocabulary, and the spec section. The human corrects instead of
|
|
128
|
+
answering. One sub-domain first, to stabilize the vocabulary, then
|
|
129
|
+
extend. A code-graph tool (an MCP server the project configured)
|
|
130
|
+
helps if present; read the code if not. The harness installs none.
|
|
131
|
+
3. **`/intent <verb + object>`** (the typed transaction): write the intent as
|
|
132
|
+
`proposed`, at the right place in the tree, with 2 to 5 observable
|
|
133
|
+
acceptance criteria and its `requires:` / `creates:`. **Refuse** to
|
|
134
|
+
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.
|
|
136
|
+
4. **Deliver** (`proposed` → `implemented`, in the pull request that
|
|
137
|
+
ships the code): add `anchors:` to the code and the tests, write
|
|
138
|
+
tests whose titles restate the acceptance criteria, remove
|
|
139
|
+
`acceptance:`, set `last_reviewed`. A delivered intent changes only
|
|
140
|
+
in the PR that delivers the change: a later change of behavior is a
|
|
141
|
+
sibling `proposed` intent, merged into it when delivered.
|
|
142
|
+
5. **Withdraw** (`implemented` → `deprecated`): set the status, keep the
|
|
143
|
+
node one release, delete it at the next one. Never back to
|
|
144
|
+
`proposed`.
|
|
145
|
+
6. **Check**: run `npx @vaubaan/harness lint --pillar intents`, then
|
|
146
|
+
`npx @vaubaan/harness update .` so the index follows. Submit the
|
|
147
|
+
draft, iterate, write. Do not commit.
|
|
148
|
+
|
|
149
|
+
## Criteria
|
|
150
|
+
|
|
151
|
+
- **Verb + object** at every level; a category ("Settings", "Admin") is
|
|
152
|
+
not an intent.
|
|
153
|
+
- **A terminal intent is a user activity** that one handler, route,
|
|
154
|
+
command or mutation realizes. A step the user does not perceive is not
|
|
155
|
+
an intent.
|
|
156
|
+
- **The tree reads top-down**: an agent that opens an intent file learns in
|
|
157
|
+
one screen what the user does and where to look.
|
|
158
|
+
- **Entities are the spec's words**, in the spec's language.
|
|
159
|
+
- **Acceptance criteria are observable**: a command output, a visible
|
|
160
|
+
state, an exit code, never "works correctly".
|
|
161
|
+
|
|
162
|
+
## Guardrails
|
|
163
|
+
|
|
164
|
+
- **Decide nothing on the human's behalf.** Propose, let them validate
|
|
165
|
+
intent by intent. A doubt on where a node belongs is a question, not a
|
|
166
|
+
guess.
|
|
167
|
+
- **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`
|
|
171
|
+
refuses an undefined entity rather than coining one.
|
|
172
|
+
- **Do not commit.** Write the files only; the commit follows the
|
|
173
|
+
project's workflow.
|
|
174
|
+
- **Never edit `docs/intents/README.md`.** It is rendered.
|
|
@@ -15,7 +15,7 @@ Target 20-50 lines, bullets. Do not restate the runner config.
|
|
|
15
15
|
|
|
16
16
|
## Scope
|
|
17
17
|
|
|
18
|
-
- The complete system against real or staging dependencies, on the
|
|
18
|
+
- The complete system against real or staging dependencies, on the user flows that cannot be validated in [integration](./integration-tests.md).
|
|
19
19
|
- <project-specific boundary>
|
|
20
20
|
|
|
21
21
|
## Stack
|
|
@@ -15,7 +15,7 @@ Target 20-50 lines, bullets. Do not restate the runner config.
|
|
|
15
15
|
|
|
16
16
|
## Scope
|
|
17
17
|
|
|
18
|
-
- Several modules assembled in one process, real I/O against local dependencies (ephemeral DB, network-level mocks, temporary filesystem). Unit tests live next to the code; full-system
|
|
18
|
+
- Several modules assembled in one process, real I/O against local dependencies (ephemeral DB, network-level mocks, temporary filesystem). Unit tests live next to the code; full-system scenarios are in [e2e-tests.md](./e2e-tests.md).
|
|
19
19
|
- <project-specific boundary>
|
|
20
20
|
|
|
21
21
|
## Stack
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: <VERB + OBJECT>
|
|
3
|
+
status: proposed
|
|
4
|
+
actors: [<ACTOR>]
|
|
5
|
+
spec: ../spec/<SUBSYSTEM>.md
|
|
6
|
+
last_reviewed: <DATE>
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# <VERB + OBJECT>
|
|
10
|
+
|
|
11
|
+
As a <actor>, I want <intent> so that <outcome>.
|
|
12
|
+
|
|
13
|
+
<!--
|
|
14
|
+
The paragraph above is the intent statement. One file per level-1 intent; its sub-intents are nested headings, verb +
|
|
15
|
+
object at every level. A terminal intent is a heading with no sub-heading:
|
|
16
|
+
it carries its fields on the lines right under the title, one field per
|
|
17
|
+
line, values comma-separated, and no prose. An internal node may carry one
|
|
18
|
+
sentence: its intent statement.
|
|
19
|
+
|
|
20
|
+
Fields of a terminal intent:
|
|
21
|
+
requires: / creates: entities of the linked spec's Vocabulary (kebab-case)
|
|
22
|
+
anchors: paths or globs of the code and tests (implemented)
|
|
23
|
+
acceptance: observable criteria as a list (proposed)
|
|
24
|
+
status: proposed | implemented | deprecated, when it differs
|
|
25
|
+
from the file's
|
|
26
|
+
spec: link to the spec section that holds the rule
|
|
27
|
+
|
|
28
|
+
Targets: 2-9 children per node, 40-120 lines per file. Longer: split into
|
|
29
|
+
two level-1 intents. The rule lives in the spec, the how in the handbook.
|
|
30
|
+
-->
|
|
31
|
+
|
|
32
|
+
## <Verb + object>
|
|
33
|
+
|
|
34
|
+
requires: <entity>
|
|
35
|
+
creates: <entity>
|
|
36
|
+
anchors: <path or glob>, <path or glob>
|
|
37
|
+
|
|
38
|
+
## <Verb + object>
|
|
39
|
+
|
|
40
|
+
### <Verb + object>
|
|
41
|
+
|
|
42
|
+
status: proposed
|
|
43
|
+
requires: <entity>
|
|
44
|
+
acceptance:
|
|
45
|
+
- <observable criterion>
|
|
46
|
+
- <observable criterion>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vaubaan/harness",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.3.0",
|
|
4
4
|
"description": "Project conventions as code for Claude Code, Codex and OpenCode — skills, agents, commands and linters",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -43,12 +43,7 @@
|
|
|
43
43
|
"import": "./dist/init.js"
|
|
44
44
|
}
|
|
45
45
|
},
|
|
46
|
-
"files": [
|
|
47
|
-
"dist",
|
|
48
|
-
"README.md",
|
|
49
|
-
"LICENSE",
|
|
50
|
-
"NOTICE"
|
|
51
|
-
],
|
|
46
|
+
"files": ["dist", "README.md", "LICENSE", "NOTICE"],
|
|
52
47
|
"scripts": {
|
|
53
48
|
"build": "tsup && node scripts/copy-content.mjs",
|
|
54
49
|
"dev": "tsup --watch",
|
|
@@ -61,6 +56,7 @@
|
|
|
61
56
|
"test:coverage": "vitest run --coverage",
|
|
62
57
|
"lint:harness": "node dist/cli/index.js lint --cwd .",
|
|
63
58
|
"ci": "npm run typecheck && npm run lint && npm run test && npm run build && npm run lint:harness",
|
|
59
|
+
"version": "node scripts/sync-version.mjs && biome format --write package.json",
|
|
64
60
|
"prepare": "husky"
|
|
65
61
|
},
|
|
66
62
|
"dependencies": {
|