joetawil7/first-pass/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, machine-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, what a local run could send to real people (outward: sender variable names from the example env files the repo commits, never their values, the switches that stop a send, and sending packages), 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). It also describes this machine (machine: OS, cores, memory, and what can look at a UI here: Playwright's installed browsers, Android SDK tools and emulators, iOS simulators on a Mac, device tools such as agent-device or maestro, Docker, ffmpeg). 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, on this machine. May sessions start databases, browsers, emulators, media

tools or full builds without asking? Any memory or time limit, or a wrapper they must go through (in a main folder it also becomes partWrapper, step 4)? (Default: ask before each heavy run.) Say that the answer applies in every project on this machine, except a server, a worker or an end-to-end or integration run in a repo with no first-pass section, or whose real-people line says "unknown" or is missing, which asks first: it goes in the machine block, which every Claude Code session here loads, not in the repos' sections, which teammates on other machines share. Show what the survey found for looking at a UI here, and ask about anything it cannot see (a phone plugged in, a simulator with the app installed). Then, for each UI repo, what is missing to look at it running here, each with its install command, and ask which to install:

• a web repo whose browser tests use Playwright, when the build they drive is not among the

survey's: npx playwright install chromium run in the package that depends on Playwright, with its dependencies installed (otherwise npx fetches the newest Playwright, whose build that repo's tests don't drive); its --dry-run says which build that is (its "Install location"); on Linux, --with-deps when the browser cannot start for missing system libraries (it installs them with sudo);

• a web repo with no browser tests: Playwright's Chromium (npx playwright install chromium),

then a session looks with npx playwright screenshot <url> <file> (--device "iPhone 13" for a phone width);

• a native app: a simulator or emulator for each device class it ships to (on a Mac, Xcode's

iOS simulators; the Android SDK's emulator with a system image and an AVD), and a tool a session can drive it with (agent-device, maestro), when the survey finds none. Take each command from the tool's current docs, never from memory. Install only what the owner says yes to, one at a time, then run the survey again and use what it now finds; what they decline stays listed in the machine block.

• 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);

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

The machine block goes in ~/.claude/CLAUDE.md in every mode ($CLAUDE_CONFIG_DIR/CLAUDE.md when CLAUDE_CONFIG_DIR is set; create the file if there is none): it describes this machine, so every Claude Code session on it loads it from any folder, and it never travels with a folder that is shared or synced to another computer. Only Claude Code reads that file: say so in the report, since other tools fall back to the rules' "ask before each heavy run". The machine block never goes in a file teammates share. Fill assets/machine-block.md from the survey's machine and the owner's heavy-run answer: