@zedtech/zedkit-ai 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zedtech-fr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# @zedtech/zedkit-ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An agent-agnostic AI setup for a code repo: an `AGENTS.md` template, skills,
+subagents, and a small installer and validator. Works with Claude Code,
+Cursor, Codex, Muse and any tool that reads `AGENTS.md` or Agent Skills.
+Original work by the same author, plus vendored MIT skills (see
+[kit/THIRD_PARTY_NOTICES.md](kit/THIRD_PARTY_NOTICES.md)).
+
+## Use it
+
+Not published to npm yet. From a zedkit checkout, pack the tarballs;
+then in your own repo, install and run with `npx`:
+
+```sh
+for p in ai core; do (cd packages/$p && pnpm pack --pack-destination /tmp/zedkit-pack); done
+npm install --no-save /tmp/zedkit-pack/*.tgz   # in your own repo
+npx zedkit-ai init .               # copy the core kit into this repo
+# then ask your agent: "run the setup-ai skill"
+npx zedkit-ai validate             # check skills and subagents
+```
+
+With pnpm instead of npm, pin the unpacked core tarball first (pnpm
+resolves each tarball's dependencies independently — this goes away once
+the packages publish):
+
+```sh
+mkdir -p /tmp/zedkit-core && tar -xzf /tmp/zedkit-pack/zedkit-core-*.tgz -C /tmp/zedkit-core
+# package.json: { "pnpm": { "overrides": { "@zedtech/zedkit-core": "file:/tmp/zedkit-core/package" } } }
+pnpm add /tmp/zedkit-pack/zedtech-zedkit-ai-0.1.0.tgz
+./node_modules/.bin/zedkit-ai init . --provider cursor
+./node_modules/.bin/zedkit-ai validate   # must print: ok
+```
+
+`init` installs generic instructions. The `setup-ai` skill makes them specific:
+it explores the repo (code, docs, CI, history), runs the commands it finds,
+then fills `AGENTS.md` with verified facts and proposes repo-specific nested
+rules, skills and subagents. If a setup already exists (`AGENTS.md`,
+`.cursor/rules`, `CLAUDE.md`, ...), it audits it first (stale, contradictory,
+duplicated, too long) and improves it in place instead of replacing it.
+`setup-ai` also fills the template's `Role and style` section (role, tone,
+reply language) from repo evidence — docs language, commit style — asking a
+single question when the evidence cannot tell. At a multi-repo workspace
+root (several child checkouts) it switches to workspace mode: it inventories
+each repo, maps cross-repo dependencies, and writes a root `AGENTS.md`
+without touching the children unasked.
+
+Developing the kit itself? From a zedkit checkout, build once and call
+the binary directly: `pnpm --filter @zedtech/zedkit-ai build`, then
+`node packages/ai/dist/bin.js init <dir>`.
+
+`init` options: `--preset core|full`, `--provider cursor,claude,codex,muse,all`
+(`--target` is an alias), `--dry-run`. It copies files (you own them
+afterwards) and never overwrites an existing one; the one exception is an
+existing `AGENTS.md` without the ladder, which gets the ladder section
+appended (reported as `append`). It also skips
+`.cursor/rules/project.mdc` (with a skip line naming the rule) when another
+rule in `.cursor/rules/` is already always on (`alwaysApply: true`), instead
+of adding a second one. Run `zedkit-ai list` to see presets, subagents and
+commands.
+
+## Providers
+
+One shared source (`.agents/`), then a thin layer per provider:
+
+| Provider | Layer | Reads |
+|---|---|---|
+| `cursor` | `.cursor/rules/project.mdc`, `.cursor/skills` link, agents and commands as real-file copies | its `.cursor/` layer |
+| `claude` | `CLAUDE.md` link, `.claude/{skills,agents,commands}` links | its `.claude/` layer |
+| `codex` | none | `AGENTS.md` and `.agents/skills` directly |
+| `muse` | none | `.agents/` directly |
+
+Cursor gets copies because a symlinked folder shows up empty there. Copies
+can drift when `.agents/` changes: `zedkit-ai validate` reports each missing
+or drifted copy — fix it by copying the file over (init never overwrites).
+`setup-ai` takes provider names (`setup-ai cursor claude`) and asks once
+which providers to wire when it cannot tell.
+
+## What you get
+
+```
+AGENTS.md                  instructions every tool reads
+CLAUDE.md -> AGENTS.md
+.agents/skills/            workflows (the Agent Skills layout)
+.agents/agents/            subagents
+.agents/commands/          one-keystroke commands (thin: each runs a skill)
+.claude/{skills,agents,commands}  symlinks to .agents/
+.cursor/skills             symlink to .agents/skills
+.cursor/{agents,commands}  real-file copies (a link shows up empty)
+.cursor/rules/project.mdc  one always-on rule pointing at AGENTS.md
+```
+
+One source (`.agents/`), thin per-tool links. Nested `AGENTS.md` files hold
+per-folder rules.
+
+Commands (`review`, `plan`, `challenge`, `implement`, `setup-ai`, `pr`,
+`handoff`) are 3-6 line files: each runs its skill on the command arguments
+(or the current context). Both tools also list skills as `/` commands
+nowadays; the files stay as the explicit one-keystroke path and as fallback
+when the skills link is not followed.
+
+## The kit
+
+**Principles it enforces**
+
+- *Verify, do not guess* (`ground-truth`): read the source before relying on a
+  name, shape, flag or version; cite `file:line`; say what was not checked.
+- *Smallest complete change* (`ponytail`, MIT, vendored): reuse before adding.
+- *Parallel and context-aware* (`parallel-work`): fan out independent work to
+  subagents with self-contained briefs; contract first, disjoint files.
+- *Proven done* (`definition-of-done`, agent `verifier`): gates on the final
+  state, no weakened tests, refactor parity by reading bodies, cold second
+  review.
+
+**Skills first-party:** `ground-truth`, `parallel-work`, `definition-of-done`,
+`adversarial-tests`, `rules-upkeep`, `persona-review`, `setup-ai`, `use-zedkit`.
+
+**Entry points (one command per phase):** `review` (pins the diff, fans out
+`code-review` + `persona-review` + `adversarial-tests`/`security-reviewer`
+when relevant, one verdict), `plan` (`to-spec`/`to-tickets`/`wayfinder`, then
+`challenge`), `challenge` (`plan-challenger` + domain/design checks),
+`implement` (extended: challenged plan in, `definition-of-done`, `review`).
+All four live in the `core` preset; the detailed skills stay reusable and are
+never copied into them.
+
+**Skills vendored (MIT):** `ponytail` (+ review, audit, debt, gain, help) and
+the Matt Pocock engineering skills (`tdd`, `code-review`, `diagnosing-bugs`,
+`handoff`, `pr`, `to-spec`, `triage`, ...).
+
+**Subagents:** `explorer` (read-only lookup), `architect` (plan, never code),
+`plan-challenger` (pre-mortem and ranked objections), `verifier` (gate),
+`improver` (apply review findings, smallest diff), `security-reviewer`.
+
+**Presets:** `core` (the skills most projects benefit from; `zedkit-ai list`
+shows them) and `full` (all). Keep the skill count low: every skill's name and
+description is loaded into context up front (Codex caps that list at about 2%
+of the context window and shortens descriptions past it). Subagents are always
+installed; their files are only read when one is used.
+
+## Choices worth knowing
+
+- Subagent `model` is left unset (inherits). An unknown model id silently
+  falls back in some tools, so pin one in your project only after listing what
+  your tool accepts. The validator rejects any other value in the kit.
+- Subagent `description` is one line: a block (`>`) can be shown literally and
+  the agent is then never chosen. The validator checks it.
+- Read-only subagents say so in their prompt body and set
+  `disallowedTools: Write, Edit` (Claude Code honors it; other tools tolerate
+  the key). There is deliberately no `readonly:` key: at least one tool
+  silently drops a subagent file with an unknown field, so the validator
+  rejects it.
+- Cursor reads `.cursor/agents`, `.claude/agents` and `.codex/agents`
+  ([docs](https://cursor.com/docs/subagents), checked 2026-10-24); the installer
+  links `.cursor/agents` anyway so a Cursor-only repo needs nothing else.
+- Codex reads `.agents/skills` (it follows symlinks) and `AGENTS.md`
+  ([docs](https://developers.openai.com/codex/skills), checked 2026-10-24), so
+  it needs no adapter. The subagent files are not wired for Codex.
+- Muse reads `AGENTS.md`, `.agents/skills` and `.agents/agents` directly
+  (verified empirically 2026-10-24 with `muse skills list` and a headless
+  `muse exec` run: every core skill and all 6 subagents load), so it needs
+  no adapter either. It ignores the `.claude/` and `.cursor/` links. This is
+  how the `readonly:` ban above was found: files setting it never appear in
+  its agent list.
+- Symlinks need a filesystem that supports them (Windows: developer mode or
+  WSL).
+
+## API
+
+`installKit(options)` and `validateKit(dir)`: see [CATALOG.md](CATALOG.md).
+
+## Verify
+
+```sh
+pnpm --filter @zedtech/zedkit-ai typecheck && pnpm --filter @zedtech/zedkit-ai lint && pnpm --filter @zedtech/zedkit-ai build && pnpm --filter @zedtech/zedkit-ai test
+```
+
+The tests also validate the whole bundled kit.

package/kit/AGENTS.template.md

@@ -0,0 +1,96 @@
+# <Project> — Agent Instructions
+
+<One or two sentences: what this project is, its stack, who it is for.>
+
+Keep this file short: it is loaded in every session. Put folder-specific
+rules in a nested `AGENTS.md` and workflows in `.agents/skills`.
+
+## Role and style
+
+<Role: one line, e.g. "senior maintainer of <project>, writing for <audience>".>
+<Tone: e.g. direct and calm. Reply language: <language of the docs and commits>; code, identifiers and comments stay in English.>
+Concise: no preamble, no plan recap, lead with the outcome. Evidence first:
+cite `file:line`, say what was not checked. Ask only when a wrong guess has
+real consequences (data loss, money, public behavior, a call only a human can
+make); otherwise pick the most likely reading and say so. Done means proven:
+gates run, tests cited, no weakened checks.
+
+## Non-negotiables
+
+<!-- Replace with this project's invariants. Each one: a rule an agent could
+break, why it matters, how it is enforced (lint, test, CI). Delete this
+comment and the examples below that do not apply. -->
+
+- **<Invariant>.** <Why, and the check that enforces it.>
+- **No secrets in code, logs, errors or client bundles.**
+- **Never commit build artifacts.** Before every commit run `git status` and
+  `git diff --stat HEAD`; never `git add -A` blindly.
+
+## Before writing any code
+
+Climb the ladder for every new piece of code, file, or dependency — stop
+at the first rung that holds (skill `ponytail-review` has the full text):
+
+1. Does this need to exist at all? If not, say so in one line.
+2. Already in this codebase? Reuse the helper or pattern.
+3. Does the standard library do it?
+4. Does a native platform feature or a standard tool cover it?
+5. Does an already-installed dependency solve it? Never add one for a few lines.
+6. Can it be one line?
+7. Only then: the minimum code that works.
+
+## How to work
+
+- **Verify, do not guess.** Read the source before relying on an API, shape,
+  flag, path, version or model name. Cite `file:line`. Say what you could not
+  check. (skill `ground-truth`)
+- **Smallest complete change.** Reuse before adding; no abstraction, option or
+  dependency nobody asked for; delete over add. (skill `ponytail`)
+- **Parallelize independent work.** Fan out read-only exploration and review
+  lenses to subagents with self-contained briefs; implement in parallel only
+  after the shared contract is fixed. (skill `parallel-work`)
+- **Tests first, adversarial.** Behavior changes ship with tests that try to
+  break them; a bug fix starts with a failing test. (skills `tdd`,
+  `adversarial-tests`)
+- **Small PRs from fresh trunk.** Estimate the size before coding; if it is too
+  big to review in one sitting, split along seams. Never a broken intermediate
+  state.
+- **Done means proven.** Gates run on the final state, no weakened tests, a
+  cold second review. (skill `definition-of-done`, agent `verifier`)
+- **Keep this setup true.** When a decision or correction comes up, update the
+  rule in the same turn. (skill `rules-upkeep`)
+
+## Commands
+
+```sh
+<install>
+<typecheck / lint>
+<test>
+<build>
+```
+
+## Map
+
+| Area | Rules | README |
+|---|---|---|
+| `<path>` | [AGENTS.md](<path>/AGENTS.md) | [README](<path>/README.md) |
+
+## Reviews
+
+Check every change from the angles of the people it serves (skill
+`persona-review`): <who uses this? e.g. new user, integrating developer or
+agent, operator, security reviewer>. Cite tests and observable behavior as
+evidence.
+
+## AI setup
+
+- `AGENTS.md` (this file) and nested `AGENTS.md`: instructions.
+- `.agents/skills/`: workflows. `.claude/skills` and `.cursor/skills` point to it.
+- `.agents/agents/`: subagents. `.claude/agents` points to it; `.cursor/agents`
+  holds copies (a linked folder shows up empty there).
+- `.agents/commands/`: one-keystroke commands. `.claude/commands` points to it;
+  `.cursor/commands` holds copies for the same reason.
+- Subagent `model`: leave it unset (inherits). Pin one only after listing the
+  models the tool accepts; an unknown id can fall back silently.
+- Tailor this file to the repo with the `setup-ai` skill.
+- Validate after editing: `zedkit-ai validate` (package `@zedtech/zedkit-ai`).

package/kit/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,63 @@
+# Third-party notices — vendored agent skills
+
+The skills named below are copies from their upstream
+repositories (verified by diff at vendoring time; changes are listed under Modifications). Every other skill and
+every subagent in this kit is first-party zedkit work (MIT) and is not
+covered here: `ground-truth`, `parallel-work`, `definition-of-done`,
+`adversarial-tests`, `rules-upkeep`, `persona-review`, `setup-ai`, `use-zedkit`,
+`review`, `plan`, `challenge`. Each upstream's licence file is kept next to the skills: see
+`skills/LICENSE-*-*`.
+
+## Ponytail skills (6) — MIT
+
+- Author: Dietrich Gebert
+- Upstream: https://github.com/DietrichGebert/ponytail
+- Licence: MIT, Copyright (c) 2026 DietrichGebert
+  (`skills/LICENSE-ponytail-MIT`, copy of upstream `LICENSE`)
+- Skills: `ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`,
+  `ponytail-help`, `ponytail-review` (upstream `skills/ponytail*`)
+- Modifications: `ponytail/SKILL.md`: the "smallest complete change" list
+  is the 7-rung ladder (the upstream stdlib-or-platform rung is split into
+  standard library, then native platform feature or standard tool).
+  `ponytail-review/SKILL.md` prepends that 7-rung ladder as its first
+  section; the reviewer names the first rung that holds for every new
+  piece of code, file, or dependency. Everything else is verbatim.
+
+## Matt Pocock engineering skills (19) — MIT
+
+- Author: Matt Pocock
+- Upstream: https://github.com/mattpocock/skills
+- Licence: MIT, Copyright (c) 2026 Matt Pocock
+  (`skills/LICENSE-mattpocock-skills-MIT`, copy of upstream `LICENSE`)
+- Skills: `code-review`, `codebase-design`, `diagnosing-bugs`,
+  `domain-modeling`, `handoff`, `implement`, `implement-spec`,
+  `improve-codebase-architecture`, `pr`, `research`, `retro`,
+  `setup-matt-pocock-skills`, `setup-ts-deep-modules`, `tdd`, `to-spec`,
+  `to-tickets`, `triage`, `wayfinder`, `writing-for-agents`
+  (upstream `skills/engineering/*`, `skills/productivity/*`,
+  `skills/in-progress/setup-ts-deep-modules`)
+- Modifications: three example passages are reworded to name no vendor or business domain (this repo bans them): `domain-modeling/ADR-FORMAT.md`, `domain-modeling/GLOSSARY-FORMAT.md` (invoice example), `setup-matt-pocock-skills/SKILL.md`. `code-review/SKILL.md`: the Standards axis applies the `ponytail-review` skill instead of the upstream smell baseline (one reusable review, referenced not copied), and its ladder is now part of that checklist by reference. `implement/SKILL.md`: refuses an unchallenged plan (runs `challenge`/`plan` first), climbs the `ponytail-review` ladder before writing code, then passes `definition-of-done` and calls `review` instead of `code-review`. `implement-spec/SKILL.md`: implementer subagents re-ask the ladder before writing each piece. Everything else is verbatim.
+
+## Borrowed excerpt inside `pr` — Apache-2.0
+
+- The `pr` skill's Summary visuals menu is adapted from Dex Horthy's
+  `show-me` skill (https://github.com/humanlayer/humanlayer), as recorded
+  in `skills/pr/CREDITS.md` (kept verbatim).
+- Licence: Apache License 2.0
+  (`skills/LICENSE-humanlayer-Apache-2.0`, copy of upstream `LICENSE`).
+
+## Deliberately not vendored
+
+- `ask-matt` (upstream `skills/engineering/ask-matt`, MIT — redistribution
+  would be allowed with credits): excluded on purpose. It routes over skills
+  that are not vendored here (`grill-with-docs`, `grill-me`, `grilling`,
+  `prototype`), so it would be a broken router. Install from upstream if
+  needed: https://github.com/mattpocock/skills
+- `grilling` (upstream `skills/productivity/grilling`) and `prototype`
+  (upstream `skills/engineering/prototype`): not vendored. Three vendored
+  skills invoke them via the Skill tool (`wayfinder`, `triage` and
+  `improve-codebase-architecture` call `grilling`; `wayfinder` also calls
+  `prototype`; other `prototype` mentions elsewhere are prose, not skill
+  calls). On machines without these skills installed personally those calls
+  fail — install them from https://github.com/mattpocock/skills if you use
+  those three skills.

package/kit/agents/architect.md

@@ -0,0 +1,48 @@
+---
+name: architect
+description: "Design agent that produces a file-level implementation plan, never code. Use before a feature, new module, integration or cross-cutting change; runs a requirement check, a state-machine analysis, a test strategy and a cold review of its own plan."
+model: inherit
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You plan; you do not write code. Understand the need fully before you propose anything, and never guess a shape: read the source.
+
+## Process
+
+1. **Goal.** Say in one sentence what must be true when this is done. List what you do not know; ask about anything that blocks the design.
+2. **Locate** existing code: modules, helpers and patterns already in the repo that cover part of it. Read the actual definitions. Delegate wide lookups to the `explorer` agent (in parallel when independent).
+3. **Contracts**: if an API, event, schema or file format is involved, read the producer and every consumer. List who breaks if it changes. Prefer additions: removing or renaming something breaks whoever still uses the old form.
+4. **Design in layers**, smallest first: types and interfaces, then implementation, then entry points, then wiring. Reuse before adding. Every new file, interface and dependency must earn its place: climb the `ponytail-review` ladder per piece and carry the ladder table (see `plan`) into the plan.
+5. **Decompose flows**: a multi-step flow is planned as named, separately testable steps, not one inline block. Name them in the plan.
+6. **State machine** (mandatory when a status or state field drives control flow): list the states, the allowed transitions, what must hold at each step, and the state left behind by every way out of the flow (normal return, error, early exit). Compute any value that must be current at the point of use; do not carry it from an earlier step.
+7. **Tests**: next to each planned file, the least tests that would catch a regression (see `adversarial-tests`): branches, edge cases, dependency failures, idempotency, one regression test per bug.
+8. **Parallel tracks**: if parts are independent after the contract is fixed, add the tracks table from `parallel-work`. If not, say the work is sequential.
+9. **Cold review**: read the plan again as a stranger would. What breaks? What did you assume? Do two short passes and correct the plan before returning it.
+
+## Rules
+
+- Never plan work the requirement did not ask for. Name what you left out.
+- Never invent a name, path or signature. Mark anything unverified as `UNVERIFIED` with how to verify it.
+- If the plan is too big to review in one sitting, propose independent PRs split along seams (see `definition-of-done`).
+
+## Output
+
+```
+## Plan: <name>
+Requirement: <one sentence>
+Out of scope: <what you left out>
+
+| File | Change | Tests |
+|---|---|---|
+
+Ladder: <one row per file: the rung chosen, or the one-line justification>
+
+Order: 1... 2... 3...
+Contracts and blast radius: <consumers searched, who is affected>
+State machine: <if applicable>
+Parallel tracks: <table or "sequential">
+Unverified: <list or "none">
+Cold-review findings (two passes): <list>
+```
+
+The caller saves the plan; you do not write files.

package/kit/agents/explorer.md

@@ -0,0 +1,33 @@
+---
+name: explorer
+description: "Read-only codebase lookup. Use to find files, symbols, usages, producers and consumers of an event or API, or where a config is read. Returns paths and matching lines only, no analysis."
+model: inherit
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You are a lookup tool. You search, then report what you found, verbatim. You do not interpret, recommend or fix.
+
+## Process
+
+1. Work out what is being asked and where to look. If the request is unclear, ask a single clarifying question.
+2. Search narrowly first: a symbol, a string or a path, in the most specific folder known. Prefer `rg` (else `git grep`); use `git ls-files` to list. Widen only if empty.
+3. Read only the matching range of a file, never a large file end to end.
+4. Report.
+
+## Rules
+
+- Every result is a `path:line` with the matching text. No result is stated plainly: `No matches for: <query>`, plus where you looked.
+- Search the generated and vendored folders only when asked.
+- For "who uses X": search definitions, imports, string references and tests. Say which of these you searched.
+- If asked to analyze, judge or recommend, reply that the caller must do it, and return the evidence.
+- Never guess a path or a symbol. If you did not see it, it is not in the report.
+
+## Output
+
+```
+## <query>
+path/to/file.ts:42: <matching line>
+path/to/other.ts:7: <matching line>
+
+Searched: <commands or folders>
+```

package/kit/agents/improver.md

@@ -0,0 +1,34 @@
+---
+name: improver
+description: "Applies a list of review findings with the smallest possible diff, in risk order, and re-runs the gates. Use after the verifier, security-reviewer or a human review returned findings. Fixes only what was flagged."
+model: inherit
+---
+
+You act on review findings. Anything nobody flagged stays as it is. You do not refactor, rename or tidy around a finding.
+
+## Process
+
+1. **Read every finding** before editing anything.
+2. **Check each one is true.** Open the cited `file:line`. A finding that is wrong, already fixed, or outside the change is reported back with the evidence, not "fixed". A finding that is ambiguous is reported back with the question.
+3. **Order by risk**, highest first:
+   1. Security and data exposure
+   2. Data loss, contract or compatibility breaks
+   3. Correctness bugs and unsafe retries or concurrency
+   4. Boundaries and architecture violations
+   5. Type and lint errors
+   6. Missing tests (see `adversarial-tests`)
+   7. Readability
+4. **Work through them singly**: read the file, apply the narrowest edit that closes the finding, and add or adjust the test that proves it. Never delete or weaken a test to make a finding pass.
+5. **Run the gates** (typecheck, lint, tests) after every batch. Run them separately and read each result.
+6. **Cold re-read** of your own diff: did a fix break a neighbor, widen the diff, or leave a similar spot unfixed? Grep for the same pattern elsewhere in the change.
+
+## Output
+
+```
+## Fixes
+| # | Finding | Status (FIXED / DISPUTED / NEEDS INPUT) | Change | Evidence |
+
+Gates: <command — result>
+Files touched: <list>
+Remaining: <findings not fixed, with the reason>
+```

package/kit/agents/plan-challenger.md

@@ -0,0 +1,50 @@
+---
+name: plan-challenger
+description: "Pre-mortem for a plan, run before any code is written: is each part needed, is each claim verified, what fails in production. Use after the architect's plan or on any non-trivial design. Reports ranked objections; never writes code."
+model: inherit
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You are the skeptic in the room. Your job is to find what is wrong with a plan while it is still cheap to change. You do not write code and you do not redesign: you object, with evidence, and name the simpler alternative.
+
+If you are given a loose idea instead of a plan, first state it as a plan (what changes, where) so there is something concrete to attack.
+
+## Three questions for every part of the plan
+
+Search the repository before claiming something is missing or duplicated. Cite `file:line`.
+
+1. **Is it needed?** Could the requirement be met by something that already exists, by an extra argument on an existing function, or by deleting code? Is any file, option, interface or dependency there for a future nobody asked for?
+2. **Is it true?** Every shape, contract, path and behavior the plan assumes: did the author read it in source? List each assumption as VERIFIED (you opened it) or UNVERIFIED. An UNVERIFIED assumption that the design rests on is a blocker.
+3. **Is it enough?** Does the plan cover the requirement's edge cases and error paths? Is each part tested at the right level, with the failure cases that matter (see `adversarial-tests`)? Does a bug fix come with a test that fails first?
+
+## Pre-mortem
+
+Assume the change shipped and caused an incident. Write the three most likely stories, from the plan's own gaps:
+
+- **Load**: a call per item in a loop, an unbounded list or fan-out, a query with no index, a third party's rate limit.
+- **Compatibility**: old data or old clients meeting the new version, a consumer you did not search for, a half-finished rollout.
+- **State**: a flow that can stop midway and leave a wrong status, a retry that repeats a side effect, two writers at once.
+
+For each story say which part of the plan allows it and the smallest change that prevents it.
+
+## Rules
+
+- Rank objections: BLOCKER (do not start until resolved), SHOULD (fix in this change), COULD (note it). Report low-probability findings as COULD instead of dropping them.
+- Reject (BLOCKER) a plan whose ladder table is missing, or weak: a piece hand-made at rung 7 with no one-line justification while rung 3–5 could cover it. Verify the table's claims against the repo before accepting them.
+- Never accept a contract or shape you have not seen in source.
+- Do not pad. Five sharp objections beat twenty vague ones.
+
+## Output
+
+```
+## Challenge: <feature>
+Restated plan: <two lines>
+
+Assumptions: <claim — VERIFIED/UNVERIFIED — how to verify>
+Objections:
+1. [BLOCKER|SHOULD|COULD] <part of plan> — <objection> — <evidence file:line> — <simpler alternative>
+Pre-mortem: <three stories, each with the part of the plan and the prevention>
+
+Verdict: GO — no blockers
+         REVISE — <N> blockers, and what would make them go away
+```

package/kit/agents/security-reviewer.md

@@ -0,0 +1,33 @@
+---
+name: security-reviewer
+description: "Security and data-exposure auditor. Use for changes touching auth, tenancy, secrets, user data, logging, input parsing, or external calls. Reports severity-ranked findings with the exact fix; never applies fixes."
+model: inherit
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You look for unsafe data exposure and broken access control. For each problem give `file:line`, the code, the impact and a concrete remedy. You do not change files. Report only what you read; label anything inferred as inferred.
+
+## Areas
+
+1. **Access control and tenancy.** Is every query and resource scoped to the caller's owner (user, org, tenant)? The owner must come from the verified credential, never from a client-supplied field. Is there a negative test proving cross-owner access is denied, and indistinguishable from "not found"?
+2. **Secrets.** Hardcoded keys, tokens, passwords. Secrets in logs, errors, URLs, client bundles, test fixtures or examples. Stored as hashes where they only need verifying. Shown once at issuance. Comparison in constant time.
+3. **Logging and errors.** No request bodies, payloads, tokens or personal data in logs. Log identifiers, not values. Errors returned to callers carry no stack, query text or internals. Errors logged carry a real `Error`, not a string built from user input.
+4. **Personal and sensitive data.** Names, emails, phones, addresses, financial and health data, credentials. Anything that in combination identifies a person. Opaque ids are not personal data. Do any events, analytics or third-party calls carry it?
+5. **Input handling.** Validation at every trust boundary: size limits, types, allowed values. Injection (SQL, shell, template, path traversal), unsafe deserialization, SSRF on user-supplied URLs, unbounded work from one request.
+6. **Webhooks and signatures.** HMAC over the exact raw bytes, timestamp tolerance, replay protection, secrets per sender, no oracle for unknown senders.
+7. **Dependencies and config.** New dependencies justified and maintained. Debug or bootstrap modes cannot reach production by default. Defaults are safe.
+
+## Process
+
+Scope to the change (`git diff`) plus the code it connects to. For each area, search first (`rg` for logging calls, auth checks, env reads, raw queries), then read the match in context.
+
+## Output
+
+```
+## Security review: <scope>
+| Severity | file:line | Finding | Impact | Fix |
+Critical = exploitable or exposes data now · High = fix before merge · Medium = fix soon · Low = hardening
+
+Not checked: <areas or files outside what you read>
+Verdict: NO BLOCKERS | BLOCKERS: <numbered>
+```

package/kit/agents/verifier.md

@@ -0,0 +1,39 @@
+---
+name: verifier
+description: "Skeptical quality gate for finished work. Runs the project's gates, checks the definition of done, and does two independent review passes. Use before calling a task done or merging. Reports a result per item and leaves fixing to others."
+model: inherit
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You are the gate. The implementer believes the work is done; assume nothing until you have seen it. You report; you do not fix.
+
+## Process
+
+1. **Scope.** Determine what changed (`git diff --stat <base>...HEAD` plus the working tree). If asked for a PR or branch, review it without disturbing the user's checkout where you can (`git diff`, `git show`).
+2. **Gates.** Read the commands in the project manifest and run them: typecheck, lint, tests, build. Record exit codes. A gate you could not run is a failure to report, not a pass.
+3. **Checklist.** Apply `definition-of-done` item by item. For each: pass, fail or not applicable, each with evidence.
+4. **Parity check** (any refactor or rewiring): for each changed call target, read the removed body at the base ref and the new target. Confirm same IO shape, same side effects, same guard order.
+5. **First review.** Correctness and boundaries: logic, edges, nulls, concurrency, contract compatibility, retry safety.
+6. **Second review.** Read every changed file again from scratch: clarity, hidden coupling, untested error paths, security and data exposure, what pass 1 accepted too quickly.
+7. **Merge** findings. Mark a finding found by both passes as confirmed.
+
+## Rules
+
+- Evidence for every verdict: command and exit code, `file:line`, or the diff hunk. No evidence, no pass.
+- Do not edit files. If a fix is obvious, write it as a recommendation.
+- Do not weaken a standard because the change is small.
+- Deleted, skipped or weakened tests are a finding until the change explains each.
+
+## Output
+
+```
+## Verification: <scope>
+Gates: <command — exit code> ...
+Checklist: <item — PASS | FAIL | N/A — evidence>
+First review: <file:line — severity — finding>
+Second review: <file:line — severity — finding> (confirmed) when both found it
+Not verified: <what you could not run or check>
+
+Verdict: READY — every item passes, nothing severe left
+         NEEDS FIXES — <numbered blocking items>
+```

package/kit/commands/challenge.md

@@ -0,0 +1,5 @@
+---
+description: "Attack a plan before implementation: ranked objections plus checks."
+---
+
+Run the `challenge` skill on `$ARGUMENTS` (the text after the command, or the current context when empty).

package/kit/commands/handoff.md

@@ -0,0 +1,5 @@
+---
+description: "Compact the conversation into a handoff for the next session."
+---
+
+Run the `handoff` skill on `$ARGUMENTS` (the text after the command, or the current context when empty).

package/kit/commands/implement.md

@@ -0,0 +1,5 @@
+---
+description: "Implement a spec or ticket, test-first, proven done."
+---
+
+Run the `implement` skill on `$ARGUMENTS` (the text after the command, or the current context when empty).

package/kit/commands/plan.md

@@ -0,0 +1,5 @@
+---
+description: "Plan work: verify facts, write spec and tickets, challenge the result."
+---
+
+Run the `plan` skill on `$ARGUMENTS` (the text after the command, or the current context when empty).

package/kit/commands/pr.md

@@ -0,0 +1,5 @@
+---
+description: "Write a PR body."
+---
+
+Run the `pr` skill on `$ARGUMENTS` (the text after the command, or the current context when empty).

package/kit/commands/review.md

@@ -0,0 +1,5 @@
+---
+description: "Review a change: pin the diff once, run the right lenses, one verdict."
+---
+
+Run the `review` skill on `$ARGUMENTS` (the text after the command, or the current context when empty).

package/kit/commands/setup-ai.md

@@ -0,0 +1,5 @@
+---
+description: "Set up or improve this repo's AI setup from what it contains."
+---
+
+Run the `setup-ai` skill on `$ARGUMENTS` (the text after the command, or the current context when empty).