@vaubaan/harness 2.3.0 → 2.4.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
@@ -1,8 +1,11 @@
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.
4
+ <picture>
5
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/hero-dark.svg">
6
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/hero-light.svg">
7
+ <img alt="Project context as code. A context database for your project, kept in the repo, rendered for your coding agents, linted in CI." src="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/hero.svg" width="100%">
8
+ </picture>
6
9
  </p>
7
10
 
8
11
  <p align="center">
@@ -43,21 +46,13 @@ You and your coding agents share a codebase. It holds two databases.
43
46
 
44
47
  The **code database** is `src/`, the tests, the configs: what the machine runs. The **meta database** is `docs/`: what the code cannot say, kept in a small fixed set of Markdown files that point to the code for everything else. Both personas read and write both. You decide, validate and merge; the agent writes docs and code with judgment; the harness is the schema of the meta database, its integrity constraints and its views.
45
48
 
46
- ```mermaid
47
- flowchart LR
48
- H["You<br/>decide, validate, merge"]
49
- A["Your coding agents<br/>write docs and code"]
50
- subgraph CB["one repository"]
51
- direction TB
52
- CODE["code database<br/>src · tests · configs"]
53
- META["meta database<br/>docs/ and its rendered views"]
54
- META -- "tracks · anchors · realized by" --> CODE
55
- end
56
- X["harness<br/>schema · 19 constraints · views"]
57
- H <--> CB
58
- A <--> CB
59
- X -. "keeps the meta database consistent<br/>with itself and with the code" .-> META
60
- ```
49
+ <p align="center">
50
+ <picture>
51
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/two-databases-dark.svg">
52
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/two-databases-light.svg">
53
+ <img alt="You and your coding agents share one repository that holds a code database and a meta database; the harness is the schema, the constraints and the views of the meta database." src="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/two-databases.svg" width="100%">
54
+ </picture>
55
+ </p>
61
56
 
62
57
  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.
63
58
 
@@ -260,6 +255,14 @@ npx -y @vaubaan/harness init . --engines=claude-code
260
255
  # or: --engines=claude-code,codex-cli,opencode
261
256
  ```
262
257
 
258
+ <p align="center">
259
+ <picture>
260
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/terminal-dark.svg">
261
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/terminal-light.svg">
262
+ <img alt="Terminal: init renders 20 files; lint reports a drift warning on a handbook and names the skill that fixes it; CI passes." src="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/terminal.svg" width="100%">
263
+ </picture>
264
+ </p>
265
+
263
266
  This writes, for each engine:
264
267
 
265
268
  ```
@@ -407,15 +410,13 @@ npx @vaubaan/harness uninstall .
407
410
 
408
411
  ## How it works
409
412
 
410
- ```mermaid
411
- flowchart LR
412
- D["docs/<br/>your context, in Markdown"]
413
- R["AGENTS.md · .claude/ · .agents/ · .opencode/<br/>rendered for each engine, committed"]
414
- E["Claude Code · Codex · OpenCode<br/>read the same context, write the code"]
415
- L["vaubaan-harness lint<br/>pre-commit and CI, zero tokens"]
416
- D -- "init · update" --> R --> E -- "code and docs" --> L
417
- L -. "fails when context and code disagree" .-> D
418
- ```
413
+ <p align="center">
414
+ <picture>
415
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/how-it-works-dark.svg">
416
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/how-it-works-light.svg">
417
+ <img alt="docs/ is rendered into AGENTS.md and the engine folders; agents read it and write code and docs; the linter runs in pre-commit and CI and fails when context and code disagree." src="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/how-it-works.svg" width="100%">
418
+ </picture>
419
+ </p>
419
420
 
420
421
  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.
421
422
  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.
@@ -438,6 +439,14 @@ Eight things you will do with a harnessed project, again and again. Each one is
438
439
 
439
440
  One word first. In the intents pillar, every heading is an **intent**: what the user wants, verb + object, at every level. The file is the level-1 intent, its headings are sub-intents. An intent with no sub-intent is **terminal**: it carries the fields. Terminal and `proposed`, it is decided and not delivered, the backlog item; terminal and `implemented`, it is delivered and points to its code.
440
441
 
442
+ <p align="center">
443
+ <picture>
444
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/intent-tree-dark.svg">
445
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/intent-tree-light.svg">
446
+ <img alt="An intent file is a tree: level-1 intent, sub-intents, terminal intents with anchors or acceptance criteria. Read it as an OKR tree whose progress is computed from the repo." src="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/intent-tree.svg" width="100%">
447
+ </picture>
448
+ </p>
449
+
441
450
  <a name="specify-a-change-without-a-ticketing-tool"></a>
442
451
  <details>
443
452
  <summary><strong>Specify a change, without a ticketing tool</strong></summary>
@@ -670,37 +679,13 @@ Never:
670
679
 
671
680
  The first question is always the same: does the behavior visible to the user change?
672
681
 
673
- ```mermaid
674
- flowchart TB
675
- Q0["The user asks for something"]
676
- Q5{"A question, not a<br/>request for change?"}
677
- Q1{"Does the behavior visible<br/>to the user change?"}
678
- Q2{"Does a proposed intent<br/>already exist?"}
679
- Q3{"Are the words in the<br/>spec Vocabulary?"}
680
- Q4{"A structural choice,<br/>costly to reverse?"}
681
- X{"An intent to deliver?"}
682
- R["Answer from the docs and the code<br/>Report the gap, invent nothing"]
683
- S["/intent: a proposed intent with<br/>acceptance criteria, no code"]
684
- SP["/spec first: define the word<br/>then back to /intent"]
685
- D["/decision before the code"]
686
- C["Code + tests titled after the criteria<br/>intent → implemented with anchors"]
687
- F["Code + regression test<br/>handbook if an invariant changed<br/>tracks and anchors if files moved"]
688
- E["update . → lint → follow docs/workflow"]
689
- Q0 --> Q5
690
- Q5 -- yes --> R
691
- Q5 -- no --> Q1
692
- Q1 -- yes --> Q2
693
- Q2 -- no --> Q3
694
- Q3 -- yes --> S
695
- Q3 -- no --> SP --> S
696
- S -- "the user validates" --> Q4
697
- Q2 -- yes --> Q4
698
- Q1 -- no --> Q4
699
- Q4 -- yes --> D --> X
700
- Q4 -- no --> X
701
- X -- yes --> C --> E
702
- X -- no --> F --> E
703
- ```
682
+ <p align="center">
683
+ <picture>
684
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/agent-decision-tree-dark.svg">
685
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/agent-decision-tree-light.svg">
686
+ <img alt="Decision tree: a question is answered from the docs; a visible change starts with a proposed intent and spec vocabulary; a costly choice starts with an ADR; every path ends with update, lint and the team workflow." src="https://raw.githubusercontent.com/vaubaan/harness/main/.github/readme/agent-decision-tree.svg" width="100%">
687
+ </picture>
688
+ </p>
704
689
 
705
690
  </details>
706
691
 
package/dist/cli/index.js CHANGED
@@ -445,7 +445,7 @@ import { join as join4 } from "path";
445
445
  import { z } from "zod";
446
446
 
447
447
  // src/version.ts
448
- var VERSION = "2.3.0";
448
+ var VERSION = "2.4.0";
449
449
 
450
450
  // src/cli/manifest.ts
451
451
  var MANIFEST_FILENAME = ".harness-manifest.json";