From agent-starter
Audits an existing codebase and incrementally applies agent-starter patterns (hooks, skills, CLAUDE.md, lint configs, patterns) with opt-in approval per component.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-starter:adopt-projectThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- 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.
git checkout -b adopt/agent-starter.
Everything below is reversible by dropping the branch.Ask one at a time:
~/code/agent-starter
(only needed if files will be copied).Build a gap report before proposing anything.
Detect the stack:
package.json + tsconfig.json → TypeScript/JavaScriptpyproject.toml / setup.py / requirements.txt → PythonInventory (present as a table: component | what exists | starter offering | conflicts):
biome.json, Prettier;
ruff (ruff.toml or [tool.ruff] in pyproject), mypy/pyright configsCLAUDE.md, CLAUDE.local.md, .claude/rules/, AGENTS.md.claude/settings.json hook entries; agent-starter hooks already
installed (~/.claude/hooks/.agent-starter-version)package.json scripts.test, pytest/tox config, Makefile targetsbash <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 -20process.env / os.environ, raw
throw new Error / raise Exception)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.
bash <repo-path>/install.sh - idempotent; 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.<repo-path>/skills/ to ~/.claude/skills/.mkdir -p .harness/reflections && echo '.harness/ledger.jsonl' >> .gitignore
/reflect reads it.<repo-path>/templates/CLAUDE.md, fill in project
name and description..claude/rules/starter-patterns.md → the apply-on-touch file (Tier 4).TypeScript:
templates/biome.json + 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.guides/lint-rules-for-ai.md into their config, or
(b) migrate to the starter flat config, carrying their custom rules over.Python:
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.Foundation templates (both stacks): copy only where the pattern is absent
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.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.
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.
Confirm each item before reporting done:
.harness/ledger.jsonl gitignored, if the loop was adoptednpx claudepluginhub sneg55/agent-starter --plugin agent-starterAssesses codebase for AI agent readiness by detecting stacks, monorepos, git setup, and evaluating style, testing, code quality, secrets, and file sizes.
Detects existing Claude Code agent systems, assesses maturity levels from components like CLAUDE.md and .claude/, and routes to setup or migration workflows. Triggers on 'setup agent' or 'migrate agent system'.
Bootstraps a new project by interviewing the developer (name, description, stack, optional hooks/skills), then scaffolding directory structure, CLAUDE.md, config files, and first commit.