@warren-dean/code-kit 0.25.0 → 0.26.1

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.
Files changed (41) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHANGELOG.md +24 -0
  4. package/README.md +70 -59
  5. package/bin/code-kit.mjs +113 -3
  6. package/hooks/act.mjs +96 -0
  7. package/hooks/guard-bash.mjs +27 -1
  8. package/hooks/hooks.json +42 -1
  9. package/hooks/lib/config.mjs +26 -2
  10. package/hooks/lib/events.mjs +626 -0
  11. package/hooks/lib/harness.mjs +8 -0
  12. package/hooks/lib/instructions.mjs +1 -1
  13. package/hooks/lib/next.mjs +22 -0
  14. package/hooks/lib/plan.mjs +45 -9
  15. package/hooks/lib/publish.mjs +144 -0
  16. package/hooks/lib/queue.mjs +36 -0
  17. package/hooks/lib/snapshot.mjs +33 -3
  18. package/hooks/lib/storymap.mjs +54 -17
  19. package/hooks/lib/timeline.mjs +94 -44
  20. package/hooks/lib/worktrees.mjs +19 -11
  21. package/hooks/mod/art.mjs +0 -81
  22. package/hooks/mod/board.mjs +1743 -0
  23. package/hooks/mod/characters.mjs +516 -0
  24. package/hooks/mod/loop.mjs +17 -3
  25. package/hooks/mod/mission.mjs +2 -93
  26. package/hooks/mod/panes.mjs +111 -422
  27. package/hooks/mod/register.mjs +482 -184
  28. package/hooks/mod/surface/character.mjs +79 -0
  29. package/hooks/mod/surface/clock.mjs +37 -0
  30. package/hooks/mod/surface/rail.mjs +33 -0
  31. package/hooks/mod/view.mjs +30 -602
  32. package/hooks/session.mjs +14 -11
  33. package/package.json +2 -1
  34. package/skills/decide/SKILL.md +1 -1
  35. package/skills/dispatch/SKILL.md +1 -1
  36. package/skills/init/SKILL.md +1 -1
  37. package/skills/next/SKILL.md +1 -1
  38. package/skills/review/SKILL.md +1 -1
  39. package/templates/agent.md +1 -1
  40. package/templates/claude-md.md +2 -2
  41. package/hooks/mod/register.test.ts +0 -4932
package/hooks/session.mjs CHANGED
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  // SessionStart and SessionEnd (docs/specs/23-the-team.md): a session starting is recorded as a member
3
3
  // of the team, the lead session when no other live session leads (SESS-2), and the worktrees done with
4
- // are pruned (docs/specs/20-lean-lead.md, LEAN-8); as it ends, it leads nothing more, and the lanes its
4
+ // are pruned (docs/specs/20-lean-lead.md, LEAN-8) and the acts a stopped agent left open reconciled
5
+ // (docs/specs/26-durable-lanes.md, DUR-4); as it ends, it leads nothing more, and the lanes its
5
6
  // agents had claimed are free again (SCHED-1). Its task stays, stale (SESS-4).
6
7
  import { spawn } from 'node:child_process';
7
8
  import { readFileSync } from 'node:fs';
@@ -24,16 +25,18 @@ if (config && session && process.argv[2] === 'start') {
24
25
  startSession(project, session);
25
26
  // LEAN-8: the worktrees left done with since the last session go, in the background: a project with
26
27
  // many of them never holds up a session's start.
27
- spawn(
28
- process.execPath,
29
- [
30
- fileURLToPath(new URL('../bin/code-kit.mjs', import.meta.url)),
31
- 'worktrees',
32
- 'prune',
33
- '--quiet',
34
- ],
35
- { cwd: project, detached: true, stdio: 'ignore' },
36
- ).unref();
28
+ const cli = fileURLToPath(new URL('../bin/code-kit.mjs', import.meta.url));
29
+ spawn(process.execPath, [cli, 'worktrees', 'prune', '--quiet'], {
30
+ cwd: project,
31
+ detached: true,
32
+ stdio: 'ignore',
33
+ }).unref();
34
+ // DUR-4: what an agent left open when the last session stopped is checked against git, in the background.
35
+ spawn(process.execPath, [cli, 'reconcile'], {
36
+ cwd: project,
37
+ detached: true,
38
+ stdio: 'ignore',
39
+ }).unref();
37
40
  }
