Topping Out: Setup

One command from an empty repo to a repo ready for its first job: the files installed, the repo profile written from what the repo actually has, the names files, the test adapter proved, and the checks run.

First run, before the skill is installed: start a session in the repo and say Read <package>/skills/f-setup/SKILL.md and follow it. The install copies this skill too, so every later run (an upgrade, a re-check) is just /f-setup.

The contract:

• Copy only what's missing; never overwrite. A file the repo already has may carry its adaptations (SETUP.md §1 "Adapt"). The installer's upgrade mode is the only path that replaces a file, and only one unchanged since the last install.
• Find out before asking. Read the repo for every profile field it can answer; ask the owner only what it can't, in one batch.
• Git custody: setup never pushes, and never stages or commits on its own. An install ends with the list of files for the owner's commit. An upgrade, on the owner's word, stages exactly the installer's == to commit list and commits it (Step 1b); pushing, or a PR, stays the owner's.
• Secrets: read the names of keys in .env files, never their values; never print a value. Never echo the names kept out of records (Step 3) into chat or a tracked file.
• Ends with one line: F-SETUP: READY <profile path> or F-SETUP: HALTED <specific reason>.

Step 0 · Where things are

• The repo: the current working repo. If it isn't a git repo, HALT: not a git repo.
• The package: a folder holding METHOD.md and skills/:
  • the path the owner gave, or the folder this file sits in (<package>/skills/f-setup/);
  • an installed copy (.claude/skills/f-setup/) is not the package. If no package folder is at hand (the skills came from a skills installer, or this is an upgrade), clone it: git clone <the package's repo URL> scratch/topping-out-package (the URL the owner gives, or the one in the receipt's package: line). Use a full clone, not --depth 1: an upgrade diffs against the receipt's old revision.
• Mode:
  • foreman/INSTALL-RECEIPT.txt exists → upgrade (Step 1b).
  • No receipt, but foreman/method/ or Topping Out skills in .claude/skills/ already present → an install from before receipts. Don't run install mode (it would stamp today's revision over older files). Ask the owner for the package revision it came from, write a receipt with that revision: line, then upgrade. If nobody knows it, upgrade by hand (SETUP.md §1, "Upgrade by hand").
  • Neither → install (Step 1a).
