@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 +42 -57
- package/dist/cli/index.js +1 -1
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/init.js +1 -1
- package/dist/init.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
# @vaubaan/harness
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
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
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
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