git:20260925.dbcac0d to git:20260925.b12fce8

+ description: Set up first-pass for a main folder that holds many repos, or for one repo. In a main folder it writes one set of working rules at the root that every session loads, a workspace map, and a section in each repo with that repo's real commands, test limits and invariants, and it lists each repo's own hooks so first-pass can run them from the main folder. In one repo it writes the rules and the section into that repo. Use when asked to set up, install, add, update or re-run first-pass, to "add the shipping rules", or when the start-of-session check says something drifted. Re-run to update.

+ Installs first-pass so every session, in every tool the team uses, starts with the rules,

+ and each repo's own facts load when work reaches that repo.

+ `rules-block.md`, `profile-block.md`, `words-block.md`, `workspace-block.md`,

+ `project-block.md`, `INVARIANTS.md` and `breaker.md`. (Claude Code fills in that path. In other tools it is the

+ folder this SKILL.md was loaded from.) Read them from there and copy them exactly; never

+ write them from memory. If they cannot be read, stop and say so.

+ With the Claude Code plugin, `${CLAUDE_SKILL_DIR}/../../scripts/cli.mjs` exists: it does

+ the deterministic parts (`survey`, `record`, `cursor-rules`, `check`). Without it (a skills

+ install in another tool), do the survey by reading, and skip the steps marked *plugin*.

+

+ ## 0. Which mode

+

+ - **Main folder**: the current folder holds two or more git repos (the survey looks two

+ levels down and follows links), whether or not it is a git repo itself, or it has

+ `.first-pass/workspace.json`. Sessions start here, and a repo's own agents and hooks

+ never load (Claude Code finds them only in the folder a session starts in and above it),

+ while its CLAUDE.md loads once a file in it is read.

+ - **One repo**: the current folder is a git repo holding no other repos. Follow the steps

+ with "the workspace" and "each repo" both meaning this repo; skip the workspace block and

+ steps 4 and 6.

+ - **Neither** (not a repo, and fewer than two repos inside): ask the owner which folder

+ their sessions start in, and run setup there.

+

+ *Plugin:* `node "${CLAUDE_SKILL_DIR}/../../scripts/cli.mjs" survey .` prints, as JSON, every

+ repo (including folders a `.code-workspace` file adds from outside), with: stack and

+ frameworks, a UI guess and why, package scripts, CI files and the commands each job runs,

+ test configs, test folders and compose files, monitoring packages, where words live,

+ instruction files and their imports, instruction files Claude Code will not load

+ (`loadProblems`, `cursorRuleProblems`), the repo's own Claude Code hooks (identical copies

+ share a `contentKey`), its agents and skills, and problems (unreadable files). Save it to a temp file and read it; for more than 20 repos,

+ summarise it with a script.

+ Then, for each repo, read what the survey only points at: the CI file itself (which jobs

+ gate a merge or a deploy), the test setup (what the real-database or end-to-end tests

+ need running and how to run one file), and the existing instruction files, so the new

+ blocks do not contradict them. Where they do, keep the repo's rule and note the conflict.

+ For more than 4 repos, give each repo to its own subagent (at most 3 at a time) with

+ `project-block.md` and `INVARIANTS.md`, and have it return the filled block, the drafted

+ invariants and the conflicts; the main session writes the files. Say first how many agents

+ that is and roughly what it costs.

