@warren-dean/code-kit 0.10.0 → 0.11.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.
Files changed (16) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHANGELOG.md +9 -0
  4. package/README.md +30 -28
  5. package/bin/code-kit.mjs +90 -2
  6. package/hooks/guard-bash.mjs +8 -0
  7. package/hooks/lib/team.mjs +62 -7
  8. package/hooks/mod/decisions.mjs +3 -0
  9. package/hooks/mod/panes.mjs +42 -49
  10. package/hooks/mod/register.mjs +104 -12
  11. package/hooks/mod/register.test.ts +255 -15
  12. package/hooks/mod/teamview.mjs +469 -74
  13. package/hooks/mod/view.mjs +14 -2
  14. package/package.json +1 -1
  15. package/skills/init/SKILL.md +2 -1
  16. package/skills/team-init/SKILL.md +59 -0
package/.claude-plugin/marketplace.json CHANGED
@@ -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.10.0",
12
+ "version": "0.11.0",
13
13
  "category": "development",
14
14
  "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
15
15
  "license": "MIT"
package/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "code-kit",
3
- "version": "0.10.0",
3
+ "version": "0.11.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.11.0 (2026-10-12)
6
+
7
+ Teams get their own pane and their own setup, and a hosted team provider can stand down to GitHub.
8
+
9
+ - **`/team` opens the Team pane.** It replaces the Lanes pane's Team tab. Its header names the tech lead, you, and what coordinates the team (GitHub, or a hosted provider, and whether it's live). Its tabs: People (who's at work on what), Since you looked, Claims (Keep and Release on yours; Release and Reassign for the tech lead), Intents (Agree and Drop for the tech lead), Drift (with a provider that checks for it) and Setup (the team's config and what GitHub still needs). A Team button in the band opens it on the tab its line is about.
10
+ - **Set up a team only when there is one.** `/code-kit:team-init` asks for the tech lead, each lane's owners, when a claim goes stale and where intents go, shows the team section, and writes it once you agree; it also changes a team or takes it out. `/code-kit:init` asks once whether other developers work in the repository and runs it only if they do. Behind it, `code-kit team init` (`--write` to write, `--off` for one developer again) says what GitHub still needs: gh signed in, the repository reachable, and the intents' discussion category. A lane agent can't write it.
11
+ - **A hosted provider can fall back to GitHub.** With `team.provider: { command, fallback: "github" }`, whatever the provider can't reach goes through GitHub's claim refs instead, and the band says GitHub is standing in. A live provider's state refreshes the band and the pane as it changes, and its presence and drift findings show in the pane, with drift on your own work in the band.
12
+ - **Two band lines with the same button no longer clash.** Each button and row keeps its own key.
13
+
5
14
  ## 0.10.0 (2026-10-12)
6
15
 
7
16
  An older setup is brought up to date before new work starts, and a security reviewer checks the changes that need one.
package/README.md CHANGED
@@ -288,7 +288,7 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
288
288
 
289
289
  Each button has a digit: type it in an empty prompt to press it.
290
290
 
