@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.
- package/README.md +301 -167
- package/dist/cli/index.js +886 -1882
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/handbook.cmd.md +4 -3
- package/dist/commands/test-plan.cmd.md +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +277 -1064
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +8 -23
- package/dist/init.js +270 -1036
- 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 +18 -280
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +93 -131
- package/dist/skills/doc-audit.skill.md +10 -10
- package/dist/skills/drift-detector.skill.md +6 -7
- package/dist/skills/handbook-writer.skill.md +68 -159
- package/dist/skills/readme-writer.skill.md +3 -3
- package/dist/skills/spec-writer.skill.md +111 -71
- package/dist/skills/test-plan-writer.skill.md +47 -54
- package/dist/skills/workflow-writer.skill.md +40 -6
- package/dist/templates/code-quality.md.tmpl +2 -2
- package/dist/templates/coding-workflow.md.tmpl +10 -0
- package/dist/templates/decision.md.tmpl +20 -47
- package/dist/templates/e2e-tests.md.tmpl +16 -45
- package/dist/templates/handbook.md.tmpl +20 -38
- package/dist/templates/integration-tests.md.tmpl +16 -34
- 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,192 +1,236 @@
|
|
|
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
|
|
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
|
-
##
|
|
31
|
+
## The problem
|
|
18
32
|
|
|
19
|
-
|
|
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
|
-
|
|
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
|
-
|
|
37
|
+
## A context database with pointers
|
|
26
38
|
|
|
27
|
-
|
|
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
|
-
|
|
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
|
-
|
|
32
|
-
|
|
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
|
-
|
|
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
|
-
|
|
39
|
-
|
|
40
|
-
.
|
|
41
|
-
.
|
|
42
|
-
.opencode/
|
|
43
|
-
.harness-manifest.json
|
|
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
|
-
|
|
81
|
+
Each file says what the code cannot, and points to the code for the rest.
|
|
47
82
|
|
|
48
|
-
|
|
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
|
-
|
|
85
|
+
```markdown
|
|
86
|
+
---
|
|
87
|
+
status: draft
|
|
88
|
+
---
|
|
89
|
+
# Invoicing — spec
|
|
65
90
|
|
|
66
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
-
|
|
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
|
-
|
|
108
|
+
```markdown
|
|
109
|
+
# Postgres over SQLite for the invoice store
|
|
78
110
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
137
|
+
Entry point: `src/invoicing/issue.ts#issueInvoice`. It freezes the
|
|
138
|
+
draft, writes the row, emits `invoice.issued`.
|
|
105
139
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
161
|
+
**`docs/workflow/coding-workflow.md`**: what lives outside the repo, and pointers to what lives in it.
|
|
124
162
|
|
|
125
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
151
|
-
<summary>See the list</summary>
|
|
199
|
+
## Quick start
|
|
152
200
|
|
|
153
|
-
|
|
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
|
-
|
|
203
|
+
**1. Render the harness into your project.**
|
|
166
204
|
|
|
167
|
-
|
|
205
|
+
```bash
|
|
206
|
+
npx -y @vaubaan/harness init . --engines=claude-code
|
|
207
|
+
# or: --engines=claude-code,codex-cli,opencode
|
|
208
|
+
```
|
|
168
209
|
|
|
169
|
-
|
|
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
|
-
|
|
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
|
-
|
|
221
|
+
**2. Commit all of it**, generated files included ([why](#faq)). Only two paths are gitignored:
|
|
181
222
|
|
|
182
|
-
|
|
223
|
+
```gitignore
|
|
224
|
+
.harness-overrides/ # your local, disposable overrides
|
|
225
|
+
.vaubaan/ # skill reports
|
|
226
|
+
```
|
|
183
227
|
|
|
184
|
-
|
|
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
|
-
|
|
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:
|
|
247
|
+
- run: npm ci
|
|
248
|
+
- run: npx vaubaan-harness lint
|
|
204
249
|
```
|
|
205
250
|
|
|
206
|
-
|
|
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
|
|
211
|
-
|
|
212
|
-
| `init <dir>`
|
|
213
|
-
| `update [dir]`
|
|
214
|
-
| `uninstall <dir>`
|
|
215
|
-
| `lint`
|
|
216
|
-
| `check <dir>`
|
|
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>`.
|
|
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
|
|
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
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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)
|
|
292
|
-
- [Decisions](./docs/decisions/)
|
|
293
|
-
- [Handbook](./docs/handbook/)
|
|
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)
|
|
442
|
+
[Apache 2.0](./LICENSE), see [NOTICE](./NOTICE).
|