@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 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.** 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.
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.** 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.
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 15 linters: shape, links, drift, freshness
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
- **8 skills**, each with a slash command. A skill never says *when* to do something. It says *how* to write or check one pillar.
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
- **15 linters**, fast enough to run on every commit.
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
- 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.
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