adopt-project

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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")
2. **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

From sneg55/agent-starter, MIT.

More from sneg55/agent-starter