init · diff

git:20261013.c7f31ca to git:20261027.9a257af

13 added, 1 removed. Audit A to B.

---

name: init

description: Sets up the current project for Claude Code work from what its code actually does - a conventions section in CLAUDE.md, lint and test quality-gate hooks, a review checklist, and project agents or skills only where the repo clearly needs them. Proposes everything first and writes only after approval. Use when the person runs /kit:init or asks to set up, bootstrap or kit out a project for Claude Code.

---

# kit init

You are setting this project up so that agents working in it follow its real conventions and can't report done with broken lint or tests. Everything you propose must come from this repo's code, not from general best practice. A conventions section that could be pasted into any project is worthless; leave it out.

The kit plugin already ships four agent types with their model pinned: `kit:builder` (Sonnet, implements a brief), `kit:reviewer` (Opus, read-only review against the checklist), `kit:test-writer` (Sonnet, tests from the spec first), `kit:scout` (Haiku, read-only search). Don't recreate them per project.

## 1. Scan

Use `kit:scout` agents or your own searches; read excerpts, not whole trees. Find:

- **Languages and frameworks**, from manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `*.csproj`, `Gemfile`, ...) and file counts.

- **Commands**: package scripts, `Makefile`/`justfile`/`Taskfile` targets, CI workflow steps. Name the exact lint, typecheck, format, test and build commands, and whether each can run on one file. CI is the best evidence of which commands the project really trusts.

- **Services and ports**: `docker-compose*`, `Procfile`, dev scripts that start several processes, hard-coded or env-driven ports.

- **Conventions in use**, each backed by two or more files you can cite: error handling (exceptions vs result types, where errors are logged or wrapped), module and directory layout, naming, how config and secrets are loaded, how tests are organised and what they mock, patterns that recur (repositories, handlers, hooks, DI). Note where the code is inconsistent; say so rather than picking a winner silently.

- - **What exists already**: `CLAUDE.md`, `.claude/settings.json`, `.claude/agents|skills|commands`, `.claude/kit/`. You extend these; never discard what is there. If `.claude/kit/` exists, kit has run here before: say so and suggest `/kit:revise` instead, unless the person wants a fresh pass.

+ - **What exists already**: `CLAUDE.md`, `.claude/settings.json`, `.claude/agents|skills|commands`, `.claude/kit/`. You extend these; never discard what is there. If `.claude/kit/` exists, kit has run here before: say so and suggest `/kit:revise` instead, unless the person wants a fresh pass. If it exists without `.claude/kit/manifest.json`, offer that as its own small proposal: the manifest facts read from the current files (the gates' commands, the agents in use, the setup scripts), written with `write` as in section 3.

- **Checks already in place**: hooks in `.claude/settings.json` or `.claude/hooks/` that already lint, typecheck or test; a gate script; pre-commit tooling (husky, lefthook, pre-commit); CI. A check the project already runs on edit or on stop must not run twice. Propose kit's gates only for what is missing, and say which existing check covers the rest.

- **What a fresh worktree needs before tests pass**: dependency install (pnpm, npm, yarn, uv, poetry, pip), gitignored files the code reads (`.env*`, local config), generated code (Prisma, OpenAPI, protobuf, `.next`), Docker Compose services, a local database, lint/typecheck caches.

- **Tools that scan the whole repo** (`eslint .`, `prettier .`, test runners, file watchers, `tsc` with broad `include`): check that each one's ignore config excludes `.claude/worktrees/`, where agent worktrees live. Otherwise a check run in the main checkout also scans every agent's worktree. Check git too (`git check-ignore -q .claude/worktrees/x`): unignored, the worktrees leave the main checkout permanently dirty, so the stop gate runs the tests on every stop.

## 2. Propose

Show the person one proposal, grouped by file, with the full text of new files and a diff for changed ones. Include only what the scan supports:

1. **`CLAUDE.md` conventions section.** Short: commands (exact), layout, and the conventions you found, each with a file reference. Under 60 lines; every line loads into every session.

2. **Quality-gate hooks** in `.claude/settings.json` plus small gate scripts in `.claude/kit/`. A lint or typecheck after each edit (PostToolUse on `Edit|Write|MultiEdit`), and the tests before the main agent stops (Stop), and before subagents stop (SubagentStop) when the tests take under about a minute. Use the templates in `hooks-reference.md` in this skill's directory, filled with the commands you found. Merge into existing settings; don't replace other hooks.

3. **If there is no linter or typechecker**, say so first and recommend the standard one for the stack (with its config). It catches more than any agent will, on every edit, for free. Offer to add it; don't add it without a yes.

4. **`.claude/kit/review-checklist.md`**, seeded from the conventions: 5 to 15 checkable items, each specific to this repo ("handlers return `Result`, never throw: see `src/api/users.ts`"), not generic ("code is readable"). Leave out anything the linter already enforces.

5. **Project agents, skills or commands, only where the repo clearly needs one**: a recurring multi-step procedure (release, migration, codegen), a domain that needs a specialist brief. Each with the evidence. Usually the right number is zero; `/kit:revise` adds them later from real use.

6. **`.claude/worktree-setup.sh` and/or `.ps1`, only if a fresh worktree can't run the tests without setup, or the repo runs services that need separate ports.** The `worktrees` plugin runs it in each new worktree with `WORKTREE_PATH`, `WORKTREE_SLOT` and `PORT_BASE` set; slot N owns ports `PORT_BASE` to `PORT_BASE+9`. Use the stub in `hooks-reference.md` and keep only the steps the scan found. The rules behind it: install dependencies per worktree from the shared cache (pnpm store, uv cache), never copy or symlink `node_modules` or a venv (tools resolve the link back to the main checkout; an editable install in a shared venv imports the main checkout's code); copy gitignored config; regenerate generated code rather than copying it; give each slot its own Compose project and database; copy lint/typecheck caches only with a content-based cache strategy. Setup should finish in about 30 seconds, since every editing agent waits for it.