• The one question asked first: "Is this product an AI agent built on LangChain, LangGraph or Deep Agents?" (yes / no / not sure; the repo's requirements.txt, pyproject.toml or package.json naming deepagents, langgraph or langchain makes yes the default; "not sure" is answered from those files, and none of them naming one means no). Yes adds the Deep Agents add-on (Step 1c); no skips it, and the profile's framework check is none unless the owner names another.
• Prerequisites: git, node (18 or later), python (3.9 or later), and a Bash shell (Git Bash on Windows): work orders run in Bash (templates/REPO-PROFILE.md, "Shell for work orders"). Check each with --version; a missing one is a HALT naming it.
• Required tools, checked and warned about (never a HALT): Pi (pi --version), Orca (orca --version), the Greptile app on the repo (the repo's installed GitHub apps, or ask the owner once), and an OpenRouter key (the name OPENROUTER_API_KEY in .env, never its value). Each one missing gets one loud line, REQUIRED BUT MISSING: <tool>: <what it costs you> (Pi or Orca: work orders carried by hand, no autonomous run or night shift; Greptile: no review rounds on PRs; OpenRouter: no plan-check readers from other model families), repeated in the final report. Setup still finishes.

Step 1a · Install

1. node <package>/skills/f-setup/install.mjs --repo <repo> --dry-run: show the owner the count and the kept … lines (files the repo already has, which are never replaced; a skill kept under the same name may be the repo's own, so say which).
2. node <package>/skills/f-setup/install.mjs --repo <repo>: copies what's missing, creates the foreman/ folders, writes foreman/INSTALL-RECEIPT.txt with the installed … lines, and adds scratch/ to .gitignore unless git already ignores it. Exit 2 with "uncommitted changes" means the package checkout is dirty: report it and HALT (the receipt would name a revision that doesn't match the files).
3. Builders that read .agents/skills/ instead of .claude/: if the repo has an .agents/ folder or the owner names such a builder, mirror .claude/skills/ there the same way (copy only what's missing).

Step 1b · Upgrade (also: "update Topping Out")

The owner types /f-setup; everything below is this skill's work. Say what each step found in one line.

1. A clean point: the repo on its main branch (git branch --show-current), no job worktree open (git worktree list shows only the main checkout, or worktrees the owner says aren't jobs), no tracked changes in the files the upgrade touches. Not clean: say what's open and HALT.
2. The package on this machine: the receipt's package: path if it exists here and is a git checkout of the receipt's URL; otherwise scratch/topping-out-package (clone it from the receipt's URL, full clone, if it isn't there).
3. Is there anything new? node <package>/skills/f-setup/install.mjs --repo <repo> --pkg <package> --check (read-only: it fetches the package's remote). UP TO DATE: say so and stop with F-SETUP: READY.
4. The plan, with the newest package: node <package>/skills/f-setup/install.mjs --repo <repo> --pkg <package> --upgrade --pull. It fast-forwards the package checkout, then prints the plan and what's new (the CHANGELOG.md lines this install hasn't seen), writing nothing in the repo.
   • Exit 1: a job is open (foreman/jobs/JOB_*.md) or an end game is owed (foreman/ENDGAME-PENDING.md, or a lane's foreman/ENDGAME-PENDING-<lane>.md). Report it and HALT.
   • Lane mode (the repo profile has a "Lanes" row): the installer sees only this machine's files, so before applying also read the board through snippets/board_pull.sh <remote> <board path> for every board on foreman-lanes, and run endgame.mjs check --all. Any job in progress on either lane, or any lock open: report it and HALT. Upgrade only when both lanes are idle.
   • Exit 2: report the installer's line. A diverged package checkout: clone a fresh one into scratch/. A receipt without a git revision, or a package without that revision: upgrade by hand (SETUP.md §1, "Upgrade by hand").
   • Run the package's installer, never the installed copy in .claude/skills/f-setup/: the package's is the new one.
5. Show the owner what's new in plain words, then the plan's counts (added, replaced, kept for a hand merge, removed). On the owner's yes: … --upgrade --apply.
6. Adapted files (changed here and in the package): for each, diff the repo's copy against the package's and merge the package's change into the adaptation by hand. Show each merge before writing it. Gone from the package but adapted here: ask the owner, keep or delete. Added back: a file listed under "add" that the repo once had and deleted on purpose (the voice trio, say): ask before keeping it.
7. Any repo-profile row that names a path the upgrade removed: update it. Re-read the profile against the current templates/REPO-PROFILE.md and add any row the template gained since (e.g. "Test time", "Parallel workers", "Runs on"), found out the same way as Step 2. Then the names-file check (Step 3.3) and Step 5.
8. Commit, on the owner's word: stage exactly the paths under the installer's == to commit (git add -A -- <each path>, so new files and removals are included), plus the files steps 6 and 7 changed; then git status --short must show none of those paths unstaged or untracked. Commit with a subject only, no trailer (Topping Out <old> to <new>: <what's new, in a few words>). Pushing, or opening a PR where the repo merges through PRs, is the owner's word.
9. New switches the update brought: offer each that applies, one line each, never run without a yes. Today: the parallel test proof when the adapter is pytest and the profile's "Parallel workers" row isn't proven on this machine (bash foreman/method/snippets/parallel_proof.sh <adapter> <cores minus 1, at most 6> <test paths>, 20 to 30 minutes, between jobs; only on PROVED write the number into the git-ignored foreman/.test-workers and record the line in the profile).

A newer package mid-job: never upgrade then. The foreman's site walk runs --check and only reports it; the upgrade waits for the end of the job.

Step 1c · The Deep Agents add-on (only on yes)

0. Needs Python 3.11 or later (deepagents requires it). On an existing install, upgrade first (Step 1b): the installer refuses an add-on while the receipt's revision is older than the package's, since the add-on's files would then look adapted at the next upgrade.
1. node <package>/skills/f-setup/install.mjs --repo <repo> --addon deep-agents adds /deep, deepagents-ref/ and .mcp.json (only if the repo has none; otherwise add its docs-langchain entry to the existing file and show the owner the edit). The receipt's addons: line records it, so later upgrades include it.
2. A new agent project (no product code yet): offer the running skeleton too, … --addon deep-agents --starter (src/agent/, tests, langgraph.json, requirements.txt, a CI workflow, an AGENTS.md to fill in). It copies only missing files and is never upgraded: from here on it's product code.
3. python deepagents-ref/scripts/setup_sources.py fetches what the wiki cites (the deepagents package at the pinned version, the live docs). Needs network and pip. The lint it runs may report STALE pages or missing sources: that's drift since the wiki was last checked, not a failure; say how many, and point to deepagents-ref/MAINTAINING.md. Exit 1 means the package couldn't be fetched, or no docs page arrived at all: report the line it printed (pip, network, the Python version) and HALT the add-on step; pages that fail one by one are reported as drift and don't fail it.
4. The profile's framework check row: /deep. A Pi builder reads .agents/skills/: mirror deep there too.
5. With the skeleton: python -m venv .venv, then install with the venv's own Python (.venv/Scripts/python -m pip install -r requirements.txt; macOS/Linux .venv/bin/python). After Step 4, the tests through the adapter must show 6 passed; .env gets OPENROUTER_API_KEY from the owner, never from chat (they paste it into the file).

See addons/deep-agents/README.md in the package for what each part does.

Step 2 · The repo profile

Write foreman/REPO-PROFILE-<product>.md from foreman/method/templates/REPO-PROFILE.md: every row filled, none left with a template blank. A row nothing can answer yet says not recorded and why.

Find out first (read-only):

Then ask the owner, in one batch, only what's left; typically: the product name (for the file name), ticket mode (local unless they use a tracker), board publish mode (local or artifact), the plan check seats (or leave to the first plan check), the three budgets (repair work orders, default 3 per task; wall time; foreman tokens), the builders' names for Step 3, and anything the reading left ambiguous (two candidate gate commands, say). Offer the found answer as the default in each question.

Step 3 · The names files

The records never name the builders' model, vendor or tool (RULES.md). The names live in a git-ignored file the records push checks against (METHOD.md §10 step 9), where an empty or unreadable file is exit 2, never a pass.

1. Write scratch/names-kept-out.txt (the profile's default path): the names the owner gave, one plain name per line, no regex characters. Never leave it empty: if the owner names none, seed it from the builders the profile and foreman/method/BUILDER-PROFILES.md name, as /f-signoff does, and say so. Write scratch/names-allowed.txt too: contexts that contain a name by design, such as a builder tool's own folder (.pi/); empty is fine. Confirm git check-ignore scratch/names-kept-out.txt succeeds.
2. node .claude/skills/f-signoff/names-check.mjs --self-test must print ok scan ok clean ok cli.
3. The real file: node .claude/skills/f-signoff/names-check.mjs --names scratch/names-kept-out.txt --allow scratch/names-allowed.txt foreman/method/RULES.md must exit 0 or 1 (1 only means the file mentions a name; report the count, never the hit lines). Exit 2 is a broken names file (empty, or a regex line): fix it and run again.
4. The profile holds only the paths, never the names.

Step 4 · The test adapter

1. From foreman/method/templates/TEST-ADAPTERS.md, copy the block for the profile's runner into foreman/test-adapter.sh; set its paid-key list from the profile.
2. Line endings: git check-attr eol -- foreman/test-adapter.sh. If it isn't lf and the machine has core.autocrlf=true, a checkout turns the script CRLF and Bash breaks on it: propose *.sh text eol=lf in .gitattributes (for the owner's commit) and say why (SETUP.md §8).
3. Prove it (the two-fixture check the template asks for): two folders holding the same test file, placed where the runner collects tests (jest roots/testMatch and Go packages may not look in scratch/), with tests A, B and C. In the base folder A and C fail; in the head folder B and C fail. Run each from its own folder under the money guard (( cd <base> && env -u <each paid key> bash -c 'source foreman/test-adapter.sh; run_tests …' ), the same for head), check ran_ok on both, then comm -13 <(failed_ids <base output>) <(failed_ids <head output>) must print only B: C proves a shared failure isn't reported, and the same file in both proves the IDs are stable. Delete the fixtures after.
4. In the profile's "Test adapter" row record the runner, the proof (command, date, the line comm printed), the branch-coverage command and how new tests run against the previous commit's code (defaults for each runner: TEST-ADAPTERS.md, "Coverage and the old-code check").
5. A runner with no block in the template: write the three functions (run_tests, failed_ids, ran_ok) to the same contract and prove them the same way; say so in the report.

Step 5 · The checks

Run each, read its exit code (a crash is not a pass), and report the line:

Step 6 · Report

• What was installed or upgraded (counts, and any adapted files merged or left).
• The profile path and the rows marked not recorded.
• The optional add-ons and what each still needs (SETUP.md §1: voice, f-comply), and every REQUIRED BUT MISSING line from Step 0 again.
• For the owner's commit: the exact paths setup created or changed (never scratch/). Setup doesn't commit.
• Next: the first job (SETUP.md §7): /f-sketch for an idea, /f-schedule for a big plan, or the first-job opener.

Then the terminal line: F-SETUP: READY foreman/REPO-PROFILE-<product>.md.