Adopt agent-starter in an Existing Project

<!-- Mirrors ADOPT.md in the agent-starter repo. If ADOPT.md changes, update this skill to match. -->

Use on an existing codebase. Never on a green field - that's /new-project.

An existing project has state to audit, every change is potentially destructive, and adoption must be incremental. So the flow is audit-first, merge-don't-overwrite, opt-in per component.

Safety rails (read first)

• Create a branch before any write: git checkout -b adopt/agent-starter.

Everything below is reversible by dropping the branch.

• Read every file before modifying it. Append and merge; never replace a file

the developer wrote.

• After each merge-tier step, run the project's own test suite (and linter, if

present). A red suite means stop and surface it.

• If the project has no tests, say so explicitly and default to the

non-invasive tier only.

• Surface contradictions between starter patterns and existing conventions;

never resolve them silently.

Phase 1: Interview

Ask one at a time:

1. Components - which are you interested in? (hooks / skills / CLAUDE.md +

memory / lint configs / code patterns / "audit first, then decide")

1. Repo path - local path to agent-starter, e.g. ~/code/agent-starter

(only needed if files will be copied).

Phase 2: Audit (read-only)

Build a gap report before proposing anything.

Detect the stack:

• package.json + tsconfig.json → TypeScript/JavaScript
• pyproject.toml / setup.py / requirements.txt → Python
• Both → monorepo: audit each half separately
• Neither → other stack; only Tier 1 and CLAUDE.md apply

Inventory (present as a table: component | what exists | starter offering | conflicts):

• Lint/format: ESLint configs (flat or legacy), biome.json, Prettier;

ruff (ruff.toml or [tool.ruff] in pyproject), mypy/pyright configs

• Tailwind design system: tailwindcss 4.x in package.json dependencies,

or a shadcn components.json. Either one makes the project a candidate for the @shadcn/lint fragment (Tier 3). Record the ESLint major.minor while here: the plugin needs 9.30+.

• Instructions: CLAUDE.md, CLAUDE.local.md, .claude/rules/, AGENTS.md
• Hooks: .claude/settings.json hook entries; agent-starter hooks already

installed system-wide (~/.claude/hooks/.agent-starter-version - record the stamped version to compare against the repo VERSION)

• Skills: which starter skills are already present system-wide - check

~/.claude/skills/{commit,commit-push-pr,simplify,remember,dream,new-project,adopt-project,reflect}. Hooks and skills are user-global, so anything already installed already covers this project - don't re-propose it.

• Tests: package.json scripts.test, pytest/tox config, Makefile targets
• File-size health: run bash <repo-path>/hooks/check-codebase-health.sh

from the project root, or find src -name '*.ts' -o -name '*.py' | xargs wc -l | sort -rn | head -20

• Patterns already present: central error registry? env boundary? Result

types? (grep for scattered process.env / os.environ, raw throw new Error / raise Exception)

Phase 3: Propose

Present the menu grouped by invasiveness, with per-item conflict notes from the audit. Wait for explicit approval per item (or "all of tier N"). Nothing is applied unapproved.

Tier 1 - Non-invasive (no project-file conflicts possible)

• Hooks: skip if the audit found them already installed and current (stamped

version matches the repo VERSION) - they're user-global and already cover this project. If stale, offer to update by re-running bash <repo-path>/install.sh (idempotent). Otherwise run it now: it installs to ~/.claude/hooks/ and merges the settings.json wiring with jq. Note for the developer: hooks are user-global - they will also fire in their other projects.

• Skills: copy only the ones the audit found missing from

<repo-path>/skills/ to ~/.claude/skills/; leave already-present skills as-is (for s in ...; do [ -d ~/.claude/skills/$s ] || cp -r <repo-path>/skills/$s ~/.claude/skills/; done).

• Self-improvement ledger:

mkdir -p .harness/reflections && echo '.harness/ledger.jsonl' >> .gitignore

• the hooks log to it automatically; /reflect reads it.

Tier 2 - Additive (append, never replace)

