AI Dev Setup

AI Dev Setup

Turn a repository into a tuned AI-assisted development environment — safely, modularly, and in a way the maintainer still owns.

Most repos either have nothing (greenfield, unopinionated) or a patchwork of agent files, MCP snippets, and half-configured tools. Both cases benefit from the same discipline: look first, decide with the user, install small, validate, leave a record. This skill is that discipline, plus a curated map of what to consider.

When to use

• User asks to configure, bootstrap, or harden AI tooling in a repo.
• User names a specific component (Serena, RTK, Spec Kit, an MCP server, a skill) but the install should be done safely in the context of the whole setup.
• User wants an audit/recommendation pass without changes.
• User wants to discover reusable skills for this repo.

When NOT to use

• Writing product code, fixing bugs, running tests — those are the work this skill is meant to make easier, not replace.
• Pure documentation authoring unrelated to agent context files.
• Single-file tweaks the user has already decided on (just do the edit).

Modes

The skill operates in one of four modes. Ask the user which one if it's not obvious from the request.

Default to audit when in doubt. It's the least destructive and naturally leads into the others.

Core workflow

Execute these phases in order. Each phase has a clear exit condition — don't skip ahead.

Phase 1 — Detect

Before recommending anything, understand what's already here. Read — don't write.

Run scripts/detect.sh from the skill directory. It emits a JSON profile describing:

• project type, languages, package managers, test/build tools
• existing agent context files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, .cursorrules, etc.)
• existing skills directories (.claude/skills/, .agents/skills/), skill-lock files
• existing MCP configs (.mcp.json, .vscode/mcp.json, ~/.codex/config.toml if readable)
• token-optimization tooling signals (Serena config at .serena/, RTK in PATH, Caveman, etc.)
• SDD signals (.specify/, spec/plan/task files)
• hooks, settings, permissions (.claude/settings.json, .claude/settings.local.json)
• git state (branch, remote, clean/dirty)

If the script is unavailable or fails, fall back to an inline checklist — see references/detection.md. That reference also explains how to interpret the signals (e.g. "a skill-lock.json + symlinked skills dir means a skill registry tool is managing them — do not hand-install skills there").

Exit condition: you can state, in 3–5 bullets, what this repo already has and where the gaps are.

Phase 2 — Decide the scope

Given the detection report, propose a mode and a shortlist of categories to consider. Present it to the user concisely:

Detected: <1-line summary>
Already configured: <list>
Gaps/opportunities: <list>

Proposed mode: <audit | bootstrap | optimize | selective>
Categories I'd consider: [AI artifacts, SDD, MCP, token optimization, agent/IDE integration]
Out of scope for now: <anything you're deferring and why>

OK to proceed, or adjust?

Wait for confirmation before doing any research or writes. Scope drift is the #1 failure mode of setup skills.

Phase 3 — Research & curate

For each in-scope category, consult the category-specific reference under references/categories/. Each reference lists well-known candidates, fit criteria, compatibility notes, and install sketches:

• references/categories/ai-artifacts.md — agent instructions, prompts, skills, memory
• references/categories/sdd.md — Spec Kit and alternatives
• references/categories/mcp.md — MCP servers
• references/categories/token-optimization.md — Serena, RTK, Caveman, Serena Slim
• references/categories/agent-ide.md — Claude Code, Copilot, Codex, Cursor, etc.

When skill installation is on the table, follow references/skill-discovery.md. That reference requires consulting skills.sh and/or installing/using find-skills before shortlisting.

Apply the decision framework in references/decision-framework.md to avoid tool overload. High-leverage over maximal — every tool is maintenance.

Cross-check candidates against references/compatibility.md before proposing. Some combinations conflict (e.g. two hook frameworks racing, two MCP servers offering the same capability) and must be flagged.

Exit condition: for each in-scope category you have 1–3 recommended candidates + clear reasons. No blind "install everything popular."

Phase 4 — Present decisions and get approval

