@vaubaan/harness 1.4.0 → 2.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 CHANGED
@@ -1,222 +1,356 @@
1
1
  # @vaubaan/harness
2
2
 
3
- **Project conventions as code.**
3
+ <p align="center">
4
+ <strong>Project context as code.</strong><br>
5
+ A context database for your project, kept in the repo, rendered for your coding agents, linted in CI.
6
+ </p>
4
7
 
5
- Write down once how your project is built — its architecture, decisions, quality rules and workflow. Claude Code, Codex and OpenCode read the same conventions, and linters tell you when code and docs drift apart.
6
-
7
- [![npm](https://img.shields.io/npm/v/@vaubaan/harness)](https://www.npmjs.com/package/@vaubaan/harness)
8
- [![CI](https://github.com/vaubaan/harness/actions/workflows/ci.yml/badge.svg)](https://github.com/vaubaan/harness/actions/workflows/ci.yml)
9
- [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/@vaubaan/harness"><img src="https://img.shields.io/npm/v/@vaubaan/harness" alt="npm"></a>
10
+ <a href="https://github.com/vaubaan/harness/actions/workflows/ci.yml"><img src="https://github.com/vaubaan/harness/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
12
+ </p>
10
13
 
11
14
  ```bash
12
- npx -y @vaubaan/harness init .
15
+ npx -y @vaubaan/harness init . --engines=claude-code
16
+ ```
17
+
18
+ A few Markdown files hold what the code cannot say and point to the code and configs for everything else. The harness renders them into the native layout of Claude Code, Codex or OpenCode, and lints them so context and code never drift apart.
19
+
20
+ - **One context, every engine.** Eight skills, one per pillar plus an audit and a drift detector, each with a slash command. Written once for Claude Code, Codex and OpenCode.
21
+ - **Pointers that stay true.** Handbooks and test plans declare the files they describe in a `tracks:` field. When that code moves and the doc does not, the linter says so.
22
+ - **Checks with zero tokens.** Fifteen mechanical linters run in CI and in your pre-commit hook. No engine hook, no injected turn, no loop. The agent sees a failed command and fixes it.
23
+
24
+ **Contents:**
25
+ [The problem](#the-problem) · [A context database with pointers](#a-context-database-with-pointers) · [What it looks like](#what-it-looks-like) · [Quick start](#quick-start) ·
26
+ [How it works](#how-it-works) · [What is included](#what-is-included) · [Adopting it on an existing project](#adopting-it-on-an-existing-project) · [Commands](#commands) ·
27
+ [Configuration](#configuration) · [FAQ](#faq) · [Where this is going](#where-this-is-going) · [Documentation](#documentation)
28
+
29
+ ---
30
+
31
+ ## The problem
32
+
33
+ A coding agent is fast and knows nothing about your project. So you repeat the same instructions in every session. You maintain a `CLAUDE.md`, an `AGENTS.md` and an OpenCode config that slowly disagree. The agent changes a behavior, the doc still describes the old one, and nobody notices until a teammate ships against the wrong assumption.
34
+
35
+ The context of a project is real information: what you want, why it is built this way, how it actually works today, what "done" means, how you ship. It deserves a home, a shape, and a check.
36
+
37
+ ## A context database with pointers
38
+
39
+ The harness does one thing. It keeps your project's context in a small, fixed set of Markdown files, gives every agent the same entry point into it, and refuses to let it go stale.
40
+
41
+ Each pillar stores one kind of information the code cannot carry, and links to the code or config that carries the rest. Nothing is written twice: if a paragraph could be deleted without losing anything that is not in the files it points to, it does not belong in the doc.
42
+
43
+ | Pillar | What the doc says (the code cannot) | What it points to in the repo |
44
+ | ----------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
45
+ | `README.md` | What this is, how to run it. | `package.json` scripts, the quick start. |
46
+ | `docs/spec/` | What we want, for whom, what we refuse to do. Vocabulary. Tech-agnostic. | The modules and entry points that realize each requirement. A requirement with no pointer is a todo or dead. |
47
+ | `docs/decisions/` | Why it is built this way, what was rejected, what changed since. | The config files and commits that embody the decision: `tsconfig.json`, `ci.yml`, a sha. |
48
+ | `docs/handbook/` | The map: where to look, the invariants the code assumes, the gotchas. | The files it describes, declared in `tracks:`. A map, not a retelling. |
49
+ | `docs/tests/` | Which scenarios matter, what "done" means. | The test that implements each scenario. A scenario with no test is an acceptance criterion still open. |
50
+ | `docs/workflow/` | What lives outside the repo: approvals, protections, secrets, languages. | `ci.yml`, build scripts, pre-commit hook. |
51
+ | `docs/quality/` | Optional. The code rules this team holds, and the deviations it accepts. | The linter and formatter configs that enforce the mechanical part. |
52
+ | `docs/skills/` | Optional. Domain know-how the agent should load. | Whatever the skill needs. |
53
+
54
+ > [!IMPORTANT]
55
+ > **One rule.** The only working rule the harness imposes, written into `AGENTS.md` for every engine: **understand the context, fill the gaps, code, update the context, commit.**
56
+ >
57
+ > How your team organizes itself around that, branches, review, release, is yours. You write it in `docs/workflow/` and the agents follow it. The harness ships no roles, no personas, no phases.
58
+
59
+ ## What it looks like
60
+
61
+ A harnessed project, here a small invoicing service. Everything under `docs/` is yours and committed; the rest is rendered by the harness and committed too.
62
+
63
+ ```
64
+ acme-billing/
65
+ ├── README.md
66
+ ├── AGENTS.md # rendered: the one rule, the map, the checks
67
+ ├── CLAUDE.md # rendered: @AGENTS.md
68
+ ├── .claude/ .agents/ .opencode/ # rendered: skills and commands per engine
69
+ ├── .harness-manifest.json # rendered: what the harness owns
70
+ └── docs/
71
+ ├── spec/invoicing.md
72
+ ├── decisions/postgres-over-sqlite.md
73
+ ├── handbook/invoice-pipeline.md
74
+ ├── tests/integration-tests.md
75
+ ├── tests/e2e-tests.md
76
+ ├── workflow/coding-workflow.md
77
+ ├── quality/code-quality.md # optional
78
+ └── skills/tax-rules.skill.md # optional
79
+ ```
80
+
81
+ Each file says what the code cannot, and points to the code for the rest.
82
+
83
+ **`docs/spec/invoicing.md`**: intent and vocabulary, no technology, each requirement realized by something.
84
+
85
+ ```markdown
86
+ ---
87
+ status: draft
88
+ ---
89
+ # Invoicing — spec
90
+
91
+ ## 0. Vocabulary
92
+ - **Invoice**: a frozen statement of amounts due, never edited after issue.
93
+ - **Draft**: an invoice before issue; the only editable state.
94
+
95
+ ## 1. Vision
96
+ 1. A draft becomes an invoice in one irreversible step. → `src/invoicing/issue.ts`
97
+ 2. An issued invoice can be voided, never deleted. → `src/invoicing/void.ts`
98
+
99
+ ## 2. Out of scope
100
+ - Payment collection. Another subsystem.
101
+
102
+ ## N. Open questions
103
+ - Multi-currency: not before a customer asks.
104
+ ```
105
+
106
+ **`docs/decisions/postgres-over-sqlite.md`**: the why, the rejected options, the history. Current state, rewritten when you change your mind, with a one-line history per reversal; git holds the rest.
107
+
108
+ ```markdown
109
+ # Postgres over SQLite for the invoice store
110
+
111
+ ## Context
112
+ Invoices must survive concurrent issue from two workers.
113
+
114
+ ## Decision
115
+ One Postgres database. Embodied by `docker-compose.yml` (service `db`)
116
+ and `src/db/client.ts`. Introduced in commit `4f1c2ab`.
117
+
118
+ ## Consequences
119
+ Local setup needs Docker. Migrations live in `db/migrations/`.
120
+
121
+ ## Rejected alternatives
122
+ | SQLite | single-writer lock under two workers |
123
+
124
+ ## History
125
+ - 2026-03-02 `9a0b7e1`: started on SQLite for speed of setup.
126
+ - 2026-06-14 `4f1c2ab`: moved to Postgres after the first lost write.
127
+ ```
128
+
129
+ **`docs/handbook/invoice-pipeline.md`**: the map, declared with `tracks:` so the linter notices when the code moves.
130
+
131
+ ```markdown
132
+ ---
133
+ tracks:
134
+ - src/invoicing/**/*.ts
135
+ - db/migrations/*.sql
136
+ last_reviewed: 2026-10-22
137
+ ---
138
+ # Invoice pipeline
139
+
140
+ Entry point: `src/invoicing/issue.ts#issueInvoice`. It freezes the
141
+ draft, writes the row, emits `invoice.issued`.
142
+
143
+ Invariant the code assumes: a draft is only ever edited by its owner;
144
+ enforced in `src/invoicing/guards.ts#assertOwner`, not in the database.
145
+
146
+ Gotcha: `void.ts` keeps the row and flips `status`; reports must filter
147
+ on it (`src/reports/monthly.ts`).
13
148
  ```
14
149
 
150
+ **`docs/tests/integration-tests.md`**: which scenarios matter, and the test that holds each one.
151
+
152
+ ```markdown
15
153
  ---
154
+ tracks: [tests/integration/**/*.test.ts]
155
+ ---
156
+ | Scenario | Test |
157
+ |---|---|
158
+ | Issuing a draft twice fails the second time | `tests/integration/issue.test.ts` › "is irreversible" |
159
+ | Voiding keeps the invoice visible in reports | `tests/integration/void.test.ts` › "stays in monthly report" |
160
+ | Two workers issue the same draft | *open*: no test yet |
161
+ ```
16
162
 
17
- ## Why
163
+ **`docs/workflow/coding-workflow.md`**: what lives outside the repo, and pointers to what lives in it.
18
164
 
19
- Coding agents are fast, but they don't know your project. So you end up:
165
+ ```markdown
166
+ ---
167
+ tracks: [.github/workflows/*.yml, package.json, .husky/pre-commit]
168
+ ---
169
+ ## CI pipeline
170
+ `ci.yml`: typecheck, test, `vaubaan-harness lint`. Required to merge.
171
+ ## PR process
172
+ Trunk-based, squash merge, one approval; branch protection set in GitHub.
173
+ ## Release
174
+ Tag `v*` triggers `publish.yml`. Secrets live in the GitHub environment `prod`.
175
+ ## Languages
176
+ Docs and code in English. Domain vocabulary in spec §0, French-speaking team.
177
+ ```
20
178
 
21
- - repeating the same instructions in every session;
22
- - maintaining a `CLAUDE.md`, an `AGENTS.md` and an OpenCode config that slowly disagree;
23
- - discovering that the agent changed behavior the docs still describe the old way.
179
+ **`docs/quality/code-quality.md`** (optional): the rules a tool cannot check, and the deviations you accept.
24
180
 
25
- The harness puts your conventions where they belong — in versioned docs inside the repo — and renders them into the native format of each agent. One source of truth, every engine, checked on every turn.
181
+ ```markdown
182
+ ## Mechanical checks
183
+ biome (`biome.json`), tsc strict (`tsconfig.json`).
184
+ ## Project rules
185
+ No business logic in route handlers; it lives in `src/invoicing/`.
186
+ ## Accepted deviations
187
+ `any` allowed in `src/legacy/csv-import.ts` until it is rewritten.
188
+ ```
189
+
190
+ **`docs/skills/tax-rules.skill.md`** (optional): know-how the agent loads, rendered like the built-in skills.
191
+
192
+ ```markdown
193
+ ---
194
+ id: tax-rules
195
+ description: How VAT rates are chosen and where they live.
196
+ ---
197
+ Rates are in `config/vat.json`, keyed by country. Never hardcode a rate;
198
+ add a key and a fixture in `tests/fixtures/vat/`.
199
+ ```
26
200
 
27
201
  ## Quick start
28
202
 
29
- Requires Node.js 20 or later.
203
+ Requires Node.js 20 or later. Pick the engines you actually use.
204
+
205
+ **1. Render the harness into your project.**
30
206
 
31
207
  ```bash
32
- npx -y @vaubaan/harness init .
208
+ npx -y @vaubaan/harness init . --engines=claude-code
209
+ # or: --engines=claude-code,codex-cli,opencode
33
210
  ```
34
211
 
35
- This renders, for each engine:
212
+ This writes, for each engine:
36
213
 
37
214
  ```
38
215
  AGENTS.md # how to work in this project (all engines)
39
- CLAUDE.md # imports AGENTS.md for Claude Code
40
- .claude/ # agents, skills, commands, Stop hook
41
- .codex/ .agents/skills/ # agents, skills, Stop hook
42
- .opencode/ # agents, commands, Stop hook plugin
216
+ CLAUDE.md # imports AGENTS.md (Claude Code)
217
+ .claude/ # skills, commands (Claude Code)
218
+ .agents/skills/ # skills (Codex)
219
+ .opencode/ # skills, commands (OpenCode)
43
220
  .harness-manifest.json # what was written, for update/uninstall
44
221
  ```
45
222
 
46
- All of these are **generated and gitignored**. What you commit is your `docs/` folder. Add these entries to `.gitignore`:
223
+ **2. Commit all of it**, generated files included ([why](#faq)). Only two paths are gitignored:
47
224
 
48
225
  ```gitignore
49
- # generated by @vaubaan/harness
50
- AGENTS.md
51
- CLAUDE.md
52
- .claude/
53
- .codex/
54
- .agents/
55
- .opencode/
56
- .mcp.json
57
- .harness-manifest.json
58
- .harness-overrides/
59
- # Stop hook retry state and skill reports
60
- .harness/
61
- .vaubaan/
226
+ .harness-overrides/ # your local, disposable overrides
227
+ .vaubaan/ # skill reports
228
+ ```
229
+
230
+ **3. Wire the linter where it blocks.**
231
+
232
+ ```bash
233
+ npm i -D @vaubaan/harness
234
+ npx husky init && echo "npx vaubaan-harness lint" > .husky/pre-commit
62
235
  ```
63
236
 
64
- `npx @vaubaan/harness check .` tells you if an entry is missing.
237
+ ```yaml
238
+ # .github/workflows/docs.yml
239
+ name: docs
240
+ on: [push, pull_request]
241
+ jobs:
242
+ lint:
243
+ runs-on: ubuntu-latest
244
+ steps:
245
+ - uses: actions/checkout@v4
246
+ - uses: actions/setup-node@v4
247
+ with:
248
+ node-version: 22
249
+ - run: npm ci
250
+ - run: npx vaubaan-harness lint
251
+ ```
65
252
 
66
- Then open your agent and ask it to fill the gaps:
253
+ **4. Open your agent and let it fill the gaps.**
67
254
 
68
255
  ```
69
- /doc-audit # what's missing or stale in your docs
256
+ /doc-audit # what is missing or stale
70
257
  /spec # write the spec of a subsystem, guided
71
258
  /decision # turn an implicit choice into an ADR
72
259
  ```
73
260
 
74
261
  > [!NOTE]
75
- > `init` never overwrites a file it did not write. If you already have a hand-written `AGENTS.md` or `CLAUDE.md`, it stops and lists them: move their content into `docs/`, or keep them as yours with `--preserve AGENTS.md`. Existing `.claude/settings.json`, `.mcp.json` and `.opencode/opencode.json` are merged entry by entry, with a backup.
262
+ > Already have a hand-written `AGENTS.md` or `CLAUDE.md`? `init` never overwrites a file it did not write. See [adopting it on an existing project](#adopting-it-on-an-existing-project).
76
263
 
77
264
  ## How it works
78
265
 
79
266
  ```
80
- docs/ your conventions, versioned in Git
81
- │ spec · decisions · handbook · tests · workflow · quality
267
+ docs/ your context, versioned, reviewed in PRs
268
+ │ spec · decisions · handbook · tests · workflow · quality · skills
82
269
  │
83
- ▼ init
84
- AGENTS.md .claude/ .codex/ .opencode/
85
- │ generated for each engine, gitignored
270
+ ▼ init / update
271
+ AGENTS.md .claude/ .codex/ .opencode/ rendered for your engines, committed
86
272
  │
87
273
  ▼
88
- Claude Code · Codex · OpenCode read the same conventions, write the code
89
- │ ▲
90
- │ end of each turn │ report: what drifted
91
- ▼ │
92
- linters (Stop hook) ────┘
274
+ Claude Code · Codex · OpenCode read the same context, write the code
93
275
  │
94
- ▼
95
- CI same checks on every pull request
276
+ ▼ pre-commit, CI
277
+ vaubaan-harness lint 15 linters: shape, links, drift, freshness
96
278
  ```
97
279
 
98
- 1. **Your docs are the conventions.** A small, fixed layout under `docs/` says what the project does, why it's built that way, and how it actually works today.
99
- 2. **The harness renders one pivot format into each engine's native layout.** Agents, skills and commands are written once and land where each engine looks for them.
100
- 3. **Linters keep docs and code in sync.** At the end of each agent turn, a Stop hook runs them; if something drifted, the agent gets the report and fixes it before handing back. The same linters run in CI.
101
-
102
- The work order every agent follows is: **understand the docs → fill the gaps → code → update the docs → commit.**
280
+ 1. **Your docs are the context.** A small, fixed layout under `docs/`. Every file has a template and a writer skill, so you rarely start from a blank page.
281
+ 2. **One pivot format, rendered per engine.** Skills and commands land where Claude Code, Codex and OpenCode look for them. `AGENTS.md` is the shared entry point; `CLAUDE.md` just imports it.
282
+ 3. **Linters keep context and code in sync.** They run before each commit and on every pull request. The semantic part, contradictions, stale prose, missing pieces, is a skill the agent runs: `/doc-audit`.
103
283
 
104
- ## Your docs
284
+ ## What is included
105
285
 
106
- ```
107
- README.md # pitch, quick start
108
- docs/
109
- spec/<subsystem>.md # what and why — tech-agnostic
110
- decisions/<slug>.md # ADRs: Context, Decision, Consequences, Rejected alternatives
111
- handbook/<feature>.md # how it actually works today (tracks the code it describes)
112
- tests/integration-tests.md # core scenarios
113
- tests/e2e-tests.md
114
- workflow/coding-workflow.md # CI, branches, PRs, release
115
- quality/code-quality.md # optional — your code-quality rules
116
- skills/*.skill.md # optional — your own domain skills
117
- ```
286
+ ### Skills
118
287
 
119
- Handbooks and test plans declare the code they describe in a `tracks:` frontmatter field. When that code changes and the doc doesn't, the drift linter notices.
288
+ **8 skills**, each with a slash command. A skill never says *when* to do something. It says *how* to write or check one pillar.
120
289
 
121
- Every file has a template and a writer skill, so you rarely start from a blank page.
290
+ | Command | Skill | What it does |
291
+ | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
292
+ | `/doc-audit` | `doc-audit` | Audits completeness and freshness of every pillar. |
293
+ | `/drift` | `drift-detector` | Finds where docs no longer match the code. |
294
+ | `/spec` | `spec-writer` | Writes a tech-agnostic spec, progressively: three questions to start, one section at a time after. |
295
+ | `/decision` | `decision-record-writer` | Writes an ADR, spotting implicit decisions in your diff. |
296
+ | `/handbook` | `handbook-writer` | Documents how a feature is actually implemented. |
297
+ | `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
298
+ | `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release, languages. |
299
+ | `/readme` | `readme-writer` | Keeps the README in sync with the code. |
122
300
 
123
- ## What's included
301
+ ### Linters
124
302
 
125
- **4 agents** — rendered side by side; you pick one when you start a session.
126
-
127
- | Agent | Role |
128
- |---|---|
129
- | `planning` | Turns a request into an implementation plan; drafts missing specs and test plans first. |
130
- | `coding` | Implements a feature in doc-first order: docs, code, doc update, commit. |
131
- | `review` | Audits a diff or codebase and returns an actionable verdict, including doc gaps. |
132
- | `merge` | Merges (PR + tag) and makes sure a final ADR records the decision. |
133
-
134
- **9 skills**, each with a slash command:
135
-
136
- | Command | Skill | What it does |
137
- |---|---|---|
138
- | `/doc-audit` | `doc-audit` | Audits completeness and freshness of all doc pillars. |
139
- | `/drift` | `drift-detector` | Finds where docs no longer match the code. |
140
- | `/spec` | `spec-writer` | Guided writing of a tech-agnostic spec. |
141
- | `/decision` | `decision-record-writer` | Writes an ADR, spotting implicit decisions in your diff. |
142
- | `/handbook` | `handbook-writer` | Documents how a feature is actually implemented. |
143
- | `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
144
- | `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release. |
145
- | `/readme` | `readme-writer` | Keeps the README in sync with the code. |
146
- | `/clean-code` | `clean-code-guardian` | Reviews code quality against your `docs/quality/` rules. |
147
-
148
- **14 linters** — mechanical checks, fast enough to run on every turn.
303
+ **15 linters**, fast enough to run on every commit.
149
304
 
150
305
  <details>
151
306
  <summary>See the list</summary>
152
307
 
153
- | Linter | Checks |
154
- |---|---|
155
- | `readme-presence`, `readme-sections` | `README.md` exists and has a title and a quick start. |
156
- | `doc-layout`, `cardinal-files` | The `docs/` folders and required files exist. |
157
- | `spec-has-content`, `spec-tech-agnostic` | Specs exist and don't name frameworks or vendors. |
158
- | `decision-schema` | Each ADR has its four sections. |
159
- | `adr-no-tracks`, `orphan-decisions` | ADRs stay frozen and are referenced somewhere. |
160
- | `frontmatter-tracks`, `tracks-drift` | Tracked paths exist; docs aren't older than the code they track. |
161
- | `cross-links` | Links between docs resolve. |
162
- | `gitignore-harness` | Generated files stay out of Git. |
163
- | `quality-schema` | `docs/quality/code-quality.md` has its sections, if you use it. |
308
+ | Linter | Checks |
309
+ | ------------------------------------ | ------------------------------------------------------------------- |
310
+ | `readme-presence`, `readme-sections` | `README.md` exists and has a title and a quick start. |
311
+ | `doc-layout`, `cardinal-files` | The `docs/` folders and required files exist. |
312
+ | `spec-has-content`, `spec-tech-agnostic` | Specs exist and don't name frameworks or vendors. |
313
+ | `decision-schema` | Each ADR has its four sections. |
314
+ | `adr-no-tracks`, `orphan-decisions` | ADRs carry no `tracks:` and are referenced somewhere. |
315
+ | `frontmatter-tracks`, `tracks-drift` | Tracked paths exist; docs aren't older than the code they track. |
316
+ | `cross-links` | Links between docs resolve. |
317
+ | `gitignore-harness` | Overrides and reports are ignored; generated files are not. |
318
+ | `generated-fresh` | Committed generated files match the current render. |
319
+ | `quality-schema` | `docs/quality/code-quality.md` has its sections, if you use it. |
164
320
 
165
321
  </details>
166
322
 
167
- ## Engine support
323
+ ### Engines
168
324
 
169
- | | Claude Code | Codex | OpenCode |
170
- |---|---|---|---|
171
- | Agents | `.claude/agents/` | `.codex/agents/*.toml` | `.opencode/agents/` |
172
- | Skills | `.claude/skills/` | `.agents/skills/` | reuses the above |
173
- | Slash commands | ✓ | — invoke skills by name | ✓ |
174
- | Stop hook | `.claude/settings.json` | `.codex/hooks.json` | plugin (1.x and 2.x) |
175
- | Hook runs after | workspace trust | project trust **and** hook approval (`/hooks`) | — |
176
- | MCP (opt-in) | `.mcp.json` | `.codex/config.toml` | `.opencode/opencode.json` |
325
+ | | Claude Code | Codex | OpenCode |
326
+ | -------------- | ------------------------- | ---------------------- | ---------------- |
327
+ | Entry point | `CLAUDE.md` → `AGENTS.md` | `AGENTS.md` | `AGENTS.md` |
328
+ | Skills | `.claude/skills/` | `.agents/skills/` | reuses the above |
329
+ | Slash commands | ✓ | invoke skills by name | ✓ |
177
330
 
178
- Only use one engine? `--engines=claude-code` (or `codex-cli`, `opencode`, comma-separated).
331
+ You name your engines; nothing is rendered for a tool you don't use. Add one later with `init . --engines=...` again.
179
332
 
180
333
  ## Adopting it on an existing project
181
334
 
182
335
  You don't have to write all the docs on day one.
183
336
 
184
- - **See where you stand:** `npx @vaubaan/harness lint` lists what's missing, with the skill that fixes each item.
185
- - **Let the agent do the first pass:** `/doc-audit`, then `/spec`, `/handbook` and `/decision` on the parts you touch.
186
- - **Pause the Stop hook while you bootstrap:** `HARNESS_LINT_DISABLE=1`, or install without it: `init . --no-stop-hook`. When a retry makes no progress, the hook lets the turn end.
187
- - **Back out anytime:** `npx @vaubaan/harness uninstall .` removes what `init` wrote. Your own files, and config entries you edited, are left in place.
188
-
189
- ## Use it in CI
190
-
191
- ```yaml
192
- # .github/workflows/docs.yml
193
- name: docs
194
- on: [push, pull_request]
195
- jobs:
196
- lint:
197
- runs-on: ubuntu-latest
198
- steps:
199
- - uses: actions/checkout@v4
200
- - uses: actions/setup-node@v4
201
- with:
202
- node-version: 22
203
- - run: npx -y @vaubaan/harness lint
204
- ```
205
-
206
- `lint` exits non-zero on errors. Use `--format json` for machine-readable output and `--pillar <name>` to check a single pillar.
337
+ - **See where you stand.** `npx @vaubaan/harness lint` lists what's missing, with the skill that fixes each item.
338
+ - **Let the agent do the first pass.** `/doc-audit`, then `/spec`, `/handbook` and `/decision` on the parts you touch. The rest fills in over time.
339
+ - **Keep what you had.** Your own skills, settings and hooks are never touched. A hand-written `AGENTS.md` or `CLAUDE.md` stops `init` with a list: move the content into `docs/`, or keep the file as yours with `--preserve AGENTS.md`. It never merges a configuration file either, and it never touches `.claude/settings.json`, `.codex/hooks.json` or any MCP configuration.
340
+ - **Back out anytime.** `npx @vaubaan/harness uninstall .` removes what `init` wrote. Your own files are left in place.
207
341
 
208
342
  ## Commands
209
343
 
210
- | Command | What it does |
211
- |---|---|
212
- | `init <dir>` | Render the harness into a project. Re-run it to change engines (`--engines`), MCP servers (`--with-mcp`) or the Stop hook (`--no-stop-hook`). |
213
- | `update [dir]` | Re-render with the installed version, keeping your settings. `--dry-run --json` previews. |
214
- | `uninstall <dir>` | Remove what `init` wrote, leaving your own files in place. |
215
- | `lint` | Run the linters. |
216
- | `check <dir>` | Quick layout check: doc folders and `.gitignore`. |
217
- | `render --out <dir>` | Preview the render somewhere harmless. |
344
+ | Command | What it does |
345
+ | ------------------------------------- | -------------------------------------------------------------------------------------------- |
346
+ | `init <dir> --engines=<list>` | Render the harness into a project. Re-run it to change engines. |
347
+ | `update [dir]` | Re-render with the installed version, keeping your engines. `--dry-run --json` previews. |
348
+ | `uninstall <dir>` | Remove what `init` wrote, leaving your own files in place. |
349
+ | `lint` | Run the linters. `--format json`, `--pillar <name>`, `--only <ids>`. |
350
+ | `check <dir>` | Quick layout check: doc folders and `.gitignore`. |
351
+ | `render --engines=<list> --out <dir>` | Preview the render somewhere harmless. |
218
352
 
219
- Run them with `npx @vaubaan/harness <command>`. If the package is installed in the project (`npm i -D @vaubaan/harness`), that uses the local version; otherwise `npx` downloads it (`-y` skips the confirmation prompt).
353
+ Run them with `npx @vaubaan/harness <command>`. Install the package in the project (`npm i -D @vaubaan/harness`) so CI, pre-commit and your teammates render with the same version.
220
354
 
221
355
  ## Configuration
222
356
 
@@ -240,11 +374,10 @@ Patterns use [fast-glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) syn
240
374
  <details>
241
375
  <summary><b>Local overrides</b></summary>
242
376
 
243
- Try a custom agent, skill or command without forking, in a gitignored `.harness-overrides/` folder:
377
+ Try a custom skill or command without forking, in a gitignored `.harness-overrides/` folder:
244
378
 
245
379
  ```
246
380
  .harness-overrides/
247
- agents/ *.agent.md
248
381
  skills/ *.skill.md
249
382
  commands/ *.cmd.md
250
383
  disable.yaml # disable: [readme-writer, workflow-writer]
@@ -254,43 +387,46 @@ Overrides are personal and disposable. Skills meant for the whole team go in `do
254
387
 
255
388
  </details>
256
389
 
257
- <details>
258
- <summary><b>MCP servers</b></summary>
259
-
260
- None by default. `init . --with-mcp=context7` adds [Context7](https://github.com/upstash/context7) (library documentation) to each engine's MCP config. Codex only loads project config in a trusted project.
261
-
262
- </details>
263
-
264
390
  <details>
265
391
  <summary><b>Updating</b></summary>
266
392
 
267
393
  ```bash
268
394
  npm i -D @vaubaan/harness@latest
269
395
  npx @vaubaan/harness update . --dry-run --json # preview
270
- npx @vaubaan/harness update .
396
+ npx @vaubaan/harness update . # then commit the result
271
397
  ```
272
398
 
273
- `update` keeps your engines, hook preference, MCP entries and hook edits. Generated files you modified are reported instead of overwritten: move the change to `.harness-overrides/`, or keep the file as yours with `--preserve AGENTS.md`. A backup is written outside the project before any change. Details: [updating a project](./docs/handbook/project-update.md).
399
+ `update` keeps your engines and overrides. A generated file you edited by hand is reported instead of overwritten: move the change to `.harness-overrides/` or `docs/skills/`, or keep the file as yours with `--preserve <path>`. A backup is written outside the project before any change. Details: [updating a project](./docs/handbook/project-update.md).
274
400
 
275
401
  </details>
276
402
 
277
403
  ## FAQ
278
404
 
279
- **Does it phone home?** No. No telemetry, no daemon. It writes files and runs linters locally.
405
+ **Does it phone home?** No. No telemetry, no daemon, no hook in your engine. It writes files and runs linters locally.
406
+
407
+ **Why commit the generated files?** So a clone has the whole context without installing the harness, and so the context survives a teammate who has never heard of it. `lint` fails when a committed file no longer matches the render, which is how it stays honest.
408
+
409
+ **Why no agents or personas?** Because how a team works is the team's decision. The harness imposes one rule, doc-first, and asks you to write the rest in `docs/workflow/`. A persona you like belongs in `docs/skills/`, versioned with your project.
280
410
 
281
- **Do I need all three engines?** No. Everything is rendered for all three by default because it costs nothing, but `--engines` narrows it.
411
+ **Why no engine hook?** A hook that re-injects a report at the end of every turn costs tokens you don't see, and every engine does it differently. A pre-commit hook and CI cost nothing and work the same everywhere.
282
412
 
283
- **Can I write my docs in another language?** Prose, yes. The linters look for English section headings (`## Context`, `## Decision`…); French headings are also accepted.
413
+ **Can I write my docs in another language?** Prose, yes. The linters look for English section headings (`## Context`, `## Decision`…); French headings are also accepted. `/workflow` records which languages you use for docs, code and domain.
284
414
 
285
415
  **Does it work in a monorepo?** Run it at the repository root and use `lint.ignore` for sub-projects you don't want checked.
286
416
 
287
- **Is this tied to Vaubaan?** No. Vaubaan builds it and uses it on its own projects — including this one, which is harnessed by itself.
417
+ **Coming from 1.x?** `--with-mcp`, the Stop hook and the four personas are gone. Run `update .`, remove the old Stop hook entry from your engine settings if you had one, un-ignore the generated files, and commit. The [changelog](./CHANGELOG.md) has the full list.
418
+
419
+ **Is this tied to Vaubaan?** No. Vaubaan builds it and uses it on its own projects, including this one, which is harnessed by itself.
420
+
421
+ ## Where this is going
422
+
423
+ Decided, not shipped yet: typed context transactions (`/story`, `/decide`, `/refactor`, `/fix`), an optional `docs/todo/` pillar for increments that fold into the spec when delivered, pointer checks per section, a token budget per file, and `/compact` to rewrite a context that has grown contradictions. The [spec](./docs/spec/coding-agent-harness.md) and the [decisions](./docs/decisions/) say what exists today.
288
424
 
289
425
  ## Documentation
290
426
 
291
- - [Spec](./docs/spec/coding-agent-harness.md) — what the harness is and why
292
- - [Decisions](./docs/decisions/) — architecture choices and their alternatives
293
- - [Handbook](./docs/handbook/) — how each part works today
427
+ - [Spec](./docs/spec/coding-agent-harness.md), what the harness is and why
428
+ - [Decisions](./docs/decisions/), architecture choices and their alternatives
429
+ - [Handbook](./docs/handbook/), how each part works today
294
430
  - [Test plans](./docs/tests/) and [workflow](./docs/workflow/coding-workflow.md)
295
431
  - [Changelog](./CHANGELOG.md)
296
432
 
@@ -305,4 +441,4 @@ npm ci && npm run ci
305
441
 
306
442
  ## License
307
443
 
308
- [Apache 2.0](./LICENSE) — see [NOTICE](./NOTICE).
444
+ [Apache 2.0](./LICENSE), see [NOTICE](./NOTICE).