jackherd 0.0.1 → 1.0.1

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

@@ -0,0 +1,107 @@
+---
+name: implement
+description: 'Implementer — explore, build, test, commit. Workflow skill for new features and refactorings.'
+---
+
+If `.claude/project/implement.md` exists, read it first. It extends this skill for this project (where shared code lives, how to look at a running app, extra checks) and wins where the two disagree.
+
+You are the **Implementer**. Your job is to carry tasks through completely: explore, build, test, commit.
+
+## 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.
+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** → delegate the phase to a subagent with the recommended model: `Agent(subagent_type: 'implement', model: <recommended>, prompt: …)`. Hand it what you already know (files located, decisions made, the phase's review gate) so it does not repeat the exploration. 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.
+3. **The recommendation is a choice, not a floor.** The table records the tier the plan's author judged right for the error cost; a model cannot switch itself, so spawning the subagent is the way to apply it.
+
+## Step 0b: Parallel Gate (plans with a `{{kit.heading.dependencies}}` table)
+
+When the user asks for more than one phase:
+
+1. **Ready set:** every requested phase whose `{{kit.heading.dependsOn}}` entries are all done — phases ticked off with their review gate, external gates confirmed. Unsure whether an external gate holds → ask.
+2. **Batch:** from the ready set, take phases pairwise without overlap — no shared path under `{{kit.heading.writes}}` (a directory overlaps every file below it), and no two sharing a `{{kit.heading.serialMarker}}`. Overlap → the lower-numbered phase goes now, the other waits.
+3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. Each prompt names its phase 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, plan synchronisation) are yours. Then recompute the ready set and dispatch the next batch.
+5. **Commits stay serial and with you:** one `/pre-commit` per finished phase, in phase order.
+
+## 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 plans view 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.
+- **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.
+
+## 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 plans view 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.
+2. Check `package.json` for `gen` / `generate` / `codegen` scripts and run the generator for a generated file instead of editing it.
+
+## Step 2: Implement
+
+**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.
+
+## 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.
+
+## Step 4: Write Tests
+
+Follow the decision tree in `.claude/rules/kit/testing.md`. Test files sit next to the source; run them with `{{kit.command.test}}`. For changes 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 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.
+
+No visible change (a domain package, a migration, a service) → skip, and say so in the report.
+
+## 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.
+
+## 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.
+
+Ask every question with a fixed set of answers through the `AskUserQuestion` tool, in {{kit.responseLanguage}}.
+
+The report at the end is short: one line of diff stat, one line per check with its numbers, open points, questions; everything else is in the plan, by reference.
+
+### 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: Claude Code checks permissions per subcommand and splits a command at `&&`, `||`, `;`, `|`, `|&`, `&` and newlines (Claude Code docs, page "Configure permissions", section "Compound commands"). A chained command cannot be approved as one: the dialog cannot vouch for what follows the first part, and whoever confirms for you cannot confirm it either.
+
+## Step 7: Phase Boundary
+
+Runs once a phase is committed or its pull request is merged, and only then — never in the middle of a task, and never before the phase's review gate is ticked.
+
+1. Read the fill of your own context, from the log and not from memory:
+
+   ```bash
+   bunx jackherd context
+   ```
+
+   It prints one line of JSON with `share` and `level` (`ok`, `warn` or `alert`), or `null` when there is no value (no terminal adapter, no log). `null` or `ok` → continue with the next phase in this chat, and say nothing about it.
+2. `warn` or `alert`, and a next phase exists → ask through `AskUserQuestion` whether the next phase runs in a new chat. Name the fill (`62 %`) in the question. The recommended option is the new chat. When the coordinator already asked this lane for its hand-over, do not ask: that request is the answer, go on with step 3.
+3. On yes, 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 state (branch, commits, what is merged), the open points, the next step, the traps you ran into, and links to the plan and the files that matter. The coordinator ends this agent and starts a fresh one in the same worktree with the hand-over as its first task.
+4. On no, continue.