Working on code-kit

code-kit is a Claude Code plugin: hooks (hooks/), skills (skills/<name>/SKILL.md), templates (templates/) and a command line (bin/code-kit.mjs). It's plain Node ESM with no dependencies and no build step. Node 22 or later.

Layout

• hooks/*.mjs: one file per hook event, wired in hooks/hooks.json (guard-agent.mjs claims a lane as its agent starts, and notes the lane for worktree-create.mjs, which gives a lane agent its lane's worktree; worktree-done.mjs takes away an unchanged agent's own worktree as it stops; session.mjs records a session as the lead or a working one as it starts, and frees its lanes as it ends; lead-prompt.mjs makes a session the lead, of the stream named, when the person types /code-kit:lead [stream]). Each reads the tool call from stdin, and exits 2 with a message to refuse it. act.mjs writes the event log: each tool call before and after it runs, and a lane agent handing back (spec 26).
• hooks/lib/: the shared rules.
  • rules.mjs: who may write where;
  • config.mjs: loading and validation;
  • layers.mjs: imports;
  • dependencies.mjs: the packages a command adds, and the files installing them changes;
  • registry.mjs: what the npm registry says about a package, for delegated approvals;
  • security.mjs: which branches the security reviewer looks at, and why (spec 17, ONB-7);
  • regression.mjs: weakened tests, and whether a fix's tests prove its bug (spec 18, REG-1 and REG-2);
  • testfiles.mjs: what counts as a test, for every rule that asks, and which tests a fix's proof keeps (spec 18);
  • harness.mjs: the harness settings; queue.mjs: the merge queue, and the lead's pause of it (MQ-8); deferrals.mjs: the stories the lead holds on purpose (LOOP-15); loop-state.mjs: whether the loop is paused, and which session runs it; storymap.mjs: a story's code by layer, and each requirement's trail; timeline.mjs: when each story's work happened; instructions.mjs: code-kit's own part of CLAUDE.md and the lane agents, rendered from the templates and kept current (spec 17, ONB-8); journal.mjs: the build's lineage, from the request to each merge; team.mjs: the team in the config, who the developer is, the team provider (GitHub's built in) and the team's rules for the hooks (spec 16); teamfacts.mjs: the pure parts the mod shares;
  • laneclaims.mjs: which lane is running which story, one each across every session (spec 23, SCHED-1); schedule.mjs: one story for each free lane, the open slice's first (SCHED-1, SCHED-2), and the model its size gives (SCHED-3); dispatches.mjs: each story's model from the plan, the specs and the reviews, and the log of what each lane agent started on (SCHED-3); decisionstore.mjs: the decisions waiting on the person, each owned by the session that raised it (OWN-1 to OWN-4); sessions.mjs: the sessions working the project, which one leads, each one's task and what it wrote in the shared checkout (SESS-1 to SESS-5); worktrees.mjs: the project's worktrees, why each stays, and taking away the ones done with (spec 20, LEAN-6 and LEAN-8); lanetrees.mjs: one worktree per lane, reused by each of its stories (LEAN-10);
  • standards.mjs: the project's standards, merged with an organisation's, what's wrong with them, which standard a refusal's rule is, and what weakens them (spec 22); snapshot.mjs: what a project reports to its team provider, and the allow-list a report is checked against (spec 21);
  • events.mjs: the event log of every act, per story, its replay, reconciling what a stopped agent left open, and the hand-over brief (spec 26, DUR-1 to DUR-6); publish.mjs: what's merged, put onto the remote's base, pushed or as a pull request (MQ-6);
  • designs.mjs: the design register's approved designs as files, every state with its hash, and what's wrong with an entry (spec 24, HAND-1 to HAND-5);
  • checkout.mjs: a fresh checkout for checks that mustn't run in anyone's worktree (the queue's merged tree, the fix check's), with its own copy of the installs, and the install run there when its manifests or lockfiles differ from them (MQ-1, REG-1);
  • ci.mjs: what the project's workflows run per story, what its Actions runs cost, and the release branch the full CI runs on (spec 25);
  • costs.mjs: the running budget, the cost register read against it, and what takes an environment past it (spec 29);
  • checks.mjs, verify.mjs, plan.mjs, trace.mjs, next.mjs (what to do next, including companions to set up and designs before screens, spec 17);
  • streams.mjs: the project's streams, a lead and lanes each, core and modules, the shared core lanes' turns, and change requests to core (spec 31, STRM-1 to STRM-8), with streamconfig.mjs checking the config's streams; promote.mjs: module code that belongs in core, from clones by tokens, refused imports, copies and repeated requirements, and the platform lead's decisions (PROM-1 to PROM-4);
  • adapters/: tools that share a project, such as Context Graph.
• hooks/mod/: the mod, for Claude Code 2.1.287 or later: register.mjs (its hooks and the person's acts), and what it draws and decides, as pure functions:
  • board.mjs: the pane of panels (Build, Needs you, Lanes, Queue, Log), the band, the keys, the layouts and the one table of state words, colours and glyphs (spec 27);
  • characters.mjs: each lane's character from its name, in every pose and move; surface/: the surface modules that animate on the surface's own frame clock (character.mjs, clock.mjs, rail.mjs);
  • view.mjs (the project's state and the band's lines), panes.mjs (the full views: a story, the Trail, the Code map, the Decide pane and the Journal), art.mjs (half-block cells and the timelines), loop.mjs, hold.mjs, review.mjs, mission.mjs (the milestone and the next step), codemap.mjs (the code map), trail.mjs (the trail), decisions.mjs (each decision that needs the person, with its lineage and how it's answered in the Decide pane), teamview.mjs (the team's band lines and the Team pane), streamview.mjs (a stream lead's views scoped to its own stream, and a line per other stream, STRM-10);
  • register.test.ts (run by claude plugin test, through test/mod.mjs). It reads the CLI's JSON and never enforces anything.
• bin/code-kit.mjs: the CLI (check, who, unowned, diff, baseline, graph, verify, security, status, next, instructions, standards, worktrees, adapters, trace, approve, merge, defer, requests, stops, sent-back, settings, lanes, sessions, task, decisions, hold, queue, story, timeline, loop, map, trail, journal, team, intend, ci, cost, release, publish, replay, reconcile, streams, core, promote).
• skills/: instructions for Claude, not code. They call the CLI as node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs".
• test/units.test.mjs (pure functions), test/hooks.test.mjs (every hook end to end in throwaway git repositories), test/fixture.json (the config they use), test/mod.mjs (the mod's tests, skipped on older Claude Code).

Rules

• Run npm test before finishing. Every behaviour change gets an end-to-end check in test/hooks.test.mjs.
• Format with Prettier (npx prettier --check .).
• The core never names another tool: tool-specific rules belong in hooks/lib/adapters/.
• Refusals say why, and what to do instead, in plain sentences an agent can act on.
• Keep the README's config table and CLI list in step with the code.
• When the instructions change (templates/claude-md.md, templates/agent.md or the facts that fill them), raise INSTRUCTIONS_VERSION. A session on an older code-kit relies on it to leave a newer one's instructions alone; test/units.test.mjs fails until it's raised.
• Every release adds an entry at the top of CHANGELOG.md: the version, the date, and what changed for someone using code-kit, in plain sentences. The GitHub Release notes use the same text.