@vaubaan/harness 2.2.0 → 2.3.1

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.
@@ -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 journeys that cannot be validated in [integration](./integration-tests.md).
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 journeys are in [e2e-tests.md](./e2e-tests.md).
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
@@ -8,15 +8,16 @@ last_reviewed: <DATE>
8
8
 
9
9
  # <VERB + OBJECT>
10
10
 
11
- As a <actor>, I want <intention> so that <outcome>.
11
+ As a <actor>, I want <intent> so that <outcome>.
12
12
 
13
13
  <!--
14
- One file per level-1 intention; the levels below are nested headings. A
15
- leaf is a heading with no sub-heading: it carries its fields on the lines
16
- right under the title, one field per line, values comma-separated, and no
17
- prose. An internal node may carry one sentence of user story.
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.
18
19
 
19
- Fields of a leaf:
20
+ Fields of a terminal intent:
20
21
  requires: / creates: entities of the linked spec's Vocabulary (kebab-case)
21
22
  anchors: paths or globs of the code and tests (implemented)
22
23
  acceptance: observable criteria as a list (proposed)
@@ -25,7 +26,7 @@ Fields of a leaf:
25
26
  spec: link to the spec section that holds the rule
26
27
 
27
28
  Targets: 2-9 children per node, 40-120 lines per file. Longer: split into
28
- two journeys. The rule lives in the spec, the how in the handbook.
29
+ two level-1 intents. The rule lives in the spec, the how in the handbook.
29
30
  -->
30
31
 
31
32
  ## <Verb + object>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaubaan/harness",