Decisions must be presented, not assumed. Use the pattern in references/interaction.md. Skeleton:

Decision <N>: <one-line decision title>
Why it matters: <one sentence>

  Option A — Recommended: <tool/approach>
    Best fit because: <reason tied to this repo>
    Tradeoffs: <honest cost>

  Option B: <alternative>
    Best fit if: <different priority>
    Tradeoffs: ...

  Option C: <do nothing / defer>
    Best fit if: <e.g. too early>

Your call?

Batch related decisions but cap at ~5 at a time — cognitive load matters. For audit mode, stop here and produce a written recommendation document instead of asking for decisions.

Phase 5 — Install, configure, validate

Only after explicit approval. Follow references/install-playbook.md. Hard rules:

1. Back up first. scripts/backup.sh snapshots touched files into a tarball under .ai-dev-setup/backups/<timestamp>/. Run it before any write.
2. Idempotent writes. Prefer merging into existing files (e.g. appending an MCP server to .mcp.json) over full rewrites. If you must rewrite, diff-preview first.
3. No silent overwrites. If a target file exists and your change isn't purely additive, show the diff and ask.
4. Log the change. Append an entry to .ai-dev-setup/changelog.md with what, why, which backup.
5. Validate. Run scripts/validate.sh (or the category-specific validator). For MCP: attempt the listed tools work. For skills: the skill shows up in the expected location. For Serena: the hook fires.
6. Surface rollback. Tell the user the exact command to undo (tar -xf <backup> -C /).

Exit condition: validation passes, or you've surfaced a real failure with a clear next step. Never report success without running the validator.

Phase 6 — Report

One concise report at the end:

• What was installed/changed (file-by-file, with backup locations).
• What was deliberately not installed, and why (so the user can revisit later).
• Suggested next steps (e.g. "run rtk gh auth login once before using the GitHub MCP").
• How to roll back.

Skill discovery

Any time the in-scope work includes installing reusable skills, you MUST perform active skill discovery before recommending anything. Read and follow references/skill-discovery.md. Summary:

1. Check if find-skills is installed locally. If yes, use it.
2. Otherwise, consult skills.sh (https://skills.sh/) as a web source.
3. Offer to install find-skills as a durable helper if the user will likely do this again.
4. Curate — do not dump — shortlisted candidates. Flag overlap with installed skills (read the detection inventory).
5. Get explicit approval per-skill before install.

Do not invent skill names. If you can't confirm a skill exists on skills.sh or in a known index, say so rather than guessing.

Safety constraints

• Never modify ~/.claude/settings.json or other user-global config without explicit, specific approval. Prefer project-local scopes (.claude/settings.json, .mcp.json).
• Never commit secrets. GitHub tokens, API keys, etc. go in .env (git-ignored) and are referenced by env var in configs.
• If the git tree is dirty, warn the user and offer to stash or create a dedicated branch before writing.
• If the skill detects an active skill-registry tool (e.g. a skills-lock.json), do not hand-install into the managed skills directory — use the registry tool's own install path, or tell the user.
• On destructive prompts (overwrites, deletes), require explicit confirmation with the file path echoed back.

Reference index

Scripts

All scripts assume POSIX shell, jq, and rg. They degrade gracefully if a tool is missing (print a clear message; don't crash the skill flow).

Anti-patterns to avoid

• Installing everything popular. Maintenance is a real cost; each added tool adds surface. Prefer 3 tools the user will actually use over 10 they won't.
• Assuming the agent. This repo may be used by Claude Code, Copilot, Codex, or all three. Detect, don't assume.
• Rewriting existing guidance wholesale. If CLAUDE.md already exists and reflects deliberate choices, merge — never clobber.
• Silent destructive operations. Always announce file path + intent before writing.
• Skipping validation. A setup that "installed without errors" but doesn't work is worse than no setup.
• Overwhelming prompts. If you're asking more than ~5 questions in a batch, you haven't done enough curation.