@warren-dean/code-kit 0.16.1 → 0.17.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 +9 -0
- package/README.md +28 -27
- package/hooks/lib/harness.mjs +9 -0
- package/hooks/lib/rules.mjs +8 -0
- package/hooks/mod/loop.mjs +24 -0
- package/hooks/mod/register.mjs +56 -0
- package/hooks/mod/register.test.ts +57 -1
- package/hooks/mod/view.mjs +1 -0
- package/hooks/stop-check.mjs +11 -1
- package/package.json +1 -1
- package/skills/decide/SKILL.md +1 -1
- package/skills/dispatch/SKILL.md +1 -1
- package/skills/review/SKILL.md +1 -0
- package/templates/agent.md +3 -1
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"name": "code-kit",
|
|
10
10
|
"source": "./",
|
|
11
11
|
"description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
|
|
12
|
-
"version": "0.
|
|
12
|
+
"version": "0.17.0",
|
|
13
13
|
"category": "development",
|
|
14
14
|
"tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
|
|
15
15
|
"license": "MIT"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "code-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.0",
|
|
4
4
|
"description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Warren Langeveldt"
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
|
|
4
4
|
|
|
5
|
+
## 0.17.0 (2026-10-17)
|
|
6
|
+
|
|
7
|
+
The lead's context stays lean: lanes report to a file, and the lead's context is compacted when a milestone finishes.
|
|
8
|
+
|
|
9
|
+
- A lane on a story's branch now writes its full report to `.claude/state/reports/<branch>.md` before it finishes: what it did, the commands it ran with their output, what's left, and anything it needs decided. It hands the lead at most ten lines naming that file. The stop hook won't let a lane finish without the report, and the review, dispatch and decide skills read it when they need the detail. Before, every lane pasted its whole report, output included, into the lead's context; in one project that was about 236k of the lead's 780k tokens.
|
|
10
|
+
- Lanes don't message the lead while they work. They hand back once, when they finish or when they're blocked.
|
|
11
|
+
- When a milestone finishes during the session, the lead's context is compacted before the loop's next step, as the new `harness.compact.milestone` setting says: `ask` (the default) asks you in Claude Code's dialog, `auto` compacts at once, and `off` leaves it alone. The summary keeps the stories in flight and what waits on you, and drops the finished stories' detail. It's skipped when the context is under 25% full.
|
|
12
|
+
- Re-run `/code-kit:init` to update your lane agent files with the new reporting rules. Until then, the stop hook tells each lane what to do.
|
|
13
|
+
|
|
5
14
|
## 0.16.1 (2026-10-16)
|
|
6
15
|
|
|
7
16
|
The lead loop stops asking for stories that are waiting on other work.
|
package/README.md
CHANGED
|
@@ -334,6 +334,7 @@ The loop keeps the build moving between your prompts, under `harness.autonomy`.
|
|
|
334
334
|
- **It reads the lead's reply first.** Before prompting again, the loop reads the lead's last reply with a side call over the lead's own conversation. A reply that waits on you (a question, a design to look at, an approval), or a turn you stopped, holds the loop until you answer or speak to the lead: the band says what the lead waits on, and its question is asked in Claude Code's own question dialog. A step the lead didn't take waits in the band with its reason and **Ask again**.
|
|
335
335
|
- **Stories waiting on other work.** When the lead says a story isn't due yet because it waits on work still going (a paired story a lane is building, a rebuild, a check running), the loop parks that story and leaves it out of every step, so a step naming it with others prompts only the others. It wakes when what it waits on moves: its own branch, the stories the lead named, or the unfinished stories that depend on it. Other lanes' commits don't wake it, and after 30 minutes with nothing moving the lead is asked once more.
|
|
336
336
|
- **A step that doesn't move.** One the lead was prompted with twice in a row that is still next goes to you instead: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Ask again**.
|
|
337
|
+
- **A lean lead.** A lane writes its full report, with its commands and their output, to `.claude/state/reports/<branch>.md`, and hands the lead a few lines naming it; the stop hook won't let a lane on a story branch finish without it, and the lead reads the file when it reviews. Lanes don't message the lead while they work. When a milestone finishes, the lead's context is compacted before the next one (`harness.compact.milestone`: you're asked by default, or it's done at once): the summary keeps what's in flight and what waits on you, and drops the finished stories' detail.
|
|
337
338
|
- **Designs.** A design story is handed to the lead once a session; while you and the lead design it, the loop leaves it to you.
|
|
338
339
|
- **One session runs it.** The first session whose loop acts runs it for the project. Another session you open there, for any reason, never prompts its lead: its band reads "the loop runs in another session", with **Lead from here** to move the loop to it.
|
|
339
340
|
- **Modes.** **Pause** and **Resume** stop and start it. Under `propose`, each step waits for **Go**; under `off`, the loop does nothing. When every story is done, the band says so and the loop stops.
|
|
@@ -476,33 +477,33 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
|
|
|
476
477
|
|
|
477
478
|
`.claude/code-kit.json`. Globs use `*` (one segment), `**` (any depth), `**/` (zero or more folders), `?` and `{a,b}`. Patterns under `shell` are regular expressions.
|
|
478
479
|
|
|
479
|
-
| Field | Required | What it is
|
|
480
|
-
| ------------------------------ | ----------------- |
|
|
481
|
-
| `version` | yes | `1`
|
|
482
|
-
| `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch
|
|
483
|
-
| `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan
|
|
484
|
-
| `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions`
|
|
485
|
-
| `lead.paths` | yes | What the main session writes. `.claude/**` is always added.
|
|
486
|
-
| `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included.
|
|
487
|
-
| `anyActor` | no | Paths every writer may change (e.g. the lockfile), read-only agents included. `.claude/state/**` is always included. An entry may be `{ "glob", "reviewer" }` to name the lane (or `"lead"`) that reviews changes to it; otherwise the lead reviews them, and `who` and `trace` say so.
|
|
488
|
-
| `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners? }`: the agent name maps a subagent to its lane; `owners` (GitHub handles) are the people whose sessions work it, in a team (needs `team`). A worktree with a `.lane` file holding the lane name makes the main session that lane.
|
|
489
|
-
| `protected[]` | no | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs an approval: the lead's where `approvals.delegate.protected` names it, otherwise a person's (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`.
|
|
490
|
-
| `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) lists them. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs
|
|
491
|
-
| `layers[]` | no | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself.
|
|
492
|
-
| `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths
|
|
493
|
-
| `shell.block[]` | no | `{ pattern, why, person?, command? }`: never run. `person: true` marks a person's act, which the lead may do for them with `approvals.lead` on. `command: true` matches the pattern from the start of each command the line runs, so a heredoc or quoted text that mentions it isn't refused
|
|
494
|
-
| `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes
|
|
495
|
-
| `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped.
|
|
496
|
-
| `tests[]` | no | Globs naming the test files, for the weakened-test and fix rules. Default: the usual conventions (`*.test.*`, `*.spec.*`, `__tests__/`, `test/`, `tests/`, `e2e/`, `*_test.go`, `test_*.py`).
|
|
497
|
-
| `regression.prepare` | no | A command run in a fresh checkout before a fix's tests run there without the fix, such as `npm ci`. Without it, the checkout's `node_modules` and virtualenvs are linked in.
|
|
498
|
-
| `checks[]` | no | `{ name, files, exclude?, run[], each?, owners?, ifMissing?, timeoutSeconds? }`: before finishing, when matching files changed. `each` runs the commands in every changed folder matching that glob. `owners` limits who may change the files (the lead always may). `ifMissing: "fail"` makes a missing tool an error (the default is to skip the check, which `verify` and a merge list as not run).
|
|
499
|
-
| `adapters` | no | `{ "<adapter>": false }` switches off an adapter that would otherwise be detected; `true` says the project wants that tool, so until it's set up here `next` gives its setup before any code. See [Adapters](#adapters).
|
|
500
|
-
| `approvals.lead` | no | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals).
|
|
501
|
-
| `approvals.delegate` | no | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: what the lead decides, inside the guardrails you keep: the protected approvals it grants, and packages it approves for a story, with `code-kit approve --delegated`; with `merge`, merges into a protected branch with `code-kit merge --delegated`. Lanes ask the lead for these, never you. npm packages are also checked against the registry; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals).
|
|
502
|
-
| `setup` | no | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it
|
|
503
|
-
| `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default) or `{ command, fallback? }` for another team provider, such as the code-kit teams hub; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached. See docs/specs/16-teams.md.
|
|
504
|
-
| `branches.protected` | no | Default `["main", "master"]`
|
|
505
|
-
| `harness` | no | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 10; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (default the session's), `agents.lanes.model` (the model each lane agent starts on, unless the lead's call or the lane's agent file names one; default the session's), `background.pauseAtPercent` (default 80) and `report.on` (agents draft bug reports for code-kit, which you send or discard; default `false`). Change them with `/harness` or `code-kit settings set`. |
|
|
480
|
+
| Field | Required | What it is |
|
|
481
|
+
| ------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
482
|
+
| `version` | yes | `1` |
|
|
483
|
+
| `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
|
|
484
|
+
| `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
|
|
485
|
+
| `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
|
|
486
|
+
| `lead.paths` | yes | What the main session writes. `.claude/**` is always added. |
|
|
487
|
+
| `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included. |
|
|
488
|
+
| `anyActor` | no | Paths every writer may change (e.g. the lockfile), read-only agents included. `.claude/state/**` is always included. An entry may be `{ "glob", "reviewer" }` to name the lane (or `"lead"`) that reviews changes to it; otherwise the lead reviews them, and `who` and `trace` say so. |
|
|
489
|
+
| `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners? }`: the agent name maps a subagent to its lane; `owners` (GitHub handles) are the people whose sessions work it, in a team (needs `team`). A worktree with a `.lane` file holding the lane name makes the main session that lane. |
|
|
490
|
+
| `protected[]` | no | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs an approval: the lead's where `approvals.delegate.protected` names it, otherwise a person's (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`. |
|
|
491
|
+
| `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) lists them. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs |
|
|
492
|
+
| `layers[]` | no | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself. |
|
|
493
|
+
| `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
|
|
494
|
+
| `shell.block[]` | no | `{ pattern, why, person?, command? }`: never run. `person: true` marks a person's act, which the lead may do for them with `approvals.lead` on. `command: true` matches the pattern from the start of each command the line runs, so a heredoc or quoted text that mentions it isn't refused |
|
|
495
|
+
| `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes |
|
|
496
|
+
| `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
|
|
497
|
+
| `tests[]` | no | Globs naming the test files, for the weakened-test and fix rules. Default: the usual conventions (`*.test.*`, `*.spec.*`, `__tests__/`, `test/`, `tests/`, `e2e/`, `*_test.go`, `test_*.py`). |
|
|
498
|
+
| `regression.prepare` | no | A command run in a fresh checkout before a fix's tests run there without the fix, such as `npm ci`. Without it, the checkout's `node_modules` and virtualenvs are linked in. |
|
|
499
|
+
| `checks[]` | no | `{ name, files, exclude?, run[], each?, owners?, ifMissing?, timeoutSeconds? }`: before finishing, when matching files changed. `each` runs the commands in every changed folder matching that glob. `owners` limits who may change the files (the lead always may). `ifMissing: "fail"` makes a missing tool an error (the default is to skip the check, which `verify` and a merge list as not run). |
|
|
500
|
+
| `adapters` | no | `{ "<adapter>": false }` switches off an adapter that would otherwise be detected; `true` says the project wants that tool, so until it's set up here `next` gives its setup before any code. See [Adapters](#adapters). |
|
|
501
|
+
| `approvals.lead` | no | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals). |
|
|
502
|
+
| `approvals.delegate` | no | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: what the lead decides, inside the guardrails you keep: the protected approvals it grants, and packages it approves for a story, with `code-kit approve --delegated`; with `merge`, merges into a protected branch with `code-kit merge --delegated`. Lanes ask the lead for these, never you. npm packages are also checked against the registry; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals). |
|
|
503
|
+
| `setup` | no | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it |
|
|
504
|
+
| `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default) or `{ command, fallback? }` for another team provider, such as the code-kit teams hub; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached. See docs/specs/16-teams.md. |
|
|
505
|
+
| `branches.protected` | no | Default `["main", "master"]` |
|
|
506
|
+
| `harness` | no | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 10; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (default the session's), `agents.lanes.model` (the model each lane agent starts on, unless the lead's call or the lane's agent file names one; default the session's), `background.pauseAtPercent` (default 80), `compact.milestone` (when a milestone finishes, compact the lead's context: `ask`, `auto` or `off`; default `ask`) and `report.on` (agents draft bug reports for code-kit, which you send or discard; default `false`). Change them with `/harness` or `code-kit settings set`. |
|
|
506
507
|
|
|
507
508
|
Add `.claude/approvals/`, `.claude/state/` and `.claude/code-kit.draft.json` to `.gitignore`, and `.claude/approval-log.jsonl merge=union` to `.gitattributes`, so merging branches that both logged changes keeps every entry. Commit `.claude/code-kit.baseline.json` if the project has one.
|
|
508
509
|
|
package/hooks/lib/harness.mjs
CHANGED
|
@@ -6,6 +6,9 @@ export const AUTONOMY = ['autonomous', 'propose', 'off'];
|
|
|
6
6
|
export const MODELS = ['haiku', 'sonnet', 'opus'];
|
|
7
7
|
|
|
8
8
|
/** Each setting by its dotted key: its default, and why a value is wrong (or null when it's right). */
|
|
9
|
+
/** LEAN-3: what the loop does with the lead's context when a milestone finishes. */
|
|
10
|
+
export const COMPACT = ['ask', 'auto', 'off'];
|
|
11
|
+
|
|
9
12
|
export const SETTINGS = {
|
|
10
13
|
autonomy: {
|
|
11
14
|
default: 'autonomous',
|
|
@@ -66,6 +69,12 @@ export const SETTINGS = {
|
|
|
66
69
|
Number.isFinite(v) && v > 0 && v <= 100 ? null : 'must be a percentage from 1 to 100',
|
|
67
70
|
about: "The plan's 5-hour use at which background agents pause",
|
|
68
71
|
},
|
|
72
|
+
'compact.milestone': {
|
|
73
|
+
default: 'ask',
|
|
74
|
+
problem: (v) => (COMPACT.includes(v) ? null : `must be one of ${COMPACT.join(', ')}`),
|
|
75
|
+
about:
|
|
76
|
+
"When a milestone finishes, compact the lead's context before the next: ask you, do it, or leave it",
|
|
77
|
+
},
|
|
69
78
|
'report.on': {
|
|
70
79
|
default: false,
|
|
71
80
|
problem: (v) => (typeof v === 'boolean' ? null : 'must be true or false'),
|
package/hooks/lib/rules.mjs
CHANGED
|
@@ -815,6 +815,14 @@ export function ownerOf(rel, config) {
|
|
|
815
815
|
return matchesAny(rel, config.lead.paths) ? 'lead' : null;
|
|
816
816
|
}
|
|
817
817
|
|
|
818
|
+
/**
|
|
819
|
+
* LEAN-1: a lane's full report for its branch: what it did, the commands it ran and their output, its
|
|
820
|
+
* questions. The lead's context gets a short hand-back naming this file, and reads it when it reviews.
|
|
821
|
+
*/
|
|
822
|
+
export function reportPath(root) {
|
|
823
|
+
return `.claude/state/reports/${currentBranch(root).replace(/[^\w.-]+/g, '_')}.md`;
|
|
824
|
+
}
|
|
825
|
+
|
|
818
826
|
// Lane work starts with the spec-check skill: its report for the branch must exist first.
|
|
819
827
|
export function specCheckPath(root) {
|
|
820
828
|
return `.claude/state/spec-check/${currentBranch(root).replace(/[^\w.-]+/g, '_')}.md`;
|
package/hooks/mod/loop.mjs
CHANGED
|
@@ -310,3 +310,27 @@ export function laneModel({ type, model = null, lanes = {}, setting = null, file
|
|
|
310
310
|
if (fileModel && fileModel !== 'inherit') return null;
|
|
311
311
|
return setting;
|
|
312
312
|
}
|
|
313
|
+
|
|
314
|
+
/** LEAN-3: compacting a context below this share of its window isn't worth the summary it costs. */
|
|
315
|
+
export const COMPACT_FLOOR = 25;
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* LEAN-3: the milestones every story of which is done, in the plan's order. A milestone with no stories
|
|
319
|
+
* isn't one.
|
|
320
|
+
*/
|
|
321
|
+
export function milestonesDone(stories = []) {
|
|
322
|
+
const by = new Map();
|
|
323
|
+
for (const s of stories) {
|
|
324
|
+
if (!s.milestone) continue;
|
|
325
|
+
by.set(s.milestone, [...(by.get(s.milestone) ?? []), s]);
|
|
326
|
+
}
|
|
327
|
+
return [...by].filter(([, list]) => list.every((s) => s.state === 'done')).map(([m]) => m);
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/** LEAN-3: what the lead's summary keeps when its context is compacted after a milestone. */
|
|
331
|
+
export const compactInstructions = (milestone) =>
|
|
332
|
+
[
|
|
333
|
+
`${milestone} is done; the build goes on with the next milestone.`,
|
|
334
|
+
'Keep: the milestone just finished, in a line; every story in flight now, with its lane, its branch and where it stands (building, in review, in the merge queue, waiting and on what); the decisions and questions waiting on the person; what the person decided or asked for in this session that still applies; and the rules and preferences they set.',
|
|
335
|
+
"Drop: the finished stories' details, lane reports and hand-backs, command output, diffs and file contents. Each is in git, the plan or the lanes' report files, to read again when it's needed.",
|
|
336
|
+
].join('\n');
|
package/hooks/mod/register.mjs
CHANGED
|
@@ -58,7 +58,10 @@ import {
|
|
|
58
58
|
leadPrompt,
|
|
59
59
|
nudgeText,
|
|
60
60
|
outcomePrompt,
|
|
61
|
+
COMPACT_FLOOR,
|
|
61
62
|
PARK_MS,
|
|
63
|
+
compactInstructions,
|
|
64
|
+
milestonesDone,
|
|
62
65
|
parkWatch,
|
|
63
66
|
readOutcome,
|
|
64
67
|
restartPrompt,
|
|
@@ -128,6 +131,8 @@ const loop = {
|
|
|
128
131
|
handedDesign: new Set(), // LOOP-12: design stories handed to the lead this session
|
|
129
132
|
// LOOP-13: stories the lead said wait on other work: id → { on, why, watch, sig, at }
|
|
130
133
|
parked: new Map(),
|
|
134
|
+
// LEAN-3: the milestones already done when this session first looked, and those finished since.
|
|
135
|
+
milestones: null,
|
|
131
136
|
};
|
|
132
137
|
// LOOP-10: whether this session runs the loop, the session that does when another does, and when this
|
|
133
138
|
// one last renewed its lease.
|
|
@@ -1144,6 +1149,55 @@ export function register(on) {
|
|
|
1144
1149
|
for (const [id, p] of loop.parked)
|
|
1145
1150
|
if (now - p.at >= PARK_MS || seen.sig(p.watch) !== p.sig) loop.parked.delete(id);
|
|
1146
1151
|
},
|
|
1152
|
+
// LEAN-3: a milestone finished in this session: the lead's context is compacted before the next,
|
|
1153
|
+
// asked in Claude Code's dialog or done at once, as compact.milestone says. True when it took over
|
|
1154
|
+
// the turn's end, so the loop's step waits until the compaction is done or declined.
|
|
1155
|
+
compactAtMilestone: async () => {
|
|
1156
|
+
const done = milestonesDone(model.state?.stories ?? []);
|
|
1157
|
+
if (loop.milestones === null) {
|
|
1158
|
+
loop.milestones = new Set(done);
|
|
1159
|
+
return false;
|
|
1160
|
+
}
|
|
1161
|
+
const fresh = done.filter((m) => !loop.milestones.has(m));
|
|
1162
|
+
if (!fresh.length) return false;
|
|
1163
|
+
const mode = harness().compact?.milestone ?? 'ask';
|
|
1164
|
+
if (mode === 'off' || offering || !where.interactive || (lease.other && !lease.mine)) {
|
|
1165
|
+
for (const m of fresh) loop.milestones.add(m);
|
|
1166
|
+
return false;
|
|
1167
|
+
}
|
|
1168
|
+
const box = await $.prompt.read().catch(() => null);
|
|
1169
|
+
if (box?.text?.trim()) return false;
|
|
1170
|
+
for (const m of fresh) loop.milestones.add(m);
|
|
1171
|
+
const percent = (await $.session.usage().catch(() => null))?.context?.percent ?? 0;
|
|
1172
|
+
if (percent < COMPACT_FLOOR) return false;
|
|
1173
|
+
const milestone = fresh.at(-1);
|
|
1174
|
+
const compact = async () => {
|
|
1175
|
+
const r = await $.session
|
|
1176
|
+
.compact({ instructions: compactInstructions(milestone) })
|
|
1177
|
+
.catch((err) => ({ skip: String(err?.message ?? err) }));
|
|
1178
|
+
if (r?.skip) notice = `The lead's context wasn't compacted: ${r.skip}`;
|
|
1179
|
+
await act.record('compact', milestone);
|
|
1180
|
+
$.ui.invalidate('ui.render');
|
|
1181
|
+
await act.step('resume').catch(() => {});
|
|
1182
|
+
};
|
|
1183
|
+
if (mode === 'auto') {
|
|
1184
|
+
compact().catch(() => {});
|
|
1185
|
+
return true;
|
|
1186
|
+
}
|
|
1187
|
+
offering = true;
|
|
1188
|
+
$.ui
|
|
1189
|
+
.ask(
|
|
1190
|
+
`${milestone} is done, and the lead's context is ${Math.round(percent)}% full. Compact it before the next milestone? The summary keeps what's in flight and what waits on you, and drops the finished stories' detail.`,
|
|
1191
|
+
{ options: ['Compact now', 'Not now'], header: 'Context' },
|
|
1192
|
+
)
|
|
1193
|
+
.catch(() => null)
|
|
1194
|
+
.then(async (answer) => {
|
|
1195
|
+
offering = false;
|
|
1196
|
+
if (answer === 'Compact now') await compact();
|
|
1197
|
+
else await act.step('resume').catch(() => {});
|
|
1198
|
+
});
|
|
1199
|
+
return true;
|
|
1200
|
+
},
|
|
1147
1201
|
// LOOP-11: the lead's last reply, read once before the loop prompts it again. A reply that waits on
|
|
1148
1202
|
// the person, or a turn they stopped, holds the loop until they speak; a step the lead didn't take
|
|
1149
1203
|
// holds that step while it's still next.
|
|
@@ -1981,6 +2035,8 @@ export function register(on) {
|
|
|
1981
2035
|
$.prompt.submit({ text }).catch(() => {});
|
|
1982
2036
|
return res;
|
|
1983
2037
|
}
|
|
2038
|
+
// LEAN-3: a milestone just finished: its compaction comes before the next step.
|
|
2039
|
+
if (await act?.compactAtMilestone().catch(() => false)) return res;
|
|
1984
2040
|
await act?.step('turn').catch(() => {});
|
|
1985
2041
|
// DECIDE-4: a decision waiting, asked in Claude Code's own dialog; not awaited, the person answers.
|
|
1986
2042
|
act?.offer().catch(() => {});
|
|
@@ -74,6 +74,7 @@ function project() {
|
|
|
74
74
|
refs: ' aaa refs/heads/main\n bbb refs/heads/web/st-4\n',
|
|
75
75
|
agents: [] as { type: string; status: string; id?: string; description?: string }[],
|
|
76
76
|
limits: [] as { kind: string; percentUsed: number }[],
|
|
77
|
+
contextPercent: 0, // LEAN-3: how full the lead's context is
|
|
77
78
|
approveExit: 0,
|
|
78
79
|
mergeExit: 0,
|
|
79
80
|
answer: 'Merge',
|
|
@@ -403,7 +404,9 @@ function stub(on: any, w: World) {
|
|
|
403
404
|
w.spawned.push(e);
|
|
404
405
|
return { model: e.model ?? 'claude-opus-5-5', agentId: `a-${w.spawned.length}` };
|
|
405
406
|
});
|
|
406
|
-
on('session.usage', () => ({
|
|
407
|
+
on('session.usage', () => ({
|
|
408
|
+
value: { startedAt: 0, context: { percent: w.contextPercent }, rateLimits: w.limits },
|
|
409
|
+
}));
|
|
407
410
|
on('session.measure', ($: any, e: any) => ({ changed: e.changed }));
|
|
408
411
|
// A model request, answered with the usage the test gave it.
|
|
409
412
|
on('turn.step', async function* ($: any, e: any) {
|
|
@@ -2510,6 +2513,59 @@ test('LOOP-11 dismissed, what the lead waits on stays in the band, and the loop
|
|
|
2510
2513
|
expect(w.prompts.at(-1)).toBe('Review ST-4: run /code-kit:review ST-4.');
|
|
2511
2514
|
});
|
|
2512
2515
|
|
|
2516
|
+
test("LEAN-3 when a milestone finishes, the person is asked to compact the lead's context first, and the loop goes on after", async ($, on) => {
|
|
2517
|
+
const w = project();
|
|
2518
|
+
w.stories = [
|
|
2519
|
+
{
|
|
2520
|
+
id: 'ST-1',
|
|
2521
|
+
title: 'Foundations',
|
|
2522
|
+
lane: 'web',
|
|
2523
|
+
state: 'in review',
|
|
2524
|
+
branch: 'web/st-1',
|
|
2525
|
+
milestone: 'M0',
|
|
2526
|
+
waitingOn: [],
|
|
2527
|
+
},
|
|
2528
|
+
...w.stories.map((s) => ({ ...s, milestone: 'M1' })),
|
|
2529
|
+
];
|
|
2530
|
+
const compacted: string[] = [];
|
|
2531
|
+
w.contextPercent = 62;
|
|
2532
|
+
on('session.compact', ($: any, e: any) => {
|
|
2533
|
+
compacted.push(e.instructions);
|
|
2534
|
+
// A compaction leaves the summary in the conversation's place.
|
|
2535
|
+
return {
|
|
2536
|
+
messages: [
|
|
2537
|
+
{ role: 'user', text: 'Summary: M0 done; ST-4 in progress on web/st-4.', toolUses: [] },
|
|
2538
|
+
],
|
|
2539
|
+
};
|
|
2540
|
+
});
|
|
2541
|
+
const clock = await start($, on, w);
|
|
2542
|
+
await leadTurn($);
|
|
2543
|
+
await settle(clock);
|
|
2544
|
+
expect(compacted).toEqual([]);
|
|
2545
|
+
const prompted = w.prompts.length;
|
|
2546
|
+
// ST-1 merges: M0 is done, and the next turn's end asks before the loop's next step.
|
|
2547
|
+
w.stories[0] = { ...w.stories[0], state: 'done' };
|
|
2548
|
+
w.refs += ' m1 refs/heads/main-moved\n';
|
|
2549
|
+
await clock.advance(2000);
|
|
2550
|
+
w.answer = 'Compact now';
|
|
2551
|
+
await leadTurn($, 't-2');
|
|
2552
|
+
await settle(clock);
|
|
2553
|
+
expect(w.asked.at(-1)?.question).toMatch(
|
|
2554
|
+
/^M0 is done, and the lead's context is 62% full\. Compact it/,
|
|
2555
|
+
);
|
|
2556
|
+
expect(w.asked.at(-1)?.options).toEqual(['Compact now', 'Not now']);
|
|
2557
|
+
expect(compacted).toHaveLength(1);
|
|
2558
|
+
expect(compacted[0]).toMatch(/^M0 is done/);
|
|
2559
|
+
expect(compacted[0]).toMatch(/every story in flight now/);
|
|
2560
|
+
// The loop's step follows the compaction.
|
|
2561
|
+
expect(w.prompts.length).toBeGreaterThan(prompted);
|
|
2562
|
+
// The same milestone isn't offered twice, and a context below the floor isn't worth compacting.
|
|
2563
|
+
w.contextPercent = 10;
|
|
2564
|
+
await leadTurn($, 't-3');
|
|
2565
|
+
await settle(clock);
|
|
2566
|
+
expect(compacted).toHaveLength(1);
|
|
2567
|
+
});
|
|
2568
|
+
|
|
2513
2569
|
test('LOOP-13 stories the lead says wait on other work are parked, each until what it waits on moves', async ($, on) => {
|
|
2514
2570
|
const w = project();
|
|
2515
2571
|
w.stories.push(
|
package/hooks/mod/view.mjs
CHANGED
|
@@ -1513,6 +1513,7 @@ const CHOICES = {
|
|
|
1513
1513
|
autonomy: ['autonomous', 'propose', 'off'],
|
|
1514
1514
|
'agents.reviewer.model': ['', 'haiku', 'sonnet', 'opus'],
|
|
1515
1515
|
'agents.lanes.model': ['', 'haiku', 'sonnet', 'opus'],
|
|
1516
|
+
'compact.milestone': ['ask', 'auto', 'off'],
|
|
1516
1517
|
};
|
|
1517
1518
|
const shown = (v) =>
|
|
1518
1519
|
v === null || v === '' ? "the session's" : v === true ? 'on' : v === false ? 'off' : String(v);
|
package/hooks/stop-check.mjs
CHANGED
|
@@ -8,7 +8,8 @@ import { loadBaseline, newProblems } from './lib/baseline.mjs';
|
|
|
8
8
|
import { runChecks } from './lib/checks.mjs';
|
|
9
9
|
import { block, start } from './lib/hook.mjs';
|
|
10
10
|
import { layerProblems } from './lib/layers.mjs';
|
|
11
|
-
import { actorFor, actorRoot } from './lib/rules.mjs';
|
|
11
|
+
import { actorFor, actorRoot, currentBranch, reportPath } from './lib/rules.mjs';
|
|
12
|
+
import { storyOfBranch } from './lib/teamfacts.mjs';
|
|
12
13
|
import { auditProblems, changedFiles } from './lane-audit.mjs';
|
|
13
14
|
|
|
14
15
|
const { input, project, config, error } = start();
|
|
@@ -92,4 +93,13 @@ if (actor.kind === 'lane' && changed.length) {
|
|
|
92
93
|
changed.join('\n'),
|
|
93
94
|
);
|
|
94
95
|
}
|
|
96
|
+
|
|
97
|
+
// LEAN-1: the lead's context gets a short hand-back; the detail waits in a file it reads when it reviews.
|
|
98
|
+
if (actor.kind === 'lane' && storyOfBranch(currentBranch(root))) {
|
|
99
|
+
const report = reportPath(root);
|
|
100
|
+
if (!existsSync(join(root, report)))
|
|
101
|
+
blockCounted(
|
|
102
|
+
`Write your full report to ${report} before you finish: what you did and why, the spec section, the commands you ran with their output, what's left, and anything you need decided (with the choices, and any text you'd have pasted, such as a migration you can't write yet). Then finish with a short hand-back of at most ten lines: the story and branch, done or blocked, any decision the lead must make, and that report's path. Don't paste output or code into the hand-back; the lead reads the file when it reviews.`,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
95
105
|
passed();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@warren-dean/code-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.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
|
@@ -13,7 +13,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
|
|
|
13
13
|
|
|
14
14
|
`requests --json` lists each open request with its number (`n`), the lane, what it asked for (`names`, `what`), and whose decision it is (`by`). The argument, if given, names the numbers to take. Take every request `by: "lead"`. A request `by: "person"` is theirs: see step 4.
|
|
15
15
|
|
|
16
|
-
For each, read the lane's change request (its
|
|
16
|
+
For each, read the lane's change request (its report, in `.claude/state/reports/<branch>.md` in its worktree), its story in the plan, and the requirements the story cites, in the specs.
|
|
17
17
|
|
|
18
18
|
## 2. Judge it
|
|
19
19
|
|
package/skills/dispatch/SKILL.md
CHANGED
|
@@ -89,4 +89,4 @@ Give them the same brief. Claude Code opened in that worktree then acts as the l
|
|
|
89
89
|
|
|
90
90
|
- Set each dispatched story's `**Status:**` in the plan to `in progress`, and commit it on the lead's branch.
|
|
91
91
|
- Tell the person, in a few lines: what was dispatched, to which lane and branch, what's still blocked and on what, and what's ready next.
|
|
92
|
-
- As each agent finishes, read its report. If it came back with a change request or a question, decide it yourself with `/code-kit:decide`, and bring to the person only what crosses a guardrail. If it came back done, run the review skill on its branch.
|
|
92
|
+
- As each agent finishes, read its hand-back: a few lines saying done or blocked, and the path of its full report (`.claude/state/reports/<branch>.md`). Open the report only when you need its detail: in the review, or to decide what it asks. If it came back with a change request or a question, decide it yourself with `/code-kit:decide`, and bring to the person only what crosses a guardrail. If it came back done, run the review skill on its branch.
|
package/skills/review/SKILL.md
CHANGED
|
@@ -14,6 +14,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`. `<base>` is the bran
|
|
|
14
14
|
- **The branch and its story.** `status --json` lists each story with its branch, its commits ahead of the base, and its worktree, if one is checked out. For a pull request, `gh pr view <n> --json headRefName,baseRefName` gives both.
|
|
15
15
|
- **Where to run things.** Use the branch's worktree if it has one. Otherwise check it out in a throwaway worktree: `git worktree add .claude/worktrees/review-st-<n> <branch>`, and remove it when you're done.
|
|
16
16
|
- **The spec-check report** is in that worktree, in `.claude/state/spec-check/<branch with / as _>.md`. The state folder isn't committed, so a branch pushed from elsewhere may not have one. Say so, and review against the specs directly.
|
|
17
|
+
- **The lane's report** is beside it, in `.claude/state/reports/<branch with / as _>.md`: what it did, the commands it ran with their output, and what's left. Its hand-back to you was a few lines naming this file; read the file here, not before, and only the parts the review needs.
|
|
17
18
|
|
|
18
19
|
## 2. Run the rules
|
|
19
20
|
|
package/templates/agent.md
CHANGED
|
@@ -29,4 +29,6 @@ Always:
|
|
|
29
29
|
- Fixing a bug: first write a test that fails because of the bug, through the code that's already there, then fix it. `verify` runs your test without the fix, and it must fail on an assertion, not because it calls something the fix adds.
|
|
30
30
|
- Never weaken a test to get to green: no deleting, skipping or focusing tests, cutting cases or assertions, or rewriting snapshots. The commit is refused without the person's approval. Fix the code; if the test itself is wrong, say why in a change request for the lead.
|
|
31
31
|
- Commit your work on your branch before finishing; the stop hook runs the checks and requires it.
|
|
32
|
-
-
|
|
32
|
+
- Don't message the lead while you work: it hears from you once, when you finish. If you're blocked on something only the lead or the person can settle, finish and say so.
|
|
33
|
+
- Before you finish, write your full report to `.claude/state/reports/<branch>.md` (the branch with `/` as `_`, as for spec-check): what you did and why, the spec section, the commands you ran with their output, what's left, and anything you need decided, with the choices and any text you'd otherwise paste. The stop hook requires it.
|
|
34
|
+
- Finish with a short hand-back, at most ten lines: the story and branch, done or blocked, any decision the lead must make, and the report's path. No output or code in it: the lead reads the report when it reviews.
|