38
41
  if (config && session && process.argv[2] === 'end') {
39
42
  endSession(project, session);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.25.0",
3
+ "version": "0.26.1",
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",
@@ -25,6 +25,7 @@
25
25
  "files": [
26
26
  "bin",
27
27
  "hooks",
28
+ "!hooks/**/*.test.ts",
28
29
  "skills",
29
30
  "templates",
30
31
  ".claude-plugin",
@@ -53,7 +53,7 @@ For each, read the lane's change request (its report, in `.claude/state/reports/
53
53
 
54
54
  ## 4. The person's requests
55
55
 
56
- A request `by: "person"` is a guardrail the lane hit: a spec, a contract, a design, CI, or a weakened test. Check the lane really needs it first: often the story can be done inside the guardrail, and you tell the lane how and drop the request. If it does need it, the request is already in the person's Decisions tab. Add your recommendation with `ask` when the choice isn't obvious from the request alone.
56
+ A request `by: "person"` is a guardrail the lane hit: a spec, a contract, a design, CI, or a weakened test. Check the lane really needs it first: often the story can be done inside the guardrail, and you tell the lane how and drop the request. If it does need it, the request is already waiting for the person, in their band and the pane's Needs you. Add your recommendation with `ask` when the choice isn't obvious from the request alone.
57
57
 
58
58
  ## 5. Report
59
59
 
@@ -48,7 +48,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team claim ST-<n> --lease "<glob>,
48
48
 
49
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.
50
50
 
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 and "Read your earlier report first: `.claude/state/reports/<branch with / as _>.md` in the main checkout". A long-lived agent rereads its whole context on every step, which is most of what a build costs.
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
 
53
53
  Start each story with the Agent tool: `subagent_type` is the lane's agent, `model` the one `code-kit next --json` gives the story in `models` (with the lane model `story`, each story's model follows its `**Size:**`, raised for a security requirement, a fix or a send-back; a story with no size runs on Sonnet, so size it in the plan first if it's plainly small or large), `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Start every story in the batch in the same message so they run in parallel.
54
54
 
@@ -76,7 +76,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
76
76
  - **`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 three 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), or `off`. 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.
77
77
  - **`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.
78
78
  - **`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.
79
- - **`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 Decisions tab: 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.
79
+ - **`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.
80
80
  - **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
81
81
  - **`approvals.lead`:** ask the person whether they'll ever approve from a phone or another chat-only client, where a `!` command arrives as plain text. If so, set it to `true`: the lead then records approvals they give in chat (`code-kit approve`), and runs the `shell.block` commands marked `person: true` when they say so. Mark a `shell.block` command `person: true` only if the person wants to be able to have the lead run it on their say-so. Leave the setting out if the lead will run unattended.
82
82
 
@@ -59,7 +59,7 @@ After a step finishes, run `next --json` again and carry on with the new step, w
59
59
  - the step is `wait` or `done`;
60
60
  - the same step comes back twice in a row with nothing changed. Report what's stuck instead of looping.
61
61
 
62
- **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 Decisions tab, where it waits until they answer instead of scrolling away:
62
+ **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:
63
63
 
64
64
  ```
65
65
  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" ask "<the question, in a sentence>" [--story ST-n --blocks] [--why "<why you can't settle it>"] --option "<choice>: <what it does>" --option "…"
@@ -77,7 +77,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
77
77
  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue add <branch>
78
78
  ```
79
79
 
80
- 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.
80
+ 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.
81
81
 
82
82
  - **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:
83
83
 
@@ -30,7 +30,7 @@ Always:
30
30
  - 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.
31
31
  - 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.
32
32
  - Run the narrowest tests that prove each step, with failures only in the output (a quiet reporter, or `| tail -40` on failure); run the full suite once, before you commit. Long output stays in your context and is paid for on every step after it.
33
- - Commit your work on your branch before finishing; the stop hook runs the checks and requires it.
33
+ - Commit after each step whose tests pass, not once at the end, so a crash loses at most the step you're on; and commit your work before finishing: the stop hook runs the checks and requires it.
34
34
  - 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.
35
35
  - One story per agent. If you're asked to wrap up because your context is large, finish the step you're on, commit, write your report and hand back: a fresh agent carries the story on from your report.
36
36
  - 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.
@@ -10,7 +10,7 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
10
10
  - {{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
11
  - the project's checks before any agent finishes.
12
12
 
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 Decisions tab, 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.
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
14
 
15
15
  {{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
16
 
@@ -30,6 +30,6 @@ 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
- 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.
33
+ 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
34
 
35
35
  Changing the rules means editing `.claude/code-kit.json` (the lead only), then running the `code-kit:check` skill.