291
- - **`/lanes`** opens the Lanes pane. Its first line counts the stories by state (building, in review, queued, sent back, blocked, ready, merged), with the loop's state and the plan's 5-hour use; press a count to show only those lanes. Beneath it, whatever needs you (held calls, approvals, reviews, merges, stalled lanes, outliers) is pinned with its key. Tabs on **1** to **8**: **Lanes** opens on the loop as a card: its mode, the steps it took, the one running and the next. Then each lane on fixed columns: its name, state and story, its agent's current or last tool call with the time since beneath (amber once quiet, red when stalled), and its tokens; the lead reads orchestrating while its turn runs. A selected lane shows its stories as cards (state, requirements, what each waits on or its branch), then its agent and the paths it owns. **Decisions**, each decision that needs you as a card: what you asked for, the story and its requirements, what was happening, what's already settled, why the lead couldn't settle it, and each option with what it does; **Team** (8, in a team's project): since you last looked, then each person with the lanes they own, their claims (stale ones marked, Keep or Release for yours), pull requests and intents (Agree or Drop for the tech lead); **Journal**, the build from your request to now in plain sentences, by day: the request and the decisions in the brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session, yours in yellow. Each lane has its own small pixel character, tinted in the lane's colour, whose pose shows its state: working (animated while its agent works), waiting on you, quiet, stalled, done or resting; the lead's wears a crown. Under each lane, its story's timeline on a shared time axis: building, then in review, with send-backs (↩), approvals (◆) and the merge (✓) marked where they fell; **Code map**, the whole project's folders by layer when no story is at work, or a story's files in a column per layer with the imports between them: a file fills with a lane's colour while that lane reads or edits it, and says whether its why (its Context Graph card) is written, out of date or not written yet; **j**/**k** select a file to see its card and what it imports and what imports it, and **o** opens it in Context Graph (box-drawing text in the terminal, an SVG on Desktop); **Trail**, every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, the code they changed and the tests that name it; beneath the cells, the spec's trail drawn as a flow, each requirement to its stories, code and tests, with a missing link dashed in red; **Queue**, the merge queue; and **Usage**. **j** and **k** move between lanes, and the selected lane's acts are on **a** (approve), **r** (review), **s** (send back, with your reason), **m** (merge), **n** (nudge its agent) and **x** (stop it); **p** pauses or resumes the loop, and **f** filters the lanes by name, agent or story. **Enter** (or **o**) opens the selected lane's story: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, and its diff against the base, file by file, with the acts its state allows. **b** or Escape goes back to the lanes. Inline (when the terminal can't dock it beside the transcript), it shows the counts, what needs you and a line per lane. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
291
+ - **`/lanes`** opens the Lanes pane. Its first line counts the stories by state (building, in review, queued, sent back, blocked, ready, merged), with the loop's state and the plan's 5-hour use; press a count to show only those lanes. Beneath it, whatever needs you (held calls, approvals, reviews, merges, stalled lanes, outliers) is pinned with its key. Tabs on **1** to **7**: **Lanes** opens on the loop as a card: its mode, the steps it took, the one running and the next. Then each lane on fixed columns: its name, state and story, its agent's current or last tool call with the time since beneath (amber once quiet, red when stalled), and its tokens; the lead reads orchestrating while its turn runs. A selected lane shows its stories as cards (state, requirements, what each waits on or its branch), then its agent and the paths it owns. **Decisions**, each decision that needs you as a card: what you asked for, the story and its requirements, what was happening, what's already settled, why the lead couldn't settle it, and each option with what it does; **Journal**, the build from your request to now in plain sentences, by day: the request and the decisions in the brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session, yours in yellow. Each lane has its own small pixel character, tinted in the lane's colour, whose pose shows its state: working (animated while its agent works), waiting on you, quiet, stalled, done or resting; the lead's wears a crown. Under each lane, its story's timeline on a shared time axis: building, then in review, with send-backs (↩), approvals (◆) and the merge (✓) marked where they fell; **Code map**, the whole project's folders by layer when no story is at work, or a story's files in a column per layer with the imports between them: a file fills with a lane's colour while that lane reads or edits it, and says whether its why (its Context Graph card) is written, out of date or not written yet; **j**/**k** select a file to see its card and what it imports and what imports it, and **o** opens it in Context Graph (box-drawing text in the terminal, an SVG on Desktop); **Trail**, every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, the code they changed and the tests that name it; beneath the cells, the spec's trail drawn as a flow, each requirement to its stories, code and tests, with a missing link dashed in red; **Queue**, the merge queue; and **Usage**. **j** and **k** move between lanes, and the selected lane's acts are on **a** (approve), **r** (review), **s** (send back, with your reason), **m** (merge), **n** (nudge its agent) and **x** (stop it); **p** pauses or resumes the loop, and **f** filters the lanes by name, agent or story. **Enter** (or **o**) opens the selected lane's story: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, and its diff against the base, file by file, with the acts its state allows. **b** or Escape goes back to the lanes. Inline (when the terminal can't dock it beside the transcript), it shows the counts, what needs you and a line per lane. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
292
292
  - **Refusals** a code-kit hook gives an agent are drawn as cards: what was refused, the rule, what to do, and Approve… where your approval would allow it. The full text is a press away.
293
293
  - **`/harness`** opens the harness settings: how the lead loop acts, how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, and the use at which background agents pause. Changing one asks your reason, writes `.claude/code-kit.json` and logs a `kit` approval. Lanes, paths and rules still change through `/code-kit:init`.
