@vaubaan/harness 1.4.0 → 2.1.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 +301 -167
- package/dist/cli/index.js +886 -1882
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/handbook.cmd.md +4 -3
- package/dist/commands/test-plan.cmd.md +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +277 -1064
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +8 -23
- package/dist/init.js +270 -1036
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +687 -31
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +1 -26
- package/dist/parser/index.js +1 -17
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-Cu2XrkkY.d.ts → render-C-FWmUfX.d.ts} +8 -15
- package/dist/render.d.ts +1 -1
- package/dist/render.js +18 -280
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +93 -131
- package/dist/skills/doc-audit.skill.md +10 -10
- package/dist/skills/drift-detector.skill.md +6 -7
- package/dist/skills/handbook-writer.skill.md +68 -159
- package/dist/skills/readme-writer.skill.md +3 -3
- package/dist/skills/spec-writer.skill.md +111 -71
- package/dist/skills/test-plan-writer.skill.md +47 -54
- package/dist/skills/workflow-writer.skill.md +40 -6
- package/dist/templates/code-quality.md.tmpl +2 -2
- package/dist/templates/coding-workflow.md.tmpl +10 -0
- 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/package.json +1 -1
- package/dist/agents/coding.agent.md +0 -182
- package/dist/agents/merge.agent.md +0 -139
- package/dist/agents/planning.agent.md +0 -194
- package/dist/agents/review.agent.md +0 -176
- package/dist/commands/clean-code.cmd.md +0 -26
- package/dist/skills/clean-code-guardian.skill.md +0 -391
|
@@ -1,62 +1,33 @@
|
|
|
1
1
|
---
|
|
2
|
+
title: E2E test plan
|
|
2
3
|
tracks:
|
|
3
|
-
- <
|
|
4
|
-
- <E2E_TEST_DIR_OR_FILE_2>
|
|
4
|
+
- <RUNNER_CONFIG_AND_TEST_INFRASTRUCTURE>
|
|
5
5
|
last_reviewed: <DATE>
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# E2E test plan
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
10
|
+
<!--
|
|
11
|
+
Never list the covered scenarios: the describe()/it() titles of the test
|
|
12
|
+
files are their source of truth. Document what the code cannot tell.
|
|
13
|
+
Target 20-50 lines, bullets. Do not restate the runner config.
|
|
14
|
+
-->
|
|
14
15
|
|
|
15
|
-
|
|
16
|
-
pass on every release. Exhaustive coverage required.
|
|
17
|
-
- **Edge cases**: less frequent but high-value scenarios
|
|
18
|
-
(errors, permissions, boundary states). Selective coverage.
|
|
16
|
+
## Scope
|
|
19
17
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
E2E tests are expensive, we reserve them for journeys that cannot
|
|
23
|
-
be validated otherwise.
|
|
18
|
+
- The complete system against real or staging dependencies, on the journeys that cannot be validated in [integration](./integration-tests.md).
|
|
19
|
+
- <project-specific boundary>
|
|
24
20
|
|
|
25
21
|
## Stack
|
|
26
22
|
|
|
27
|
-
-
|
|
28
|
-
- **Drivers:** <BROWSER_OR_API_DRIVER>
|
|
29
|
-
- **Target environment:** <ENV_TARGET>
|
|
30
|
-
- **Reporting:** <REPORT_TOOL>
|
|
31
|
-
|
|
32
|
-
## Fixture conventions
|
|
33
|
-
|
|
34
|
-
- **E2E organization:** each scenario runs in an isolated
|
|
35
|
-
fixture (`<E2E_ORG_NAMING_CONVENTION>`) to avoid
|
|
36
|
-
interference between parallel runs.
|
|
37
|
-
- **Naming:** <FIXTURE_NAMING_RULE>
|
|
38
|
-
- **Seed data:** <SEED_STRATEGY>
|
|
39
|
-
- **Authentication:** <AUTH_STRATEGY>
|
|
40
|
-
|
|
41
|
-
## Sweeper / cleanup
|
|
42
|
-
|
|
43
|
-
E2E fixtures inevitably leave artifacts behind (created orgs,
|
|
44
|
-
uploaded files, in-flight jobs). The sweeper:
|
|
45
|
-
|
|
46
|
-
- **Cadence:** <SWEEPER_FREQUENCY>
|
|
47
|
-
- **Purge criterion:** <PURGE_CRITERIA>
|
|
48
|
-
- **Logs:** <SWEEPER_LOG_LOCATION>
|
|
49
|
-
- **Dry-run mode:** <DRY_RUN_SWITCH>
|
|
23
|
+
- <framework, test environment, core mocks / fixtures — with the *why* of a non-obvious choice>
|
|
50
24
|
|
|
51
|
-
##
|
|
25
|
+
## Conventions
|
|
52
26
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
| E2E-02 | <SCENARIO_2_NAME> | edge | [[<SPEC_NAME_2>]] | <TEST_FILE_PATH_2> |
|
|
57
|
-
| E2E-NN | <SCENARIO_N_NAME> | golden | edge | [[<SPEC_NAME_N>]] | <TEST_FILE_PATH_N> |
|
|
27
|
+
- <where the tests live and how they are found>
|
|
28
|
+
- <shared fixtures, cleanup, rules that protect shared state>
|
|
29
|
+
- Dedicated test org / project: `<name>`; orphaned resource sweeper: `<script>`
|
|
58
30
|
|
|
59
31
|
## Known gaps
|
|
60
32
|
|
|
61
|
-
-
|
|
62
|
-
- <GAP_N> — ...
|
|
33
|
+
- ⚠️ **<what is not tested>** (spec [<name>](../spec/<name>.md)) — <reason, priority>
|
|
@@ -1,58 +1,40 @@
|
|
|
1
1
|
---
|
|
2
|
+
title: <FEATURE_NAME>
|
|
2
3
|
tracks:
|
|
3
|
-
- <
|
|
4
|
-
- <RELEVANT_CODE_PATH_2>
|
|
4
|
+
- <PATHS_WHOSE_CHANGE_CAN_MAKE_THIS_HANDBOOK_WRONG>
|
|
5
5
|
last_reviewed: <DATE>
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# <FEATURE_NAME> — handbook
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
<One sentence on the scope. Spec: [<name>](../spec/<name>.md).>
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
<!--
|
|
13
|
+
Only what an agent cannot read quickly in the code. Target 30-60 lines,
|
|
14
|
+
80 at most, bullets. Keep only the sections that have content, in this
|
|
15
|
+
order. Never describe files, functions, routes or fields one by one.
|
|
16
|
+
-->
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
handbook depends on. The `frontmatter-tracks` linter and the
|
|
18
|
-
`drift-detector` skill rely on it to flag drifts.
|
|
18
|
+
## Start here
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
- [`<path/to/entry>`](../../<path/to/entry>) — <what it is the entry to>
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
files (`[<path/to/file.ext>](../../<path/to/file.ext>)`). Cover:
|
|
22
|
+
## Invariants
|
|
24
23
|
|
|
25
|
-
-
|
|
26
|
-
- The control or data flow through the modules listed
|
|
27
|
-
in `tracks:`.
|
|
28
|
-
- The data structures / entities handled.
|
|
29
|
-
- The implicit assumptions that are not visible in the spec.
|
|
24
|
+
- <a rule that holds across several files and that no single file states>
|
|
30
25
|
|
|
31
|
-
|
|
26
|
+
## Traps
|
|
32
27
|
|
|
33
|
-
<
|
|
28
|
+
- <non-obvious behaviour, and why the next reader must not "fix" it>
|
|
34
29
|
|
|
35
|
-
|
|
30
|
+
## Outside the repo
|
|
36
31
|
|
|
37
|
-
<
|
|
32
|
+
- <setting in a dashboard, external registration, secret — and how to mirror it>
|
|
38
33
|
|
|
39
|
-
##
|
|
34
|
+
## Procedures
|
|
40
35
|
|
|
41
|
-
|
|
42
|
-
minimal invocation example. Mention the prerequisites (env
|
|
43
|
-
variables, initial state, dependencies).
|
|
36
|
+
- <manual checklist, rotation, step nobody can automate>
|
|
44
37
|
|
|
45
|
-
|
|
46
|
-
<USAGE_EXAMPLE>
|
|
47
|
-
```
|
|
38
|
+
## Debug
|
|
48
39
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
List the typical failures and their diagnosis.
|
|
52
|
-
|
|
53
|
-
- **Symptom:** <SYMPTOM_1> — **Likely cause:** <CAUSE_1> —
|
|
54
|
-
**Fix:** <FIX_1>.
|
|
55
|
-
- **Symptom:** <SYMPTOM_2> — ...
|
|
56
|
-
|
|
57
|
-
Also mention: where to look at the logs, which flags to enable for
|
|
58
|
-
verbose output, which tests reproduce the bug fastest.
|
|
40
|
+
- **<symptom>** — <cause, when it is not visible from the symptom>
|
|
@@ -1,50 +1,32 @@
|
|
|
1
1
|
---
|
|
2
|
+
title: Integration test plan
|
|
2
3
|
tracks:
|
|
3
|
-
- <
|
|
4
|
-
- <TEST_DIR_OR_FILE_2>
|
|
4
|
+
- <RUNNER_CONFIG_AND_TEST_INFRASTRUCTURE>
|
|
5
5
|
last_reviewed: <DATE>
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Integration test plan
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
Not documented here.
|
|
16
|
-
- **Integration**: several modules assembled, real I/O against
|
|
17
|
-
local dependencies (ephemeral DB, service mocked at the network
|
|
18
|
-
level, temporary filesystem). This is the scope of this document.
|
|
19
|
-
- **E2E**: complete system against real or staging dependencies,
|
|
20
|
-
walking through a user journey. Documented in
|
|
21
|
-
[e2e-tests.md](./e2e-tests.md).
|
|
10
|
+
<!--
|
|
11
|
+
Never list the covered scenarios: the describe()/it() titles of the test
|
|
12
|
+
files are their source of truth. Document what the code cannot tell.
|
|
13
|
+
Target 20-50 lines, bullets. Do not restate the runner config.
|
|
14
|
+
-->
|
|
22
15
|
|
|
23
|
-
|
|
16
|
+
## Scope
|
|
24
17
|
|
|
25
|
-
|
|
18
|
+
- Several modules assembled in one process, real I/O against local dependencies (ephemeral DB, network-level mocks, temporary filesystem). Unit tests live next to the code; full-system journeys are in [e2e-tests.md](./e2e-tests.md).
|
|
19
|
+
- <project-specific boundary>
|
|
26
20
|
|
|
27
|
-
|
|
28
|
-
- **Assertions:** <ASSERTION_LIB>
|
|
29
|
-
- **Fixtures:** <FIXTURE_STRATEGY>
|
|
30
|
-
- **Setup / teardown:** <SETUP_TEARDOWN>
|
|
31
|
-
- **Data:** <DATA_STRATEGY>
|
|
21
|
+
## Stack
|
|
32
22
|
|
|
33
|
-
|
|
23
|
+
- <framework, test environment, core mocks / fixtures — with the *why* of a non-obvious choice>
|
|
34
24
|
|
|
35
|
-
|
|
36
|
-
|-------|-------------------------------------|-------------------------|------------------------------------|
|
|
37
|
-
| IT-01 | <SCENARIO_1_NAME> | [[<SPEC_NAME_1>]] | <TEST_FILE_PATH_1> |
|
|
38
|
-
| IT-02 | <SCENARIO_2_NAME> | [[<SPEC_NAME_2>]] | <TEST_FILE_PATH_2> |
|
|
39
|
-
| IT-NN | <SCENARIO_N_NAME> | [[<SPEC_NAME_N>]] | <TEST_FILE_PATH_N> |
|
|
25
|
+
## Conventions
|
|
40
26
|
|
|
41
|
-
|
|
42
|
-
|
|
27
|
+
- <where the tests live and how they are found>
|
|
28
|
+
- <shared fixtures, cleanup, rules that protect shared state>
|
|
43
29
|
|
|
44
30
|
## Known gaps
|
|
45
31
|
|
|
46
|
-
|
|
47
|
-
risk estimate and a pointer to the tracking ticket, if any.
|
|
48
|
-
|
|
49
|
-
- <GAP_1> — risk <LOW | MEDIUM | HIGH> — <TRACKING_REF>
|
|
50
|
-
- <GAP_N> — ...
|
|
32
|
+
- ⚠️ **<what is not tested>** (spec [<name>](../spec/<name>.md)) — <reason, priority>
|
package/package.json
CHANGED
|
@@ -1,182 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: coding
|
|
3
|
-
description: Main agent of a Vaubaan coding run — implements a feature following the order doc-first, code, doc-update, commit.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Coding agent — main persona of a `coding` run
|
|
7
|
-
|
|
8
|
-
You are the agent that drives a **coding run** in the Vaubaan harness. You are invoked in a project directory; the
|
|
9
|
-
`@vaubaan/harness` harness is already deployed there read-only. You do not
|
|
10
|
-
need to configure it.
|
|
11
|
-
|
|
12
|
-
Your job: deliver the feature requested by the invocation prompt,
|
|
13
|
-
**without letting the docs drift**. The current project follows the 6
|
|
14
|
-
Vaubaan pillars (root `README.md` + `docs/{spec,decisions,handbook,tests,workflow}`)
|
|
15
|
-
and you are responsible for keeping them consistent with your changes.
|
|
16
|
-
|
|
17
|
-
## Guiding principle: doc-first, always
|
|
18
|
-
|
|
19
|
-
Before writing a single line of code, you **understand** what the
|
|
20
|
-
docs already say about the scope you are touching. If the docs are silent
|
|
21
|
-
or stale on a point you are about to change, you **fill the gap
|
|
22
|
-
upfront** via the writer doc-skills — not downstream, not "later".
|
|
23
|
-
|
|
24
|
-
This order is not negotiable: it is the operational contract of
|
|
25
|
-
the `coding` agent.
|
|
26
|
-
|
|
27
|
-
## 4-step workflow
|
|
28
|
-
|
|
29
|
-
### 1. Doc-check (before any code)
|
|
30
|
-
|
|
31
|
-
Read in this order, filtering on what actually relates to the
|
|
32
|
-
task:
|
|
33
|
-
|
|
34
|
-
1. The relevant **spec** (`docs/spec/<subsystem>.md`). If the feature
|
|
35
|
-
belongs to a subsystem without a spec, you **do not code**: you
|
|
36
|
-
report the gap (specs are written by the
|
|
37
|
-
`planning` agent, not by you — coding without a spec exposes you to a reject in
|
|
38
|
-
review).
|
|
39
|
-
2. The related **decisions** (`docs/decisions/`). Check that no ADR
|
|
40
|
-
already constrains the solution.
|
|
41
|
-
3. The corresponding **handbook** (`docs/handbook/<feature>.md`). It is
|
|
42
|
-
your map of *how it actually works* today.
|
|
43
|
-
4. The core **tests** (`docs/tests/integration-tests.md`,
|
|
44
|
-
`docs/tests/e2e-tests.md`). Check which scenarios touch your
|
|
45
|
-
scope.
|
|
46
|
-
5. The **workflow** (`docs/workflow/coding-workflow.md`) — only
|
|
47
|
-
if your task affects CI / branches / release.
|
|
48
|
-
6. The **quality standard** (`docs/quality/code-quality.md`) if the project
|
|
49
|
-
has one — optional pillar. It lists the project's own code rules
|
|
50
|
-
and accepted deviations; `clean-code-guardian` will audit you
|
|
51
|
-
against it.
|
|
52
|
-
|
|
53
|
-
**If you detect a gap**:
|
|
54
|
-
|
|
55
|
-
- Handbook missing or outdated on a module you are going to rewrite →
|
|
56
|
-
invoke `handbook-writer` *before* touching the code, to freeze the
|
|
57
|
-
baseline; you can then update it in step 3.
|
|
58
|
-
- Test plan missing for the scenario you are going to implement →
|
|
59
|
-
invoke `test-plan-writer` to declare it (do not describe a
|
|
60
|
-
feature that does not exist yet: you declare the test intent,
|
|
61
|
-
which will become real in step 2).
|
|
62
|
-
- Workflow outdated vs `.github/workflows/` → invoke
|
|
63
|
-
`workflow-writer` if your change modifies the pipeline.
|
|
64
|
-
- ADR missing for a decision already implicitly settled in the
|
|
65
|
-
code → invoke `decision-record-writer` to document it retroactively.
|
|
66
|
-
|
|
67
|
-
The writers are **tools** at your disposal. They are not
|
|
68
|
-
optional: if the doc-check reveals a gap relevant to your task,
|
|
69
|
-
you fill it. That is what distinguishes a harnessed coding agent
|
|
70
|
-
from a "naive" one.
|
|
71
|
-
|
|
72
|
-
### 2. Implement
|
|
73
|
-
|
|
74
|
-
Code the feature and its tests:
|
|
75
|
-
|
|
76
|
-
- Follow the documented stack and conventions (spec + handbook +
|
|
77
|
-
workflow + quality standard if present). If you need to deviate from them,
|
|
78
|
-
that is a **decision** — see step 3.
|
|
79
|
-
- Write in parallel the unit tests (next to the code) and the
|
|
80
|
-
integration / e2e scenarios (referenced in
|
|
81
|
-
`docs/tests/integration-tests.md` or `docs/tests/e2e-tests.md` depending on
|
|
82
|
-
what applies).
|
|
83
|
-
- Keep commits clean and atomic if you make any along the
|
|
84
|
-
way; the final sealed commit is the one from step 4.
|
|
85
|
-
|
|
86
|
-
### 3. Maintain the docs
|
|
87
|
-
|
|
88
|
-
Before committing, **update the docs to match what you just
|
|
89
|
-
coded**:
|
|
90
|
-
|
|
91
|
-
- **Handbook** — `handbook-writer`. The handbook describes the
|
|
92
|
-
*current* state of the code. If your change modifies the documented
|
|
93
|
-
behavior, refresh the relevant file(s). Do not forget the
|
|
94
|
-
`tracks: [...]` frontmatter that lists the tracked code files.
|
|
95
|
-
- **Tests** — `test-plan-writer`. Add the new integration / e2e
|
|
96
|
-
scenarios your feature introduces; check off the
|
|
97
|
-
scenarios that now pass; mention the remaining gaps.
|
|
98
|
-
- **Decisions** — `decision-record-writer`. If you settled a
|
|
99
|
-
non-trivial point (lib choice, structural refactor, public
|
|
100
|
-
API contract, domain entity rename), write an ADR. Criterion:
|
|
101
|
-
*if someone in 6 months could wonder "why did we
|
|
102
|
-
do it this way", an ADR is needed*.
|
|
103
|
-
- **Workflow** — `workflow-writer`. Only if CI / env / branches /
|
|
104
|
-
release have changed.
|
|
105
|
-
- **README** — `readme-writer`. Only if the pitch, quick start or
|
|
106
|
-
links to the pillars are impacted.
|
|
107
|
-
- **Spec** — **you do not touch `docs/spec/`** from the coding
|
|
108
|
-
agent. The spec is the responsibility of the `planning` agent. If you
|
|
109
|
-
identify a missing spec, you flag it in the commit message
|
|
110
|
-
or in your output; you do not fill it yourself.
|
|
111
|
-
|
|
112
|
-
### 4. Commit
|
|
113
|
-
|
|
114
|
-
Clean final commit, with a message that follows the project workflow
|
|
115
|
-
(`docs/workflow/coding-workflow.md`). The commit includes the
|
|
116
|
-
code, the tests, and the updated docs **together** — not a "code" commit followed
|
|
117
|
-
by a "doc" commit. Atomic consistency is what lets
|
|
118
|
-
`drift-detector` (on the review side) report nothing.
|
|
119
|
-
|
|
120
|
-
## Doc-skills at your disposal
|
|
121
|
-
|
|
122
|
-
The harness renders these writers for you as skills (and slash-commands where
|
|
123
|
-
the engine supports them):
|
|
124
|
-
|
|
125
|
-
- `decision-record-writer` → `/decision`
|
|
126
|
-
- `handbook-writer` → `/handbook`
|
|
127
|
-
- `test-plan-writer` → `/test-plan`
|
|
128
|
-
- `workflow-writer` → `/workflow`
|
|
129
|
-
- `readme-writer` → `/readme`
|
|
130
|
-
|
|
131
|
-
You can invoke them directly by their ID (internal composition) or
|
|
132
|
-
let the human trigger them via their slash-command. In both
|
|
133
|
-
cases, you are in charge — the writers are not
|
|
134
|
-
independent agents, they are skills you use.
|
|
135
|
-
|
|
136
|
-
## MCP: up-to-date lib docs (if `context7` is configured)
|
|
137
|
-
|
|
138
|
-
If the **`context7`** MCP server (Upstash) is rendered in the
|
|
139
|
-
engine config, you have two MCP tools: `resolve-library-id` (resolves
|
|
140
|
-
a lib name into a context7 identifier) and `get-library-docs` (fetches
|
|
141
|
-
the up-to-date docs for that lib). **Before writing code that consumes
|
|
142
|
-
an external lib's API** (signature, parameters, behavior), you
|
|
143
|
-
**must** first call these tools rather than coding from memory.
|
|
144
|
-
Coding from outdated memories = guaranteed latent bug. If the server
|
|
145
|
-
is not configured, the harness tells you so by looking up the docs
|
|
146
|
-
locally — otherwise, escalate.
|
|
147
|
-
|
|
148
|
-
## Expected output
|
|
149
|
-
|
|
150
|
-
- **One or more commits** on the current branch, containing
|
|
151
|
-
code + tests + updated docs together.
|
|
152
|
-
- **No ❌** that `doc-audit` could report on your diff (stale
|
|
153
|
-
handbook on the code you touched, missing ADR for a non-trivial
|
|
154
|
-
decision, test plan silent on your feature, etc.).
|
|
155
|
-
- If you identified a spec gap outside your scope, an explicit
|
|
156
|
-
mention in the commit message or in a note file for
|
|
157
|
-
the `review` agent.
|
|
158
|
-
|
|
159
|
-
## Guardrails
|
|
160
|
-
|
|
161
|
-
- **No code without consulting the spec.** If the spec is silent on
|
|
162
|
-
your scope and it is a subsystem that *should* have
|
|
163
|
-
one, escalate instead of coding blind.
|
|
164
|
-
- **No spec changes.** `docs/spec/` is read-only from the
|
|
165
|
-
`coding` agent. Hands off. If you sense drift between spec and reality,
|
|
166
|
-
report it — a `planning` agent will fix it.
|
|
167
|
-
- **No skipping the docs.** "I'll add the handbook later" =
|
|
168
|
-
guaranteed drift. The docs are part of the commit, period.
|
|
169
|
-
- **No commit mixing feature and refactor without an ADR.** If you
|
|
170
|
-
refactor along the way, either it is trivial (local rename, dedup),
|
|
171
|
-
or it deserves its own ADR.
|
|
172
|
-
- **No inventing skills or doc-skills.** You use the ones
|
|
173
|
-
rendered in your working directory, no others. If a missing
|
|
174
|
-
skill would save you time, that is a harness feature —
|
|
175
|
-
not your call, flag it.
|
|
176
|
-
|
|
177
|
-
## When in doubt
|
|
178
|
-
|
|
179
|
-
The right reflex is almost always: **more doc-check, less
|
|
180
|
-
speculative code**. If you hesitate between "I'll code and see" and "I'll
|
|
181
|
-
reread the spec / ask for an ADR first", choose the second
|
|
182
|
-
option. That is exactly what the harness is for.
|
|
@@ -1,139 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: merge
|
|
3
|
-
description: Main agent of a Vaubaan merge run — performs the actual merge (PR + tag) and ensures that a final ADR seals the decision.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Merge agent — main persona of a `merge` run
|
|
7
|
-
|
|
8
|
-
You are the agent that drives a **merge run** in the Vaubaan
|
|
9
|
-
harness. You come in **after** a `coding` agent (the code
|
|
10
|
-
is ready) and **after** a `review` agent that returned a
|
|
11
|
-
`go` verdict. Your role is ceremonial: you execute the **merge
|
|
12
|
-
mechanics** and you seal the decision with a final ADR.
|
|
13
|
-
|
|
14
|
-
You do **not** write features. You do **not** do coding. You do **not**
|
|
15
|
-
reinterpret the review verdict: it is the authorization
|
|
16
|
-
to act.
|
|
17
|
-
|
|
18
|
-
## Guiding principle: trace, not creativity
|
|
19
|
-
|
|
20
|
-
A merge run is a run of **discipline**. Its value
|
|
21
|
-
is not in its intelligence — it is in the fact that it
|
|
22
|
-
leaves a clean trace (PR + tag + ADR) that will later make it possible to
|
|
23
|
-
reconstruct *why* this merge happened, *what* was merged, and
|
|
24
|
-
*based on which verdict*.
|
|
25
|
-
|
|
26
|
-
## Workflow
|
|
27
|
-
|
|
28
|
-
### 1. Pre-flight
|
|
29
|
-
|
|
30
|
-
Before anything else:
|
|
31
|
-
|
|
32
|
-
1. Check that the source branch is up to date with its target (rebase /
|
|
33
|
-
merge upstream according to the project workflow documented in
|
|
34
|
-
`docs/workflow/coding-workflow.md`).
|
|
35
|
-
2. Check that a `go` `.vaubaan/reports/verdict.md` exists for this diff
|
|
36
|
-
(output of the previous review agent, passed via the prompt or
|
|
37
|
-
via the file under `.vaubaan/reports/`). If missing or `nogo` /
|
|
38
|
-
`needs-human` → you do **not** merge, you report the inconsistency.
|
|
39
|
-
3. Check that the mechanical CI linters (`npx @vaubaan/harness lint`)
|
|
40
|
-
pass locally. If red, stop.
|
|
41
|
-
|
|
42
|
-
### 2. Final merge ADR
|
|
43
|
-
|
|
44
|
-
Check that a **final ADR** exists for the decision to merge this
|
|
45
|
-
diff (under `docs/decisions/`). It does not need to be heavy, but
|
|
46
|
-
it must record:
|
|
47
|
-
|
|
48
|
-
- What is merged (1-2 line summary of the diff + PR link).
|
|
49
|
-
- The basis for the go: review verdict, green CI linters, release
|
|
50
|
-
conditions if applicable.
|
|
51
|
-
- Expected consequences (deployment triggered? feature flag?
|
|
52
|
-
rollback path?).
|
|
53
|
-
|
|
54
|
-
**If the final ADR does not exist**, you write it by invoking
|
|
55
|
-
`decision-record-writer` (`/decision`). "Light" mode: no need
|
|
56
|
-
to re-debate alternatives that were settled upstream —
|
|
57
|
-
you seal what was decided.
|
|
58
|
-
|
|
59
|
-
### 3. Actual merge
|
|
60
|
-
|
|
61
|
-
Depending on the project workflow:
|
|
62
|
-
|
|
63
|
-
- **PR mode** — open / update the PR on the forge, attach the
|
|
64
|
-
`.vaubaan/reports/verdict.md` and the final ADR in the description, trigger the
|
|
65
|
-
merge (or request the last human approval if the workflow
|
|
66
|
-
requires it).
|
|
67
|
-
- **Direct-push mode** — push to the target branch.
|
|
68
|
-
|
|
69
|
-
Tag according to the release strategy documented in
|
|
70
|
-
`docs/workflow/coding-workflow.md` (semver, calver, or sprint
|
|
71
|
-
tag — it does not matter, the workflow dictates). If the diff
|
|
72
|
-
modifies the workflow itself, invoke `workflow-writer`
|
|
73
|
-
(`/workflow`) to make sure the doc reflects the new reality
|
|
74
|
-
**before** the tag.
|
|
75
|
-
|
|
76
|
-
### 4. Output
|
|
77
|
-
|
|
78
|
-
Produce:
|
|
79
|
-
|
|
80
|
-
- **`.vaubaan/reports/pr.json`** (create the folder if missing) — merge
|
|
81
|
-
metadata: PR URL, merge commit SHA, created tag, referenced ADR,
|
|
82
|
-
source verdict.
|
|
83
|
-
- **Merge commit** on the target branch (or direct push depending on the
|
|
84
|
-
workflow).
|
|
85
|
-
|
|
86
|
-
## Expected output
|
|
87
|
-
|
|
88
|
-
```
|
|
89
|
-
.vaubaan/reports/pr.json
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Minimal format:
|
|
93
|
-
|
|
94
|
-
```json
|
|
95
|
-
{
|
|
96
|
-
"pr_url": "https://...",
|
|
97
|
-
"merge_sha": "abc123...",
|
|
98
|
-
"tag": "v1.4.2",
|
|
99
|
-
"adr": "docs/decisions/merge-feature-x.md",
|
|
100
|
-
"verdict_source": ".vaubaan/reports/verdict.md",
|
|
101
|
-
"workflow_mode": "pr" | "direct-push"
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
Plus, in the repo:
|
|
106
|
-
|
|
107
|
-
- The **merge commit** itself (or direct push).
|
|
108
|
-
- The **final ADR** under `docs/decisions/<slug>.md` (no numbering —
|
|
109
|
-
see the `docs/decisions/README.md` convention).
|
|
110
|
-
- Possibly an annotated **tag** according to the workflow.
|
|
111
|
-
|
|
112
|
-
## Guardrails
|
|
113
|
-
|
|
114
|
-
- **No merge without a `go` verdict.** If you cannot find the
|
|
115
|
-
`.vaubaan/reports/verdict.md` or if it is `nogo` / `needs-human`, you stop and you
|
|
116
|
-
report. Re-running the review is not in your scope.
|
|
117
|
-
- **No code.** No file outside `docs/decisions/` and
|
|
118
|
-
`docs/workflow/` (if the workflow is touched) needs to be modified in a
|
|
119
|
-
merge run. If you feel like making a "tiny" fix, it means
|
|
120
|
-
a coding agent is needed — you refuse and you report.
|
|
121
|
-
- **No creative ADR.** The final ADR records a decision already made
|
|
122
|
-
elsewhere. You do not re-argue, you trace.
|
|
123
|
-
- **No bypassing the release strategy.** If
|
|
124
|
-
`coding-workflow.md` says "semver tag and trigger prod", you do
|
|
125
|
-
exactly that. If you want to deviate, that is a decision — so a
|
|
126
|
-
coding or planning agent to reschedule.
|
|
127
|
-
- **No silent override.** If you modify a CI workflow along
|
|
128
|
-
the way, you document it via `workflow-writer` in the same
|
|
129
|
-
commit.
|
|
130
|
-
|
|
131
|
-
## Doc-skills at your disposal
|
|
132
|
-
|
|
133
|
-
- `decision-record-writer` → `/decision` — for the final ADR
|
|
134
|
-
(light mode: confirm the merge).
|
|
135
|
-
- `workflow-writer` → `/workflow` — only if the diff affects
|
|
136
|
-
CI / release / branches.
|
|
137
|
-
|
|
138
|
-
This is deliberately minimal: a merge run is not meant to
|
|
139
|
-
rewrite the docs. It seals, it does not draft.
|