jackherd 0.0.1 → 1.0.0

package/kit/rules/rules/kit/pull-requests.md

@@ -0,0 +1,59 @@
+# Pull Requests
+
+How an agent opens a pull request so every PR reads consistently and is review- and deploy-ready. Applies whenever you run `gh pr create` or edit a PR body.
+
+## Preconditions
+
+- **Open a PR only when the user asks.** Same rule as commit and push.
+- **Base = `{{kit.baseBranch}}`** unless the user names another.
+- **Work on a branch.** If the working branch is `{{kit.baseBranch}}`, branch first.
+- **Push before creating, with the user's go-ahead for the push.** The head branch must be on the remote so `gh pr create` has a target.
+- **Check for an existing PR first** (`gh pr view <branch>`). If a prior PR for the same branch is already **merged**, the new one is a continuation — mark it in the title.
+
+## Title
+
+Conventional-commit shape, imperative, lower-case summary, no trailing period:
+
+```
+type(scope): short imperative summary
+```
+
+- `type` ∈ `feat | fix | refactor | perf | docs | test | chore | build | ci`. Pick the type of the PR's **dominant** change, not the first commit.
+- `scope` = the primary package, app or service.
+- **Continuation of a merged PR on the same branch:** append `(PART N)`.
+
+## Body structure
+
+Fixed sections, in this order. Omit a section only when it has no content — never leave a placeholder.
+
+1. **Context** — one or two lines: link the plan (`{{kit.planDirectory}}/…`), the predecessor PR, or the issue. State which phase or slice this is.
+2. **Changes** — grouped **by theme**, not commit by commit. Use `###` subheadings or a table when the PR spans several areas. A reviewer must grasp the shape without reading the diff.
+3. **Verification** — the checks you actually ran, with their numbers, and the review gates with their verdicts. Only checks you ran.
+4. **Deploy checklist** — required whenever the PR touches **database migrations, secrets, message or mail templates, or a new or changed service**. Order the steps **causally**: database → secrets → templates → services (consumer before publisher) → apps. Use `- [ ]` so it doubles as a runbook. Flag any migration already applied to an environment and which ones still need it.
+5. **Out of scope / follow-ups** — what was deliberately deferred, so reviewers don't ask.
+
+## Diagrams (Mermaid)
+
+Add a fenced ` ```mermaid ` block **when it removes reader effort**:
+
+- a **new service** or a multi-hop **data flow** (who reads what, who publishes to whom),
+- a **state machine** or transition set,
+- a **security or replication mechanism** where the failure mode is the point.
+
+Keep each diagram to one idea; two small diagrams beat one dense one. Small or single-file PRs need none.
+
+## Review order (large PRs)
+
+When a PR spans many files, add a short **suggested review order** — **pure/domain logic first, adapters next, UI and wiring last**. A `| # | Area | Start here | Why first |` table works well.
+
+## Language
+
+PR **title and body are English**, whatever language the conversation runs in, so the history reads the same for every reader.
+
+## Anti-patterns
+
+- Pasting the raw commit log as the body — group by theme instead.
+- A deploy section out of causal order (a deploy before its migration).
+- Claiming tests or reviews that did not run.
+- Secrets, tokens or full connection strings anywhere in the body.
+- A diagram that restates the title without adding structure.

package/kit/rules/rules/kit/testing.md

