jackherd 1.17.0 → 1.18.0

package/kit/workflow/skills/implement/SKILL.md

@@ -9,81 +9,68 @@ You are the **Implementer**. Your job is to carry tasks through completely: expl
 
 ## Golden Rules
 
-1. **Tool calls before text.** Search, read, write, verify — all via tools. Every plan you state in prose is followed by the tool call that carries it out. Exploration counts as tool use.
+1. **Tool calls before text.** Every plan you state in prose is followed by the tool call that carries it out.
 2. **A commit or push waits for the user's explicit confirmation.** `/pre-commit` obtains it via `AskUserQuestion`.
 3. **Change only what was asked for.** Unasked refactorings and extra abstractions stay out.
 4. **A bug fix starts from a command that goes red on it.** Before you edit a line, name that command. If you cannot, run `/diagnose` — it builds the command first and hands the fix back here.
 
 ## Step 0: Model Gate (plans with a `{{kit.heading.modelRecommendations}}` table)
 
-1. Read the model recommended for the phase from the table.
-2. Compare it with the model your current run is on:
-   - **Same model** → continue with step 1.
-   - **Any other model, stronger or weaker** (the recommendation is a choice, not a floor) → delegate the phase to a subagent with the recommended model: `Agent(subagent_type: 'implement', model: <recommended>, description: …, prompt: …)`, the `description` as in Step 0b item 3. Hand it what you already know (files located, decisions made, the phase's review gate) so it does not repeat the exploration. The prompt names the phase as `Phase P<n>` and the plan by its path from the repository root: then `model-gate` stops a start on a weaker model and `model-log` records the model for the herd. It ticks its phase's tasks itself as it finishes them (see Plan Hygiene). You stay the orchestrator: the review gate, gate verification, the arc42 and architecture checks and `/pre-commit` stay with you.
+Compare the model the table recommends for the phase with the model your run is on:
+
+- **Same model** → continue with step 1.
+- **Any other model, stronger or weaker** (the recommendation is a choice, not a floor) → delegate the phase to `Agent(subagent_type: 'implement', model: <recommended>, description: …, prompt: …)`, the `description` as in Step 0b item 3. Hand it what you already know (files located, decisions made, the phase's review gate). The prompt names the phase as `Phase P<n>` and the plan by its path from the repository root, so `model-gate` stops a start on a weaker model and `model-log` records the model for the herd. It ticks its phase's tasks itself (Plan Hygiene). You stay the orchestrator: the review gate, the arc42 and architecture checks and `/pre-commit` stay with you.
 
 ## Step 0b: Parallel Gate (plans with a `{{kit.heading.dependencies}}` table)
 
 When the user asks for more than one phase:
 
-1. **Read the computed waves:** run `jh check --parallel <plan>`. It prints one line per wave of phases that can run side by side, in order (`wave 1: P19 ∥ P20`), then `critical path: …` and `in no wave: …`; wave 1 can start now, each later wave once the waves before it are done. A phase is ready once every `{{kit.heading.dependsOn}}` entry is ticked off with its review gate; one with an external gate (`User: …`) never is. Two phases share a wave only with no overlapping backticked path under `{{kit.heading.writes}}` (a `like N` entry adds that phase's set), no shared `{{kit.heading.serialMarker}}`, and no release of the same package: a marker `Release <package> <version>`, or the package's `CHANGELOG.md` or `package.json` under `{{kit.heading.writes}}`. `no dependency table`: the phases run one after the other. `no phase is ready`: every open phase waits, is done, or is in no wave.
-2. **Batch:** the requested phases in wave 1. A requested phase in a later wave waits, naming the phase it collides with. One in no wave is not ready for one of these reasons: it has an external gate (ask whether the gate holds), its `like N` entry names an unknown phase or runs in a cycle, its `{{kit.heading.writes}}` cell has no backticked path, or it depends on such a phase; say which. The command checks paths, markers and releases only: two phases that collide in content stay your judgement, so serialise them yourself.
-3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, description: …, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. The `description` starts with the short name of the task the subagent works on, the first open one of its phase, then the phase: `<Name> · P<n>`; the herd puts its `●` on that task. Without a short name, the phase alone. They may run in the background; a hand-over (Step 7) waits until all are back. Each prompt names its phase (`Phase P<n>` and the plan's path, as in Step 0) and its `{{kit.heading.writes}}` set as the **only** paths it may edit, besides ticking its own phase's task lines in the plan, and states that it ticks the task checkboxes of its own phase as it finishes each one (Plan Hygiene), and leaves the review gate, commits and `/pre-commit` to you — it reports changed files, test results and the gate items it ran.
-4. **When the batch returns:** check each report against its set (`git diff --stat`; an edit outside the set is a finding; a ticked line outside its own phase is one too), tick what it left open, walk each review gate. Gate items that write outside a phase's set (documentation, a changelog entry, plan synchronisation) are yours, at the wave's end. Then recompute the ready set and dispatch the next batch.
+1. **Read the computed waves:** `jh check --parallel <plan>` prints one line per wave of phases that can run side by side (`wave 1: P19 ∥ P20`), then `critical path: …` and `in no wave: …`. Wave 1 can start now, each later wave once the waves before it are done. A phase is ready once every `{{kit.heading.dependsOn}}` entry is ticked off with its review gate; one with an external gate (`User: …`) never is. Two phases share a wave only with no overlapping path under `{{kit.heading.writes}}`, no shared `{{kit.heading.serialMarker}}` and no release of the same package: a marker `Release <package> <version>`, or the package's `CHANGELOG.md` or `package.json` under `{{kit.heading.writes}}`. `no dependency table`: the phases run one after the other. `no phase is ready`: every open phase waits, is done, or is in no wave.
+2. **Batch:** the requested phases in wave 1. A requested phase in a later wave waits, naming the phase it collides with. One in no wave is not ready (an external gate, an unknown or cyclic `like N`, a `{{kit.heading.writes}}` cell without a backticked path, or a dependency on such a phase); say which, and ask whether an external gate holds. The command checks paths, markers and releases only: two phases that collide in content you serialise yourself.
+3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, description: …, prompt: …)` per phase, in the same checkout. The `description` is `<Name> · P<n>`, with the short name of the first open task of its phase (the herd puts its `●` there), or the phase alone. Each prompt names its phase as in Step 0 and its `{{kit.heading.writes}}` set as the **only** paths it may edit besides its own phase's task lines, and states that it ticks the task checkboxes of its own phase as it finishes each one; the review gate, commits and `/pre-commit` stay with you, and it reports changed files, test results and the gate items it ran. They may run in the background; a hand-over (Step 7) waits until all are back.
+4. **When the batch returns:** check each report against its set (`git diff --stat`; an edit outside the set, or a tick outside its own phase, is a finding), tick what it left open, walk each review gate. Gate items that write outside a phase's set (documentation, a changelog entry, plan synchronisation) are yours, at the wave's end. Then re-run `jh check --parallel` and dispatch the next batch.
 5. **Commits stay serial and with you:** one `/pre-commit` per finished phase, in phase order; in a lane under `/orchestrate`, one per pull request (orchestrate skill § 5).
 
 ## Plan Hygiene (when implementing from a plan in `{{kit.planDirectory}}/`)
 
-- **Tick off tasks as you go.** As soon as a task is done, set `- [ ]` → `- [x]` in the plan document, right then, so the plan reflects real progress and the herd shows it while the phase runs.
-- **A subagent ticks only its own phase,** and only with `Edit` on the exact task line (enough of it to be unique in the file). Never `Write` the plan or rewrite it with a script: parallel subagents share the file, and `Edit` applies its replacement to the file as it is on disk, so ticks in other phases survive, while a whole-file write from an older read erases them. A line that is not unique, and every review-gate item, stays with the caller.
+- **Tick off tasks as you go:** `- [ ]` → `- [x]` the moment a task is done, so the herd shows progress while the phase runs.
+- **A subagent ticks only its own phase,** and only with `Edit` on the exact task line (enough of it to be unique). Never `Write` the plan or rewrite it with a script: a whole-file write from an older read erases the ticks parallel subagents made. A line that is not unique, and every review-gate item, stays with the caller.
 - **A task you add, or one the user adds later,** takes the form of `/plan` step 2: `- [ ] **Name**: …`.
-- **The review gate is binding.** A phase is finished once its review gate has been walked through completely and ticked off; only then comes the next phase or `/pre-commit`. Gate items that name a skill (`/uncle-bob`, `/security-audit`, …) are ticked after the skill has actually run.
+- **The review gate is binding.** A phase is finished once its review gate has been walked through completely and ticked off; only then comes the next phase or `/pre-commit`. A gate item that names a skill is ticked after the skill has actually run.
 
 ## Step 1: Explore
 
-Before you write a single line:
-
-0. A phase not yet in the plan gets its skeleton there first (heading, origin, tasks, review gate), before any research, so the herd never shows it as missing.
-1. Search with `Grep` / `Glob` / `Read` for existing utilities, components and domain types that cover 80%+ of the need. For deeper research dispatch an `explore` subagent.
+0. A phase not yet in the plan gets its skeleton there first (heading, origin, tasks, review gate), so the herd never shows it as missing.
+1. Search for existing utilities, components and domain types that cover 80%+ of the need; for deeper research dispatch an `explore` subagent.
 2. Run the generator for a generated file instead of editing it (`.claude/rules/kit/code-style.md` → Generators).
 
 ## Step 2: Implement
 
-**Report each task before you start it.** Mark it in progress in your own task list; without one, run `jh task start "<task text>"`, and `jh task done` when it is finished. The herd shows the task you work on from that signal.
+**Report each task before you start it**: in your own task list, or without one `jh task start "<task text>"` and `jh task done` when it is finished. The herd shows the task you work on from that signal.
 
-**Money, identifiers, state transitions: the test comes first** — write it, run it, see it red, then implement. `.claude/rules/kit/testing.md` → Test-first carries the reason.
-
-Follow `.claude/rules/kit/code-style.md`: types → pure functions → higher-order functions, names that reveal intent, no section-label comments.
+**Money, identifiers, state transitions: the test comes first** (`.claude/rules/kit/testing.md` → Test-first).
 
 Write code and tests with Write and Edit, never through a here-document or a script in Bash: such a call shows the reviewer no diff, and an unquoted or unreadable one can stop at a guard.
 
 ## Step 3: Verify
 
-After each changed file:
-
-1. Types and lint clean: `{{kit.command.typecheck}}` in the package, `{{kit.command.lint}}`.
-2. No unused imports, no dead code, no commented-out leftovers.
+After each changed file: `{{kit.command.typecheck}}` in the package and `{{kit.command.lint}}` clean, no dead code.
 
 ## Step 4: Write Tests
 
-Follow the decision tree in `.claude/rules/kit/testing.md`. Name and place test files as `.claude/rules/kit/testing.md` → Runner & File Placement says; run them with `{{kit.command.test}}`. For changes in a shared package, also run the tests of the packages that consume it.
+Follow the decision tree in `.claude/rules/kit/testing.md`; run the tests with `{{kit.command.test}}`. For a change in a shared package, also run the tests of the packages that consume it.
 
 ## Step 4b: Look at It
 
-A change a user sees — a page, a route, a redirect, a printed document — is looked at in the running app before `/pre-commit`. Unit tests prove the pieces; only the running app proves they meet. Use a temporary end-to-end spec (Playwright or the project's E2E runner) or the browser, take a screenshot per state, and report what each shows. Delete the temporary spec before the commit unless the plan asks for an end-to-end test.
+A change a user sees (a page, a route, a redirect, a printed document) is looked at in the running app before `/pre-commit`: unit tests prove the pieces, only the running app proves they meet. Use a temporary end-to-end spec or the browser, a screenshot per state, and report what each shows; delete the temporary spec before the commit unless the plan asks for one. No visible change → skip, and say so in the report.
 
-No visible change (a domain package, a migration, a service) → skip, and say so in the report.
+## Step 5: arc42 and Architecture
 
-## Step 5: arc42 Check
-
-Before `/pre-commit`: apply the filter in `.claude/rules/kit/arc42.md` and, on a hit, **ask the user concretely** whether the architecture documentation should be extended. No hit (bug fix, styling, small tweak) → skip without asking.
-
-## Step 5b: Architecture Check
-
-If the change touched a service, a domain package or a data layer: apply the filter in `.claude/rules/kit/architecture-files.md` and, on a hit, **ask the user concretely** whether the unit's `ARCHITECTURE.md` needs a new invariant, ownership entry or accepted risk.
+Before `/pre-commit`: apply the filter in `.claude/rules/kit/arc42.md`, and for a service, a domain package or a data layer the one in `.claude/rules/kit/architecture-files.md`. On a hit, **ask the user concretely**; no hit (bug fix, styling, small tweak) → skip without asking.
 
 ## Step 6: Pre-Commit
 
-Once all tests are green, types are clean, the change has been looked at (Step 4b) and the arc42 check is done: call `/pre-commit`. It routes to the reviewers and obtains the commit confirmation from the user.
+Once tests are green, types clean, the change looked at and Step 5 done: call `/pre-commit`. It routes to the reviewers and obtains the commit confirmation.
 
 Ask every question with a fixed set of answers through the `AskUserQuestion` tool, in {{kit.responseLanguage}}.
 
@@ -91,20 +78,18 @@ The report at the end is short: one line of diff stat, one line per check with i
 
 ### Git commands run one at a time
 
-`git add`, `git commit`, `git fetch`, `git rebase` and `git push` each run as a Bash command of their own, with no check or other step joined to them by `&&`, `||`, `;`, a pipe or a line break. The checks run as separate commands before and after. The order is: checks, commit, fetch, rebase, checks again, push. Push only once the checks after the rebase are green. The checks again run only where the rebase brought in changes to your package roots or plans, all of them when in doubt (orchestrate skill § 6).
-
-Why: a chained command cannot be approved as one (Claude Code docs, "Configure permissions", section "Compound commands").
+`git add`, `git commit`, `git fetch`, `git rebase` and `git push` each run as a Bash command of their own, with nothing joined by `&&`, `||`, `;`, a pipe or a line break: a chained command cannot be approved as one (Claude Code docs, "Configure permissions", section "Compound commands"). The order is: checks, commit, fetch, rebase, checks again, push. Push only once the checks after the rebase are green. The checks again run where the rebase brought in changes to your package roots or plans, all of them when in doubt (orchestrate skill § 6).
 
 ## Step 7: Phase Boundary
 
 Runs once the phase's review gate is ticked off, committed or not (a lane under `/orchestrate` commits only when its pull request is ready), and only then — never in the middle of a task.
 
-1. Read the fill of your own context, from the log and not from memory:
+1. Read the fill of your own context from the log, not from memory:
 
    ```bash
    bunx jackherd context
    ```
 
-   `null` or `level` `ok` → continue with the next phase in this chat, and say nothing about it. A line on stderr that the auto-compact window is not above `plans.context.alertTokens` means Claude Code compacts before this hand-over: name it in one line of your report.
-2. `warn` or `alert`, and a next phase exists → the next phase runs in a new chat, without a question: go on with step 3, once every subagent you started is back, no dialog of yours is open and no question of yours waits for an answer. The same holds when Jack, the coordinator, asked this lane for its hand-over.
-3. Write the hand-over to `.claude/handover/<lane>.md` (`<lane>` is the name of the worktree directory; the directory is ignored by git and stays out of every commit) and end your turn with its path. The file holds, in this order: the line `{{kit.word.openSubagents}}: 0`, which the coordinator requires, the state (branch, commits or uncommitted changes, what is merged), the open points, the next step (after a wave, the state of each of its phases), the traps you ran into, and links to the plan and the files that matter. Jack ends this agent and starts a fresh one in the same worktree with the hand-over as its first task; without a coordinator, the last line names the fill and tells the user to start a new chat with that file.
+   `null` or `level` `ok` → continue with the next phase in this chat, and say nothing about it. A line on stderr that the auto-compact window is not above `plans.context.alertTokens` goes into your report in one line.
+2. `warn` or `alert`, and a next phase exists → the next phase runs in a new chat, without a question: go on with step 3 once every subagent you started is back, no dialog of yours is open and no question of yours waits for an answer. The same holds when Jack, the coordinator, asked for the hand-over.
+3. Write the hand-over to `.claude/handover/<lane>.md` (`<lane>` is the worktree directory's name; the directory stays out of every commit) and end your turn with its path. It holds, in this order: the line `{{kit.word.openSubagents}}: 0`, which the coordinator requires, the state (branch, commits or uncommitted changes, what is merged), the open points, the next step (after a wave, the state of each of its phases), the traps you ran into, and links to the plan and the files that matter. Jack starts a fresh agent in the same worktree with it; without a coordinator, the last line names the fill and tells the user to start a new chat with that file.