@vaubaan/harness 2.1.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 +12 -6
- package/dist/cli/index.js +541 -74
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/journey.cmd.md +22 -0
- package/dist/commands/story.cmd.md +24 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +302 -54
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +299 -51
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +521 -54
- 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 +87 -8
- package/dist/render.js.map +1 -1
- package/dist/skills/doc-audit.skill.md +34 -4
- package/dist/skills/drift-detector.skill.md +36 -5
- package/dist/skills/handbook-writer.skill.md +3 -0
- package/dist/skills/journey-writer.skill.md +159 -0
- 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) ·
|
|
@@ -50,6 +50,7 @@ Each pillar stores one kind of information the code cannot carry, and links to t
|
|
|
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
|
|
|
@@ -254,6 +256,7 @@ jobs:
|
|
|
254
256
|
/doc-audit # what is missing or stale
|
|
255
257
|
/spec # write the spec of a subsystem, guided
|
|
256
258
|
/decision # turn an implicit choice into an ADR
|
|
259
|
+
/story # a proposed leaf with acceptance criteria, before the code
|
|
257
260
|
```
|
|
258
261
|
|
|
259
262
|
> [!NOTE]
|
|
@@ -272,7 +275,7 @@ jobs:
|
|
|
272
275
|
Claude Code · Codex · OpenCode read the same context, write the code
|
|
273
276
|
│
|
|
274
277
|
▼ pre-commit, CI
|
|
275
|
-
vaubaan-harness lint
|
|
278
|
+
vaubaan-harness lint 19 linters: shape, links, drift, freshness
|
|
276
279
|
```
|
|
277
280
|
|
|
278
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.
|
|
@@ -283,7 +286,7 @@ jobs:
|
|
|
283
286
|
|
|
284
287
|
### Skills
|
|
285
288
|
|
|
286
|
-
**
|
|
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.
|
|
287
290
|
|
|
288
291
|
| Command | Skill | What it does |
|
|
289
292
|
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
|
|
@@ -295,10 +298,12 @@ jobs:
|
|
|
295
298
|
| `/test-plan` | `test-plan-writer` | Keeps integration and e2e test plans up to date. |
|
|
296
299
|
| `/workflow` | `workflow-writer` | Documents CI, environments, PR process, branches, release, languages. |
|
|
297
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. |
|
|
298
303
|
|
|
299
304
|
### Linters
|
|
300
305
|
|
|
301
|
-
**
|
|
306
|
+
**19 linters**, fast enough to run on every commit.
|
|
302
307
|
|
|
303
308
|
<details>
|
|
304
309
|
<summary>See the list</summary>
|
|
@@ -315,6 +320,7 @@ jobs:
|
|
|
315
320
|
| `gitignore-harness` | Overrides and reports are ignored; generated files are not. |
|
|
316
321
|
| `generated-fresh` | Committed generated files match the current render. |
|
|
317
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. |
|
|
318
324
|
|
|
319
325
|
</details>
|
|
320
326
|
|
|
@@ -418,7 +424,7 @@ npx @vaubaan/harness update . # then commit the result
|
|
|
418
424
|
|
|
419
425
|
## Where this is going
|
|
420
426
|
|
|
421
|
-
|
|
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.
|
|
422
428
|
|
|
423
429
|
## Documentation
|
|
424
430
|
|