@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 +303 -167
- package/dist/cli/index.js +884 -1880
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +275 -1062
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +9 -23
- package/dist/init.js +268 -1034
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +687 -31
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +1 -26
- package/dist/parser/index.js +1 -17
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-Cu2XrkkY.d.ts → render-C-FWmUfX.d.ts} +8 -15
- package/dist/render.d.ts +1 -1
- package/dist/render.js +16 -278
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +3 -4
- package/dist/skills/doc-audit.skill.md +7 -7
- package/dist/skills/drift-detector.skill.md +1 -1
- package/dist/skills/handbook-writer.skill.md +2 -2
- package/dist/skills/readme-writer.skill.md +3 -3
- package/dist/skills/spec-writer.skill.md +89 -71
- package/dist/skills/test-plan-writer.skill.md +3 -3
- package/dist/skills/workflow-writer.skill.md +20 -3
- package/dist/templates/code-quality.md.tmpl +2 -2
- package/dist/templates/coding-workflow.md.tmpl +10 -0
- package/package.json +1 -1
- package/dist/agents/coding.agent.md +0 -182
- package/dist/agents/merge.agent.md +0 -139
- package/dist/agents/planning.agent.md +0 -194
- package/dist/agents/review.agent.md +0 -176
- package/dist/commands/clean-code.cmd.md +0 -26
- package/dist/skills/clean-code-guardian.skill.md +0 -391
package/README.md
CHANGED
|
@@ -1,222 +1,356 @@
|
|
|
1
1
|
# @vaubaan/harness
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
-
|
|
163
|
+
**`docs/workflow/coding-workflow.md`**: what lives outside the repo, and pointers to what lives in it.
|
|
18
164
|
|
|
19
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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
|
|
40
|
-
.claude/ #
|
|
41
|
-
.
|
|
42
|
-
.opencode/ #
|
|
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
|
-
|
|
223
|
+
**2. Commit all of it**, generated files included ([why](#faq)). Only two paths are gitignored:
|
|
47
224
|
|
|
48
225
|
```gitignore
|
|
49
|
-
#
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
.
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
.
|
|
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
|
-
|
|
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
|
-
|
|
253
|
+
**4. Open your agent and let it fill the gaps.**
|
|
67
254
|
|
|
68
255
|
```
|
|
69
|
-
/doc-audit # what
|
|
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
|
-
>
|
|
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/
|
|
81
|
-
│
|
|
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
|
|
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
|
-
|
|
276
|
+
▼ pre-commit, CI
|
|
277
|
+
vaubaan-harness lint 15 linters: shape, links, drift, freshness
|
|
96
278
|
```
|
|
97
279
|
|
|
98
|
-
1. **Your docs are the
|
|
99
|
-
2. **
|
|
100
|
-
3. **Linters keep
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
301
|
+
### Linters
|
|
124
302
|
|
|
125
|
-
**
|
|
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
|
|
154
|
-
|
|
155
|
-
| `readme-presence`, `readme-sections` | `README.md` exists and has a title and a quick start.
|
|
156
|
-
| `doc-layout`, `cardinal-files`
|
|
157
|
-
| `spec-has-content`, `spec-tech-agnostic` | Specs exist and don't name frameworks or vendors.
|
|
158
|
-
| `decision-schema`
|
|
159
|
-
| `adr-no-tracks`, `orphan-decisions`
|
|
160
|
-
| `frontmatter-tracks`, `tracks-drift` | Tracked paths exist; docs aren't older than the code they track.
|
|
161
|
-
| `cross-links`
|
|
162
|
-
| `gitignore-harness`
|
|
163
|
-
| `
|
|
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
|
-
|
|
323
|
+
### Engines
|
|
168
324
|
|
|
169
|
-
|
|
|
170
|
-
|
|
171
|
-
|
|
|
172
|
-
| Skills
|
|
173
|
-
| Slash commands | ✓
|
|
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
|
-
|
|
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
|
|
185
|
-
- **Let the agent do the first pass
|
|
186
|
-
- **
|
|
187
|
-
- **Back out anytime
|
|
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
|
|
211
|
-
|
|
212
|
-
| `init <dir>`
|
|
213
|
-
| `update [dir]`
|
|
214
|
-
| `uninstall <dir>`
|
|
215
|
-
| `lint`
|
|
216
|
-
| `check <dir>`
|
|
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>`.
|
|
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
|
|
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
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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)
|
|
292
|
-
- [Decisions](./docs/decisions/)
|
|
293
|
-
- [Handbook](./docs/handbook/)
|
|
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)
|
|
444
|
+
[Apache 2.0](./LICENSE), see [NOTICE](./NOTICE).
|