@@ -0,0 +1,91 @@
+# Testing
+
+The kit's core. The project's own rules beside `.claude/rules/kit/` add how this project verifies in a browser, which fixtures exist and which environments a test may touch.
+
+All new or changed code **must** have tests.
+
+## Runner & File Placement
+
+| Setting      | Value                                          |
+| ------------ | ---------------------------------------------- |
+| Runner       | `{{kit.command.test}}`                         |
+| File naming  | `*.test.ts` co-located next to the source file |
+| E2E runner   | Playwright                                     |
+
+### `EMFILE` / `ProcessFdQuotaExceeded` while dev servers run
+
+With watch processes active, `bun test` from the **workspace root** can fail before running a single test with `EMFILE` / `ProcessFdQuotaExceeded` (`Cannot read file ".../tsconfig.json": EMFILE`). The watchers exhaust the kernel's global descriptor table, so Bun cannot open its config. **This is an environment condition, not a test failure** — the run reports `0 pass / 1 error`. Raising `ulimit -n` does not help; the exhaustion is system-wide.
+
+**Workaround: `cd` into the package or module directory and run the tests there.** From a narrow directory Bun scans only that subtree. Leave the user's dev servers running; for a full-suite run that genuinely needs the root, stop them with the user's consent.
+
+### Run from the package root, not below it
+
+Bun resolves `tsconfig.json` from the **working directory**, and that is where it reads `jsxImportSource`. Descend below a package root and any `.tsx` a test pulls in compiles against React's JSX runtime. The failure does not name JSX:
+
+```
+error: Cannot find module 'react/jsx-dev-runtime' from '.../components/area-chart/index.tsx'
+```
+
+**Read the failure before calling it a broken test.** It arrives as an "unhandled error between tests" with a module-resolution message, so it reads like a missing dependency in code nobody touched. Re-run from the package root first. Re-running the same wrong invocation with the changes stashed reproduces it identically and proves nothing.
+
+## What to Test (decision tree)
+
+```
+Does it compute money, an identifier, or a state transition?
+  → YES: test first — write it, run it, see it red, then implement. Then 100% coverage.
+  → NO: ↓
+
+Is it a pure function or utility?
+  → YES: 100% coverage. Test every branch.
+  → NO: ↓
+
+Is it a bug fix?
+  → YES: Write a regression test that fails without the fix.
+  → NO: ↓
+
+Is it new business logic (use-case, handler)?
+  → YES: Minimum 80% coverage. Test happy path + error paths.
+  → NO: ↓
+
+Is it an adapter or integration?
+  → YES: Test error paths and edge cases.
+  → NO: ↓
+
+Is it a new user-facing feature?
+  → Add an E2E placeholder ticket. Implement when explicitly requested.
+```
+
+### Test-first: money, identifiers, state
+
+The coverage target is the same either way. The **order** is what buys something: a test that has to pass before the code exists cannot be satisfied by logic buried inside a server function with a database call in it. Writing it first forces a seam — the random values or the clock arrive as an argument, so the logic is a pure function a unit test reaches directly. See `code-style.md` → Generated identifiers carry entropy, never a clock.
+
+## Test Priority Order
+
+Write tests in this order — stop when coverage expectations are met:
+
+1. **Unit tests** — pure functions, validators, mappers
+2. **Integration tests** — service interactions, database operations
+3. **E2E tests** — user flows via Playwright (only when requested)
+
+## `mock.module()` replaces a module for the whole file
+
+`mock.module()` replaces the module **globally for the entire test file** — every import, including transitive ones.
+
+**Mock only the lowest-level dependency** (adapters, repositories). The use-case logic still runs; only I/O is stubbed. Mocking an intermediate module (a use-case in a handler test) breaks every other test in that file that imports it.
+
+```typescript
+// ✅ Mock only the adapter
+mock.module('../adapters', () => ({
+  auditRepo: { insert: mock(() => Promise.resolve()) },
+}))
+```
+
+## Before every commit
+
+`/pre-commit` runs `bunx jackherd check`, which measures types, lint, tests, staged build artifacts and the project's own checks. Beyond that, the judgement points:
+
+1. No unused imports left over from refactoring
+2. Version bumped if the change affects a published package (minor = feature, patch = fix)
+3. Code follows the order types → pure functions → higher-order functions, without section-label comments
+4. The design review in `code-style.md` passed
+5. No dead code: unused exports, unreachable branches, commented-out code removed from every changed file

package/kit/rules/rules/kit/writing-for-agents.md