294
294
  - **`/approvals`** lists the requests waiting and the approvals in force, with minutes left. **`/verify-branch`** runs `code-kit verify` on this branch. Neither calls the model.
@@ -311,11 +311,12 @@ Once init has switched the rules on, the lead runs the build in a loop:
311
311
 
312
312
  ## Teams (preview)
313
313
 
314
- For several people in one repository, each with their own agents. Add `"team": { "techLead": "<GitHub handle>" }` to the config, and owners to the lanes people own. Everything goes through GitHub; there's no server:
314
+ For several people in one repository, each with their own agents. Not every developer works in a team, so it's off until you set it up: `/code-kit:init` asks whether others work in the repository, and `/code-kit:team-init` sets the team up (or changes it, or takes it out) at any time, asking for the tech lead and each lane's owners and showing what it writes first. Everything goes through GitHub; there's no server:
315
315
 
316
316
  - **Owners and claims.** A lane's owners are the only ones whose agents work it. Making a story's branch claims the story, through a ref in the shared repository, so two people can't both take it. The lead says what files the story will change (`team claim --lease`), and each commit adds what it changed; another person's agent editing a leased file is refused with who holds it.
317
317
  - **The tech lead's paths.** Only the tech lead's sessions change the plan, specs and contracts. Anyone else raises an **intent** (`code-kit intend`), a discussion in the repository's Intents category, before any code. The tech lead agrees, drops or marks it a duplicate; an agreed one becomes a numbered decision record (`code-kit intend record`) through a pull request, where every agent reads it.
