@warren-dean/code-kit 0.28.0 → 0.30.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/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +31 -0
- package/README.md +17 -9
- package/bin/code-kit.mjs +498 -60
- package/hooks/act.mjs +30 -2
- package/hooks/guard-bash.mjs +59 -25
- package/hooks/lib/adapters/hub/client.mjs +7 -1
- package/hooks/lib/checkout.mjs +78 -1
- package/hooks/lib/checks.mjs +13 -3
- package/hooks/lib/deferrals.mjs +107 -0
- package/hooks/lib/designs.mjs +100 -42
- package/hooks/lib/events.mjs +49 -0
- package/hooks/lib/instructions.mjs +1 -1
- package/hooks/lib/next.mjs +124 -15
- package/hooks/lib/plan.mjs +186 -11
- package/hooks/lib/queue.mjs +61 -12
- package/hooks/lib/regression.mjs +18 -11
- package/hooks/lib/reviews.mjs +43 -2
- package/hooks/lib/rules.mjs +11 -2
- package/hooks/lib/security.mjs +50 -7
- package/hooks/lib/shell.mjs +97 -0
- package/hooks/lib/snapshot.mjs +125 -8
- package/hooks/lib/storymap.mjs +13 -7
- package/hooks/lib/team.mjs +35 -13
- package/hooks/lib/teamfacts.mjs +80 -2
- package/hooks/lib/testfiles.mjs +22 -0
- package/hooks/lib/verify.mjs +55 -11
- package/hooks/lib/worktrees.mjs +25 -3
- package/hooks/mod/board.mjs +12 -1
- package/hooks/mod/loop.mjs +9 -2
- package/hooks/mod/register.mjs +4 -3
- package/hooks/mod/view.mjs +51 -11
- package/package.json +1 -1
- package/skills/design/SKILL.md +4 -4
- package/skills/dispatch/SKILL.md +1 -1
- package/skills/init/SKILL.md +5 -0
- package/skills/next/SKILL.md +1 -0
- package/skills/review/SKILL.md +12 -4
- package/templates/agent.md +2 -1
- package/templates/claude-md.md +2 -0
package/hooks/mod/view.mjs
CHANGED
|
@@ -414,8 +414,12 @@ export function bandLines({
|
|
|
414
414
|
// build themselves, does a finished story wait in the band for their Review or Merge; otherwise the
|
|
415
415
|
// loop prompts the lead (or, under propose, offers the step with Go).
|
|
416
416
|
const loopOff = (check?.harness?.autonomy ?? 'autonomous') === 'off';
|
|
417
|
+
// LOOP-15: a story the lead holds isn't offered for review.
|
|
418
|
+
const heldStories = new Set((nextStep?.deferred ?? []).map((d) => d.story));
|
|
417
419
|
const inReview = loopOff
|
|
418
|
-
? state.lanes
|
|
420
|
+
? state.lanes
|
|
421
|
+
.filter((l) => l.state === 'in review' && !heldStories.has(l.story?.id))
|
|
422
|
+
.map((l) => l.story)
|
|
419
423
|
: [];
|
|
420
424
|
if (inReview.length && !working) {
|
|
421
425
|
const [story] = inReview;
|
|
@@ -455,8 +459,33 @@ export function bandLines({
|
|
|
455
459
|
text: `background agents paused: plan at ${plan.percent}%`,
|
|
456
460
|
actions: [],
|
|
457
461
|
});
|
|
458
|
-
// MQ-2: where the lead doesn't merge, the head of the queue waits for the person's Merge.
|
|
459
|
-
|
|
462
|
+
// MQ-2: where the lead doesn't merge, the head of the queue waits for the person's Merge. HUBR-9: a
|
|
463
|
+
// branch the team provider's drift findings hold (`drift`, from `queue --json`) isn't offered; it's said.
|
|
464
|
+
const inQueue = queue.filter((e) => ['waiting', 'merging'].includes(e.state));
|
|
465
|
+
// MQ-8: the lead's pause of the queue (from `next`, or carried on each entry by `queue --json`);
|
|
466
|
+
// LOOP-15: a branch whose story the lead holds isn't offered either.
|
|
467
|
+
const queuePaused = nextStep?.queuePaused ?? inQueue.find((e) => e.paused)?.paused ?? null;
|
|
468
|
+
const next = queuePaused ? null : inQueue.find((e) => !e.drift?.length && !e.deferred);
|
|
469
|
+
for (const e of inQueue.filter((x) => x.drift?.length && !working))
|
|
470
|
+
lines.push({
|
|
471
|
+
kind: 'drift',
|
|
472
|
+
text: `${e.branch} is held by the drift check: ${e.drift[0].title || e.drift[0].conflictsWith}`,
|
|
473
|
+
actions: [],
|
|
474
|
+
});
|
|
475
|
+
if (queuePaused && !working)
|
|
476
|
+
lines.push({
|
|
477
|
+
kind: 'queuePaused',
|
|
478
|
+
text: `merge queue paused: ${queuePaused.reason}`,
|
|
479
|
+
actions: [],
|
|
480
|
+
});
|
|
481
|
+
const deferred = nextStep?.deferred ?? [];
|
|
482
|
+
if (deferred.length && !working)
|
|
483
|
+
lines.push({
|
|
484
|
+
kind: 'deferred',
|
|
485
|
+
text: `${deferred.length > 1 ? `${deferred.length} stories held: ` : ''}${deferred[0].words ?? `${deferred[0].story} is held: ${deferred[0].reason}`}`,
|
|
486
|
+
deferred,
|
|
487
|
+
actions: [],
|
|
488
|
+
});
|
|
460
489
|
const autonomous = (check?.harness?.autonomy ?? 'autonomous') === 'autonomous';
|
|
461
490
|
// SETUP-2: with no rules on the base yet, the lead puts them there first and then merges.
|
|
462
491
|
const leadMerges = autonomous && (check?.delegatesMerge || check?.firstMerge);
|
|
@@ -1159,11 +1188,15 @@ export function attribution(agentId, agent, check, state) {
|
|
|
1159
1188
|
return { key: agentId, lane, story: named ?? laneStory(lane), background: false };
|
|
1160
1189
|
}
|
|
1161
1190
|
|
|
1162
|
-
/**
|
|
1163
|
-
|
|
1164
|
-
|
|
1191
|
+
/**
|
|
1192
|
+
* The ledger with one request added: entries by agent, story and the model the request ran on (as
|
|
1193
|
+
* Claude Code names it on the step), their tokens summed.
|
|
1194
|
+
*/
|
|
1195
|
+
export function withUsage(ledger, who, usage, model = null) {
|
|
1196
|
+
const named = typeof model === 'string' && model && !/[\r\n]/.test(model) ? model : null;
|
|
1197
|
+
const id = `${who.key}|${who.story ?? ''}${named ? `|${named}` : ''}`;
|
|
1165
1198
|
const t = tokensOf(usage);
|
|
1166
|
-
const was = ledger[id] ?? { ...who, input: 0, output: 0, cache: 0 };
|
|
1199
|
+
const was = ledger[id] ?? { ...who, model: named, input: 0, output: 0, cache: 0 };
|
|
1167
1200
|
return {
|
|
1168
1201
|
...ledger,
|
|
1169
1202
|
[id]: {
|
|
@@ -1176,9 +1209,9 @@ export function withUsage(ledger, who, usage) {
|
|
|
1176
1209
|
}
|
|
1177
1210
|
|
|
1178
1211
|
/**
|
|
1179
|
-
* HUBR-2: the ledger as a report carries it: [{ story, kind, input, output, cache }], each entry's
|
|
1180
|
-
* (lead, lane, reviewer, security-reviewer or background) from who made it and `typeOf(key)`, the
|
|
1181
|
-
* type. Tokens only: no prompt, no message.
|
|
1212
|
+
* HUBR-2: the ledger as a report carries it: [{ story, kind, model, input, output, cache }], each entry's
|
|
1213
|
+
* kind (lead, lane, reviewer, security-reviewer or background) from who made it and `typeOf(key)`, the
|
|
1214
|
+
* agent's type, and the model its requests ran on (report version 6). Tokens only: no prompt, no message.
|
|
1182
1215
|
*/
|
|
1183
1216
|
export function usageForReport(ledger, typeOf = () => null) {
|
|
1184
1217
|
return Object.fromEntries(
|
|
@@ -1196,7 +1229,14 @@ export function usageForReport(ledger, typeOf = () => null) {
|
|
|
1196
1229
|
: 'background';
|
|
1197
1230
|
return [
|
|
1198
1231
|
id,
|
|
1199
|
-
{
|
|
1232
|
+
{
|
|
1233
|
+
story: e.story ?? null,
|
|
1234
|
+
kind,
|
|
1235
|
+
model: e.model ?? null,
|
|
1236
|
+
input: e.input,
|
|
1237
|
+
output: e.output,
|
|
1238
|
+
cache: e.cache,
|
|
1239
|
+
},
|
|
1200
1240
|
];
|
|
1201
1241
|
}),
|
|
1202
1242
|
);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@warren-dean/code-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.30.0",
|
|
4
4
|
"description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Warren Langeveldt",
|
package/skills/design/SKILL.md
CHANGED
|
@@ -5,7 +5,7 @@ description: Design a design story's screens with the person before any of them
|
|
|
5
5
|
|
|
6
6
|
# Design before code
|
|
7
7
|
|
|
8
|
-
A screen is designed and approved before anyone builds it. The design gate refuses a lane writing a screen file until the design register
|
|
8
|
+
A screen is designed and approved before anyone builds it. The design gate refuses a lane writing a screen file until the design register holds its exported design (an entry naming only an artboard in the tool doesn't count), and the plan's screen stories depend on their design story, so nothing is dispatched early. Designing is the lead's work with the person: you propose, they decide.
|
|
9
9
|
|
|
10
10
|
The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
|
|
11
11
|
|
|
@@ -13,7 +13,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
|
|
|
13
13
|
|
|
14
14
|
For each story given (`**Lane:** design` in the plan):
|
|
15
15
|
|
|
16
|
-
- read the requirements it cites and the `## Screens` section of their specs: each screen, what it shows, what the person can do there, and its empty, loading and error states;
|
|
16
|
+
- read the requirements it cites and the `## Screens` section of their specs: each screen, what it shows, what the person can do there, and its empty, loading and error states. A screen is a `###` or `####` heading, a `- **Name** (…)` bullet or a table row, by its exact name, with a `**States:**` line or a States column. If the story designs only some of a spec's screens, name them in the plan with a `**Screens:**` line under the story;
|
|
17
17
|
- read the architecture for the design tool and the folders screens live in, and the principles for the brand, theme and accessibility targets;
|
|
18
18
|
- look at the designs already approved (`design/register.json` and what it links to), so the new screens match them.
|
|
19
19
|
|
|
@@ -74,11 +74,11 @@ For each approved screen, add an entry to the register, naming the code file the
|
|
|
74
74
|
|
|
75
75
|
`story` is this design story. One design can serve several code files, such as the web and the mobile screen: each has its own entry, naming the same states. Committing the register is refused while an entry names a file that isn't there, a hash that isn't the file's, a state with no image, or leaves out a state the spec lists for the screen; `code-kit designs` lists every entry and what's wrong with it.
|
|
76
76
|
|
|
77
|
-
The register is protected by the `design` approval, which is the person's: writing it is refused until they approve, and in a session with the code-kit mod the write waits in the band for their Approve. Give the approval a reason in their words ("bookings list and detail, as shown"). Then commit the designs and the register on `design/st-<n
|
|
77
|
+
The register is protected by the `design` approval, which is the person's: writing it is refused until they approve, and in a session with the code-kit mod the write waits in the band for their Approve. Give the approval a reason in their words ("bookings list and detail, as shown"). Then commit the designs and the register on `design/st-<n>`. Commit each screen as the person approves it: the story reads as in progress until every screen it designs is in the branch's register (or you set its `**Status:**` to `review` in the plan), and then `code-kit next` sends it to review. Review and merge it like the lead's own story. Once it's merged, `code-kit next` dispatches the screen stories that waited on it.
|
|
78
78
|
|
|
79
79
|
## Handing over designs approved before (`--hand-over`)
|
|
80
80
|
|
|
81
|
-
`code-kit next` names register entries whose design is only in a design tool ("6 approved screens are only in paper"). For each, find the artboard the entry names, and ask the person whether it's still the design they approved: the tool's copy may have changed since. Once they confirm, export it as in step 4 and rewrite its entry as in step 5. Then, for each of those screens that's already built, compare the build with the export as the review does (each state's screenshot beside its PNG), and add a fix story to the plan for each difference, citing the screen's requirements.
|
|
81
|
+
`code-kit next` names register entries whose design is only in a design tool ("6 approved screens are only in paper"), and holds every story that builds one of those screens, giving the `design` step with `handOver: true` and the design stories to hand over; a lane's write to such a screen is refused until it's handed over. For each, find the artboard the entry names, and ask the person whether it's still the design they approved: the tool's copy may have changed since. Once they confirm, export it as in step 4 and rewrite its entry as in step 5. Then, for each of those screens that's already built, compare the build with the export as the review does (each state's screenshot beside its PNG), and add a fix story to the plan for each difference, citing the screen's requirements.
|
|
82
82
|
|
|
83
83
|
## 6. Report
|
|
84
84
|
|
package/skills/dispatch/SKILL.md
CHANGED
|
@@ -46,7 +46,7 @@ Commit everything the lanes need first. Each lane branches from the lead's branc
|
|
|
46
46
|
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team claim ST-<n> --lease "<glob>,<glob>"
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
|
|
49
|
+
When the story carries out an intent the team agreed (`code-kit intend`), add `--intent <its number>`, so the team sees which pull request is the intent's. The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
|
|
50
50
|
|
|
51
51
|
One agent per story: never send a running lane agent a second story, or a send-back. A story that goes on (sent back, or handed back at its context limit) gets a fresh agent: first run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" worktrees release <branch>`, which keeps the branch's commits and moves its report to the main checkout, then start the agent as below with the brief, "Read your earlier report first: `.claude/state/reports/<branch with / as _>.md` in the main checkout", and what `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" replay <story> --brief` prints: the story's last commit, the tests last run, what changed since, and what was reconciled, from its event log, which holds them even when the stopped agent wrote no report. A long-lived agent rereads its whole context on every step, which is most of what a build costs.
|
|
52
52
|
|
package/skills/init/SKILL.md
CHANGED
|
@@ -120,6 +120,11 @@ Draft, alongside the config:
|
|
|
120
120
|
- Leave out the template's `Always:` list: it's code-kit's part, which `code-kit instructions --write` adds once the config is written, between its markers.
|
|
121
121
|
- If an agent already exists, keep its content and add only what's missing.
|
|
122
122
|
- Drop the spec-check lines if the config has no `docs.specs`.
|
|
123
|
+
- **The design tool, for reference (HAND-8):** where the architecture or the config names a design tool with an MCP server (Paper, Figma, Pencil), add that server's read-only tools to the `tools:` line of every lane agent that builds screens and of the QA lane's agent, and fill the template's **Design tool** line. Name the tools as this session lists them (`mcp__<server>__<tool>`, the server as it's installed here or in `.mcp.json`), and only the ones that read; never one that writes, exports, opens or switches a file:
|
|
124
|
+
- **Paper:** `get_basic_info`, `get_selection`, `get_children`, `get_tree_summary`, `find_nodes`, `get_node_info`, `get_jsx`, `get_computed_styles`, `get_fill_image`, `get_font_family_info`, `get_tokens`, `get_screenshot`, `get_guide`, `list_resources`, `list_comment_threads`, `get_comment_thread`. Not `write_html`, `create_*`, `update_*`, `set_*`, `delete_*`, `duplicate_nodes`, `move_nodes`, `rename_*`, `arrange_pages`, `finish_working_on_nodes`, `export`, `export_combined_pdf` or `open_file`.
|
|
125
|
+
- **Figma:** its read tools (`get_design_context`, `get_metadata`, `get_screenshot`, `get_variable_defs`, `get_code_connect_map`, and `get_code` or `get_image` where the server has them). Nothing that writes to the file.
|
|
126
|
+
- **Pencil, or another tool:** the tools whose names and descriptions say they only read (`get_…`, `list_…`, `find_…`, screenshots, snapshots); leave out any that edits, creates or saves. When it isn't clear, leave it out and say so.
|
|
127
|
+
The lanes still build from the register's exported files: they're the approved record, which the gate and the review hold the build to; the tool's live copy may have changed since, so it's for what the export can't carry (how parts relate, other artboards, interactions).
|
|
123
128
|
- **A security reviewer:** write `.claude/agents/security-reviewer.md` from `${CLAUDE_PLUGIN_ROOT}/templates/security-reviewer.md`, in the same approval as the lane agents, whenever the product handles sign-in, personal data, payments, input from outside (forms, APIs, webhooks, uploads) or secrets. That's almost every product; leave it out only for one with none of these, such as a static site or a local tool with no accounts, and say why. It is a reviewer, not a lane: no entry in `lanes`, no paths, and only read-only tools (Read, Grep, Glob, and Bash for commands that change nothing), so the hooks treat it as read-only too. Fill it in from the docs (or the code, for brownfield):
|
|
124
129
|
- what's sensitive, who might attack it and the trust boundaries, from the specs' `## Threat model` sections (brownfield, or specs without one: from the data the code stores and the routes it exposes, as a question to the person);
|
|
125
130
|
- the spec files it reads;
|
package/skills/next/SKILL.md
CHANGED
|
@@ -30,6 +30,7 @@ It returns `step`, `why`, `args`, `then` (steps that can follow straight after)
|
|
|
30
30
|
| A lane waits on a request you decide | `decide`: approve it, or answer with an alternative |
|
|
31
31
|
| Stories finished on their branches | `review`, then `dispatch` what's ready |
|
|
32
32
|
| Design stories ready (`**Lane:** design`) | `design`, then `dispatch` what needs no design |
|
|
33
|
+
| Ready stories whose screens' designs are only in the tool | `design` with `handOver: true`: `--hand-over` first |
|
|
33
34
|
| Stories ready | `dispatch` |
|
|
34
35
|
| The lead's own stories ready (`**Lane:** lead`) | `lead`: the lead builds them itself |
|
|
35
36
|
| Stories being built, nothing else can start | wait |
|
package/skills/review/SKILL.md
CHANGED
|
@@ -28,13 +28,14 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" verify --base <base>
|
|
|
28
28
|
|
|
29
29
|
- that every protected change is in the approval log, which is append-only;
|
|
30
30
|
- new layer violations, and a baseline that grew;
|
|
31
|
-
- screens without an approved design;
|
|
31
|
+
- screens without an approved design, or with one only in the design tool;
|
|
32
|
+
- for a lane's branch that builds screens, each approved state the review hasn't yet compared and recorded ("Builds compared with their designs"): it lists the comparisons step 3 still owes, and clears as you record each screenshot, so it isn't a reason on its own to send the branch back;
|
|
32
33
|
- committed secrets;
|
|
33
34
|
- tests weakened (deleted, skipped or focused, cut down, or a snapshot rewritten) without the person's `tests` approval in the log;
|
|
34
35
|
- for a fix (its story has `**Fixes:**`, or the branch is `<lane>/fix-…`), that its tests fail without the fix, as the bug, and pass with it;
|
|
35
36
|
- the project's checks for the changed files.
|
|
36
37
|
|
|
37
|
-
Any problem it reports means the branch goes back. Don't fix a lane's code yourself; the lead doesn't write lane paths.
|
|
38
|
+
Any other problem it reports means the branch goes back. Don't fix a lane's code yourself; the lead doesn't write lane paths.
|
|
38
39
|
|
|
39
40
|
## 3. Check the work against the story
|
|
40
41
|
|
|
@@ -48,7 +49,14 @@ Read the story and every requirement it cites. Then start from what's already be
|
|
|
48
49
|
- **Its journeys still pass end to end:** where the project has a QA lane, run the end-to-end suites that cover this story's requirements (the qa lane's command, filtered to them) against the branch. A journey that broke fails the review, even when the story's own tests pass. A story the QA lane delivered is reviewed the same way: each journey's test proves the requirements it cites, through the real screens and services, with no mocked responses.
|
|
49
50
|
- **The spec-check report matches:** its table has no row still `missing` or `conflicts` without an answer, and its questions were answered, not guessed.
|
|
50
51
|
- **Only the story:** changes beyond the story (refactors elsewhere, other stories' requirements) are sent back, or split into their own story. A new dependency is yours to judge, as in `/code-kit:decide`: the story's requirements need it, nothing the project has does the job, and it fits the principles and the layer. Only what crosses a guardrail (the spec, a contract, the architecture) is the person's call.
|
|
51
|
-
- **Built to its design:** for a story that builds screens, `code-kit designs ST-<n>` lists each screen's approved states. Take a screenshot of each built state at the design's viewport (the project's end-to-end runner, or a headless browser) and set it beside the state's PNG. A missing state or a different layout is a blocker, naming the state and its design file; different copy or components fail it too; spacing within the design system's scale is a nit.
|
|
52
|
+
- **Built to its design:** for a story that builds screens, `code-kit designs ST-<n>` lists each screen's approved states. Take a screenshot of each built state at the design's viewport (the project's end-to-end runner, or a headless browser) as a PNG, and set it beside the state's PNG. A missing state or a different layout is a blocker, naming the state and its design file; different copy or components fail it too; spacing within the design system's scale is a nit. Record each screenshot you compared, whatever the verdict:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" designs evidence ST-<n> <screen file> <state> <screenshot.png>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
It's refused when the screenshot isn't a PNG at the design's viewport (1x to 4x); take it again at that size. `verify`, and the merge queue, report every approved state of the branch's screens with no screenshot recorded since the screen last changed, so a branch that moves after your review is compared again. A state the build can't serve yet (the contract has no field for what the design shows) goes in the report with what's missing, and you add the story that provides it, rather than leaving a gap nobody sees.
|
|
59
|
+
|
|
52
60
|
- **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
|
|
53
61
|
- **Standards kept:** `code-kit standards --for <changed files>` lists the project's standards for those files' layers. Check each changed file against the ones marked `checked` (the hooks already refuse what an `enforced` one names). A broken required standard sends the branch back, naming the standard's id and where; a broken recommended one is a concern; advice is at most a nit.
|
|
54
62
|
|
|
@@ -78,7 +86,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
|
|
|
78
86
|
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue add <branch>
|
|
79
87
|
```
|
|
80
88
|
|
|
81
|
-
Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. The queue records the commit your review passed and merges exactly that commit. A branch that moves on after your review leaves the queue: review it again, then queue it again. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree. Where the base's rules set `branches.publish`, the merge also reaches the remote's base on its own: pushed, or as a pull request code-kit opens from `code-kit/publish-<base>` (and merges, where pushing the base is delegated to you). Never merge a story into another branch to get it there: `code-kit publish --delegated` tries again when GitHub held it back. A branch that breaks the base merged on its own (a new API whose callers another story updates) is queued with the branches it lands with: `queue add <branch> --with <other>`. It waits in the queue, without asking for review again, until they're reviewed and queued too, and then they're verified and merged as one.
|
|
89
|
+
Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. The queue records the commit your review passed and merges exactly that commit. A branch that moves on after your review leaves the queue: review it again, then queue it again. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree. Where the base's rules set `branches.publish`, the merge also reaches the remote's base on its own: pushed, or as a pull request code-kit opens from `code-kit/publish-<base>` (and merges, where pushing the base is delegated to you). Never merge a story into another branch to get it there: `code-kit publish --delegated` tries again when GitHub held it back. A branch that breaks the base merged on its own (a new API whose callers another story updates) is queued with the branches it lands with: `queue add <branch> --with <other>`. It waits in the queue, without asking for review again, until they're reviewed and queued too, and then they're verified and merged as one. In a team whose provider checks pushes for drift, a branch with an open finding at the level the provider's setting names waits in its place too, and the queue goes on with the next: `queue` and `next` say which finding and that the tech lead decides. It clears when the finding is resolved on the provider, or a push fixes what it found; never merge around it.
|
|
82
90
|
|
|
83
91
|
- **Send back.** List each problem, where it is, and what "fixed" looks like, with the requirement or the standard's id it breaks. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
|
|
84
92
|
|
package/templates/agent.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: {{agent}}
|
|
3
3
|
description: {{what this lane builds, in one sentence}} Use for {{the paths or kinds of work it owns}}.
|
|
4
|
-
tools: Read, Grep, Glob, Edit, Write, Bash
|
|
4
|
+
tools: Read, Grep, Glob, Edit, Write, Bash{{, the design tool's read-only MCP tools, for a lane that builds screens and the QA lane (init, HAND-8)}}
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
You are the {{lane}} engineer for this repository.
|
|
@@ -11,6 +11,7 @@ You are the {{lane}} engineer for this repository.
|
|
|
11
11
|
**Specs:** {{the spec files this lane reads}}
|
|
12
12
|
**Skills to use:** spec-check{{, every project skill whose recipe touches this lane's paths}}
|
|
13
13
|
**Prove your work with:** `{{the command that proves this lane's work}}`
|
|
14
|
+
{{if the lane builds screens or tests them, and the architecture names a design tool with an MCP server}}**Design tool (reference only):** you can read {{the tool}} through its read-only tools. Build to the exported files the design register names: they're the approved design, which the gate and the review hold your screen to. The tool's copy may have changed since it was approved; use it only for what the export can't show.{{end}}
|
|
14
15
|
|
|
15
16
|
Lane rules:
|
|
16
17
|
{{- one line per rule the docs set for this lane}}
|
package/templates/claude-md.md
CHANGED
|
@@ -30,6 +30,8 @@ The build runs from the specs in `{{docs.specs}}` and the stories in `{{docs.pla
|
|
|
30
30
|
|
|
31
31
|
{{if ci}}Pull requests run `code-kit verify`, and it must pass before a person merges to a protected branch.{{end}}
|
|
32
32
|
|
|
33
|
+
When you mean to leave a story alone for a while (it waits on something outside the build, or on a date), hold it rather than letting the loop ask about it again: `code-kit defer <story> --reason "…" [--until <date>]`, and `code-kit defer release <story>` when it can go on. `code-kit queue pause --reason "…"` holds the whole merge queue the same way, until `code-kit queue resume`.
|
|
34
|
+
|
|
33
35
|
A story reaches the base only through the merge queue: never merge a story's branch into another branch with git. Where the remote's base only moves through pull requests, `"branches.publish": "pull-request"` has code-kit open them after each merge. The merge queue checks each story before it merges, so the project's full CI runs on its release branches, not on every merge. Releasing is the person's decision: when they ask for a release, cut it with `code-kit release <version>`, which branches `release/<version>` from the base and pushes it, and the full CI runs there once. Never cut one unasked. `code-kit ci check` says what in the project's workflows still runs per story, and `code-kit ci usage` what the project spent on GitHub Actions.
|
|
34
36
|
|
|
35
37
|
Changing the rules means editing `.claude/code-kit.json` (the lead only), then running the `code-kit:check` skill.
|