setupdotclaude

Set up dotclaude in this project with one governing principle: install nothing without evidence and consent. Every rule, hook, agent, and skill must be justified by something found in the codebase or explicitly requested by the user. When in doubt, leave it out — the user can always add more later; unused config costs tokens and trust forever.

CLAUDE.md for this project goes at the project root (./CLAUDE.md), committed so the team shares it; all other config lives inside .claude/. Claude reads and layers other scopes too: ~/.claude/CLAUDE.md (your personal, cross-project preferences), CLAUDE.local.md (gitignored personal overrides for this project), and nested CLAUDE.md in subdirectories (monorepo packages). Route team-shared instructions to the committed root file, personal ones to the home or .local file.

Two modes, decided by what exists:

• Fresh: no .claude/ content yet (whether the user will install from this plugin or has nothing at all).
• Existing: .claude/ already has settings, rules, skills, agents, or hooks (from a clone+copy, an earlier run, or hand-rolled). Same scan and interview, but Phase 4 becomes a gap analysis: add what's missing and justified, propose removing what's unjustified, never touch user-customized content without showing the change first.

If $ARGUMENTS names a focus area (e.g. frontend), weight the scan and the proposals toward it.

Phase 1: Deep scan (read-only — no writes of any kind in this phase)

Build an evidence table. Don't stop at manifests; read real code.

1. Stack: manifests (package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json, build.gradle, pom.xml, Makefile, Dockerfile) and CI workflows (.github/workflows/, .gitlab-ci.yml). Record the actual build/test/lint/dev commands and script names, not guesses.
2. Monorepo: workspaces key, pnpm-workspace.yaml, lerna.json, nx.json, turbo.json, or multiple manifests at depth 2+. List the packages.
3. Source layout: list the real source directories (src/, app/, lib/, packages/*/src, cmd/, internal/, ...). These become rule paths: globs later — record actual paths, never assume src/.
4. Tests: config files (jest.config.*, vitest.config.*, pytest.ini, conftest.py, playwright.config.*, ...), then open 2-3 real test files: runner, naming convention (*.test.ts vs test_*.py), test directory layout, assertion style, how much mocking they actually do.
5. Frontend: .tsx/.jsx/.vue/.svelte files, component directories, framework and styling approach from dependencies.
6. Backend/API: route/controller/handler/service directories; ORM and migration dirs (prisma/, alembic/, migrations/, db/migrate/, ...).
7. Docs: a docs/ directory or substantial .md files beyond the README.
8. Formatter/linter: configs AND binaries (Biome, Prettier, Ruff, Black, rustfmt, gofmt, ESLint).
9. Git: default branch (git symbolic-ref refs/remotes/origin/HEAD), commit message style (git log --oneline -20), whether PRs/gh are part of the workflow (remote on GitHub, gh installed).
10. Read 5-10 representative source files across the main directories: naming style (camelCase vs snake_case), error-handling patterns (typed errors vs bare catch), comment density, generated-file markers (*.gen.ts, *_pb2.py, // Code generated).
11. Existing AI/editor config: ./CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/, .github/copilot-instructions.md, current .claude/*. This is content to migrate, never to clobber.
12. Domain: skim the README for domain terms, abbreviations, and architecture statements that aren't obvious from code.

If the project is empty (no source files, no manifests): say so, offer only the minimal baseline (CLAUDE.md template + safety hooks + settings), and stop after installing it. "Re-run after adding code to customize."