@warren-dean/code-kit 0.35.0 → 0.36.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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +11 -0
- package/README.md +55 -33
- package/bin/code-kit.mjs +312 -14
- package/hooks/guard-agent.mjs +32 -1
- package/hooks/guard-bash.mjs +2 -2
- package/hooks/guard-paths.mjs +21 -2
- package/hooks/hooks.json +11 -0
- package/hooks/lead-prompt.mjs +44 -0
- package/hooks/lib/config.mjs +8 -0
- package/hooks/lib/harness.mjs +13 -0
- package/hooks/lib/instructions.mjs +11 -1
- package/hooks/lib/layers.mjs +18 -0
- package/hooks/lib/loop-state.mjs +4 -3
- package/hooks/lib/next.mjs +100 -9
- package/hooks/lib/plan.mjs +19 -5
- package/hooks/lib/promote.mjs +554 -0
- package/hooks/lib/sessions.mjs +97 -13
- package/hooks/lib/shell.mjs +1 -1
- package/hooks/lib/streamconfig.mjs +80 -0
- package/hooks/lib/streams.mjs +244 -0
- package/hooks/lib/verify.mjs +14 -0
- package/hooks/mod/loop.mjs +7 -0
- package/hooks/session.mjs +8 -0
- package/package.json +1 -1
- package/skills/decide/SKILL.md +9 -2
- package/skills/init/SKILL.md +10 -2
- package/skills/lead/SKILL.md +12 -6
- package/skills/promote/SKILL.md +49 -0
- package/skills/review/SKILL.md +1 -0
- package/skills/spec-check/SKILL.md +2 -1
- package/skills/spec-design/SKILL.md +1 -0
- package/templates/agent.md +1 -0
- package/templates/claude-md.md +2 -0
package/skills/lead/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lead
|
|
3
|
-
description: Make this Claude Code session the project's lead session, where code-kit's loop runs and the plan's stories are dispatched from, when several sessions work one project.
|
|
3
|
+
description: Make this Claude Code session the project's lead session (or, in a project built as streams, one stream's lead), where code-kit's loop runs and the plan's stories are dispatched from, when several sessions work one project. Running it moves the lead here as the person sends it; the skill confirms it and says what it means. Use when the person says this session should lead, asks which session leads, or runs /code-kit:lead.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Lead from this session
|
|
@@ -9,6 +9,14 @@ Several Claude Code sessions can work one project at once. One is the lead sessi
|
|
|
9
9
|
|
|
10
10
|
The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project root.
|
|
11
11
|
|
|
12
|
+
**When the person ran `/code-kit:lead`**, typing it was their choice: code-kit recorded this session as the lead (of the stream they named) as the prompt arrived, and its note in your context says so, or why it couldn't. Don't ask them to run anything. Run `who` to confirm, and tell them in a sentence or two what it means: which stream this session leads, its lanes and plan, and which session leads the rest. When the note says another lead holds the main checkout, move this session into a worktree of its own on the branch the note names (EnterWorktree) before you change anything. If the note says it couldn't (a stream that doesn't exist, say), tell them why and what the streams are.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" who
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
**When the person asked in words** ("lead from this session"), and didn't run the command:
|
|
19
|
+
|
|
12
20
|
1. See who leads now:
|
|
13
21
|
|
|
14
22
|
```bash
|
|
@@ -17,12 +25,10 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project
|
|
|
17
25
|
```
|
|
18
26
|
|
|
19
27
|
2. If this session already leads, say so and stop.
|
|
20
|
-
3. Otherwise, tell
|
|
28
|
+
3. Otherwise, tell them what moving the lead does: this session starts running the loop and dispatching the plan's stories, and the session that led becomes a working session, which stops prompting its lead. Choosing the lead is theirs, and the hooks refuse it from an agent: they run `/code-kit:lead` (with the stream, in a project built as streams), or use **Lead from here** in the code-kit band.
|
|
21
29
|
|
|
22
|
-
|
|
23
|
-
! node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sessions lead
|
|
24
|
-
```
|
|
30
|
+
**A project built as streams** (`code-kit streams` lists them; spec 31) has a lead per stream, and they lead at once: each runs its own loop, dispatches only its own stream's lanes and stories, and writes only its own stream's plan and specs. The argument names the stream (`/code-kit:lead studio`).
|
|
25
31
|
|
|
26
|
-
|
|
32
|
+
Moving one stream's lead leaves the other streams' leads as they are. The first lead works in the main checkout; every other stream's lead works in a worktree of its own (start the session with `claude --worktree`, or move it into one), on `lead/<stream>`, and its plan changes reach the base through the merge queue. A session that leads with no stream named leads every stream that has no lead of its own. A working session joins a stream with `sessions stream <name>`, the person's command too.
|
|
27
33
|
|
|
28
34
|
A working session doesn't need this to work: it records its task (`code-kit task "<what>" --touches "<globs>"`), works in a worktree of its own, and `code-kit task done` when it's finished.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: promote
|
|
3
|
+
description: Decide the candidates for core in a project built as streams (spec 31): code in one stream's module that another stream repeats, wants to import or copied, or that repeats core. Reads each candidate's evidence, promotes it with a platform story that moves it into core and switches every stream to it, or keeps it in its module with why. Use when code-kit's loop or `code-kit next` says candidates are proposed for core, or the person runs /code-kit:promote [candidate ids].
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Decide what goes into core
|
|
7
|
+
|
|
8
|
+
In a project built as streams, each stream's lanes own its modules, and core is the code every stream builds on. When the same capability shows up in two streams, it belongs in core: built once, with one owner. code-kit raises a candidate when it sees code alike in two streams' modules (names aside), a lane refused an import of another stream's module, a lane copying files into a module, module code that repeats core, or a story's requirement that another stream's spec already has. Nothing moves by itself: you decide each one. It's yours when your stream is the platform (it owns core), or, without a platform stream, when the candidate touches your stream.
|
|
9
|
+
|
|
10
|
+
The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
|
|
11
|
+
|
|
12
|
+
## 1. Read the candidates
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" promote --json
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Each open candidate has its `id`, `kind` (`clone`, `core-clone`, `import`, `copy`, `requirement`), `what`, the files (`where`), the streams it touches and its evidence. The argument, if given, names the ids to take. For each, read the code on both sides: the lines `what` names, and enough around them to see what the code does and what it depends on.
|
|
19
|
+
|
|
20
|
+
## 2. Judge it
|
|
21
|
+
|
|
22
|
+
Promote only when all of these hold:
|
|
23
|
+
|
|
24
|
+
- **A second real use.** Two streams use it, or one stream uses it and another needs it now (a refused import, a story whose requirement repeats one). One stream's code stays in its module however general it looks.
|
|
25
|
+
- **The same thing.** The two copies do the same job for the same reason. Code alike by accident (two loops over different things) isn't a capability: reject it with that reason.
|
|
26
|
+
- **Core can own it without knowing the streams.** Once moved, it must not import a module or name a stream's types, data or rules. Where it does, either the stream-specific part stays behind (core takes a parameter, an interface or a callback), or it isn't core's.
|
|
27
|
+
- **It fits core's layer.** It moves into the core layer of the same technical layer (an API module's code into API core), never across layers.
|
|
28
|
+
|
|
29
|
+
A `core-clone` is a stream rebuilding what core already has: there's nothing to promote. Reject it with "use core's <name>", and tell that stream's lead, who sends the lane back to use core's.
|
|
30
|
+
|
|
31
|
+
## 3. Act on it
|
|
32
|
+
|
|
33
|
+
- **Promote.** Write a story in the platform's plan (yours, as the platform's lead; without one, in your stream's plan on a core lane), with `**Promotes:** <id>`, that moves the code into core, switches every stream's module that had it to core's, and proves it with tests every stream that uses it runs. Large code moves in steps, lower layers first, a few files a story. Then record it:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" promote accept <id> --story ST-n
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The candidate closes when that story merges.
|
|
40
|
+
|
|
41
|
+
- **Keep it in its module.** Say why, so it isn't proposed again until its evidence changes (a third stream, a new copy):
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" promote reject <id> --reason "<why it stays>"
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## 4. Report
|
|
48
|
+
|
|
49
|
+
One line per candidate: what it was, what you decided and why. "P-3: the price rounding in both streams' checkout promoted as ST-210 (same rule, no stream types)."
|
package/skills/review/SKILL.md
CHANGED
|
@@ -59,6 +59,7 @@ Read the story and every requirement it cites. Then start from what's already be
|
|
|
59
59
|
|
|
60
60
|
- **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
|
|
61
61
|
- **Running cost (spec 29):** where the config has a budget, a branch that changes the infrastructure files (`cost.paths`) changes `docs/costs.md` too (verify fails it otherwise). Read the two together: the size, tier and count in the code are the ones in the register's rows, every new paid thing has a row, and the estimate is for the load the spec gives, not a provider's production default. A mismatch sends the branch back, naming the file and the row. `code-kit cost` shows the totals against the budget and the prices to recheck.
|
|
62
|
+
- **Core reused, streams kept apart (spec 31):** in a project built as streams, `code-kit promote scan --branch <branch>` lists the branch's code that repeats core or another stream's module. Code that repeats core sends the branch back: it uses core's. Code alike in another stream is raised for core as a candidate: note it in the report; it's the platform's decision (`/code-kit:promote`), not a reason to send the branch back.
|
|
62
63
|
- **Standards kept:** `code-kit standards --for <changed files>` lists the project's standards for those files' layers. Check each changed file against the ones marked `checked` (the hooks already refuse what an `enforced` one names). A broken required standard sends the branch back, naming the standard's id and where; a broken recommended one is a concern; advice is at most a nit.
|
|
63
64
|
|
|
64
65
|
## 4. The security review
|
|
@@ -18,7 +18,8 @@ The project's specs are in the folder named by `docs.specs` in `.claude/code-kit
|
|
|
18
18
|
| Requirement | Status (done / partial / missing / conflicts) | Where | Note |
|
|
19
19
|
| ----------- | --------------------------------------------- | ----- | ---- |
|
|
20
20
|
|
|
21
|
-
6. **
|
|
21
|
+
6. **In a project built as streams** (the config has `streams`), run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" promote --story <ST-n>`: it lists each requirement of the story that another stream's spec already has. Don't build it again: note it in the table, and ask the lead whether it comes from core (a change request to the platform) or from that stream.
|
|
22
|
+
7. **List questions** for the lead wherever the spec is missing, ambiguous, or contradicts the code or another spec. Don't resolve them by guessing.
|
|
22
23
|
|
|
23
24
|
## Output
|
|
24
25
|
|
|
@@ -99,6 +99,7 @@ A spec answers what and why, not how: no framework, file or function names unles
|
|
|
99
99
|
|
|
100
100
|
These are what `/code-kit:init` turns into enforced rules, so be concrete.
|
|
101
101
|
|
|
102
|
+
- **Product lines (spec 31), asked once:** does the product have, or plan, separate product lines (offerings for different users, each with its own roadmap), or is it platform capability other products will build on? If yes, the architecture is a core per technical layer plus a module per product line (`api/core`, `api/<line>`), a module never imports another line's module, and core never imports a module; the plan has a plan file per line under `docs/plan/` and, when the person wants a team to own core, one for the platform. If no, a plain layout, as below; streams can be added later. Don't guess seams the brief doesn't show: a product split along lines it never follows makes every feature cross them.
|
|
102
103
|
- **`docs/architecture.md`:**
|
|
103
104
|
- the components (apps, services, packages, jobs) and what each is for;
|
|
104
105
|
- the **layers**, the folders each will live in, and which layers each may depend on (for example `ui → application → domain`, with adapters implementing the domain's ports);
|
package/templates/agent.md
CHANGED
|
@@ -23,6 +23,7 @@ Always:
|
|
|
23
23
|
- {{if standards}}Build to the project's standards for your layers, from `{{docs.standards}}` (read a standard's why and evidence there when you need it). A required one that review checks sends your branch back if it's broken; advice is yours to weigh:{{standards}}{{end}}
|
|
24
24
|
- Read every file you change in full. Of what it imports and what calls it, read what your change needs: the definitions it uses and the call sites it changes. A context tool's fresh card for a file stands for reading it whole; read the source where the card is missing, stale or not enough.
|
|
25
25
|
- Search before you build; reuse existing services, providers, components and schemas.
|
|
26
|
+
- {{if streams}}Look in core first: this project is built as streams, and what every stream needs lives there. Never import or copy another stream's module; if you need what it has, write a change request for the lead to have it promoted into core.{{end}}
|
|
26
27
|
- Change files with the Edit and Write tools, not the shell: no `cat > file <<EOF`, `python3 - <<EOF`, `sed -i` or `>>`. In your own worktree, Claude Code refuses a shell command it can't prove stays inside it, and each refusal is a step lost. Keep shell commands to running things, one plain command at a time, from your worktree's root.
|
|
27
28
|
- Write only in your owned paths. For anything else, write a short change request for the lead and stop.
|
|
28
29
|
- You answer to the lead, never the person. A question the spec doesn't settle (a product choice, UX the spec is silent on, an account): write it for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead decides, or asks the person.
|
package/templates/claude-md.md
CHANGED
|
@@ -19,6 +19,8 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
|
|
|
19
19
|
|
|
20
20
|
{{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}}
|
|
21
21
|
|
|
22
|
+
{{if streams}}This project is built as streams (`code-kit streams`): {{streams}}. Each stream has its own lead session, plan, specs and lanes, and a lead dispatches only its own stream's stories and writes only its own stream's plan and specs. A module never imports another stream's module, and core never imports a module: the hooks refuse both. Core is the code the streams share{{platform}}. When the same code shows up in two streams' modules, it's a candidate for core: `code-kit promote` lists them, and the lead whose they are decides each (`/code-kit:promote`). In review, `code-kit promote scan --branch <branch>` lists what a branch repeats: code that repeats core goes back to use core's.{{end}}
|
|
23
|
+
|
|
22
24
|
- {{if harness.report.on}}When code-kit itself is wrong (a refusal that shouldn't have happened, a crash), draft a report with `code-kit report "<title>" --what "…" --expected "…"`: only code-kit's facts, never the project's. The person reads it and sends it, or not.{{end}}
|
|
23
25
|
|
|
24
26
|
Several sessions may work this project at once. One leads (the loop runs there, and stories are dispatched from it); the others are working sessions. `code-kit who` says which this is. In a working session, record what you're doing before you change code, with the paths you'll change, and work in a worktree of your own: `code-kit task "<what>" --touches "<globs>"`, and `code-kit task done` when it's finished. Never stash, discard or commit another session's files: ask that session.
|