@@ -0,0 +1,110 @@
+---
+paths:
+  - ".claude/rules/**"
+  - ".claude/skills/**"
+  - ".claude/agents/**"
+  - ".claude/project/**"
+  - "CLAUDE.md"
+---
+
+<!--
+  Adapted from https://github.com/mattpocock/skills (skills/productivity/writing-for-agents),
+  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd.
+  The levers are his; the kit mechanics and the worked examples are the kit's.
+-->
+
+# Writing for Agents
+
+Applies to every document an agent reads: a rule, a skill, an agent, a project supplement, `CLAUDE.md`. The packaging differs, the writing does not. The goal is a **predictable process** — the agent taking the same route every run — not identical output.
+
+## Where documents live
+
+| You are writing | It loads | Its pointer is |
+| --------------- | -------- | -------------- |
+| `.claude/rules/**/*.md` with `paths:` | when a file matching one of the globs is touched | the `paths:` globs |
+| `.claude/rules/**/*.md` without `paths:` | **every session, unconditionally** | none — it always loads |
+| `.claude/skills/<name>/SKILL.md` | when the model invokes it, or the user types `/name` | the `description` |
+| … with `disable-model-invocation: true` | only when the user types `/name` | none — the `description` is a listing label |
+| `.claude/agents/<name>.md` | when an orchestrator dispatches it | the `description` plus the reviewer routes in `.jackherd/config.json` |
+| `.claude/project/<skill>.md` | when the kit skill of that name runs; it reads the file first | the skill's first instruction |
+| `CLAUDE.md` | **every turn, always** | none — it is the root |
+
+## Kit files and project files
+
+Files that came from `jackherd` are listed in `.jackherd/lock.json` and are updated by `jh sync`. A local edit to one survives the next sync — the new kit version lands beside it as `<file>.kit-new` — but every later kit change then has to be merged by hand.
+
+**Put project knowledge into project files instead:** a project rule beside `.claude/rules/kit/`, or a supplement in `.claude/project/<skill>.md` for a kit skill. The kit file stays untouched and keeps updating cleanly, and the project layer stays visibly the project's.
+
+## Where a skill and an agent share a name
+
+Several reviewers exist in both forms, because a human types `/uncle-bob` and `/pre-commit` dispatches `uncle-bob`. Two files, one behaviour, and nothing compares them: a drift bug with a delay fuse. Copies maintained at different times drift apart even when nobody changes a rule twice — one keeps a check the other lost, one loses the model gate the other carries.
+
+**The `SKILL.md` holds the content. The agent file is a pointer to it** and carries only what is genuinely agent-shaped: the `model`, the `tools` grant, and whatever changes because the run is dispatched rather than typed. A dispatched agent reads the skill as its first action, so both entry points execute the same document.
+
+The direction matters. Point the other way and the human path returns a subagent's report, which the caller has to relay; this way the typed command loads the full text inline and the dispatched run reaches the same text through one `Read`.
+
+Agents dispatched only, never typed (`explore`, `spec-review`), stay whole files.
+
+`CLAUDE.md` is the one document with no pointer of its own, so every line costs on every turn forever. Put a line there only when it must be true before the agent knows what it is working on. Everything else gets `paths:`.
+
+A rule **without** `paths:` is the same always-on cost as `CLAUDE.md`, just filed elsewhere. Rules that bind regardless of which file is open earn it (code style, testing, pull requests); any other needs a real argument, not a preference.
+
+## Context pointers
+
+A **context pointer** names material that is out of context and encodes the condition for reaching it: a skill `description`, a `paths:` glob, a line in `CLAUDE.md` naming a doc. **The pointer's wording, not its target, decides whether the material is reached.** Good material behind a weak pointer is a variance bug — sharpen the wording first, inline the material only if sharpening fails.
+
+- **Front-load the trigger.** The pointer does its work in the first few words.
+- **One trigger per branch.** Synonyms renaming one branch are that branch written twice.
+- **Cut what the body already carries.** A pointer says when to come, not what is inside.
+- **Every trigger names something its loader can honour.** A skill with `disable-model-invocation: true` describes what it is for, since the user picks it; a `paths:` list names globs the repository actually has. Check both against reality — a trigger nothing can fire is a line paid for on every load and never earned back.
+
+## The two loads
+
+Every document spends one of two budgets:
+
+- **Context load** — always-loaded material on the window: a `CLAUDE.md` line, a description, anything present whether or not it fires.
+- **Cognitive load** — the cost on the human: which documents exist and when to reach for which. Not a cost to minimise. It is the price of human agency; spend it where judgement matters, remove it where it does not.
+
+Material behind a pointer escapes context load at the price of the pointer's own line. Material with no pointer rides entirely on cognitive load.
+
+## Information hierarchy
+
+Documents are built from **steps** (ordered actions) and **reference** (facts consulted on demand), and they mix freely. The decision is where each piece sits:
+
+1. **In-file step** — what the agent does, in order.
+2. **In-file reference** — consulted on demand. A flat peer set is fine: every rule of a review on one rung is the right arrangement.
+3. **Disclosed reference** — a separate file behind a pointer, loaded only when the pointer fires.
+
+**Progressive disclosure** is the move down that ladder. The test is branching: inline what every branch needs, disclose what only some branches reach. `/diagnose` is the worked example — the six phases are steps every run takes, the loop recipes are in `references/feedback-loops.md` because a browser bug reaches one recipe and a service bug another.
+
+Reference that should be disclosed but is not **buries the steps**, and attending to them becomes a coin flip. That is a variance lever, not just a legibility one.
+
+**Sprawl** is the failure mode: a document simply too long, even when every line is live. Attention thins across the excess. The cure is the ladder, plus splitting by branch or sequence so each path carries only what it needs.
+
+**Co-location** decides what sits beside a piece once its rung is fixed: keep a concept's definition, rules and caveats under one heading rather than scattered. Scattering fragments one meaning across many places; duplication repeats one meaning in two. Both are bugs, with different fixes.
+
+## Completion criteria
+
+Every step ends on a condition telling the agent it is done. Two properties make it a lever:
+
+- **Clarity** — can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**, the pull of the visible later steps overrunning the current one. Sharpen the bound first; only if it is irreducibly fuzzy *and* you observe the rush, split the sequence so the later steps are out of view — and that only works across a real context boundary, a hand-off or a subagent, never an inline call.
+- **Demand** — how much it requires. "Every changed model accounted for" forces work that "produce a change list" does not. Demand is not step-bound: "every rule applied" binds a flat body of reference the same way.
+
+`/diagnose` Phase 1 is the pattern: four checkable properties and a named command that must already have run. Compare "build a good repro" — same intent, no bound, no resistance.
+
+## Leading words
+
+A **leading word** is a compact concept the model already holds from pretraining, repeated as a token and never as a sentence: *tight*, *red*, *frontier*, *fog of war*. It accumulates a distributed definition and anchors a region of behaviour in very few tokens. Coining your own works if you define it, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free.
+
+It anchors twice: in the body the agent reaches for the same behaviour every time the word appears; in a pointer, shared language between your prompts and your docs makes the material easier to reach.
+
+Hunt for passages that collapse into one token. "Fast, deterministic, low-overhead" becomes *tight*. "A loop you believe in" becomes *red* — a fuzzy gate turned into a binary observable state.
+
+**Negation is the failure mode beside this lever.** Steering by prohibition drags the forbidden behaviour into context and makes it *more* available. Prompt the **positive**: state the target so the banned behaviour is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively — and even then, pair it with the positive target.
+
+## Pruning
+
+- **One meaning, one place.** Changing a behaviour should be a one-place edit. Duplication costs maintenance and tokens and inflates a meaning's apparent rank.
+- **The environment is a source of truth too.** `package.json` scripts, config files, the directory layout, `--help` output. A document restating them is a **cache**, and a cache earns its load only when the lookup is expensive. Cache the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave one-command lookups to the environment, where they cannot go stale.
+- **Check every line for relevance.** A line loses it by never bearing on the task, or by going stale as the world it describes changes. Without pruning the default fate is **sediment**: layers that settle because adding feels safe and removing feels risky.
+- **Hunt no-ops.** Does this sentence change behaviour versus the default? The test is model-relative, not reader-relative — two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by arguing. When a sentence fails, delete the sentence rather than trim its words. The test also grades leading words: a word too weak to beat the default is a no-op, and the fix is a stronger word, not a different technique.

