dotclaude Project Setup

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."

Phase 2: Interview

Use AskUserQuestion (batch up to 4 questions per call; use multiSelect where choices aren't exclusive). Two rounds — enough to capture intent, not an interrogation.

Round 1 — confirm reality. First present a compact findings summary in text (stack, package manager, test runner, formatter, layout, git workflow, anything ambiguous). Then ask:

• "Did I read the project right?" — options: correct / mostly (I'll correct via Other) / wrong, let me describe it.
• If monorepo: "Which packages should this setup focus on?" (multiSelect of detected packages).
• "Anything the scan can't see?" — options like: generated dirs I must never touch / unusual deploy or branch constraints / domain terms worth recording / nothing special. Fold answers into the evidence table.

Round 2 — scope and taste.

• "Setup size?"
  • Minimal: CLAUDE.md + settings.json + the four safety hooks + code-quality.md. (Recommended for small projects or skeptics.)
  • Standard (recommended): Minimal + every component the evidence justifies (see Phase 3 mapping) — and nothing else.
  • Full kit: everything dotclaude ships, trimmed only where clearly inapplicable.
  • Let me pick: walk through each component group.
• "Which workflow skills do you want?" (multiSelect). Offer only the justified ones: ship/pr-review need a git/PR workflow, fix-issue needs a GitHub remote with gh, tdd/test-writer need a working test runner, catchup/claude-md/debug-fix/explain/refactor/context-budget are universal. Preselect per evidence; let the user drop any.
• "Optional hooks?" (multiSelect):
  • format-on-save — only offer if a formatter was detected.
  • auto-test — warn plainly: runs the matching test file after every edit; only sensible with a fast suite.
  • notify — OS notification when Claude needs attention. Personal taste.
  • session-start — injects branch + dirty state, ~5-10 tokens/session. Cheap, default on.
  • The four safety hooks (protect-files, scan-secrets, block-dangerous-commands, warn-large-files) are default-on in every size; only "Let me pick" can drop them.

Phase 3: Install plan — the manifest

Produce a single plan table before touching anything. For every dotclaude component: Install? | Evidence | Cost class (always-loaded / path-scoped / invoked-only / hook—no context cost). Then a short "Not installing" list, each with a one-line reason. The plan is the contract: Phase 4 applies exactly this, nothing more.

Hard mapping rules (no exceptions without the user overriding):

settings.json is never copied verbatim: its hooks section must wire only the hooks being installed, and permissions.allow must list only commands that exist in this project (real package manager, real script names; gh rules only if PRs are part of the workflow). Keep the deny rules for secrets as-is — those are universal.

Ask one final AskUserQuestion: approve the plan / adjust (loop back) / cancel. Do not proceed without approval.