318
- - **Since you last looked.** `code-kit team since` says, by person, what was pushed, opened, merged, reviewed, claimed and intended. The Team tab shows it, then each person's lanes, claims, pull requests and intents.
318
+ - **Since you last looked.** `code-kit team since` says, by person, what was pushed, opened, merged, reviewed, claimed and intended. The Team pane shows it.
319
+ - **`/team`** opens the Team pane: the tech lead, who you are, and what coordinates the team (GitHub, or a hosted provider, and whether it's live). Its tabs: **People**, each person with their lanes, where they're at work (with a live provider), claims, pull requests and intents; **Since you looked**; **Claims**, with Keep and Release on yours, and Release and Reassign for the tech lead; **Intents**, with Agree and Drop for the tech lead; **Drift**, when the provider checks for it; and **Setup**, the team's config and what GitHub still needs.
319
320
  - **Stale claims** (nothing pushed for three working days) are flagged, never released on their own: the holder keeps or releases it, and the tech lead can reassign it.
320
321
  - **GitHub does its part.** `code-kit team codeowners --write` writes CODEOWNERS from the config, and `"board": { "owner", "number" }` mirrors the plan onto a GitHub Project.
321
322
 
@@ -373,6 +374,7 @@ code-kit timeline [--json] # when each story'
373
374
  code-kit journal [--json] # the build's lineage: the request, its decisions, the spec, each story handed out, sent back and merged, each approval and who gave it
374
375
  code-kit team [--json] [--fresh] # the team (preview): tech lead, owners, claims, intents and open pull requests (spec 16)
375
376
  code-kit team since [--json] [--peek] # what everyone pushed, opened, merged, reviewed, claimed and intended since you last looked
377
+ code-kit team init --tech-lead <handle> [--owner <lane>=<handles>] [--stale-days n] [--intents category] [--write] | team init --off [--write] # show, then write, the team's setup; or make the project one developer's again
376
378
  code-kit team claim <story> [--lease globs] | team release <story> # claim a story for yourself, leasing what it changes; release it (yours, or any as the tech lead)
377
379
  code-kit team keep <story> | team reassign <story> <handle> # keep your stale claim (its clock starts again); the tech lead hands a claim to someone else
378
380
  code-kit team codeowners [--write] # .github/CODEOWNERS from the config: the tech lead for their paths, each lane's owners for its paths
@@ -393,31 +395,31 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pan
393
395
 
394
396
  `.claude/code-kit.json`. Globs use `*` (one segment), `**` (any depth), `**/` (zero or more folders), `?` and `{a,b}`. Patterns under `shell` are regular expressions.
395
397
 
396
- | Field | Required | What it is |
397
- | ------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
398
- | `version` | yes | `1` |
399
- | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
400
- | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
401
- | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
402
- | `lead.paths` | yes | What the main session writes. `.claude/**` is always added. |
403
- | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included. |
404
- | `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. |
405
- | `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. |
406
- | `protected[]` | no | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs a person's approval (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`. |
407
- | `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 |
408
- | `layers[]` | no | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself. |
409
- | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
410
- | `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 |
411
- | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes |
412
- | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
413
- | `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). |
414
- | `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). |
415
- | `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). |
416
- | `approvals.delegate` | no | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: approvals the lead may grant on its own, with `code-kit approve --delegated`, and with `merge`, merges into a protected branch with `code-kit merge --delegated`. Dependencies are checked against the npm 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). |
417
- | `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 |
418
- | `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 }` for another team provider. See docs/specs/16-teams.md. |
419
- | `branches.protected` | no | Default `["main", "master"]` |
420
- | `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), and `background.pauseAtPercent` (default 80). Change them with `/harness` or `code-kit settings set`. |
398
+ | Field | Required | What it is |
399
+ | ------------------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
400
+ | `version` | yes | `1` |
401
+ | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
402
+ | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
403
+ | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
404
+ | `lead.paths` | yes | What the main session writes. `.claude/**` is always added. |
405
+ | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included. |
406
+ | `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. |
407
+ | `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. |
408
+ | `protected[]` | no | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs a person's approval (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`. |
409
+ | `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 |
410
+ | `layers[]` | no | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself. |
411
+ | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
412
+ | `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 |
413
+ | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes |
414
+ | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
415
+ | `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). |
416
+ | `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). |
417
+ | `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). |
418
+ | `approvals.delegate` | no | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: approvals the lead may grant on its own, with `code-kit approve --delegated`, and with `merge`, merges into a protected branch with `code-kit merge --delegated`. Dependencies are checked against the npm 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). |
419
+ | `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 |
420
+ | `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. |
421
+ | `branches.protected` | no | Default `["main", "master"]` |
422
+ | `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), and `background.pauseAtPercent` (default 80). Change them with `/harness` or `code-kit settings set`. |
421
423
 
422
424
  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.
423
425
 
package/bin/code-kit.mjs CHANGED
@@ -120,7 +120,21 @@ const minutesGiven = option('--minutes');
120
120
  const answerGiven = option('--answer');
121
121
  const leaseGiven = option('--lease');
122
122
  const touchesGiven = option('--touches');
123
- const FLAGS = ['--write', '--no-checks', '--json', '--delegated', '--person', '--fresh', '--peek'];
123
+ const techLeadGiven = option('--tech-lead');
124
+ const staleDaysGiven = option('--stale-days');
125
+ const intentsGiven = option('--intents');
126
+ const ownersGiven = [];
127
+ for (let o = option('--owner'); o !== undefined; o = option('--owner')) ownersGiven.push(o);
128
+ const FLAGS = [
129
+ '--write',
130
+ '--no-checks',
131
+ '--json',
132
+ '--delegated',
133
+ '--person',
134
+ '--fresh',
135
+ '--peek',
136
+ '--off',
137
+ ];
124
138
  const flag = (name) => args.includes(name);
125
139
  const writeBaseline = flag('--write');
126
140
  const [command, ...rest] = args.filter((a) => !FLAGS.includes(a));
@@ -1310,6 +1324,7 @@ function ago(iso) {
1310
1324
  */