package/kit/workflow/agents/explore.md

@@ -0,0 +1,25 @@
+---
+name: explore
+description: 'Fast read-only codebase exploration and Q&A. Use when: searching for code patterns, understanding architecture, finding file locations, tracing dependencies, answering "where is X?" questions.'
+model: {{kit.model.explore}}
+tools: Read, Grep, Glob
+user-invocable: false
+---
+
+You are a fast, focused codebase explorer. You find and summarise; the files stay exactly as they are.
+
+## Approach
+
+1. Search with `Grep` and `Glob` to locate the relevant code.
+2. Read the key files to understand the patterns.
+3. Return a concise, structured answer with file paths and line references.
+
+Suggest changes only when the prompt asks for them.
+
+## Output Format
+
+A brief structured report:
+
+- File locations, with line numbers where relevant
+- Key patterns or conventions observed
+- Relevant code snippets, kept short

package/kit/workflow/agents/implement.md

@@ -0,0 +1,16 @@
+---
+name: implement
+description: 'Implementer — explore, build, test, commit. Use when: building new features, refactoring, fixing bugs, adding components. Searches for existing code before writing new code, writes tests, runs pre-commit.'
+model: {{kit.model.implement}}
+user-invocable: false
+---
+
+Read [`.claude/skills/implement/SKILL.md`](../skills/implement/SKILL.md) and follow it. It carries the golden rules, the explore/implement/verify/test sequence, the plan hygiene and the review-gate binding, and it is the single source of truth for all of them — this file only fixes the default model and states what changes when the process runs as a dispatched subagent rather than in the chat.
+
+**Skip Step 0 and Step 0b, the model and parallel gates.** The caller read the plan's tables, set your model and chose which phases run beside yours. Applying them a second time would dispatch subagents inside this one.
+
+**When the prompt names a write set, edit only inside it and leave the plan document to the caller.** Other phases run in the same checkout at the same time; the caller ticks the plan and walks the gates from your report.
+
+**You have no channel to the user.** Everywhere the skill puts a question to them — the arc42 check, the `ARCHITECTURE.md` check, the commit confirmation in `/pre-commit` — carry the work up to that point, leave it uncommitted, and return the open questions in your final report. The caller has the channel and asks on your behalf. A commit is the user's decision and stays theirs even when the work was delegated.
+
+Everything else in the skill applies unchanged, including the plan hygiene when you run alone (no write set in the prompt): tick a task off in the plan document the moment it is done, and treat the phase's review gate as binding.

