@warren-dean/code-kit 0.30.1 → 0.31.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 +29 -0
- package/README.md +38 -32
- package/bin/code-kit.mjs +77 -15
- package/hooks/guard-bash.mjs +94 -27
- package/hooks/guard-paths.mjs +2 -1
- package/hooks/lib/adapters/context-graph.mjs +3 -0
- package/hooks/lib/adapters/index.mjs +1 -0
- package/hooks/lib/checkout.mjs +20 -4
- package/hooks/lib/config.mjs +36 -2
- package/hooks/lib/dependencies.mjs +4 -1
- package/hooks/lib/harness.mjs +13 -2
- package/hooks/lib/instructions.mjs +3 -0
- package/hooks/lib/next.mjs +9 -4
- package/hooks/lib/plan.mjs +12 -6
- package/hooks/lib/queue.mjs +97 -12
- package/hooks/lib/regression.mjs +14 -1
- package/hooks/lib/rules.mjs +52 -7
- package/hooks/lib/shell.mjs +40 -0
- package/hooks/lib/worktrees.mjs +5 -3
- package/hooks/mod/view.mjs +2 -2
- package/package.json +1 -1
- package/skills/decide/SKILL.md +2 -0
- package/skills/design/SKILL.md +2 -0
- package/skills/init/SKILL.md +3 -3
- package/skills/next/SKILL.md +2 -0
- package/skills/review/SKILL.md +2 -2
- package/skills/spec-design/SKILL.md +2 -0
- package/templates/claude-md.md +5 -2
package/hooks/lib/regression.mjs
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// WHO-2), the person's otherwise and always on the lead's own. The commit hook
|
|
5
5
|
// refuses a weakening commit; verify finds what a branch weakened, from git.
|
|
6
6
|
import { execFileSync, spawnSync } from 'node:child_process';
|
|
7
|
-
import { existsSync, readFileSync, rmSync } from 'node:fs';
|
|
7
|
+
import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
8
8
|
import { join } from 'node:path';
|
|
9
9
|
import { freshCheckout } from './checkout.mjs';
|
|
10
10
|
import { runChecks } from './checks.mjs';
|
|
@@ -227,6 +227,9 @@ const UNREACHABLE =
|
|
|
227
227
|
const ASSERTED =
|
|
228
228
|
/AssertionError|AssertionFailedError|Expected:|Received:|expected .+ to |toBe|toEqual|assert\w* failed|^\s*--- FAIL|Error: expect\(/m;
|
|
229
229
|
|
|
230
|
+
// What a test file holds to break it: unbalanced, so no language's parser takes it.
|
|
231
|
+
const UNPARSEABLE = 'broken on purpose by code-kit, to see whether a check runs this test (\n';
|
|
232
|
+
|
|
230
233
|
/** The names a failure says can't be reached: quoted ones on its unreachable lines. */
|
|
231
234
|
function missingNames(output) {
|
|
232
235
|
const names = new Set();
|
|
@@ -326,6 +329,16 @@ export function proveFix({ root, from, base, changed, config, fix }) {
|
|
|
326
329
|
`${what}, but its tests (${tests.join(', ')}) pass without the fix's other changes, and fail without it only because they load test code the fix adds (${added.join(', ')}), which the base never had. A test that goes through the code the fix changed fails on an assertion when the bug is there: write that one. If the fix is only in the tests and their helpers, keep the branch to test files.`,
|
|
327
330
|
];
|
|
328
331
|
}
|
|
332
|
+
if (!without) {
|
|
333
|
+
// A check can pass without running a test at all (its runner's config leaves the file out). Broken
|
|
334
|
+
// on purpose, a test it runs fails: one that still passes was never run, so it shows nothing.
|
|
335
|
+
for (const f of tests) writeFileSync(join(dir, f), UNPARSEABLE);
|
|
336
|
+
const { failure: broken } = runChecks(strict, tests, dir, actor);
|
|
337
|
+
if (!broken)
|
|
338
|
+
return [
|
|
339
|
+
`${what}, but the checks covering its tests (${covering.map((c) => c.name).join(', ')}) pass even with them broken, so they don't run them (${tests.join(', ')}), and code-kit can't tell whether they fail without the fix. Give the tests a check that runs them: where the test runner's default config leaves them out, a check that runs them with the config that includes them.`,
|
|
340
|
+
];
|
|
341
|
+
}
|
|
329
342
|
if (!without)
|
|
330
343
|
return [
|
|
331
344
|
`${what}, but its tests (${tests.join(', ')}) also pass without the fix, so they don't prove the bug and it can come back. Write a test that fails on ${base} and passes here.`,
|
package/hooks/lib/rules.mjs
CHANGED
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
// - any other subagent (research, planning, review) is read-only, but for the paths any actor may write
|
|
6
6
|
// (a card or a decision it records, code-kit's own state);
|
|
7
7
|
// - the main session in a worktree with a .lane file acts as that lane (a person running a lane);
|
|
8
|
-
// - the main session otherwise is the lead, who writes the lead's paths and delegates the rest
|
|
8
|
+
// - the main session otherwise is the lead, who writes the lead's paths and delegates the rest;
|
|
9
|
+
// - a fork of the session (Claude Code's `fork` agent) is the session it was forked from.
|
|
9
10
|
// Protected paths are recorded in the approval log whenever they are committed; only the lead may
|
|
10
11
|
// write them without a person's approval.
|
|
11
12
|
//
|
|
@@ -31,6 +32,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
|
|
|
31
32
|
import { fileURLToPath } from 'node:url';
|
|
32
33
|
import { DEPENDENCY_APPROVAL, isDependencyFile } from './dependencies.mjs';
|
|
33
34
|
import { globToRegExp, literalPath, matchesAny } from './glob.mjs';
|
|
35
|
+
import { CONFIG_FILE } from './config.mjs';
|
|
34
36
|
import { noteFor } from './standards.mjs';
|
|
35
37
|
|
|
36
38
|
export const APPROVAL_LOG = '.claude/approval-log.jsonl';
|
|
@@ -88,7 +90,9 @@ export const delegateCommand = (names, lane) =>
|
|
|
88
90
|
export function leadDecides(name, config, actor) {
|
|
89
91
|
const rules = config?.approvals?.delegate;
|
|
90
92
|
if (!rules) return false;
|
|
91
|
-
|
|
93
|
+
// VIBE-2: under vibe, on the lead's own branches too.
|
|
94
|
+
if (name === 'tests')
|
|
95
|
+
return rules.tests === true && (actor?.kind === 'lane' || rules.own === true);
|
|
92
96
|
if (String(name).startsWith(DEPENDENCY_APPROVAL)) return Boolean(rules.dependencies);
|
|
93
97
|
return (rules.protected ?? []).includes(name);
|
|
94
98
|
}
|
|
@@ -105,6 +109,29 @@ export const leadNeedsApproval = (name, config) =>
|
|
|
105
109
|
Boolean(config?.approvals?.delegate?.merge) &&
|
|
106
110
|
!leadDecides(name, config, { kind: 'lead' });
|
|
107
111
|
|
|
112
|
+
/**
|
|
113
|
+
* Whether code-kit is being set up in `root`: its config is in the checkout, not ignored, and no commit
|
|
114
|
+
* the repository has ever held it. The person approves the setup as init shows it, the specs, standards
|
|
115
|
+
* and design register it protects included, so until the commit that switches code-kit on the lead
|
|
116
|
+
* writes and commits them with no approval of their own. Once any commit has held the config it never
|
|
117
|
+
* is again, even after a commit takes the config away.
|
|
118
|
+
*/
|
|
119
|
+
export function beforeSetup(root) {
|
|
120
|
+
const git = (...args) => {
|
|
121
|
+
try {
|
|
122
|
+
return execFileSync('git', ['-C', root, ...args], {
|
|
123
|
+
encoding: 'utf8',
|
|
124
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
125
|
+
});
|
|
126
|
+
} catch {
|
|
127
|
+
return null;
|
|
128
|
+
}
|
|
129
|
+
};
|
|
130
|
+
if (!existsSync(join(root, CONFIG_FILE))) return false;
|
|
131
|
+
if (git('check-ignore', '-q', CONFIG_FILE) !== null) return false;
|
|
132
|
+
return git('log', '--all', '--format=%H', '-1', '--', CONFIG_FILE) === '';
|
|
133
|
+
}
|
|
134
|
+
|
|
108
135
|
/** HELM-2: whose decision approvals `names` are: the lead's when it may grant every one, else the person's. */
|
|
109
136
|
export const decidedBy = (names, config, actor) =>
|
|
110
137
|
[names].flat().every((n) => leadDecides(n, config, actor)) ? 'lead' : 'person';
|
|
@@ -287,13 +314,22 @@ export function sessionRoot(input, project = projectDir()) {
|
|
|
287
314
|
return root && projectWorktrees(project).includes(root) ? root : null;
|
|
288
315
|
}
|
|
289
316
|
|
|
317
|
+
/**
|
|
318
|
+
* Claude Code's fork: a copy of the session's own conversation, working on for it in the background. It
|
|
319
|
+
* isn't another agent, so it's the session it was forked from (the lead, or a person's lane), with the
|
|
320
|
+
* same rights.
|
|
321
|
+
*/
|
|
322
|
+
export const FORK_AGENT = 'fork';
|
|
323
|
+
export const subagentOf = (input) =>
|
|
324
|
+
input.agent_type && input.agent_type !== FORK_AGENT ? input.agent_type : null;
|
|
325
|
+
|
|
290
326
|
/**
|
|
291
327
|
* The checkout whose changes are this actor's own. A subagent works where its cwd is (often its own
|
|
292
328
|
* worktree). The main session owns the checkout it was opened in, even when its shell has wandered
|
|
293
329
|
* into an agent's worktree, whose in-progress edits are that agent's, not the lead's.
|
|
294
330
|
*/
|
|
295
331
|
export function actorRoot(input, project = projectDir()) {
|
|
296
|
-
if (input
|
|
332
|
+
if (subagentOf(input)) return sessionRoot(input, project);
|
|
297
333
|
return worktreeRoot(project) ?? project;
|
|
298
334
|
}
|
|
299
335
|
|
|
@@ -313,7 +349,7 @@ export function currentBranch(root) {
|
|
|
313
349
|
export function actorFor(input, root, config) {
|
|
314
350
|
// OWN-1: the session it acts in, whose decisions what it's refused become.
|
|
315
351
|
const session = input.session_id ?? null;
|
|
316
|
-
const agent = input
|
|
352
|
+
const agent = subagentOf(input);
|
|
317
353
|
if (agent) {
|
|
318
354
|
const lane = Object.keys(config.lanes).find((l) => config.lanes[l].agent === agent);
|
|
319
355
|
return lane
|
|
@@ -810,7 +846,9 @@ export function writeProblem(actor, rel, root, config) {
|
|
|
810
846
|
// The lead writes protected files without an approval where the person merges: they review them in
|
|
811
847
|
// the pull request, and every committed change is in the audit log. Where the lead merges, what the
|
|
812
848
|
// person keeps needs their approval (WHO-1). Anyone else needs an approval as well.
|
|
813
|
-
const leadFree =
|
|
849
|
+
const leadFree =
|
|
850
|
+
actor.kind === 'lead' &&
|
|
851
|
+
(!leadNeedsApproval(guarded?.approval, config) || (guarded && beforeSetup(root)));
|
|
814
852
|
if (guarded && !leadFree && !approval(root, guarded.approval, actor)) {
|
|
815
853
|
recordRequest(root, actor, guarded.approval, rel, guarded.why);
|
|
816
854
|
const who =
|
|
@@ -926,11 +964,18 @@ function specCheckProblem(rel, root) {
|
|
|
926
964
|
}
|
|
927
965
|
if (rel === report) return null;
|
|
928
966
|
// In the worktree, or in the main checkout, where it's kept when a worktree goes (#55).
|
|
967
|
+
// A report without the table is named as such: the lane wrote one, and only its table is missing.
|
|
968
|
+
let untabled = false;
|
|
929
969
|
const read = (dir) => {
|
|
930
970
|
const file = join(dir, report);
|
|
931
|
-
|
|
971
|
+
if (!existsSync(file)) return false;
|
|
972
|
+
if (/\|\s*Requirement\s*\|/i.test(readFileSync(file, 'utf8'))) return true;
|
|
973
|
+
untabled = true;
|
|
974
|
+
return false;
|
|
932
975
|
};
|
|
933
976
|
if (read(root) || read(projectWorktrees(root)[0] ?? root)) return null;
|
|
977
|
+
if (untabled)
|
|
978
|
+
return `${report} has no requirement table: the gate looks for the table's header row, which starts \`| Requirement |\` (that word, not an abbreviation), as the spec-check skill writes it. Rewrite the table with that header, one row per requirement, then continue.`;
|
|
934
979
|
return `Run the spec-check skill before writing code on this branch. Save its report (the requirement table, questions and recommendation) to ${report}, then continue.`;
|
|
935
980
|
}
|
|
936
981
|
|
|
@@ -958,5 +1003,5 @@ export function screenProblem(rel, root, config) {
|
|
|
958
1003
|
s.source?.tool ?? String(s.design ?? '').match(/^([a-z][\w-]*):/i)?.[1] ?? 'the design tool';
|
|
959
1004
|
return `${rel} is a screen, and its approved design${s.screen ? ` (${s.screen})` : ''} is only in ${tool}, not as files a lane can build from, so it can't be built yet.\nThe lead hands it over first with /code-kit:design --hand-over, which exports every state into design/ and rewrites its entry in ${gate.register}; then build it from those files. Until then, write a change request for the lead and work on what doesn't need the screen.`;
|
|
960
1005
|
}
|
|
961
|
-
return `${rel} is a screen, and its design is not approved yet.\n${gate.howTo}\nOnce a person approves it, the lead adds { "file": "${rel}", ... } to ${gate.register}.`;
|
|
1006
|
+
return `${rel} is a screen, and its design is not approved yet.\n${gate.howTo}\nOnce a person approves it, the lead adds { "file": "${rel}", ... } to ${gate.register}.\nIf this file draws no screen (a file router's hook, API route or middleware), the design gate's screens are too wide: hand the lead a change request to leave it out with the screen's "not" in designGate.screens, and work on what doesn't need it meanwhile.`;
|
|
962
1007
|
}
|
package/hooks/lib/shell.mjs
CHANGED
|
@@ -119,6 +119,13 @@ const READERS = [
|
|
|
119
119
|
/^(?!.*\s(?:-[a-zA-Z]*o|--output\b|--compress-program\b))sort(?:\s|$)/,
|
|
120
120
|
];
|
|
121
121
|
|
|
122
|
+
// code-kit's own commands that only read and print: what the config says, who owns a path, the
|
|
123
|
+
// imports, a requirement's trail, the build's state, the next step and the approved designs (not their
|
|
124
|
+
// `evidence`, which records a screenshot), with nothing written but code-kit's own state.
|
|
125
|
+
const CODE_KIT_READS = new RegExp(
|
|
126
|
+
String.raw`^(?!.*\s--write\b)${CODE_KIT}\s+(?:check|who|unowned|diff|graph|trace|adapters|status|next|designs(?!\s+evidence\b))(?:\s|$)`,
|
|
127
|
+
);
|
|
128
|
+
|
|
122
129
|
/** A command's words, quotes taken off. */
|
|
123
130
|
const wordsOf = (text) =>
|
|
124
131
|
(text.match(/'[^']*'|"(?:\\.|[^"\\])*"|\S+/g) ?? []).map((w) =>
|
|
@@ -189,6 +196,7 @@ export function readsOnly(cmd) {
|
|
|
189
196
|
parts.length > 0 &&
|
|
190
197
|
parts.every(({ text, code: c }) => {
|
|
191
198
|
if (READERS.some((re) => re.test(c))) return true;
|
|
199
|
+
if (CODE_KIT_READS.test(text)) return true;
|
|
192
200
|
if (/^sed(?:\s|$)/.test(c)) return sedPrints(text);
|
|
193
201
|
if (/^awk(?:\s|$)/.test(c)) return awkPrints(text);
|
|
194
202
|
if (/^uniq(?:\s|$)/.test(c)) return uniqPrints(text);
|
|
@@ -197,6 +205,38 @@ export function readsOnly(cmd) {
|
|
|
197
205
|
);
|
|
198
206
|
}
|
|
199
207
|
|
|
208
|
+
// What could change what a later command in the line runs: a function or alias defined, a variable
|
|
209
|
+
// set (PATH among them), a file sourced, a shell option.
|
|
210
|
+
const REDEFINES =
|
|
211
|
+
/(?:^|[;&|\n(]\s*)(?:[\w.-]+\s*\(\s*\)|function\s|alias\s|unalias\s|source\s|\.\s|hash\s|enable\s|builtin\s|set\s|setopt\s|shopt\s|unset\s|export\s|typeset\s|declare\s|local\s|readonly\s|[A-Za-z_]\w*=)/;
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* The parts of `cmd` that name `pattern`, each a pipeline (`a | b`) of its own, that don't only read
|
|
215
|
+
* (readsOnly): what a rule for a file only reads may hold. A line with a heredoc, or one that could
|
|
216
|
+
* change what its commands run (REDEFINES), is one part, judged whole.
|
|
217
|
+
*/
|
|
218
|
+
export function unreadNames(cmd, pattern) {
|
|
219
|
+
const read = withoutHarmlessRedirects(cmd);
|
|
220
|
+
const code = codeOf(read);
|
|
221
|
+
if (!pattern.test(cmd)) return [];
|
|
222
|
+
if (/<</.test(cmd) || REDEFINES.test(code)) return readsOnly(cmd) ? [] : [cmd];
|
|
223
|
+
const text = withoutHeredocs(read);
|
|
224
|
+
const parts = [];
|
|
225
|
+
let start = 0;
|
|
226
|
+
for (let i = 0; i <= code.length; i++) {
|
|
227
|
+
const two = code.slice(i, i + 2);
|
|
228
|
+
const end = i === code.length || code[i] === ';' || code[i] === '\n';
|
|
229
|
+
const andOr = two === '&&' || two === '||';
|
|
230
|
+
const background = code[i] === '&' && !andOr && code[i - 1] !== '&' && code[i - 1] !== '>';
|
|
231
|
+
if (end || andOr || background) {
|
|
232
|
+
parts.push(text.slice(start, i));
|
|
233
|
+
start = i + (andOr ? 2 : 1);
|
|
234
|
+
if (andOr) i++;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
return parts.filter((p) => pattern.test(p) && !readsOnly(p));
|
|
238
|
+
}
|
|
239
|
+
|
|
200
240
|
// What may come before a command it runs: a package runner (`npx`, `pnpm exec`, `uv run`…) or a wrapper
|
|
201
241
|
// (`xargs`, `nice`, `timeout 60`), so a rule naming the command finds it there too.
|
|
202
242
|
const WRAPPER = String.raw`(?:(?:npx|bunx|pnpx)(?:\s+-\S+)*\s+|(?:pnpm|yarn|bun)\s+(?:(?:exec|dlx|x|run)\s+)?(?:-\S+\s+)*|npm\s+(?:exec|x|run)\s+(?:--\s+)?|(?:uv|poetry|pipenv)\s+run\s+|(?:xargs|nice|nohup|time|command|exec)(?:\s+-\S+)*\s+|timeout\s+(?:-\S+\s+)*\S+\s+)`;
|
package/hooks/lib/worktrees.mjs
CHANGED
|
@@ -161,12 +161,14 @@ export const BUSY_MS = 3 * 60_000;
|
|
|
161
161
|
/**
|
|
162
162
|
* LEAN-6: whether a lane agent is still at work on a worktree's story, by the story's event log (spec
|
|
163
163
|
* 26): its lane's last act is still open, or came within BUSY_MS, with no hand-back or stop after it. Releasing
|
|
164
|
-
* a worktree under a running agent takes its git away mid-step.
|
|
164
|
+
* a worktree under a running agent takes its git away mid-step. Only the branch's own lane counts: the
|
|
165
|
+
* lead's helpers (a reviewer, a security reviewer) act on the story too, but never commit on its branch.
|
|
165
166
|
*/
|
|
166
167
|
export function agentBusy(root, w, now = Date.now()) {
|
|
167
|
-
if (!w.story) return false;
|
|
168
|
+
if (!w.story || !w.branch?.includes('/')) return false;
|
|
169
|
+
const lane = w.branch.split('/')[0];
|
|
168
170
|
const last = readEvents(root, w.story)
|
|
169
|
-
.filter((e) => e.actor
|
|
171
|
+
.filter((e) => e.actor === lane && e.agent)
|
|
170
172
|
.at(-1);
|
|
171
173
|
if (!last || ['handback', 'stopped'].includes(last.kind)) return false;
|
|
172
174
|
return last.phase === 'start' || now - Date.parse(last.at) < BUSY_MS;
|
package/hooks/mod/view.mjs
CHANGED
|
@@ -486,7 +486,7 @@ export function bandLines({
|
|
|
486
486
|
deferred,
|
|
487
487
|
actions: [],
|
|
488
488
|
});
|
|
489
|
-
const autonomous = (check?.harness?.autonomy ?? 'autonomous')
|
|
489
|
+
const autonomous = ['autonomous', 'vibe'].includes(check?.harness?.autonomy ?? 'autonomous');
|
|
490
490
|
// SETUP-2: with no rules on the base yet, the lead puts them there first and then merges.
|
|
491
491
|
const leadMerges = autonomous && (check?.delegatesMerge || check?.firstMerge);
|
|
492
492
|
if (next && !leadMerges && !working)
|
|
@@ -996,7 +996,7 @@ export function approvalsText(requests) {
|
|
|
996
996
|
|
|
997
997
|
export const SETTINGS_ID = 'code-kit-settings';
|
|
998
998
|
const CHOICES = {
|
|
999
|
-
autonomy: ['autonomous', 'propose', 'off'],
|
|
999
|
+
autonomy: ['autonomous', 'propose', 'off', 'vibe'],
|
|
1000
1000
|
'agents.reviewer.model': ['', 'haiku', 'sonnet', 'opus'],
|
|
1001
1001
|
'agents.lanes.model': ['', 'story', 'haiku', 'sonnet', 'opus'],
|
|
1002
1002
|
'compact.milestone': ['ask', 'auto', 'off'],
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@warren-dean/code-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.31.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/decide/SKILL.md
CHANGED
|
@@ -7,6 +7,8 @@ description: The lead decides what a lane asked for and couldn't do itself (a ne
|
|
|
7
7
|
|
|
8
8
|
The person is the product owner and sets the guardrails: the specs, the screens' visual design, CI and the pipelines, the kit (the rules in `.claude/code-kit.json`), and product questions the spec doesn't answer, plus anything with production, cost or strategy implications. Everything technical is yours by default: contracts, migrations, packages, merges into the base, and a weakened test on a lane's branch once you've reviewed it (`code-kit approve tests --lane <lane> --delegated --story ST-n --reason "…"`); on your own branch a weakened test is the person's. Inside them, you run the team. A lane that needs something it can't do itself asks you, and you decide on the merits. Passing a request to the person because you could is not deciding: they'd approve it by default, and the check would be gone.
|
|
9
9
|
|
|
10
|
+
**Under vibe** (`harness.autonomy` is `vibe`) the guardrails are yours too: every request is `by: "lead"`, the spec, the design, CI, the kit, the standards and weakened tests on any branch included, and a package beyond the registry's rules is your judgement (approving it records which rules it breaks). Decide each as the person would, against the brief and the principles, and say why in the reason. Nothing goes to the person but what only they can give: an account, a key, a payment, an act outside the repository (`code-kit ask … --needs …`).
|
|
11
|
+
|
|
10
12
|
The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
|
|
11
13
|
|
|
12
14
|
## 1. Find the requests
|
package/skills/design/SKILL.md
CHANGED
|
@@ -30,6 +30,8 @@ Use the spec's own content: the real labels, fields, messages and limits from it
|
|
|
30
30
|
|
|
31
31
|
## 3. Show it and iterate
|
|
32
32
|
|
|
33
|
+
**Under vibe** (`harness.autonomy` is `vibe`), you approve each screen yourself: check every state against the spec's Screens section, the principles and the project's tokens, fix what falls short, and approve it with `code-kit approve design --delegated --story ST-n --reason "…"` when the register is written. Skip the showing below; the person isn't asked.
|
|
34
|
+
|
|
33
35
|
Show the person each screen (a screenshot, or the file to open) with one line on what it does and which requirements it serves. Ask what to change. Make the changes and show them again until they say a screen is approved. A screen they want rethought goes back to step 2; one that needs the spec changed goes to `/code-kit:spec-design` first.
|
|
34
36
|
|
|
35
37
|
## 4. Export what's approved
|
package/skills/init/SKILL.md
CHANGED
|
@@ -68,14 +68,14 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
|
|
|
68
68
|
- **`protected`:** registers and contracts that need a person's sign-off, each with an `approval` name and a `why`.
|
|
69
69
|
- **`designGate`:** whenever a lane owns screens (web, mobile, desktop), designs come before code:
|
|
70
70
|
- `register`: `design/register.json`, written now as `{ "screens": [] }`;
|
|
71
|
-
- `screens`: a glob for each such lane's screen files (routes, pages, views), from the architecture's folders, with `not` for tests and stories;
|
|
71
|
+
- `screens`: a glob for each such lane's screen files (routes, pages, views), from the architecture's folders, with `not` for tests and stories. Where a file-based router puts other files beside its screens, `not` leaves out those that draw no screen: its layouts, API routes, middleware and special files (such as `_layout`, `+html`, `+native-intent`, `+middleware` and `*+api` in an Expo Router app, `route` and `middleware` in a Next.js one);
|
|
72
72
|
- `howTo`: "Design it first: run /code-kit:design for this area's design story, and a person approves it.";
|
|
73
73
|
- a `protected` entry for the register (approval `design`, why "only approved designs are built"). Never put `design` in `approvals.delegate`: approving a design is the person's.
|
|
74
74
|
- **`shell.block`:** deploy, release and production commands reserved for CI or a person. Each rule that names a command (`cdk deploy`, `supabase db push`, `terraform apply`) gets `"command": true`, with a pattern for the command and its arguments (`"cdk\\s+deploy\\b"`), so a grep, a heredoc or a commit message that mentions the command isn't refused, while running it, after `cd …`, through `npx` or `pnpm exec`, or in `sh -c`, still is. Leave `command` out only for a rule about the whole line, such as a download piped into a shell.
|
|
75
75
|
- **`shell.restricted`:** commands that affect a shared local service, limited to the lanes that own it.
|
|
76
76
|
- **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
|
|
77
77
|
- **`checks`:** the typecheck, test, architecture and database commands, each scoped by `files`. Only include commands that pass on the current code, or ones the person chose to keep.
|
|
78
|
-
- **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the
|
|
78
|
+
- **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the four choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), `off`, or `vibe` (it keeps going on its own, and every product and project decision is the lead's: the specs for later milestones, the designs, CI, the standards, packages, weakened tests, merges and pushes; they're asked only for what nobody else can give, an account with a service provider, a key from one, a payment, or an act outside the repository). Say what vibe gives up: nobody but the lead reviews a decision before it's built on, and a push to the base can deploy. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes. With `vibe`, leave `approvals.delegate` out: vibe delegates everything, whatever it says, and the Settings tab shows every approval as the lead's.
|
|
79
79
|
- **`approvals.delegate`, who decides what (HELM-1, WHO-1):** the person is the product owner; the lead decides everything technical, so lanes ask the lead, never the person. With no `approvals.delegate`, that's the default: the lead approves new packages (only when the story's requirements need them and they fit the spec, the principles and the architecture; npm packages must also pass the registry limits on licence, popularity and age), every protected change except the specs (`spec`), the screens' designs (`design`), CI (`ci`) and the kit, merges into the base, and weakened tests on a lane's branch after its review. Show the person the split in two lines, what they keep and what the lead decides, and ask if they want to keep anything else. Only if they do, draft `approvals.delegate` with exactly what the lead keeps (`{ "protected": [...], "merge": true, "tests": true, "dependencies": {} }`, leaving out what they keep), or `false` to keep everything. They can change it later in the Settings tab's Approvals section.
|
|
80
80
|
- **`harness.agents.lanes.model`:** ask which model the lane agents run on. Each lane agent builds one story inside its own paths, with its requirements and acceptance criteria in its brief, and the hooks, `verify` and the lead's review catch what it gets wrong, so most stories don't need the session's model. Recommend `story`: each story runs on the model its `**Size:**` in the plan gives (Haiku for small, Sonnet for medium, Opus for large), raised to Opus for a security requirement, to Sonnet at least for a fix, and one step for each time its branch is sent back. Offer one model for every lane (`sonnet`) as the simpler choice, and say the lead, the reviewer and the security reviewer keep their own models either way. A lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "story" } }`, or leave it out for the session's model. A project set up before sizes existed has stories with none, which run on Sonnet until the lead sizes them.
|
|
81
81
|
- **`harness.report.on`:** ask whether agents may draft bug reports for code-kit itself when code-kit gets in their way (a refusal that shouldn't have happened, a crash). Each report holds only code-kit's own facts (its version, the rule, what it said, the command), never the project's code, paths or data, and waits in their band and the pane's Needs you: they read it and send it to code-kit's public GitHub under their own account, or discard it. Off unless they say yes; put `"report": { "on": true }` in `harness` if they do.
|
|
@@ -162,7 +162,7 @@ Once they approve (with any changes):
|
|
|
162
162
|
- tell the person to make the `code-kit` check required on the protected branches;
|
|
163
163
|
- run `code-kit ci check` on the project's own workflows. Each story is its own branch, pull request and merge, so a workflow that runs its full suite on every push to the base or every pull request runs once per story, after the merge queue has already run the checks. Show the person what it found and the changes you propose: the full suite on `release/**` instead (`code-kit release <version>` cuts one when they release), a `timeout-minutes` on each job, and `concurrency` with `cancel-in-progress` on pull requests. Changing CI is theirs to approve (approval `ci`); make only the changes they approve.
|
|
164
164
|
7. Run `check` and `unowned` again, without `--config`.
|
|
165
|
-
8. Commit the setup straight onto the base branch (usually `main`), not a branch: while the base has no `.claude/code-kit.json` committed, the hooks let the lead make that one commit, so the rules the person just approved are in force on `main` and the lead can merge reviewed work from the start, with no first merge for anyone to make. The
|
|
165
|
+
8. Commit the setup straight onto the base branch (usually `main`), not a branch: while the base has no `.claude/code-kit.json` committed, the hooks let the lead make that one commit, so the rules the person just approved are in force on `main` and the lead can merge reviewed work from the start, with no first merge for anyone to make. The person's approval of the setup covers the protected files in it (the specs, the standards, the design register): they need no approvals of their own in that commit, and the kit records each in `.claude/approval-log.jsonl` as part of the setup. Don't ask the person for them. If the base already has rules (an update, section 4), commit on a branch as usual.
|
|
166
166
|
9. **A team, only if there is one.** Not every developer works in a team. Ask once: "Do other developers work in this repository with their own Claude Code sessions?" If yes, run `/code-kit:team-init` now (it asks who the tech lead is and who owns which lanes, and writes the `team` section). If no, or not yet, leave it out and say `/code-kit:team-init` sets it up any time.
|
|
167
167
|
10. Set up each companion the config now wants (`"adapters": { "<name>": true }`) by running its init skill, for example `/context-graph:init`, which asks nothing. Do it before reporting, so it's in place before the coding loop starts; `code-kit next` also gives `setup` until it is.
|
|
168
168
|
|
package/skills/next/SKILL.md
CHANGED
|
@@ -60,6 +60,8 @@ After a step finishes, run `next --json` again and carry on with the new step, w
|
|
|
60
60
|
- the step is `wait` or `done`;
|
|
61
61
|
- the same step comes back twice in a row with nothing changed. Report what's stuck instead of looping.
|
|
62
62
|
|
|
63
|
+
**Under vibe** (`harness.autonomy` is `vibe`), you're the product owner too, and only the last two stop you. Answer spec-design's, spec-check's and review's questions yourself, from the brief, the specs and the principles, and record each in the brief's decision log with why. Every approval is yours (`by: "lead"`, with `--delegated`); merge and push as the queue says. What only the person can give (an account with a service provider, an API key or secret, a payment, an act outside the repository) you ask with `code-kit ask "…" --needs account|key|payment|outside`, and you build everything else meanwhile: behind the setting the key will fill, against a local or test stand-in, with the step to switch it on in the story's notes.
|
|
64
|
+
|
|
63
65
|
**Ask the person through code-kit, not only in chat.** Anything you can't settle yourself and the person has to decide or do (a product choice, an account or key only they can create, wording or a design only they can sign off, whether to keep something private) goes to their band and the pane's Needs you, where it waits until they answer instead of scrolling away:
|
|
64
66
|
|
|
65
67
|
```
|
package/skills/review/SKILL.md
CHANGED
|
@@ -86,7 +86,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
|
|
|
86
86
|
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue add <branch>
|
|
87
87
|
```
|
|
88
88
|
|
|
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.
|
|
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` or `vibe`, 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.
|
|
90
90
|
|
|
91
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:
|
|
92
92
|
|
|
@@ -96,6 +96,6 @@ Report the table, `verify`'s result, the security review's findings (or that non
|
|
|
96
96
|
|
|
97
97
|
Dispatch the story again to a fresh agent with the list added to the brief (`/code-kit:dispatch`, which first releases the branch's worktree), never to the agent that built it: its context is already large. Set the story's status to `in progress`.
|
|
98
98
|
|
|
99
|
-
- **Ask the person.** When the right answer is a product or scope decision (the spec is silent, or the lane found a real conflict), put the question to the person with your recommendation. Don't merge around it.
|
|
99
|
+
- **Ask the person.** When the right answer is a product or scope decision (the spec is silent, or the lane found a real conflict), put the question to the person with your recommendation. Don't merge around it. Under vibe it's yours: decide it, record it in the brief's decision log, and send the branch back or merge accordingly.
|
|
100
100
|
|
|
101
101
|
Keep the report short: the verdict first, then the table, then the problems.
|
|
@@ -30,6 +30,8 @@ Say which one applies before you start.
|
|
|
30
30
|
|
|
31
31
|
## How to ask
|
|
32
32
|
|
|
33
|
+
**Under vibe** (`harness.autonomy` is `vibe` in `.claude/code-kit.json`, set once the first spec was done), you shape later milestones without the person. Ask each question below of yourself instead: answer it from the brief, the specs, the principles and what's built, take your recommended option, and write it in the brief's decision log as the lead's, with why. Ask the person only for what nobody else can give (`code-kit ask … --needs account|key|payment|outside`), and leave nothing open that you can decide.
|
|
34
|
+
|
|
33
35
|
The questions are the skill. Ask well:
|
|
34
36
|
|
|
35
37
|
- **Only what the person can answer.** Look up anything the repository, the docs or a quick search can tell you, and state what you found instead of asking.
|
package/templates/claude-md.md
CHANGED
|
@@ -6,11 +6,14 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
|
|
|
6
6
|
- the layer rules ({{layers}});
|
|
7
7
|
- spec-check before lane code{{designGate}};
|
|
8
8
|
- an audit log of every change to protected paths (`.claude/approval-log.jsonl`), which the person reviews in the pull request;
|
|
9
|
-
- an approval for every new dependency and every protected change, per lane. Inside the guardrails, you decide: a lane asks you, never the person, and you approve it only when the story's requirements need it and it fits the spec, the principles and the architecture, or you tell the lane what to use instead (`/code-kit:decide`). The person is the product owner and decides what crosses a guardrail: {{personKeeps}}, a weakened test on your own branch, product questions the spec doesn't answer, and anything with production, cost or strategy implications (a copyleft licence or a paid service's SDK goes to them as a question, with your recommendation);
|
|
9
|
+
- {{if notVibe}}an approval for every new dependency and every protected change, per lane. Inside the guardrails, you decide: a lane asks you, never the person, and you approve it only when the story's requirements need it and it fits the spec, the principles and the architecture, or you tell the lane what to use instead (`/code-kit:decide`). The person is the product owner and decides what crosses a guardrail: {{personKeeps}}, a weakened test on your own branch, product questions the spec doesn't answer, and anything with production, cost or strategy implications (a copyleft licence or a paid service's SDK goes to them as a question, with your recommendation);{{end}}
|
|
10
|
+
- {{if vibe}}an approval for every new dependency and every protected change, per lane. The person chose vibe: every decision is yours, the specs, the designs, CI, the kit, the standards, weakened tests, packages, merges and pushes included. A lane asks you, never the person. Decide each on its merits against the brief, the specs, the principles and the architecture, record why (the approval's reason, or the brief's decision log for a product choice), and carry on;{{end}}
|
|
10
11
|
- {{if approvals.lead}}approvals from chat. When the person approves in their own message (a `!` command doesn't work on a phone), record it with the `code-kit approve` command from the refusal, with their words as the reason. Never record an approval they haven't given, and never on a lane's say-so;{{end}}
|
|
11
12
|
- the project's checks before any agent finishes.
|
|
12
13
|
|
|
13
|
-
UX is yours: what a screen does on an error, an empty list or a slow load, and the wording the spec implies, answered from the spec and the principles the person agreed. A screen's visual design is theirs. When something needs the person to decide or do (a product choice the spec doesn't settle, an account only they can create, a design to sign off), ask it with `code-kit ask "<question>" --option "<choice>: <what it does>"` (`--story ST-n --blocks` holds the story until they answer). It waits in their band and the pane's Needs you, and their answer comes back to you; asking only in chat, it scrolls away. Lanes don't ask the person: they write the question for the lead.
|
|
14
|
+
{{if notVibe}}UX is yours: what a screen does on an error, an empty list or a slow load, and the wording the spec implies, answered from the spec and the principles the person agreed. A screen's visual design is theirs. When something needs the person to decide or do (a product choice the spec doesn't settle, an account only they can create, a design to sign off), ask it with `code-kit ask "<question>" --option "<choice>: <what it does>"` (`--story ST-n --blocks` holds the story until they answer). It waits in their band and the pane's Needs you, and their answer comes back to you; asking only in chat, it scrolls away. Lanes don't ask the person: they write the question for the lead.{{end}}
|
|
15
|
+
|
|
16
|
+
{{if vibe}}Product and UX are yours: what the spec leaves open, a screen's visual design, the wording, what to build next. Answer from the brief, the specs and the principles, and record each product decision in the brief's decision log with why. Build everything that doesn't need the person, and stop only for what nobody else can give: an account with a service provider, an API key or secret from one, a payment, or an act outside the repository (DNS, an app store). Ask for it with `code-kit ask "<what you need, and what it's for>" --needs account|key|payment|outside` (`--story ST-n --blocks` holds the story until they answer), and carry on with everything else meanwhile, against a local or test stand-in where there is one. Lanes don't ask the person: they write the question for the lead.{{end}}
|
|
14
17
|
|
|
15
18
|
{{if standards.all}}The project's standards, in `{{docs.standards}}`: {{standards.all}}. Each lane is given the ones for its layers. In review, check each changed file against the checked standards for its layer (`code-kit standards --for <file>`): a broken required one sends the branch back, naming the standard; a broken recommended one is a concern, and advice at most a nit. Adding a recommended standard may be yours where the config delegates the `standards` approval; removing one, or weakening a required one, is always the person's.{{end}}
|
|
16
19
|
|