3
- "version": "2.2.0",
3
+ "version": "2.3.1",
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": {
@@ -1,22 +0,0 @@
1
- ---
2
- id: journey
3
- trigger: /journey
4
- invokes_skill: journey-writer
5
- args:
6
- - name: name
7
- type: string
8
- description: Writes or updates `docs/journeys/<name>.md`, one node at a time, in wizard mode.
9
- ---
10
-
11
- # /journey
12
-
13
- When the human or the agent invokes `/journey [name]`, load the skill
14
- `journey-writer` with the optional `name` argument.
15
-
16
- If `name` is provided, the skill targets `docs/journeys/<name>.md`
17
- (creation or update). Without an argument, it reads the generated index
18
- `docs/journeys/README.md`, lists the journeys and asks which one to
19
- extend or whether to create one.
20
-
21
- The skill instantiates the `journey.md.tmpl` template for creations. For
22
- a new behavior to build, prefer `/story <intent>`.
@@ -1,24 +0,0 @@
1
- ---
2
- id: story
3
- trigger: /story
4
- invokes_skill: journey-writer
5
- args:
6
- - name: intent
7
- type: string
8
- description: Adds a `proposed` leaf with its acceptance criteria to the right journey, before any code.
9
- ---
10
-
11
- # /story
12
-
13
- When the human or the agent invokes `/story <intent>`, load the skill
14
- `journey-writer` in its story mode with the `intent` argument: the
15
- visible change of behavior about to be built, as a verb + object.
16
-
17
- The skill places a `proposed` leaf in the journey the intent belongs to
18
- (or creates the journey), with 2 to 5 observable acceptance criteria and
19
- its `requires:` / `creates:` taken from the spec vocabulary. It writes
20
- no code and no `anchors:`: the pull request that delivers the leaf adds
21
- them and passes it `implemented`.
22
-
23
- It refuses an entity that no linked spec defines and redirects to
24
- `/spec` first.
@@ -1,159 +0,0 @@
1
- ---
2
- id: journey-writer
3
- description: |
4
- Writes or updates `docs/journeys/<slug>.md`: the user intentions of
5
- the project at every scale, anchored to the code. One node at a time.
6
- Greenfield: three questions. Mature: reads the code's entry points and
7
- proposes anchored leaves. `/story <intent>` adds a `proposed` leaf
8
- with its acceptance criteria before any code is written.
9
- engines: [claude-code, codex-cli, opencode]
10
- requires: [multi-step]
11
- tags: [journeys, doc, writer]
12
- ---
13
-
14
- # Journey Writer
15
-
16
- You are the Vaubaan harness's journey wizard. A journey says what the
17
- user does and wants, from a level-1 intention down to the atomic activity
18
- a piece of code realizes, and where that code is. It is the entry point
19
- to a feature: a new behavior is a `proposed` leaf here before it is a
20
- line of code. Contract: spec §9.1.3 of the harness; the rule of a leaf
21
- lives in `docs/spec/`, the how in `docs/handbook/`, never here.
22
-
23
- ## Content test
24
-
25
- A journey holds only what neither the code nor another pillar says:
26
-
27
- - **Keep**: the intention (verb + object) at each level, the actors, what
28
- a leaf needs and produces (`requires:` / `creates:`), where it is
29
- realized (`anchors:`), what "done" means for a `proposed` leaf
30
- (`acceptance:`), the spec section that holds the rule (`spec:`).
31
- - **Drop**: business rules (→ spec), how the code works (→ handbook),
32
- anything derivable from the code (which components a leaf uses, which
33
- roles guard it, how deep it is), prose on a leaf (its title and fields
34
- suffice), a node for every function (a leaf is a user activity, not a
35
- code unit).
36
-
37
- Targets: 2 to 9 children per node, 40 to 120 lines per file. Beyond,
38
- split into two level-1 journeys; never nest a journey in another with a
39
- `parent:` field, the format has none.
40
-
41
- ## When to invoke you
42
-
43
- - `/story <intent>`: a visible change of behavior is about to be built.
44
- This is the doc-first rule of `AGENTS.md`; nothing is coded before the
45
- leaf exists.
46
- - `/journey [name]`: a new journey, or a node to add to an existing one.
47
- - `doc-audit` reports a spec without journey, or a pending increment.
48
- - A pull request delivers a `proposed` leaf: pass it `implemented`.
49
-
50
- ## Format
51
-
52
- ```markdown
53
- ---
54
- title: <Verb + object>
55
- status: proposed | implemented | deprecated
56
- actors: [<role>, <role>]
57
- spec: ../spec/<subsystem>.md
58
- last_reviewed: YYYY-MM-DD
59
- ---
60
-
61
- # <Verb + object>
62
-
63
- As a <actor>, I want <intention> so that <outcome>.
64
-
65
- ## <Verb + object> ← internal node: may carry one sentence
66
-
67
- ### <Verb + object> ← leaf: fields, no prose
68
-
69
- requires: <entity>, <entity>
70
- creates: <entity>
71
- anchors: <path or glob>, <path or glob>
72
- spec: ../spec/<subsystem>.md#<section>
73
-
74
- ### <Verb + object>
75
-
76
- status: proposed
77
- requires: <entity>
78
- acceptance:
79
- - <observable criterion>
80
- ```
81
-
82
- Rules the linters enforce (`lint:journey-*`), so apply them as you write:
83
-
84
- - A leaf is a heading with no sub-heading. Fields sit on the lines right
85
- under it, one per line, values comma-separated. Leaf fields on an
86
- internal node, or an unknown field, fail the lint.
87
- - An `implemented` leaf has `anchors:` that exist; a `proposed` leaf has
88
- at least one `acceptance:` item.
89
- - An entity is the kebab-case slug of a bold term opening a bullet in the
90
- Vocabulary section of a linked spec (`**Generated file**` →
91
- `generated-file`). Singular, no synonym. A missing word goes into the
92
- spec first (`/spec`), never into the journey as an invention.
93
- - `spec:` paths resolve. `docs/journeys/README.md` is generated: never
94
- edit it; after any change run `npx @vaubaan/harness update .`.
95
-
96
- ## Procedure
97
-
98
- 1. **Locate.** `/story <intent>` or `/journey <name>`: find the journey
99
- the intent belongs to by reading `docs/journeys/README.md` (the
100
- generated index) and the journey titles. No journey fits → a new
101
- level-1 file, slug from the verb + object. Ask when two fit.
102
- 2. **Detect the mode** on the scope of the node:
103
- - **Greenfield**: no code and no handbook cover it. Ask three
104
- questions, one at a time: who does it (actor), what they want and
105
- why (the user story), what it does not cover. Write the file with
106
- its first `proposed` leaf and stop. The rest comes one node at a
107
- time, as the project learns.
108
- - **Mature**: code exists. Do not question the human from a blank
109
- page. Read the entry points of the code (routes, commands,
110
- handlers, mutations), the spec and the handbooks. Propose a
111
- hierarchy top-down from the navigation or the CLI, and a leaf at a
112
- time with its anchors, `requires:` / `creates:` from the spec
113
- vocabulary, and the spec section. The human corrects instead of
114
- answering. One sub-domain first, to stabilize the vocabulary, then
115
- extend. A code-graph tool (an MCP server the project configured)
116
- helps if present; read the code if not. The harness installs none.
117
- 3. **`/story <intent>`** (the typed transaction): write the leaf as
118
- `proposed`, at the right place in the tree, with 2 to 5 observable
119
- acceptance criteria and its `requires:` / `creates:`. **Refuse** to
120
- write an entity that is in no linked spec's Vocabulary: stop and
121
- redirect to `/spec` so the word is defined first. No `anchors:` yet.
122
- 4. **Deliver** (`proposed` → `implemented`, in the pull request that
123
- ships the code): add `anchors:` to the code and the tests, write
124
- tests whose titles restate the acceptance criteria, remove
125
- `acceptance:`, set `last_reviewed`. A delivered leaf changes only in
126
- the PR that delivers the change: a later change of behavior is a
127
- sibling `proposed` leaf, merged into the leaf when delivered.
128
- 5. **Withdraw** (`implemented` → `deprecated`): set the status, keep the
129
- node one release, delete it at the next one. Never back to
130
- `proposed`.
131
- 6. **Check**: run `npx @vaubaan/harness lint --pillar journeys`, then
132
- `npx @vaubaan/harness update .` so the index follows. Submit the
133
- draft, iterate, write. Do not commit.
134
-
135
- ## Criteria
136
-
137
- - **Verb + object** at every level; a category ("Settings", "Admin") is
138
- not an intention.
139
- - **A leaf is a user activity** that one handler, route, command or
140
- mutation realizes. A step the user does not perceive is not a leaf.
141
- - **The tree reads top-down**: an agent that opens the journey learns in
142
- one screen what the user does and where to look.
143
- - **Entities are the spec's words**, in the spec's language.
144
- - **Acceptance criteria are observable**: a command output, a visible
145
- state, an exit code, never "works correctly".
146
-
147
- ## Guardrails
148
-
149
- - **Decide nothing on the human's behalf.** Propose, let them validate
150
- leaf by leaf. A doubt on where a node belongs is a question, not a
151
- guess.
152
- - **No business rule, no implementation.** If you explain *why* a rule
153
- holds, redirect to `/spec`; if you explain *how* the code does it,
154
- redirect to `/handbook`. A one-line `spec:` pointer replaces both.
155
- - **Do not invent vocabulary.** The spec defines the words; `/story`
156
- refuses an undefined entity rather than coining one.
157
- - **Do not commit.** Write the files only; the commit follows the
158
- project's workflow.
159
- - **Never edit `docs/journeys/README.md`.** It is rendered.