@vaubaan/harness 1.4.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +301 -167
  2. package/dist/cli/index.js +886 -1882
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/handbook.cmd.md +4 -3
  5. package/dist/commands/test-plan.cmd.md +4 -4
  6. package/dist/index.d.ts +2 -2
  7. package/dist/index.js +277 -1064
  8. package/dist/index.js.map +1 -1
  9. package/dist/init.d.ts +8 -23
  10. package/dist/init.js +270 -1036
  11. package/dist/init.js.map +1 -1
  12. package/dist/linters/index.js +687 -31
  13. package/dist/linters/index.js.map +1 -1
  14. package/dist/parser/index.d.ts +1 -26
  15. package/dist/parser/index.js +1 -17
  16. package/dist/parser/index.js.map +1 -1
  17. package/dist/{render-Cu2XrkkY.d.ts → render-C-FWmUfX.d.ts} +8 -15
  18. package/dist/render.d.ts +1 -1
  19. package/dist/render.js +18 -280
  20. package/dist/render.js.map +1 -1
  21. package/dist/skills/decision-record-writer.skill.md +93 -131
  22. package/dist/skills/doc-audit.skill.md +10 -10
  23. package/dist/skills/drift-detector.skill.md +6 -7
  24. package/dist/skills/handbook-writer.skill.md +68 -159
  25. package/dist/skills/readme-writer.skill.md +3 -3
  26. package/dist/skills/spec-writer.skill.md +111 -71
  27. package/dist/skills/test-plan-writer.skill.md +47 -54
  28. package/dist/skills/workflow-writer.skill.md +40 -6
  29. package/dist/templates/code-quality.md.tmpl +2 -2
  30. package/dist/templates/coding-workflow.md.tmpl +10 -0
  31. package/dist/templates/decision.md.tmpl +20 -47
  32. package/dist/templates/e2e-tests.md.tmpl +16 -45
  33. package/dist/templates/handbook.md.tmpl +20 -38
  34. package/dist/templates/integration-tests.md.tmpl +16 -34
  35. package/package.json +1 -1
  36. package/dist/agents/coding.agent.md +0 -182
  37. package/dist/agents/merge.agent.md +0 -139
  38. package/dist/agents/planning.agent.md +0 -194
  39. package/dist/agents/review.agent.md +0 -176
  40. package/dist/commands/clean-code.cmd.md +0 -26
  41. package/dist/skills/clean-code-guardian.skill.md +0 -391
package/README.md CHANGED
@@ -1,192 +1,236 @@
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
13
16
  ```
14
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
+
15
29
  ---
16
30
 
17
- ## Why
31
+ ## The problem
18
32
 
19
- Coding agents are fast, but they don't know your project. So you end up:
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.
20
34
 
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.
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.
24
36
 
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.
37
+ ## A context database with pointers
26
38
 
27
- ## Quick start
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.
28
40
 
29
- Requires Node.js 20 or later.
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.
30
42
 
31
- ```bash
32
- npx -y @vaubaan/harness init .
33
- ```
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/` | The structural choices in force: why, and what was rejected. | 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/` | Test scope, stack, conventions, known gaps. Never the covered scenarios. | The test files: their titles say what is covered. A spec with no test is a known gap. |
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. |
34
53
 
35
- This renders, for each engine:
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.
36
62
 
37
63
  ```
38
- 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
43
- .harness-manifest.json # what was written, for update/uninstall
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
44
79
  ```
45
80
 
46
- All of these are **generated and gitignored**. What you commit is your `docs/` folder. Add these entries to `.gitignore`:
81
+ Each file says what the code cannot, and points to the code for the rest.
47
82
 
48
- ```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/
62
- ```
83
+ **`docs/spec/invoicing.md`**: intent and vocabulary, no technology, each requirement realized by something.
63
84
 
64
- `npx @vaubaan/harness check .` tells you if an entry is missing.
85
+ ```markdown
86
+ ---
87
+ status: draft
88
+ ---
89
+ # Invoicing — spec
65
90
 
66
- Then open your agent and ask it to fill the gaps:
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.
67
94
 
68
- ```
69
- /doc-audit # what's missing or stale in your docs
70
- /spec # write the spec of a subsystem, guided
71
- /decision # turn an implicit choice into an ADR
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.
72
104
  ```
73
105
 