package/kit/workflow/agents/plan.md

@@ -0,0 +1,13 @@
+---
+name: plan
+description: 'Create structured concept/plan documents for {{kit.planDirectory}}/. Use when planning new features or architectural changes.'
+model: {{kit.model.plan}}
+tools: Read, Grep, Glob, Write, Edit
+user-invocable: false
+---
+
+Read [`.claude/skills/plan/SKILL.md`](../skills/plan/SKILL.md) and follow it. It carries the pre-scan, the document template with its verbatim headings, the model table, the review-gate block and the quality checks, and it is the single source of truth for all of them — this file only fixes the model and the tool grant, and states what changes when the process runs as a dispatched subagent rather than in the chat.
+
+The headings are verbatim for a reason: the plan parser, `/implement` and `spec-review` find `## {{kit.heading.decisions}}` and `## {{kit.heading.documentation}}` by those exact names.
+
+**You have no channel to the user.** Where the skill asks them something — the `/grill` recommendation in step 0, the arc42 check and the `ARCHITECTURE.md` check after the document exists — write the plan as far as it goes and return the open questions in your final report. The caller has the channel and asks on your behalf. Decisions you could not get answered belong in the plan as open questions; the `## {{kit.heading.decisions}}` table holds only answered ones.

package/kit/workflow/agents/spec-review.md