+ Without the plugin, find the same facts by reading: AI tool files (`AGENTS.md`,

+ `CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, `GEMINI.md`), CI config

+ (`.github/workflows/`, `.gitlab-ci.yml`, `bitbucket-pipelines.yml`, `.circleci/`,

+ `azure-pipelines.yml`), tests and what they need, monitoring (Sentry, Datadog,

+ OpenTelemetry), and where user-facing words live (UI strings, emails, help, docs, website,

+ legal and pricing pages, other repos included).

+

+ In one message, only what matters and is not inferable:

+ - **Heavy runs.** May sessions start databases, browsers, media tools or full builds without

+ asking? Any memory or time limit, or a wrapper they must go through? (Default: ask before

+ each heavy run.)

+ - **Which repos have a UI** (propose the survey's guess, and why), and whether a design tool

+ is wanted on them (see step 6).

+ - **Which depends on which**, proposed from what you read (for example "web and mobile call

+ api's HTTP API"; "the website shows the app's pricing").

+ - **Repo hooks** (*plugin*, main folder): list each distinct repo hook once (group by

+ `contentKey`), with its event, matcher, command, the script it runs and what it does

+ (read the script). For each, ask whether first-pass should run it from the main folder,

+ and whether it applies to the whole session (a mode or a guard, like a ticket guard) or

+ only to files in its repos (a formatter, a linter, a design check). A files hook on Bash

+ sees a command as its repo's only when the command names the repo (`git -C <repo> ...`,

+ or a leading `cd <repo> &&`); a session hook applies to every repo.

+ - **The profile block** holds a default reply style (answer first, short, plain words).

+ Install it? (Default: ask; never in a file teammates share.)

+ - **Habit words**, with the profile: may the `habit-words` skill read the owner's last 20

+ Claude Code sessions (only what they typed; pasted text, tool output and anything that looks

+ like a key left out) to find the words they write that make answers worse, and map each to

+ the checks it should mean? (Default: ask. No: the default words block.)

+ - **Teammates**, per repo: do other people open this repo on its own, without the main

+ folder? Then its own file also carries the rules block (the owner loads it twice), and

+ the breaker is copied into it for teammates without the plugin.

+ ## 3. The workspace root

+ Write `AGENTS.md` at the root (Cursor, Codex and most agents read it) with, in this order:

+ 1. the rules block, `assets/rules-block.md`, verbatim;

+ 2. the profile block, `assets/profile-block.md`, verbatim, if the owner wants it;

+ 3. with the profile, the words block: the `habit-words` skill's, if the owner agreed to have

+ their sessions read (run it now, steps 1 to 6), otherwise `assets/words-block.md`

+ verbatim. A words block whose marker says `through` is the owner's own: keep it. One

+ whose marker says `default` is managed like the other blocks: replace it (with the

+ skill's block if the owner now agrees);

+ 4. in a main folder, the workspace block, `assets/workspace-block.md`, filled: a one-line summary, one table row

+ per repo (what it is in a few words, stack, UI yes/no, and its group when the repos fall

+ into groups the owner named, such as two companies; drop the Group column otherwise),

+ which depends on which, and the hooks first-pass runs.

+ In one-repo mode the root is the repo, a file teammates share: the profile and words blocks

+ go in `~/.claude/CLAUDE.md` instead, and only the rules block goes in the repo.

+ Each block sits between its markers. If a block is already there, replace it (that is how

+ updates work); never edit text outside the markers, where the owner keeps their own rules.

+ Then `CLAUDE.md` at the root:

+ - missing: create it with the single line `@AGENTS.md`;

+ - already imports `@AGENTS.md`: nothing to do;

+ - exists without that import: add `@AGENTS.md` as its first line, and report every block of

+ its own text that now repeats or contradicts the rules.

+ Once this root CLAUDE.md exists, Claude Code loads a repo's AGENTS.md only when that repo's

+ CLAUDE.md imports it (tested on Claude Code 2.1.280): step 5 makes sure every repo's does.

+ ## 4. The workspace file (*plugin*, main folder)

+ Write `.first-pass/workspace.json`, then stamp it:

+ ```json

+ {

+ "firstPass": 1,

+ "repos": [

+ { "name": "api", "path": "api", "ui": false },

+ { "name": "web", "path": "web", "ui": true },

+ { "name": "site", "path": "../site", "ui": true }

+ ],

+ "ignore": ["scratch-repo"],

+ "hooks": [

+ {

+ "id": "ticket-guard", "from": "api", "scope": "session",

+ "events": { "UserPromptSubmit": "", "PreToolUse": "Edit|Write|MultiEdit|NotebookEdit|Bash" },

+ "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/ticket-guard.js\"",

+ "approve": true

+ }

+ ]

+ }

+ ```

+ - `repos`: every repo the survey found that the owner keeps, `path` relative to the root.

+ `ignore`: repos in the folder to leave out.

+ - `hooks`: one entry per approved hook: `events` maps each event to its matcher ("" for

+ all), and `command`, `args`, `shell` and `timeout` are copied from the repo's settings

+ exactly. `${CLAUDE_PROJECT_DIR}` means the repo the hook runs for; `${FIRST_PASS_WORKSPACE}`

+ means the root. Scope `session` runs from `from` on every matching event; scope `files`

+ runs only for tool calls on files in `repos` (default `[from]`) and, on Stop, once for each

+ of them the session edited, from that repo's folder.

+ - `sameAs`: when the survey shows the same hook (same `contentKey`) in several repos, write

+ one entry, `from` one of them, and list the others in `sameAs`. A session started inside

+ any of them then gets that repo's own copy from Claude Code, and first-pass does not run

+ it a second time.

+ - first-pass runs hooks on SessionStart, UserPromptSubmit, PreToolUse, PostToolUse and Stop;

+ tool hooks for Edit, Write, MultiEdit, NotebookEdit, Bash and PowerShell; never async.

+ A repo hook outside that cannot be bridged: `record` refuses it, and the report says so.

+ Then run `node "${CLAUDE_SKILL_DIR}/../../scripts/cli.mjs" record .`. It stamps each hook

+ marked `"approve": true` with the hash of its definition and of every file in the folder of

+ each script it runs, plus the repo's commit (a changed file pauses the hook until it is

+ approved again), records each repo's CI hash and hooks hash (so a later change is noticed),

+ and the plugin version. It never replaces a CI hash that changed: once a repo's section has

+ its CI line updated (step 5), run `record . --ci <repo>`.

+ To re-approve a paused hook, show the owner what changed first:

+ `git -C <repo> diff <the approved commit> -- <the pinned files>`, then set `"approve": true`

+ again and run `record`.

+ If the root's own `.claude/settings.json` already runs a repo hook by hand (a copy lifted

+ up earlier), report it: once first-pass runs that hook, the copy runs it a second time.

+ Remove it only with the owner's yes.

+

+ ## 5. Each repo

+

+ First, the file the repo's section goes in, the same on every run: the file that already

+ holds its `first-pass:project` block; otherwise `AGENTS.md` if the repo has one (every

+ tool reads it); otherwise `CLAUDE.md`. Then make sure Claude Code loads it: the repo's

+ `CLAUDE.md` starts with `@AGENTS.md` whenever the repo has an AGENTS.md (create a

+ `CLAUDE.md` holding just that line if there is none). `@INVARIANTS.md` goes once, in the

+ same file as the section (in AGENTS.md it loads through CLAUDE.md's `@AGENTS.md`, tested).

+ When CLAUDE.md and AGENTS.md are one file (the survey's `claudeMdIsAgentsMd`: a hard link or

+ a symlink), writing either rewrites both: never replace one with an import of the other.

+ Write the section and `@INVARIANTS.md` once, into that file, appending in place with the

+ shell (`>>`, `Add-Content`): the Edit and Write tools save a new file, which splits a hard

+ link into two (tested on Windows). Then run the survey again and check `claudeMdIsAgentsMd`

+ is still true; if the link split, the old name holds the old text: put the link back

+ (`ln -f AGENTS.md CLAUDE.md`, or on Windows delete CLAUDE.md and

+ `mklink /H CLAUDE.md AGENTS.md`), and say so in the report.

+ One exception: a repo that is itself a Claude Code plugin (it has

+ `.claude-plugin/plugin.json`) gets no CLAUDE.md, because `claude plugin validate --strict`

+ rejects one at a plugin's root. Its section goes in AGENTS.md, which the breaker reads;

+ say in the report that Claude Code does not load it on its own.

+

+ - **Project block.** `assets/project-block.md`, its `{{...}}` placeholders filled with exact

+ commands and paths, not descriptions: CI's checks as the commands CI runs, one test file,

+ the real tests and what they need running and how to stop it, test limits (from the

+ repo's own rules), heavy-run rules, monitoring, where its words live (sibling repos

+ included), the same job done in two places (every pair you found: two delete paths, a

+ webhook and a reconcile job, two clients for one vendor), extra pre-mortem cases the repo

+ has (its queue's retry, its second worker, its own endings), and owner rules already

+ written in the repo. Unknown stays as "unknown: <what to find out>". When the owner keeps

+ groups of repos apart (two companies that must not be linked), a repo's files never name a

+ repo of another group, even where code is shared or copied: say it in the report instead.

+ If a `first-pass:project`

+ block exists, leave it (it belongs to the team now) and only report what looks out of

+ date, with one exception: when the survey or the start-of-session check says the repo's CI

+ changed, rewrite that block's CI line from the CI files (show the owner the old and new

+ line) and then run `record . --ci <repo>`.

+ - **Rules block** only in one-repo mode, or for a repo teammates open on its own: the same

+ block as the root, verbatim. Never the profile or words block in a file teammates share;

+ in one-repo mode those go in `~/.claude/CLAUDE.md`.

+ - **Invariants.** If `INVARIANTS.md` exists, do not overwrite it; suggest additions in the

+ report. Otherwise start from `assets/INVARIANTS.md` and draft 6 to 12 from the code:

+ 1. From this catalogue, keep the ones that apply and restate each in the system's own

+ terms (not "a side effect", but "an invoice email is sent once per invoice"):

+ - An outside side effect (post, email, SMS, payment, webhook out) happens at most once

+ per intent, and one that happened is recorded as happened.

+ - A charge happens once per unit of work, a refund at most once, back to where it came from.

+ - Every outside call has a deadline; paid vendor work runs once per request.

+ - A background job survives a deploy or a crash: it finishes once or runs again, never

+ dropped, never two copies at once.

+ - Work is marked done only after it is done.

+ - Limits and "not twice" rules are enforced by the database (a constraint or a

+ conditional update), not by read-then-write.

+ - A failure never looks like "nothing": the user sees an error and a way to retry, and

+ no code writes after a failed read.

+ - Every failure that affects a user reaches that user, and every swallowed error

+ reaches monitoring.

+ - Deleting an account or a record deletes everything the privacy policy says it does,

+ stored files and third-party grants included.

+ - Every sentence users, customers or regulators read is true of the code.

+ - Nothing reads a request body before auth and size are checked; tokens are single-use.

+ - Dates and times are in the user's (or account's) timezone everywhere.

+ - Every query is scoped to the caller's tenant.

+ - A field another repo reads keeps its meaning: API, event and export contracts change

+ in every consumer together.

+ 2. Add 2 to 4 domain invariants the code implies ("an order's total equals the sum of its

+ lines", "a time slot has at most one confirmed booking").

+ 3. For each, search the code for what holds it and fill **Held by** with file:line (or

+ "convention only" / "nothing yet"). Fill **Known breaks** only with breaks you actually

+ found while looking, with file:line; otherwise "none known". Do not audit here.

+ - **Cursor rules.** If the survey lists `.mdc` imports (Claude Code never loads them): *plugin*

+ `node "${CLAUDE_SKILL_DIR}/../../scripts/cli.mjs" cursor-rules <repo>` points each import at

+ a generated `.md` copy in `.claude/cursor-rules/` and writes the copies; the start-of-session

+ check then reports any copy that falls behind its `.mdc`. Without the plugin, write the

+ copies by hand (the `.mdc` text without its frontmatter).

+ - **The breaker.** With the plugin it is `first-pass:breaker` in every session; nothing to

+ install. Without the plugin (a skills install in Cursor or another tool), copy

+ `assets/breaker.md` to `.claude/agents/breaker.md` in the folder sessions start in (the

+ root in a main folder). Also copy it into a repo teammates open on its own. If a different

+ `breaker.md` is already there, leave it and report the difference: a repo's own agent is

+ only found by a session started inside that repo.

+

+ approval rather than skipping the step. If it is refused, or the session cannot ask (a

+ headless run), report it under "Not done" with the exact command.

+ ## 6. A design tool on the UI repos (optional)

+

+ If a design skill with its own hooks is installed in one repo (for example Impeccable in

+ `<repo>/.claude/skills/impeccable`), it only works for sessions started in that repo. Offer:

+

+ - install it at the root with its own installer (Impeccable:

+ `<repo>/.claude/skills/impeccable/scripts/impeccable install --project --providers=claude -y --no-hooks`

+ run from the root), so its skill and agents load in every session from the start;

+ - one `files` hook in `workspace.json` for the UI repos, running its hook command from the

+ root copy, for example

+ `{ "id": "impeccable", "scope": "files", "repos": [<UI repos>], "events": { "PostToolUse": "Edit|Write", "Stop": "" }, "command": "\"${FIRST_PASS_WORKSPACE}/.claude/skills/impeccable/scripts/impeccable\" hook", "timeout": 30, "approve": true }`.

+ Its end-of-turn pass only finds the session's edits when run from the edited repo's

+ folder, which is what a `files` hook does;

+ - not approving that repo's own copy of the same hook, so it does not run twice.

+

+ Its commands then run from inside the project being designed: say so in the root

+ `CLAUDE.md` (outside the markers), with the script's full path.

+

+ - Re-read every file you wrote: each block exactly once per repo across its CLAUDE.md and

+ AGENTS.md together (not per file), markers balanced, no `{{` left, and `@AGENTS.md` in

+ every repo CLAUDE.md whose repo has an AGENTS.md.

+ - If a repo formats or lints Markdown in CI (Prettier, markdownlint), run that check on the

+ files you wrote in it and fix what it reports.

+ - *Plugin:* `node "${CLAUDE_SKILL_DIR}/../../scripts/cli.mjs" check .` prints nothing out of

+ date, or explain each line it prints.

+ - If a CLI is available, confirm a fresh session loads the rules from the root and a repo's

+ block once a file in it is read, for example

+ `claude -p "Without tools: quote pre-mortem question 2 from your instructions"` at the root,

+ and `claude -p "Read <repo>/package.json, then quote that repo's CI checks line from your instructions"`.

+ first-pass <version> set up in <folder> (<main folder with N repos | one repo>)

+ Written: <file> (created | block added | block updated | import added), one per line

+ Hooks run from the main folder: <id: scope, repos>, or "none"

+ Habit words: <n> mapped from <n> sessions | the default list | not installed

+ Invariants: <n> drafted in <repo>/INVARIANTS.md, review before relying on them (one line per repo)

+ Real tests: <per repo: what exists, or "none: the biggest gap">

+ Duplicates to remove (with your yes): <each hand-made copy of a hook or rule, or "none">