Setup First Pass

setup-first-pass

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.

The files this skill copies are in its own folder, ${CLAUDE_SKILL_DIR}/assets/: 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.

Nothing is committed, pushed or branched: the owner reviews and commits.

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.

1. Survey (read only)

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).

2. Ask only what the code cannot tell you

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.
• The Jev judge (plugin, optional): does the owner have a TypeSafe Jev API key? ship-check can then ask Jev whether a review finding is real harm (it can add harm, never clear it), which small ones to fix now, and what proof a small fix needs. If yes: the variable that holds it, whether it is in the environment or in a gitignored env file, and for which repos (a key per account when repos belong to separate accounts). Never ask for the key itself. (Default: not set up; /first-pass:jev sets it up later.)

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:

{
  "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.