74
- > [!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.
106
+ **`docs/decisions/postgres-over-sqlite.md`**: one structural decision in force, about 40 lines: the why and the rejected options. When you change your mind, a new file replaces it; git holds the rest.
76
107
 
77
- ## How it works
108
+ ```markdown
109
+ # Postgres over SQLite for the invoice store
78
110
 
79
- ```
80
- docs/ your conventions, versioned in Git
81
- │ spec · decisions · handbook · tests · workflow · quality
82
- │
83
- ▼ init
84
- AGENTS.md .claude/ .codex/ .opencode/
85
- │ generated for each engine, gitignored
86
- │
87
- ▼
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) ────┘
93
- │
94
- ▼
95
- CI same checks on every pull request
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
123
+ Where it started; its single-writer lock lost a write under two workers.
96
124
  ```
97
125
 
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.
126
+ **`docs/handbook/invoice-pipeline.md`**: the map, declared with `tracks:` so the linter notices when the code moves.
101
127
 
102
- The work order every agent follows is: **understand the docs → fill the gaps → code → update the docs → commit.**
128
+ ```markdown
129
+ ---
130
+ tracks:
131
+ - src/invoicing/**/*.ts
132
+ - db/migrations/*.sql
133
+ last_reviewed: 2026-10-22
134
+ ---
135
+ # Invoice pipeline
103
136
 
104
- ## Your docs
137
+ Entry point: `src/invoicing/issue.ts#issueInvoice`. It freezes the
138
+ draft, writes the row, emits `invoice.issued`.
105
139
 
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
140
+ Invariant the code assumes: a draft is only ever edited by its owner;
141
+ enforced in `src/invoicing/guards.ts#assertOwner`, not in the database.
142
+
143
+ Gotcha: `void.ts` keeps the row and flips `status`; reports must filter
144
+ on it (`src/reports/monthly.ts`).
117
145
  ```
118
146
 
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.
147
+ **`docs/tests/integration-tests.md`**: scope, stack, conventions and known gaps. The covered scenarios are the test titles, never copied here.
120
148
 
121
- Every file has a template and a writer skill, so you rarely start from a blank page.
149
+ ```markdown
150
+ ---
151
+ tracks: [vitest.config.ts, tests/integration/fixtures/*.ts]
152
+ ---
153
+ ## Scope
154
+ Invoicing modules against a throwaway Postgres; no browser (→ e2e-tests.md).
155
+ ## Conventions
156
+ One database per worker (`fixtures/db.ts`); never share a draft across tests.
157
+ ## Known gaps
158
+ - ⚠️ Two workers issuing the same draft (spec invoicing §3) — not tested yet.
159
+ ```
122
160
 
123
- ## What's included
161
+ **`docs/workflow/coding-workflow.md`**: what lives outside the repo, and pointers to what lives in it.
124
162
 
125
- **4 agents** — rendered side by side; you pick one when you start a session.
163
+ ```markdown
164
+ ---
165
+ tracks: [.github/workflows/*.yml, package.json, .husky/pre-commit]
166
+ ---
167
+ ## CI pipeline
168
+ `ci.yml`: typecheck, test, `vaubaan-harness lint`. Required to merge.
169
+ ## PR process
170
+ Trunk-based, squash merge, one approval; branch protection set in GitHub.
171
+ ## Release
172
+ Tag `v*` triggers `publish.yml`. Secrets live in the GitHub environment `prod`.
173
+ ## Languages
174
+ Docs and code in English. Domain vocabulary in spec §0, French-speaking team.
175
+ ```
126
176
 
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. |
177
+ **`docs/quality/code-quality.md`** (optional): the rules a tool cannot check, and the deviations you accept.
133
178
 
134
- **9 skills**, each with a slash command:
179
+ ```markdown
180
+ ## Mechanical checks
181
+ biome (`biome.json`), tsc strict (`tsconfig.json`).
182
+ ## Project rules
183
+ No business logic in route handlers; it lives in `src/invoicing/`.
184
+ ## Accepted deviations
185
+ `any` allowed in `src/legacy/csv-import.ts` until it is rewritten.
186
+ ```
135
187
 
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. |
188
+ **`docs/skills/tax-rules.skill.md`** (optional): know-how the agent loads, rendered like the built-in skills.
147
189
 
148
- **14 linters** — mechanical checks, fast enough to run on every turn.
190
+ ```markdown
191
+ ---
192
+ id: tax-rules
193
+ description: How VAT rates are chosen and where they live.
194
+ ---
195
+ Rates are in `config/vat.json`, keyed by country. Never hardcode a rate;
196
+ add a key and a fixture in `tests/fixtures/vat/`.
197
+ ```
149
198
 
150
- <details>
151
- <summary>See the list</summary>
199
+ ## Quick start
152
200
 
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. |
201
+ Requires Node.js 20 or later. Pick the engines you actually use.
164
202
 
165
- </details>
203
+ **1. Render the harness into your project.**
166
204
 
167
- ## Engine support
205
+ ```bash
206
+ npx -y @vaubaan/harness init . --engines=claude-code
207
+ # or: --engines=claude-code,codex-cli,opencode
208
+ ```
168
209
 
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` |
210
+ This writes, for each engine:
177
211
 
178
- Only use one engine? `--engines=claude-code` (or `codex-cli`, `opencode`, comma-separated).
212
+ ```
213
+ AGENTS.md # how to work in this project (all engines)
214
+ CLAUDE.md # imports AGENTS.md (Claude Code)
215
+ .claude/ # skills, commands (Claude Code)
216
+ .agents/skills/ # skills (Codex)
217
+ .opencode/ # skills, commands (OpenCode)
218
+ .harness-manifest.json # what was written, for update/uninstall
219
+ ```
179
220
 
180
- ## Adopting it on an existing project
221
+ **2. Commit all of it**, generated files included ([why](#faq)). Only two paths are gitignored:
181
222
 
182
- You don't have to write all the docs on day one.
223
+ ```gitignore
224
+ .harness-overrides/ # your local, disposable overrides
225
+ .vaubaan/ # skill reports
226
+ ```
183
227
 
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.
228
+ **3. Wire the linter where it blocks.**
188
229
 
189
- ## Use it in CI
230
+ ```bash
231
+ npm i -D @vaubaan/harness
232
+ npx husky init && echo "npx vaubaan-harness lint" > .husky/pre-commit
233
+ ```
190
234
 
191
235
  ```yaml
192
236
  # .github/workflows/docs.yml
@@ -200,23 +244,111 @@ jobs:
200
244
  - uses: actions/setup-node@v4
201
245
  with:
202
246
  node-version: 22
203
- - run: npx -y @vaubaan/harness lint
247
+ - run: npm ci
248
+ - run: npx vaubaan-harness lint
204
249
  ```
205
250
 
206
- `lint` exits non-zero on errors. Use `--format json` for machine-readable output and `--pillar <name>` to check a single pillar.
251
+ **4. Open your agent and let it fill the gaps.**
252
+
253
+ ```
254
+ /doc-audit # what is missing or stale
255
+ /spec # write the spec of a subsystem, guided
256
+ /decision # turn an implicit choice into an ADR
257
+ ```
258
+
259
+ > [!NOTE]
260
+ > 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).
261
+
262
+ ## How it works
263
+
264
+ ```
265
+ docs/ your context, versioned, reviewed in PRs
266
+ │ spec · decisions · handbook · tests · workflow · quality · skills
267
+ │
268
+ ▼ init / update
269
+ AGENTS.md .claude/ .codex/ .opencode/ rendered for your engines, committed
270
+ │
271
+ ▼
272
+ Claude Code · Codex · OpenCode read the same context, write the code
273
+ │
274
+ ▼ pre-commit, CI
275
+ vaubaan-harness lint 15 linters: shape, links, drift, freshness
276
+ ```
277
+
278
+ 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.
279
+ 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.
280
+ 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`.
281
+
282
+ ## What is included
283
+
284
+ ### Skills
285
+
286
+ **8 skills**, each with a slash command. A skill never says *when* to do something. It says *how* to write or check one pillar.
287
+
288
+ | Command | Skill | What it does |
289
+ | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
290
+ | `/doc-audit` | `doc-audit` | Audits completeness and freshness of every pillar. |
291
+ | `/drift` | `drift-detector` | Finds where docs no longer match the code. |
292
+ | `/spec` | `spec-writer` | Writes a tech-agnostic spec, progressively: three questions to start, one section at a time after. |
293
+ | `/decision` | `decision-record-writer` | Writes an ADR, spotting implicit decisions in your diff. |
294
+ | `/handbook` | `handbook-writer` | Documents how a feature is actually implemented. |
295
+ | `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
296
+ | `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release, languages. |
297
+ | `/readme` | `readme-writer` | Keeps the README in sync with the code. |
298
+
299
+ ### Linters
300
+
301
+ **15 linters**, fast enough to run on every commit.
302
+
303
+ <details>
304
+ <summary>See the list</summary>
305
+
306
+ | Linter | Checks |
307
+ | ------------------------------------ | ------------------------------------------------------------------- |
308
+ | `readme-presence`, `readme-sections` | `README.md` exists and has a title and a quick start. |
309
+ | `doc-layout`, `cardinal-files` | The `docs/` folders and required files exist. |
310
+ | `spec-has-content`, `spec-tech-agnostic` | Specs exist and don't name frameworks or vendors. |
311
+ | `decision-schema` | Each ADR has its four sections. |
312
+ | `adr-no-tracks`, `orphan-decisions` | ADRs carry no `tracks:` and are referenced somewhere. |
313
+ | `frontmatter-tracks`, `tracks-drift` | Tracked paths exist; docs aren't older than the code they track. |
314
+ | `cross-links` | Links between docs resolve. |
315
+ | `gitignore-harness` | Overrides and reports are ignored; generated files are not. |
316
+ | `generated-fresh` | Committed generated files match the current render. |
317
+ | `quality-schema` | `docs/quality/code-quality.md` has its sections, if you use it. |
318
+
319
+ </details>
320
+
321
+ ### Engines
322
+
323
+ | | Claude Code | Codex | OpenCode |
324
+ | -------------- | ------------------------- | ---------------------- | ---------------- |
325
+ | Entry point | `CLAUDE.md` → `AGENTS.md` | `AGENTS.md` | `AGENTS.md` |
326
+ | Skills | `.claude/skills/` | `.agents/skills/` | reuses the above |
327
+ | Slash commands | ✓ | invoke skills by name | ✓ |
328
+
329
+ You name your engines; nothing is rendered for a tool you don't use. Add one later with `init . --engines=...` again.
330
+
331
+ ## Adopting it on an existing project
332
+
333
+ You don't have to write all the docs on day one.
334
+
335
+ - **See where you stand.** `npx @vaubaan/harness lint` lists what's missing, with the skill that fixes each item.
336
+ - **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.
337
+ - **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.
338
+ - **Back out anytime.** `npx @vaubaan/harness uninstall .` removes what `init` wrote. Your own files are left in place.
207
339
 
208
340
  ## Commands
209
341
 
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. |
342
+ | Command | What it does |
343
+ | ------------------------------------- | -------------------------------------------------------------------------------------------- |
344
+ | `init <dir> --engines=<list>` | Render the harness into a project. Re-run it to change engines. |
345
+ | `update [dir]` | Re-render with the installed version, keeping your engines. `--dry-run --json` previews. |
346
+ | `uninstall <dir>` | Remove what `init` wrote, leaving your own files in place. |
347
+ | `lint` | Run the linters. `--format json`, `--pillar <name>`, `--only <ids>`. |
348
+ | `check <dir>` | Quick layout check: doc folders and `.gitignore`. |
349
+ | `render --engines=<list> --out <dir>` | Preview the render somewhere harmless. |
218
350
 
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).
351
+ 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
352
 
221
353
  ## Configuration
222
354
 
@@ -240,11 +372,10 @@ Patterns use [fast-glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) syn
240
372
  <details>
241
373
  <summary><b>Local overrides</b></summary>
242
374
 
243
- Try a custom agent, skill or command without forking, in a gitignored `.harness-overrides/` folder:
375
+ Try a custom skill or command without forking, in a gitignored `.harness-overrides/` folder:
244
376
 
245
377
  ```
246
378
  .harness-overrides/
247
- agents/ *.agent.md
248
379
  skills/ *.skill.md
249
380
  commands/ *.cmd.md
250
381
  disable.yaml # disable: [readme-writer, workflow-writer]
@@ -254,43 +385,46 @@ Overrides are personal and disposable. Skills meant for the whole team go in `do
254
385
 
255
386
  </details>
256
387
 
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
388
  <details>
265
389
  <summary><b>Updating</b></summary>
266
390
 
267
391
  ```bash
268
392
  npm i -D @vaubaan/harness@latest
269
393
  npx @vaubaan/harness update . --dry-run --json # preview
270
- npx @vaubaan/harness update .
394
+ npx @vaubaan/harness update . # then commit the result
271
395
  ```
272
396
 
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).
397
+ `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
398
 
275
399
  </details>
276
400
 
277
401
  ## FAQ
278
402
 
279
- **Does it phone home?** No. No telemetry, no daemon. It writes files and runs linters locally.
403
+ **Does it phone home?** No. No telemetry, no daemon, no hook in your engine. It writes files and runs linters locally.
404
+
405
+ **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.
406
+
407
+ **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
408
 
281
- **Do I need all three engines?** No. Everything is rendered for all three by default because it costs nothing, but `--engines` narrows it.
409
+ **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
410
 
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.
411
+ **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
412
 
285
413
  **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
414
 
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.
415
+ **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.
416
+
417
+ **Is this tied to Vaubaan?** No. Vaubaan builds it and uses it on its own projects, including this one, which is harnessed by itself.
418
+
419
+ ## Where this is going
420
+
421
+ 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
422
 
289
423
  ## Documentation
290
424
 
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
425
+ - [Spec](./docs/spec/coding-agent-harness.md), what the harness is and why
426
+ - [Decisions](./docs/decisions/), architecture choices and their alternatives
427
+ - [Handbook](./docs/handbook/), how each part works today
294
428
  - [Test plans](./docs/tests/) and [workflow](./docs/workflow/coding-workflow.md)
295
429
  - [Changelog](./CHANGELOG.md)
296
430
 
@@ -305,4 +439,4 @@ npm ci && npm run ci
305
439
 
306
440
  ## License
307
441
 
308
- [Apache 2.0](./LICENSE) — see [NOTICE](./NOTICE).
442
+ [Apache 2.0](./LICENSE), see [NOTICE](./NOTICE).