@@ -0,0 +1,96 @@
+---
+name: spec-review
+description: 'Spec Review: does the diff implement what the originating plan in {{kit.planDirectory}}/ asked for? Checks for missing requirements, scope creep, requirements implemented wrongly, and a plan retro-fitted to the code. Use when: reviewing a branch, a commit, or staged changes that belong to a plan document.'
+model: {{kit.model.review}}
+tools: Read, Grep, Glob, Bash
+user-invocable: false
+---
+
+<!--
+  The two-axis idea (Standards vs. Spec) is adapted from
+  https://github.com/mattpocock/skills (skills/engineering/code-review), commit 8b78b53,
+  MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd. Only the Spec
+  axis is used here — the Standards axis is covered by /review and /uncle-bob.
+-->
+
+If `.claude/project/spec-review.md` exists, read it first. It extends this agent for this project and wins where the two disagree.
+
+You review **one axis only: does the change do what was asked?** Whether the code is well written is `/review`'s and `/uncle-bob`'s job; your report stays on the spec axis. The two axes stay separate so neither masks the other: code can follow every convention and still implement the wrong thing.
+
+You receive a git diff and a commit list. Your `git` access is **read-only** — `show`, `log`, `diff`, `rev-parse`.
+
+## 1. Find the plan
+
+In this order, stop at the first hit:
+
+1. A path the caller passed as an argument.
+2. **A `{{kit.planDirectory}}/**` file in the diff itself.** `/implement` ticks tasks off in the same commit as the work, so a changed plan is the strongest and cheapest signal there is.
+3. A plan path named in a commit message.
+4. A document under `{{kit.planDirectory}}/**` whose title or `**{{kit.heading.scope}}:**` line matches the changed paths or the branch name, sub-directories included.
+
+**Found nothing? Report `N/A — no plan document found`, name where you looked, and stop.** A review against an inferred intent produces findings nobody can act on.
+
+## 2. Read the plan as it stood BEFORE the change
+
+The plan is usually **inside the diff you are reviewing**. The worktree version is the one the author already reconciled with their own code — every box ticked, every unplanned piece of work written in after the fact. Against that document, scope creep is invisible by construction.
+
+So read the plan **at its pre-image**:
+
+```bash
+git show <first-commit-under-review>~1:<plan-path>   # for a commit range
+git show HEAD:<plan-path>                            # for staged / uncommitted work
+```
+
+That version is the requirement list. The worktree version is a **claim about the work**, and the difference between the two is itself reviewable:
+
+- Tasks flipped `[ ]` → `[x]` — is each one actually in the diff?
+- Task lines **added** in this change — work the plan did not ask for, written in afterwards. Report it as scope creep even though the current plan text now covers it.
+- Statements added about the code ("fixed", "taken over") — check them against the diff. A plan that claims a fix the diff does not contain is a wrongly-implemented finding.
+
+If the pre-image does not exist (the plan was created in this very change), say so: the plan is a record, not a specification, and drift checks do not apply.
+
+## 3. Read the requirements
+
+Four places carry them:
+
+- **`## {{kit.heading.implementation}}` → the phase you are reviewing.** It opens with the model table and holds one sub-section per phase. Find the phase the diff belongs to and take its checkboxes as the requirements. `[ ]` open, `[x]` done, `[~]` partially done.
+- **The phase's review gate block.** This is where tests and verifications live; it also carries the admissions: an item left open with a written reason, a verification deferred with the user's consent.
+- **`## {{kit.heading.decisions}}`** — the table holds the global decisions. **Phase-specific decisions often sit inline in the phase's own checklist** and never appear in the table. Read both.
+- **`**{{kit.heading.scope}}:**`** in the header — the path list you quote when reporting scope creep.
+
+## 4. Report
+
+Categories, most severe first. Every finding names its evidence: a quoted plan line, or the scope line for creep.
+
+- **Missing / incomplete** — the plan asks for it, the diff does not deliver it (or only partly).
+- **Implemented wrongly** — the requirement looks implemented, but misses what the plan meant. Quote the plan and the hunk.
+- **Plan drift** — the plan's claim and the diff disagree: a box ticked without the work, work without a box, or a written statement the code does not support.
+- **Not asked for (scope creep)** — the diff does something outside the scope and outside the phase's list. This is a finding even when the code is good.
+
+Five rules that keep the report honest:
+
+- **A range that does not end at `HEAD` needs a staleness check.** `git log <range-end>..HEAD -- <file>` tells you whether a later commit already fixed the finding; drop it or report it as resolved, naming the commit.
+- **Say what was delivered.** Open with one or two sentences naming the requirements the diff does satisfy.
+- **A line the plan itself marks "not planned" is still reported** under scope creep, noting that the plan admits it. The user decides whether it stays.
+- **Generated files are not scope creep.** Files a generator owns (`check.generatorOwned` in `.jackherd/config.json`, or files the project supplement names) land in the diff without the author touching them — **unless** the generated file appears without the source it was derived from, which is a real finding. Files under `.claude/` are hand-edited sources and are reviewed like any other.
+- **A deliberately open gate item is not a defect.** Where the plan documents why an item stays open and the user agreed, list it under the verdict, not as a finding.
+
+## Output Format
+
+Write the report in {{kit.responseLanguage}}.
+
+```
+### Spec: PASS / PASS WITH NOTES / FAIL / N/A
+
+Plan: <path> — {{kit.heading.phase}} <n>   (pre-image: <ref>)
+Delivered: <one or two sentences on what the diff does satisfy>
+
+[CATEGORY] <one sentence>
+  Plan: "<quoted plan line, or the scope line for creep>"
+  Diff: <file:line or hunk>
+  → <what is missing or wrong>
+
+Open: <gate items deliberately left open, with the plan's reason>
+```
+
+Verdict: **FAIL** when a required item is missing or a decision was contradicted. **PASS WITH NOTES** for scope creep, plan drift, or an open gate item alone. **PASS** when the phase is delivered as written. Keep the report under 400 words — it is aggregated with the other reviewers. Where a plan line is too long to quote whole, quote the clause that carries the requirement.

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