7. **Ignore entries** for `.claude/worktrees/` in `.gitignore` and in any repo-scanning tool's config that lacks one.

+ 8. **The manifest's facts**, as one item: the JSON object `write` will record in `.claude/kit/manifest.json`, with exactly `checks` (`{name, kind, command, gate}`, gate `edit`, `stop` or `none`), `agents` (`{name, readOnly, declaredBy}`), `riskyPaths` (`{path, why}`) and `setupScripts`. List kit's own agents as `kit:reviewer` and `kit:scout` read-only and `kit:builder` and `kit:test-writer` not, declared by `kit`; a project agent has its bare name and `declaredBy: "project"`. Propose `readOnly: true` for a project agent only when its `tools` line lists none of `Write`, `Edit`, `NotebookEdit` and `*` (Bash is fine; no `tools` line means every tool, so not read-only), and never for a Claude Code built-in type such as `general-purpose`. Beside each read-only entry, say what it does: the stop gate skips that agent type, and its Agent calls skip worktree isolation, so it runs in the main checkout. The schema is `docs/manifest.schema.json` in this plugin.

End with the list of files you will create or change, and ask whether to write all of it, some of it, or none.

## 3. Write

Write only what the person approved. Then:

+ - Write the manifest from the approved facts, never before approval: pipe them to `<python> <script> write --repo <project root> --facts -`. The script is `scripts/kit_manifest.py` in this plugin: from this skill's base directory, `../../scripts/kit_manifest.py`, resolved to an absolute path. Use the first of `python3`, `python`, `py -3` that prints Python 3.9 or newer for `--version`. It prints one JSON line; show the person its `gates` statuses. `no-markers` means a gate predates the `kit:read-only-agents` markers: propose the current template for it. The lines between the markers belong to the script and are replaced on every run. On a non-zero exit it wrote nothing; show its one stderr line, then:

+ - exit 2: the facts are wrong; fix them and run again.

+ - exit 3 `MANIFEST_CORRUPT`: the existing manifest is broken. Ask the person whether to rewrite it from the current files; on yes, rename it to `manifest.json.bak` and run `write` again.

+ - exit 3 `NEWER_VERSION`: a newer kit wrote it. Stop and tell the person to update kit.

+ - exit 1 `IO_ERROR`: the OS refused the file the line names. Ask the person; don't retry around it.

- Run each gate script once by hand (pipe it a sample hook input, as in `hooks-reference.md`) and show that it passes on the current tree, or fails for a real reason.

- Make the scripts executable on Unix (`chmod +x`).

- Tell the person what will now happen on edits and on stop, and that `/kit:revise` will suggest changes once there are a few weeks of sessions.

+ Whenever the setup changes later (a check, an agent, a risky path or a setup script added or dropped), run `write` again with the full new facts. Agents other plugins declared are kept.

Don't commit unless asked.

+ ## Declare flow

+ When started with args `declare read-only: <type>, <type>` (foundry init does this), don't scan. Show the person the declaration, for example "foundry asks kit to mark `foundry:judge`, `foundry:cynic` read-only: no worktree, no stop-gate run". Each type must be a full `plugin:name`, all with one prefix; refuse anything else. On approval run `<python> <script> declare --repo <project root> --by <the types' prefix> --read-only <type>,<type>` and show its output. If it exits 3 with `NO_MANIFEST`, run the full init above and put the declared types in its facts' `agents` as `readOnly: true`, declared by their prefix. Any other non-zero exit: handle it as for `write` above, except that exit 2 means the declaration is wrong, so show it and stop.