@vaubaan/harness 2.0.0 → 2.2.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 +25 -21
- package/dist/cli/index.js +543 -76
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/handbook.cmd.md +4 -3
- package/dist/commands/journey.cmd.md +22 -0
- package/dist/commands/story.cmd.md +24 -0
- package/dist/commands/test-plan.cmd.md +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +304 -56
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +2 -3
- package/dist/init.js +301 -53
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +523 -56
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +110 -1
- package/dist/parser/index.js +229 -2
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-C-FWmUfX.d.ts → render-BzrBb_l4.d.ts} +3 -1
- package/dist/render.d.ts +1 -1
- package/dist/render.js +89 -10
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +93 -130
- package/dist/skills/doc-audit.skill.md +37 -7
- package/dist/skills/drift-detector.skill.md +41 -11
- package/dist/skills/handbook-writer.skill.md +71 -159
- package/dist/skills/journey-writer.skill.md +159 -0
- package/dist/skills/spec-writer.skill.md +25 -3
- package/dist/skills/test-plan-writer.skill.md +46 -53
- package/dist/skills/workflow-writer.skill.md +20 -3
- 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/dist/templates/journey.md.tmpl +45 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -17,9 +17,9 @@ npx -y @vaubaan/harness init . --engines=claude-code
|
|
|
17
17
|
|
|
18
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
19
|
|
|
20
|
-
- **One context, every engine.**
|
|
20
|
+
- **One context, every engine.** Nine 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
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.**
|
|
22
|
+
- **Checks with zero tokens.** Nineteen 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
23
|
|
|
24
24
|
**Contents:**
|
|
25
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) ·
|
|
@@ -44,12 +44,13 @@ Each pillar stores one kind of information the code cannot carry, and links to t
|
|
|
44
44
|
| ----------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
45
45
|
| `README.md` | What this is, how to run it. | `package.json` scripts, the quick start. |
|
|
46
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/` |
|
|
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
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/` |
|
|
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
50
|
| `docs/workflow/` | What lives outside the repo: approvals, protections, secrets, languages. | `ci.yml`, build scripts, pre-commit hook. |
|
|
51
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
52
|
| `docs/skills/` | Optional. Domain know-how the agent should load. | Whatever the skill needs. |
|
|
53
|
+
| `docs/journeys/` | Optional. What the user does and wants, at every scale, anchored to the code. | Each leaf's `anchors:`; `requires:`/`creates:` name the spec vocabulary. |
|
|
53
54
|
|
|
54
55
|
> [!IMPORTANT]
|
|
55
56
|
> **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.**
|
|
@@ -75,6 +76,7 @@ acme-billing/
|
|
|
75
76
|
├── tests/e2e-tests.md
|
|
76
77
|
├── workflow/coding-workflow.md
|
|
77
78
|
├── quality/code-quality.md # optional
|
|
79
|
+
├── journeys/ # optional: send-an-invoice.md, README.md (rendered index)
|
|
78
80
|
└── skills/tax-rules.skill.md # optional
|
|
79
81
|
```
|
|
80
82
|
|
|
@@ -103,7 +105,7 @@ status: draft
|
|
|
103
105
|
- Multi-currency: not before a customer asks.
|
|
104
106
|
```
|
|
105
107
|
|
|
106
|
-
**`docs/decisions/postgres-over-sqlite.md`**:
|
|
108
|
+
**`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.
|
|
107
109
|
|
|
108
110
|
```markdown
|
|
109
111
|
# Postgres over SQLite for the invoice store
|
|
@@ -119,11 +121,8 @@ and `src/db/client.ts`. Introduced in commit `4f1c2ab`.
|
|
|
119
121
|
Local setup needs Docker. Migrations live in `db/migrations/`.
|
|
120
122
|
|
|
121
123
|
## Rejected alternatives
|
|
122
|
-
|
|
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.
|
|
124
|
+
### SQLite
|
|
125
|
+
Where it started; its single-writer lock lost a write under two workers.
|
|
127
126
|
```
|
|
128
127
|
|
|
129
128
|
**`docs/handbook/invoice-pipeline.md`**: the map, declared with `tracks:` so the linter notices when the code moves.
|
|
@@ -147,17 +146,18 @@ Gotcha: `void.ts` keeps the row and flips `status`; reports must filter
|
|
|
147
146
|
on it (`src/reports/monthly.ts`).
|
|
148
147
|
```
|
|
149
148
|
|
|
150
|
-
**`docs/tests/integration-tests.md`**:
|
|
149
|
+
**`docs/tests/integration-tests.md`**: scope, stack, conventions and known gaps. The covered scenarios are the test titles, never copied here.
|
|
151
150
|
|
|
152
151
|
```markdown
|
|
153
152
|
---
|
|
154
|
-
tracks: [tests/integration
|
|
153
|
+
tracks: [vitest.config.ts, tests/integration/fixtures/*.ts]
|
|
155
154
|
---
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
155
|
+
## Scope
|
|
156
|
+
Invoicing modules against a throwaway Postgres; no browser (→ e2e-tests.md).
|
|
157
|
+
## Conventions
|
|
158
|
+
One database per worker (`fixtures/db.ts`); never share a draft across tests.
|
|
159
|
+
## Known gaps
|
|
160
|
+
- ⚠️ Two workers issuing the same draft (spec invoicing §3) — not tested yet.
|
|
161
161
|
```
|
|
162
162
|
|
|
163
163
|
**`docs/workflow/coding-workflow.md`**: what lives outside the repo, and pointers to what lives in it.
|
|
@@ -256,6 +256,7 @@ jobs:
|
|
|
256
256
|
/doc-audit # what is missing or stale
|
|
257
257
|
/spec # write the spec of a subsystem, guided
|
|
258
258
|
/decision # turn an implicit choice into an ADR
|
|
259
|
+
/story # a proposed leaf with acceptance criteria, before the code
|
|
259
260
|
```
|
|
260
261
|
|
|
261
262
|
> [!NOTE]
|
|
@@ -274,7 +275,7 @@ jobs:
|
|
|
274
275
|
Claude Code · Codex · OpenCode read the same context, write the code
|
|
275
276
|
│
|
|
276
277
|
▼ pre-commit, CI
|
|
277
|
-
vaubaan-harness lint
|
|
278
|
+
vaubaan-harness lint 19 linters: shape, links, drift, freshness
|
|
278
279
|
```
|
|
279
280
|
|
|
280
281
|
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.
|
|
@@ -285,7 +286,7 @@ jobs:
|
|
|
285
286
|
|
|
286
287
|
### Skills
|
|
287
288
|
|
|
288
|
-
**
|
|
289
|
+
**9 skills**, each with a slash command. A skill never says *when* to do something. It says *how* to write or check one pillar.
|
|
289
290
|
|
|
290
291
|
| Command | Skill | What it does |
|
|
291
292
|
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
|
|
@@ -297,10 +298,12 @@ jobs:
|
|
|
297
298
|
| `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
|
|
298
299
|
| `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release, languages. |
|
|
299
300
|
| `/readme` | `readme-writer` | Keeps the README in sync with the code. |
|
|
301
|
+
| `/journey` | `journey-writer` | Writes the user journeys, one anchored node at a time; three questions on a greenfield scope, extraction from the code on a mature one. |
|
|
302
|
+
| `/story` | `journey-writer` | Adds a `proposed` leaf with acceptance criteria to the right journey, before any code. |
|
|
300
303
|
|
|
301
304
|
### Linters
|
|
302
305
|
|
|
303
|
-
**
|
|
306
|
+
**19 linters**, fast enough to run on every commit.
|
|
304
307
|
|
|
305
308
|
<details>
|
|
306
309
|
<summary>See the list</summary>
|
|
@@ -317,6 +320,7 @@ jobs:
|
|
|
317
320
|
| `gitignore-harness` | Overrides and reports are ignored; generated files are not. |
|
|
318
321
|
| `generated-fresh` | Committed generated files match the current render. |
|
|
319
322
|
| `quality-schema` | `docs/quality/code-quality.md` has its sections, if you use it. |
|
|
323
|
+
| `journey-schema`, `journey-anchors`, `journey-vocabulary`, `journey-graph` | Optional `docs/journeys/`: node grammar, anchors exist, entities are spec vocabulary, nothing requires what nothing creates. |
|
|
320
324
|
|
|
321
325
|
</details>
|
|
322
326
|
|
|
@@ -420,7 +424,7 @@ npx @vaubaan/harness update . # then commit the result
|
|
|
420
424
|
|
|
421
425
|
## Where this is going
|
|
422
426
|
|
|
423
|
-
|
|
427
|
+
Shipped: the optional `docs/journeys/` pillar and its first typed context transaction, `/story`, which writes an increment as a `proposed` leaf before the code and passes it `implemented` when delivered. Decided, not shipped yet: the other transactions (`/decide`, `/refactor`, `/fix`), 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.
|
|
424
428
|
|
|
425
429
|
## Documentation
|
|
426
430
|
|