• No CLAUDE.md → copy <repo-path>/templates/CLAUDE.md, fill in project

name and description.

• CLAUDE.md exists → append only the sections it lacks: Memory System,

Git Safety, Implementation Notes, Self-improvement loop. Read the existing file first; if its instructions contradict a starter section, list the contradictions and let the developer choose. The diff must show additions only.

• `.claude/rules/starter-patterns.md` → the apply-on-touch file (Tier 4).

Tier 3 - Merge-required (developer approval per file)

TypeScript:

• No linter → copy templates/biome.jsonc + templates/eslint.config.mjs

from the repo, install deps (see AGENT.md step 4 there), run on the codebase, and report the damage. Where existing code fails a rule en masse, downgrade that rule to warn with a ratchet note instead of fixing hundreds of violations in the adoption branch.

• Existing ESLint → offer two paths: (a) cherry-pick the Tier 1

correctness rules from guides/lint-rules-for-ai.md into their config, or (b) migrate to the starter flat config, carrying their custom rules over.

• Prettier present → don't add Biome's formatter (two formatters fight);

adopt the ESLint half only.

• Tailwind v4 present (per the inventory) → offer

templates/eslint.shadcn.mjs + npm i -D @shadcn/lint, spread into their flat config as ...shadcnRules. Adapt settings.shadcn.ui and the **/components/ui/** override to where their components live. Existing ESLint below 9.30 has to be upgraded first. Run it on the codebase and downgrade rules that fail en masse to warn with a ratchet note, same as the base config.

Python:

• No ruff config → copy templates/ruff.toml +

templates/pyrightconfig.json, run ruff check, report counts per rule family, and downgrade noisy families per-project rather than mass-fixing.

• `[tool.ruff]` in pyproject.toml → merge the starter's select/ignore

lists into pyproject. Do not drop a standalone ruff.toml next to it - ruff.toml silently takes precedence and their existing config stops applying.

• mypy in use → don't add pyright without asking; two type checkers

disagree with each other more than they catch for each other.

Foundation templates (both stacks): copy only where the pattern is absent

• env boundary (env.ts / env.py), error registry (errorIds.ts /

error_ids.py), truncator (truncate-for-context.ts / truncate_for_context.py). Adapt import paths to the project's layout. Skip any the project already has an equivalent for.

Tier 4 - Gradual-only (never a bulk refactor)

Write .claude/rules/starter-patterns.md with apply-on-touch guidance:

# Starter patterns - apply on touch

Apply these when already editing the relevant code. Never as a bulk refactor.

- Editing a file over 300 lines → split per the file-size hook's suggestions
  (types / constants / validation / utils).
- Touching a `throw` / `raise` site → route it through the error registry
  (`guides/error-id-registry.md`).
- Changing a fallible function's signature → consider returning a Result
  (`guides/discriminated-union-results.md`).
- Touching an env read → move it behind the env boundary
  (`guides/zod-at-the-boundary.md`).
- Adding a long-running operation → thread cancellation through it
  (`guides/abort-signal-threading.md`).
- Adding a new tool → use the directory-per-tool layout
  (`guides/tool-authoring-pattern.md`).

Explicitly out of scope: restructuring directories, rewriting existing error handling, or converting APIs wholesale. The starter's layout is a target for new code, not a migration mandate.

Phase 4: Apply

Execute the approved items tier by tier, in tier order. After each Tier 3 item, run the project's lint and tests; stop on red. One commit per component, so the developer can drop any single adoption from the branch.

Phase 5: Verify

Confirm each item before reporting done:

• [ ] All changes on the adoption branch; default branch untouched
• [ ] Gap report presented; every applied item was explicitly approved
• [ ] Existing CLAUDE.md content preserved (diff shows additions only)
• [ ] Project tests + lint pass (or were already red and are unchanged)
• [ ] .harness/ledger.jsonl gitignored, if the loop was adopted
• [ ] Contradictions surfaced and the developer's choices recorded

(in CLAUDE.md or the implementation notes)