1311
1325
  function teamCommand() {
1312
1326
  const { raw } = load();
1327
+ if (rest[0] === 'init') return teamInit(raw);
1313
1328
  const team = teamOf(raw);
1314
1329
  if (!team)
1315
1330
  die(
@@ -1431,7 +1446,7 @@ function teamCommand() {
1431
1446
  }
1432
1447
  if (sub !== undefined)
1433
1448
  die(
1434
- 'code-kit team [--json] [--fresh] | team since [--json] [--peek] | team claim|keep|release <story> | team reassign <story> <handle>',
1449
+ 'code-kit team [--json] [--fresh] | team init … | team since [--json] [--peek] | team claim|keep|release <story> | team reassign <story> <handle>',
1435
1450
  );
1436
1451
  const state = provider.state({ fresh: flag('--fresh') });
1437
1452
  if (flag('--json')) return out(JSON.stringify(state, null, 2));
@@ -1462,6 +1477,78 @@ function teamCommand() {
1462
1477
  out(` #${p.number} ${p.title} (${p.by}, ${p.branch}${p.draft ? ', draft' : ''})`);
1463
1478
  }
1464
1479
 
1480
+ /**
1481
+ * TEAM-13: `team init` sets the project up as a team's, or (`--off`) as one developer's again. Without
1482
+ * `--write` it shows the team section it would write; with it, it writes the config and says what the
1483
+ * team still needs on GitHub (gh signed in, origin reachable, the intents' discussion category).
1484
+ */
1485
+ function teamInit(raw) {
1486
+ const usage =
1487
+ 'code-kit team init --tech-lead <GitHub handle> [--owner <lane>=<handle>,<handle>]… [--stale-days <n>] [--intents <category>] [--write] [--json] | team init --off [--write]';
1488
+ const changed = structuredClone(raw);
1489
+ if (flag('--off')) {
1490
+ delete changed.team;
1491
+ for (const lane of Object.values(changed.lanes ?? {})) delete lane.owners;
1492
+ } else {
1493
+ const techLead = techLeadGiven ?? raw.team?.techLead;
1494
+ if (!techLead) die(usage);
1495
+ changed.team = { ...(raw.team ?? {}), techLead };
1496
+ if (staleDaysGiven !== undefined) changed.team.staleDays = Number(staleDaysGiven);
1497
+ if (intentsGiven !== undefined) changed.team.intents = intentsGiven;
1498
+ for (const given of ownersGiven) {
1499
+ const [lane, people = ''] = given.split('=');
1500
+ if (!changed.lanes?.[lane])
1501
+ die(
1502
+ `There's no lane "${lane}" in the config. The lanes are: ${Object.keys(changed.lanes ?? {}).join(', ') || 'none'}.`,
1503
+ );
1504
+ const handles = people
1505
+ .split(',')
1506
+ .map((h) => h.trim().replace(/^@/, ''))
1507
+ .filter(Boolean);
1508
+ if (handles.length) changed.lanes[lane].owners = handles;
1509
+ else delete changed.lanes[lane].owners;
1510
+ }
1511
+ }
1512
+ const problems = validate(changed);
1513
+ if (problems.length) die(`Nothing changed: ${problems.join('; ')}`);
1514
+ const team = teamOf(changed);
1515
+ const section = team
1516
+ ? {
1517
+ team: changed.team,
1518
+ owners: team.owners,
1519
+ }
1520
+ : null;
1521
+ if (!flag('--write')) {
1522
+ if (flag('--json')) return out(JSON.stringify({ written: false, ...section }, null, 2));
1523
+ if (!team)
1524
+ return out(
1525
+ 'This would take the team out of the config: one developer, no claims or owners. Run again with --write to do it.',
1526
+ );
1527
+ out(JSON.stringify({ team: changed.team }, null, 2));
1528
+ for (const [lane, owners] of Object.entries(team.owners))
1529
+ out(`lanes.${lane}.owners: ${owners.join(', ')}`);
1530
+ return out('Nothing is written yet: run again with --write.');
1531
+ }
1532
+ writeFileSync(resolve(file), `${JSON.stringify(changed, null, 2)}\n`);
1533
+ if (!team)
1534
+ return out(
1535
+ `Took the team out of ${file}: claims, owners and intents no longer apply. Commit it on a branch.`,
1536
+ );
1537
+ // What GitHub says now: the provider's own look at the repository.
1538
+ const state = teamProvider(resolve('.'), team).state({ fresh: true });
1539
+ const setup = state.setup ?? [];
1540
+ if (flag('--json'))
1541
+ return out(JSON.stringify({ written: true, ...section, me: state.me ?? null, setup }, null, 2));
1542
+ out(
1543
+ `Wrote the team to ${file}: ${team.techLead} is the tech lead; a claim is stale after ${team.staleDays} working day${team.staleDays === 1 ? '' : 's'} without a push; intents go in "${team.intents}".`,
1544
+ );
1545
+ for (const [lane, owners] of Object.entries(team.owners))
1546
+ out(`Lane ${lane}: ${owners.join(', ')}`);
1547
+ out(setup.length ? 'Still to set up:' : 'GitHub is ready for the team.');
1548
+ for (const s of setup) out(` ${s}`);
1549
+ out(`Commit ${file} on a branch; each teammate then needs code-kit and gh signed in.`);
1550
+ }
1551
+
1465
1552
  /**
1466
1553
  * TEAM-5: `intend "<what and why>" [--touches globs]` raises an intent before any code, so the team sees
1467
1554
  * a change of direction first; `intend agree|drop|duplicate <id> [--reason "…"]` is the tech lead's answer.
@@ -1586,6 +1673,7 @@ function usage() {
1586
1673
  ' | map <story>|project [--json] | trail [--json] | journal [--json]\n' +
1587
1674
  ' | story <id> [--json] | timeline [--json]\n' +
1588
1675
  ' | team [--json] [--fresh] | team since [--json] [--peek]\n' +
1676
+ ' | team init --tech-lead <handle> [--owner <lane>=<handles>] [--write] | team init --off [--write]\n' +
1589
1677
  ' | team claim <story> [--lease globs] | team keep|release <story>\n' +
1590
1678
  ' | team reassign <story> <handle> | team codeowners [--write] | team board\n' +
1591
1679
  ' | intend "<what and why>" [--touches globs] | intend agree|drop|duplicate <id> [--reason "…"] | intend record <id>',
package/hooks/guard-bash.mjs CHANGED
@@ -178,6 +178,14 @@ if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+intend\s+(agree|drop|duplicat
178
178
  block(
179
179
  `Blocked: agreeing or dropping an intent is the tech lead's own decision, from their terminal or the code-kit pane. Tell them what you'd recommend and why, and stop.\nCommand: ${cmd}`,
180
180
  );
181
+ // TEAM-13: setting the team up, or taking it out, rewrites the config: the lead's, once the person agrees.
182
+ if (
183
+ runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+team\s+init\b.*\s--write\b`)) &&
184
+ actor.kind !== 'lead'
185
+ )
186
+ block(
187
+ `Blocked: the team's setup is the lead's to write, once the person agrees (/code-kit:team-init). Tell the lead what you'd change, and stop.\nCommand: ${cmd}`,
188
+ );
181
189
  // The harness settings are the person's to change, from the pane or their terminal.
182
190
  if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+settings\s+set\b`)))
183
191
  block(
package/hooks/lib/team.mjs CHANGED
@@ -60,9 +60,16 @@ export function teamProblems(c) {
60
60
  if (
61
61
  t.provider !== undefined &&
62
62
  t.provider !== 'github' &&
63
- !(isObj(t.provider) && typeof t.provider.command === 'string' && t.provider.command.trim())
63
+ !(
64
+ isObj(t.provider) &&
65
+ typeof t.provider.command === 'string' &&
66
+ t.provider.command.trim() &&
67
+ (t.provider.fallback === undefined || t.provider.fallback === 'github')
68
+ )
64
69
  )
65
- p.push('"team.provider" must be "github" or { "command": "<the provider\'s command>" }');
70
+ p.push(
71
+ '"team.provider" must be "github" or { "command": "<the provider\'s command>", "fallback"?: "github" }',
72
+ );
66
73
  }
67
74
  for (const [name, lane] of Object.entries(isObj(c.lanes) ? c.lanes : {})) {
68
75
  if (!isObj(lane) || lane.owners === undefined) continue;
@@ -148,11 +155,44 @@ function claimOf(message) {
148
155
  }
149
156
  }
150
157
 
151
- /** The provider for this project's team: GitHub's, or the config's command. */
158
+ /**
159
+ * The provider for this project's team: GitHub's, or the config's command. A command with
160
+ * `fallback: "github"` (a hosted provider, such as the code-kit teams hub) hands each operation it
161
+ * can't reach to the GitHub provider, so claims are still checked while it's down (TEAM-8).
162
+ */
152
163
  export function teamProvider(root, team) {
153
- return team.provider === 'github'
154
- ? githubProvider(root, team)
155
- : commandProvider(root, team, team.provider.command);
164
+ if (team.provider === 'github') return githubProvider(root, team);
165
+ const command = commandProvider(root, team, team.provider.command);
166
+ if (team.provider.fallback !== 'github') return command;
167
+ const github = githubProvider(root, team);
168
+ const down = (r) => Boolean(r?.unreachable) || r?.reachable === false;
169
+ const either =
170
+ (op) =>
171
+ (...args) => {
172
+ const r = command[op](...args);
173
+ if (!down(r) && r !== null) return r;
174
+ const g = github[op](...args);
175
+ // The state says it came through GitHub, and why, for the band.
176
+ return op === 'state' && g
177
+ ? { ...g, fallback: r?.why ?? "The team provider can't be reached." }
178
+ : g;
179
+ };
180
+ return {
181
+ ...Object.fromEntries(
182
+ [
183
+ 'whoami',
184
+ 'claim',
185
+ 'release',
186
+ 'state',
187
+ 'intend',
188
+ 'settle',
189
+ 'reassign',
190
+ 'intent',
191
+ 'since',
192
+ ].map((op) => [op, either(op)]),
193
+ ),
194
+ forget: () => (command.forget(), github.forget()),
195
+ };
156
196
  }
157
197
 
158
198
  function githubProvider(root, team) {
@@ -402,11 +442,26 @@ function githubProvider(root, team) {
402
442
  'number,title,author,headRefName,isDraft,updatedAt,url',
403
443
  ]) ?? 'null',
404
444
  );
445
+ const who = me();
405
446
  const state = {
406
447
  at: new Date().toISOString(),
407
448
  reachable: Boolean(claims),
408
449
  github: Boolean(intents && pulls),
409
- me: me(),
450
+ me: who,
451
+ // What coordinates the team, for the Team pane: GitHub itself, through refs and discussions.
452
+ provider: {
453
+ name: 'GitHub',
454
+ live: false,
455
+ detail: `claims are refs on origin, intents are discussions in "${team.intents}"`,
456
+ },
457
+ // TEAM-13: what the team still needs set up for its claims and intents to work.
458
+ setup: [
459
+ ...(who ? [] : ["gh isn't signed in on this machine: run gh auth login."]),
460
+ ...(claims ? [] : ["The shared repository (origin) can't be reached."]),
461
+ ...(found && !found.category
462
+ ? [noCategory(found).replace(/, then raise the intent again\.$/, '.')]
463
+ : []),
464
+ ],
410
465
  techLead: team.techLead,
411
466
  owners: team.owners,
412
467
  staleDays: team.staleDays,
package/hooks/mod/decisions.mjs CHANGED
@@ -16,6 +16,7 @@ export const DECISION_KINDS = new Set([
16
16
  'teamCollision',
17
17
  'teamIntent',
18
18
  'teamReview',
19
+ 'teamDrift',
19
20
  ]);
20
21
 
21
22
  /** What each answer does, in the person's words. */
@@ -72,6 +73,8 @@ function whyOf(line, check) {
72
73
  if (line.kind === 'teamIntent')
73
74
  return "You're the tech lead: a change of direction is agreed or dropped by you, and until then everyone builds on what was agreed.";
74
75
  if (line.kind === 'teamReview') return "It's in a lane you own, so its review is yours.";
76
+ if (line.kind === 'teamDrift')
77
+ return "The team's drift check found your work building on something that has since changed, or heading into someone else's: settle it before it merges.";
75
78
  return null;
76
79
  }
77
80
 
package/hooks/mod/panes.mjs CHANGED
@@ -1,7 +1,6 @@
1
1
  // Panes v2 (docs/specs/11-panes.md): the Lanes pane's frame. A counts header, tabs, what needs the
2
2
  // person, the tab's body and the keys, as pure functions of what the mod already holds. The Lanes
3
3
  // tab's body is view.mjs's lanesPane; the Queue and Usage tabs reuse its sections.
4
- import { teamTab } from './teamview.mjs';
5
4
  import { trailRows as trailRowsDrawn, trailSvg } from './trail.mjs';
6
5
  import {
7
6
  MAP_LEGEND,
@@ -32,7 +31,6 @@ export const TABS = [
32
31
  { id: 'map', label: 'Trail', hotkey: '5' },
33
32
  { id: 'queue', label: 'Queue', hotkey: '6' },
34
33
  { id: 'usage', label: 'Usage', hotkey: '7' },
35
- { id: 'team', label: 'Team', hotkey: '8' },
36
34
  ];
37
35
 
38
36
  /** The pane's own state, kept by the mod between draws. */
@@ -246,8 +244,7 @@ export function lanesFrame(view, els, on) {
246
244
  key: 'tabs',
247
245
  flexDirection: 'row',
248
246
  columnGap: 1,
249
- // The Team tab is there only for a team (TEAM-7).
250
- children: TABS.filter((t) => t.id !== 'team' || view.team).map((t) =>
247
+ children: TABS.map((t) =>
251
248
  Button({
252
249
  key: `tab-${t.id}`,
253
250
  label: t.label,
@@ -272,52 +269,48 @@ export function lanesFrame(view, els, on) {
272
269
 
273
270
  const selected = state.lanes.find((l) => l.name === ui.selected) ?? null;
274
271
  const body =
275
- ui.tab === 'team'
276
- ? teamTab(view.team ?? null, view.teamSince ?? null, els, on)
277
- : ui.tab === 'decisions'
278
- ? decisionsTab(view.cards ?? [], ui, els, on)
279
- : ui.tab === 'journal'
280
- ? journalTab(view.journal ?? [], els, view.now)
281
- : ui.tab === 'code'
282
- ? codeTab(view, els, on)
283
- : ui.tab === 'map'
284
- ? mapTab(view.status, ui.cell, els, on, view.trail, {
285
- surface: view.surface,
286
- columns: view.columns,
287
- })
288
- : ui.tab === 'queue'
289
- ? queueSection(loop, text, Box)
290
- : ui.tab === 'usage'
291
- ? usageSection(view.usage, plan, text, Box)
292
- : [
293
- lanesPane(state, els, view.usage, plan, loop, {
294
- filter: ui.filter,
295
- search: ui.search,
296
- selected: ui.selected,
297
- live: view.live ?? {},
298
- art: view.art ?? null,
299
- detail: selected
300
- ? {
301
- agent: selected.agent ?? null,
302
- owns: view.paths?.[selected.name] ?? [],
303
- stories: laneStories(selected, state),
304
- }
305
- : null,
306
- combined: view.combined ?? null,
307
- }),
308
- ];
272
+ ui.tab === 'decisions'
273
+ ? decisionsTab(view.cards ?? [], ui, els, on)
274
+ : ui.tab === 'journal'
275
+ ? journalTab(view.journal ?? [], els, view.now)
276
+ : ui.tab === 'code'
277
+ ? codeTab(view, els, on)
278
+ : ui.tab === 'map'
279
+ ? mapTab(view.status, ui.cell, els, on, view.trail, {
280
+ surface: view.surface,
281
+ columns: view.columns,
282
+ })
283
+ : ui.tab === 'queue'
284
+ ? queueSection(loop, text, Box)
285
+ : ui.tab === 'usage'
286
+ ? usageSection(view.usage, plan, text, Box)
287
+ : [
288
+ lanesPane(state, els, view.usage, plan, loop, {
289
+ filter: ui.filter,
290
+ search: ui.search,
291
+ selected: ui.selected,
292
+ live: view.live ?? {},
293
+ art: view.art ?? null,
294
+ detail: selected
295
+ ? {
296
+ agent: selected.agent ?? null,
297
+ owns: view.paths?.[selected.name] ?? [],
298
+ stories: laneStories(selected, state),
299
+ }
300
+ : null,
301
+ combined: view.combined ?? null,
302
+ }),
303
+ ];
309
304
  const empty =
310
- ui.tab === 'team'
311
- ? 'This project has no team in its config.'
312
- : ui.tab === 'decisions'
313
- ? 'Nothing needs you. The lead is handling the build.'
314
- : ui.tab === 'journal'
315
- ? 'Nothing recorded yet: the journal starts with the brief.'
316
- : ui.tab === 'queue'
317
- ? 'The merge queue is empty.'
318
- : ui.tab === 'usage'
319
- ? 'No usage measured yet this session.'
320
- : null;
305
+ ui.tab === 'decisions'
306
+ ? 'Nothing needs you. The lead is handling the build.'
307
+ : ui.tab === 'journal'
308
+ ? 'Nothing recorded yet: the journal starts with the brief.'
309
+ : ui.tab === 'queue'
310
+ ? 'The merge queue is empty.'
311
+ : ui.tab === 'usage'
312
+ ? 'No usage measured yet this session.'
313
+ : null;
321
314
 
322
315
  // VIEW-6: j/k move between lanes; the selected lane's acts; f filters.
323
316
  const opening = selected ? storyToOpen(selected, state) : null;