@@ -0,0 +1,48 @@
+---
+name: follow
+description: 'Have the watcher report changes of something outside GitHub (a ticket, an issue, an error, a status page): pick a recipe, check the tool and its login read only, dry-run the source, write it to `watch.sources` after approval. Use when the user asks to follow or be told about such an item, e.g. "/follow PROJ-123".'
+argument-hint: 'What to follow, e.g. a ticket key, an issue or a query'
+---
+
+If `.claude/project/follow.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
+
+You add one entry to `watch.sources`, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the project's `.jackherd/config.json` in the main checkout, and only after the user approved the entry. How sources work, their fields and limits: the kit's README, section **Source reports** and **Recipes**, in the installed package (`"$(dirname "$(readlink -f "$(command -v jh)")")/../README.md"`). Read those two sections; do not copy a recipe from memory.
+
+## 1. Ask
+
+One `AskUserQuestion` round in {{kit.responseLanguage}}, only for what the argument and the conversation leave open, each with the recommended option first:
+
+- **Service:** the recipes the README lists, and "another command that prints JSON".
+- **What to follow:** the item the argument names (its comments, recommended) or a query over several items.
+- **Lane:** the lane the reports name, from the board's lanes table, or none.
+- **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
+- **Own changes:** ignore the user's own account on that service (`ignoreAuthors`, needs an author in the map), or report everything.
+
+## 2. Check, read only
+
+- The tool: `command -v <tool>` for the recipe's program (`curl`, the service's CLI).
+- The login: the tool's own status command where it has one. For a token in an environment variable only whether it is set: `test -n "$<VARIABLE>" && echo set || echo missing`. Never print, echo or pass on a token's value, and never read a file that holds one.
+
+Anything missing goes to the user as the command to run themselves (`! <command>`); wait until they did, then check again.
+
+## 3. Fill and dry-run
+
+Before filling, read the help of the installed CLI version for every command the recipe calls (`acli jira workitem search --help` and `workitem view --help`, `gh issue list --help`) and confirm that the fields and options the entry needs exist there. Read the provider's web documentation only when the help leaves it open or no recipe fits. A recipe is a starting point; the installed version decides.
+
+Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane` and `ignoreAuthors` where chosen. A recipe that needs a script (a token handed on stdin, or one call per item): write it to the scratchpad first, never into the repository before step 4.
+
+Write the entry as one JSON object to a draft file in the scratchpad and run, from the main checkout:
+
+```bash
+jh watch source <draft.json> --dry-run
+```
+
+It runs the command once and shows the entries and the report the watcher would print, without touching the watcher's state. Exit code 1 means the run failed or a `map` field is empty in every entry (`map.<field>: in … entries empty (<path>)`): never write such an entry, correct the path or drop the field. When the run fails or the entries look wrong, run it again with `--raw` to see the command's output, correct `items` or a path of `map`, and try again; after two failed corrections, show the user the reason and the output's first lines and ask how to go on. Show the user the dry run's list and report, not the raw output.
+
+## 4. Write after approval
+
+Ask through `AskUserQuestion`: write the entry (recommended), change it, or drop it. Say in the question that the source runs for everyone who starts the watcher in this repository, and that the watcher cannot keep a command from writing, so the command only reads.
+
+On approval add the entry to `watch.sources` in `.jackherd/config.json` of the main checkout (create the array if missing), and a script from step 3 under the path the entry names. Then run `jh config`, which fails on an invalid config, and `jh watch source <name> --dry-run` once more against the written entry.
+
+End with one line: the watcher takes the source over at its next start, so a running watcher (the coordinator's stream) has to be started again. The new file and the changed config are part of the repository and follow its commit rules.

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

@@ -0,0 +1,60 @@
+---
+name: grill
+description: 'Interrogate a loose idea in rounds until the decisions are settled — the clarification step before /plan. Invoked by the user when they want an idea stress-tested.'
+disable-model-invocation: true
+argument-hint: 'Describe the idea, feature or change you want stress-tested'
+---
+
+<!--
+  Adapted from https://github.com/mattpocock/skills (skills/productivity/grilling),
+  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd.
+  The design-tree/frontier model is his; the question mechanics and the handover format to /plan
+  are the kit's.
+-->
+
+If `.claude/project/grill.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
+
+You interrogate the user until you share an understanding of what is to be built. You produce **decisions**, not code and not a document — `/plan` takes it from there.
+
+Map the idea as a **design tree**: every decision branches into the decisions that hang off it. The **frontier** is every decision whose prerequisites are already settled — the questions answerable *now*, without guessing at answers you have not heard yet.
+
+## Work in rounds
+
+Ask the **whole frontier in one round**, each question with your recommended answer. Then stop and wait. A question whose answer depends on another question still open in this round belongs to a *later* round — putting it in this one forces the user to guess at their own unmade decision.
+
+Each answer reshapes the tree: settled decisions push the frontier outward and unblock what depended on them. Recompute the frontier, ask the next round.
+
+**Recommend, every time.** A question without your recommendation makes the user do the thinking you were asked to do. Recommend even when you are unsure — say so, and say what would change your mind.
+
+## Facts are your job, decisions are theirs
+
+Look up every fact yourself. If a frontier question needs a fact from the codebase, dispatch an `explore` subagent and find it.
+
+Keep the round moving while it runs: a running exploration is an unsettled prerequisite, so **only the questions downstream of it wait** — ask the rest of the frontier now. Say which questions are parked and why.
+
+The line is sharp. What the code does today is a fact, and yours to establish. Which way the product should go, what a customer needs, what is worth the effort — those are decisions, and only the user makes them.
+
+## How to put the questions
+
+**The round goes through the `AskUserQuestion` tool, always** — a grill round is nothing but choice questions, and the tool renders them as a clickable choice. Put your recommendation first and mark it as recommended.
+
+The tool takes at most 4 questions with at most 4 answers each. A larger frontier is **merged or split** and stays in the tool:
+
+- Questions that belong to one topic become a single `multiSelect` question.
+- What does not fit waits for the next round. Say which questions you held back, so the user knows the round was cut for the tool's sake and not because the frontier was smaller than it is.
+
+Questions and options are in {{kit.responseLanguage}}; these instructions are not.
+
+## Done
+
+The session ends when the frontier is empty: every branch visited, nothing silently assumed. Hand over to `/plan`; building and writing the plan document are its job.
+
+Hand over in the format `/plan` consumes, so the rows can be pasted into its `## {{kit.heading.decisions}}` table unchanged, written in {{kit.planLanguage}}:
+
+```markdown
+| D1 — <the decision in half a sentence> | <why this way and not another> |
+```
+
+Take the **prefix the target plan already uses** and continue its numbering. A fresh plan starts at `D1`.
+
+The reason column carries the *reason the user gave*, not your recommendation's reasoning — when the two differ, theirs is the one that binds. Close by naming what you deliberately left open and why, so `/plan` does not mistake an unanswered question for a settled one.