@warren-dean/code-kit 0.11.1 → 0.12.1

package/skills/init/SKILL.md

@@ -74,6 +74,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
 - **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
 - **`checks`:** the typecheck, test, architecture and database commands, each scoped by `files`. Only include commands that pass on the current code, or ones the person chose to keep.
 - **`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 `approvals.delegate`: `"merge": true` (the lead merges a reviewed branch once every check passes) and `"dependencies": {}` (it approves a new package within the default limits on licence, popularity and age), so neither comes to the person. Say these are the limits; anything outside them still comes to them as a decision.
+- **`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.
 - **`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.
 
 Prove the draft:
@@ -118,7 +119,7 @@ Show the person:
 1. the layers and what each may depend on, and for brownfield the existing violations the baseline will record;
 2. the lanes, their agents and their paths, and the security reviewer (or why it's left out);
 3. protected paths, blocked and restricted commands, and checks (including any left out because they fail today);
-   and whether the lead may record approvals given in chat (`approvals.lead`), and how hands-off the build is (`harness.autonomy`);
+   and whether the lead may record approvals given in chat (`approvals.lead`), how hands-off the build is (`harness.autonomy`), and whether agents may draft bug reports for code-kit (`harness.report.on`);
 4. the project skills, and which lane agents use each;
 5. the active adapters and what each adds, from `adapters`. A companion tool that's installed but not set up here (its init skill is in your skills list, for example `/context-graph:init` with no `.ctx/` folder): add `"adapters": { "<name>": true }` to the draft and say it will be set up before any code is written;
 6. every **question**: where the docs or the code are silent, ambiguous or contradictory. Don't guess; a wrong owner or layer blocks real work.

package/skills/next/SKILL.md

@@ -56,4 +56,18 @@ After a step finishes, run `next --json` again and carry on with the new step, w
 - the step is `wait` or `done`;
 - the same step comes back twice in a row with nothing changed. Report what's stuck instead of looping.
 
+**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:
+
+```
+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 "…"
+```
+
+- `--blocks` holds the story until they answer: `next` stops dispatching or reviewing it, and the stories that depend on it wait too. Carry on with anything else meanwhile.
+- Their answer comes back to you as a prompt ("The person answered Q-3 …"). If they answer in chat instead, record it: `code-kit ask answer Q-3 "<their words>"`. A question that stops mattering is withdrawn: `code-kit ask withdraw Q-3 --reason "…"`.
+- `attention` names the stories waiting on the person, and `brief` lists the brief's open questions, which they see in the same tab; when they answer one, record it in the brief's decision log and take it out of the open questions.
+- When Claude Code itself refuses a command you need (its permission check, not a code-kit hook), the person sees it in the band with the command: say what it's for, and don't try another way round it.
+- An approval request nobody needs any more (you went another way) is dropped: `code-kit requests drop <n> --reason "…"`, so it stops waiting for them.
+
+**When code-kit itself is wrong** (a refusal that shouldn't have happened, a crash, a pane showing the wrong thing) and the config has `harness.report.on`, draft a report for code-kit's maintainers: `code-kit report "<what went wrong, in a few words>" --what "<what happened>" --expected "<what should have>" --command "<what you ran>" --refusal "<what code-kit said>"`. Only code-kit's own facts go in it, never the project's code or data. The person reads it and sends it, or not. Then work around it if you can.
+
 When you stop, end with one line saying what happens next and who does it, e.g. "Next: you approve the draft config, then I dispatch ST-1 to ST-4."

package/templates/agent.md

@@ -22,6 +22,7 @@ Always:
 - Read every file you change in full, plus its imports and its callers.
 - Search before you build; reuse existing services, providers, components and schemas.
 - Write only in your owned paths. For anything else, write a short change request for the lead and stop.
+- Something only the person can decide (a product choice, wording, an account): write the question for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead asks the person.
 - A new dependency needs a person's approval for your lane. If the install is refused, put the package, why it's needed and the approval command from the refusal in a change request for the lead, and stop.
 - Build every feature end to end. No mocks, stubs, placeholder screens or "coming soon".
 - Prove each acceptance criterion with a test whose title names the requirement ID, e.g. `BOOK-4 …`.

package/templates/claude-md.md

@@ -10,6 +10,9 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every tool
 {{If approvals.lead is on: - 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;}}
 - the project's checks before any agent finishes.
 
+When something needs the person to decide or do (a product choice, an account only they can create, wording only they can 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.
+{{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.}}
+
 If a hook blocks you, fix the cause; never work around it.
 
 The build runs from the specs in {{docs.specs}} and the stories in {{docs.plan}}. `/code-kit:next` picks the right step from the project's state; the steps are: