setup

Resource Resolution Preamble

Before any other step, resolve the skill's install directory:

SKILL_DIR=$(find ~/.claude/plugins -path "*/setup/SKILL.md" -print -quit | xargs dirname)
SCRIPTS_DIR=$SKILL_DIR/scripts
TEMPLATES_DIR=$SKILL_DIR/templates
REFERENCES_DIR=$SKILL_DIR/references

If SKILL_DIR is empty, halt and tell the user: "Could not locate the setup plugin directory under ~/.claude/plugins. Verify the plugin is installed."

Phase 1: Detect Environment

Check the working directory for these manifest files: package.json, pyproject.toml, CMakeLists.txt, go.mod, Cargo.toml, Makefile.

Also check for: .git/, src/, existing CLAUDE.md.

Determine:

• New project — no manifest, no .git/, effectively an empty directory
• Existing project — manifest file present; infer language and stack from it

For existing projects, record the detected stack so Phase 2 questions can be skipped where answers are already known.

Phase 2: Socratic Questions

Use the AskUserQuestion tool for each question, one at a time. Adapt or skip questions based on what was detected in Phase 1.

Q1 — Purpose (always ask): "What are you building?" — understand whether this is a web app, REST API, CLI tool, data pipeline, ML project, firmware, mobile app, etc.

Q2 — Language/stack (skip if inferred from manifest): "What language/stack would you like to use?"

Recommend based on the answer to Q1:

• UI/web app → Node/TypeScript (default recommendation)
• Backend API → Node/TypeScript or Python
• Data science / ML → Python
• Firmware / embedded → C/C++
• Systems programming or CLI → Go or Rust

Q3 — Framework (skip if inferred; options depend on stack chosen):

• Node/TS: Express, Fastify, Next.js, NestJS, or none
• Python: FastAPI, Flask, Django, or none
• Go: net/http, Gin, Echo, or none
• C/C++: ask about build system (CMake, Make, Meson) instead of framework

Q4 — Project name (new projects only): "What should the project be called?" — suggest the current directory name as the default.

Do not ask about things you can infer. If the student says "firmware in C", ask about the build system, not web frameworks.

Phase 3: Scaffold (new projects only)

Skip this phase entirely for existing projects.

Node/TypeScript path (fast path — script does the work):

node $SCRIPTS_DIR/init-project.js --name=<name> --framework=<framework>

Python path: git init, then uv init --package <name> (or write pyproject.toml by hand when the user prefers pip; uv init --package already creates src/<package>/). Create tests/, then continue to Phase 4's Python fast path.

All other stacks (adaptive path — Claude does the work):

1. git init
2. Create standard directories: src/, tests/, scripts/, docs/
3. Generate the appropriate manifest file:
   • C/C++ with CMake: CMakeLists.txt with project name, C++ standard, and a test target
   • Go: go.mod with module path and Go version
   • Rust: Cargo.toml with package metadata
4. Install dependencies using the stack's package manager (pip, cmake, go mod tidy, cargo build)
5. Create a minimal src/main.<ext> entry point and a tests/ placeholder

Phase 4: Install Enforcement

Documentation is independently packaged under plugins/documentation/. Resolve its skill directory relative to this loaded root plugin, never by searching another plugin's cache. The Node fast-path installer delegates to its canonical installer. For adaptive application stacks, use the same dependency-free Node18+ documentation scripts when Node is available; do not invent a competing generator. If unavailable, report the runtime requirement and leave documentation installation explicit. Honor project restrictions; documentation-only setup does not edit agent settings.

Read $REFERENCES_DIR/enforcement-scripts.md first to understand the enforcement principles and the secret-scanning regex patterns before writing any scripts.

Node/TypeScript path (fast path):

node $SCRIPTS_DIR/install-enforcement.js --target=<project-root> --framework=<framework> --folder-notes

Pass --folder-notes for new projects. For an existing project, offer it and explain the consequence: every folder that directly holds source files (below the source roots) then needs a CLAUDE.md note with the five metadata fields, or the docs check fails. Write those notes from the real code before enabling it.

This also creates:

• .claude/settings.json with pre-approved commands (test, lint, build, git) and a deny list blocking destructive operations (rm -rf /, git push --force, etc.). Normal file removal still works — Claude prompts for approval so the user stays in control.
• .claude/rules/*.md — path-scoped rules (TDD, code quality, testing, TypeScript, and React for vite/nextjs) that auto-load when Claude works on matching file patterns. These use globs: YAML frontmatter for path-scoping.

Python path (fast path):

Read $REFERENCES_DIR/stack-python.md first. Then ask the size policy with AskUserQuestion. Recommend cap for new projects. For existing projects that already have files over 300 lines, recommend ratchet: those files may shrink but not grow. List them with find . -name '*.py' -not -path './.venv/*' | xargs wc -l | awk '$1 > 300'.

node $SCRIPTS_DIR/install-python.js --target=<project-root> --size-policy=<ratchet|cap> --folder-notes

It installs:

• the stdlib checks in scripts/checks/ with their pytest suites;
• scripts/checks/config.json;
• .githooks/ activated through core.hooksPath;
• Python rules and settings;
• missing .gitignore patterns;
• the documentation engine.

For uv projects it also adds pytest and ruff as dev dependencies. Pass --folder-notes only after the notes are written (same consequence as above). Afterwards, edit testMap, sizeSkip and extraPatterns in scripts/checks/config.json to match the project's real layout and credential shapes, then run python -m scripts.checks.missing_tests --all to see the existing test backlog.

All other stacks (adaptive path — Claude creates equivalent enforcement):

Use the equivalents table to choose the right tools:

Steps for the adaptive path:

1. Write a secret-scanning script using the same regex patterns from enforcement-scripts.md, adapted to the stack's scripting language (Python script, shell script, etc.)
2. Write a file size checking script enforcing the 300-line limit
3. Create scripts/lib/ directory and place both scripts there
4. Create .git/hooks/pre-commit — runs linter, formatter check, secret scanner, file size checker
5. Create .git/hooks/pre-push — runs the test suite with SHA-based caching to skip unchanged code
6. Make both hook files executable: chmod +x .git/hooks/pre-commit .git/hooks/pre-push
7. Install and configure the linter and formatter for the chosen stack
8. Create .claude/settings.json by copying $TEMPLATES_DIR/settings.json into the target project. Adjust the allow list entries to match the stack's commands, keeping the Tool(specifier) rule syntax (e.g., replace Bash(npm test) with Bash(go test:*) for Go or Bash(cargo test:*) for Rust). A bare string such as "npm test" is read as a tool name and matches nothing
9. Copy .claude/rules/*.md from $TEMPLATES_DIR/rules/ into the target project. For non-TypeScript stacks, adapt rules/typescript.md to the relevant language conventions (e.g., Go naming conventions for Go)

Phase 5: Generate CLAUDE.md

Read $REFERENCES_DIR/claude-md-guide.md first for quality guidelines — the goal is a dense, high-signal file where every line saves a future session from re-discovery.

Read $TEMPLATES_DIR/project-claude.md as the base pattern to follow.

Node/TypeScript (if generate-claude-md.js exists):

node $SCRIPTS_DIR/generate-claude-md.js --target=<project-root> --framework=<framework>

All stacks (or if the script doesn't exist yet) — Claude generates CLAUDE.md directly:

Adapt the template to include:

• Commands section: stack-appropriate build, test, lint, and format commands (Python: take them from $REFERENCES_DIR/stack-python.md, including the scripts.checks --all audits)
• Architecture section: describe src/, tests/, scripts/ layout and what goes where
• Enforcement scripts section: document the installed scripts and what triggers them
• Quality gates: 300-line file limit, 50-line function limit, complexity red flags (verbatim from global CLAUDE.md pattern)
• Critical Gotchas section: include the capture instruction — "When you hit a non-obvious issue, add it here immediately"
• Code Review Checklist: same checklist from the template
• Writing Good CLAUDE.md Content section: embed the key guidance so future agents know what to add here

If no global CLAUDE.md exists in the project's parent directory, read $TEMPLATES_DIR/global-claude.md and generate an adapted version for the detected stack.

Machine-level subagent routing (ask first): this changes ~/.claude for every project on the machine, so ask before running it, and run it on its own if the user only asks to set up subagent routing:

node $SCRIPTS_DIR/install-agent-routing.js

It sets Sonnet as the default subagent model, adds a Haiku Explore agent, and appends the routing guidance to ~/.claude/CLAUDE.md. Existing choices are kept and reported. Tell the user a new session is needed for it to take effect.

Phase 6: Verify Setup

Run a smoke test to confirm everything was installed correctly. Report each check as pass/fail and fix any failures before moving to the summary.

1. Git hooks are executable (Python fast path: check .githooks/pre-commit and .githooks/pre-push, and that git config core.hooksPath prints .githooks):

test -x .git/hooks/pre-commit && echo "PASS: pre-commit hook executable" || echo "FAIL: pre-commit hook not executable"
test -x .git/hooks/pre-push && echo "PASS: pre-push hook executable" || echo "FAIL: pre-push hook not executable"

2. Enforcement scripts run without errors: Run each enforcement script in check/dry-run mode against the project. They should all exit 0 on a freshly scaffolded project.

• Secret scanner (should find no secrets in clean scaffolding)
• File size checker (no files should exceed 300 lines)

3. CLAUDE.md exists and has required sections: Verify the file exists and contains at minimum: a Commands section, an Architecture section, and a Gotchas section.

4. Agent config is valid:

• .claude/settings.json exists and parses as valid JSON
• .claude/settings.json contains both permissions.allow and permissions.deny arrays
• At least one .claude/rules/*.md file exists with globs: in its YAML frontmatter

5. Auto-documentation pipeline works: Run node scripts/self-documentation/generate.js, review output, then run node scripts/self-documentation/generate.js --check. Documents require title, description, type, status and read_when metadata; classify missing entries visibly. Stage intended inputs and outputs before testing --staged; checks never stage. The instruction file points to docs/index.md; substantive prose remains authored. With folder notes enabled, the check also fails on any source folder without its note.

6. Linter runs clean: Run the stack's linter on the scaffolded code. A freshly generated project should have zero lint errors.

If any check fails, fix the issue immediately (e.g., chmod +x a hook, regenerate a missing file). Then re-run the failing check to confirm the fix. Only proceed to the summary once all checks pass.

Phase 7: Summary

After all phases complete and verification passes, output a summary that includes:

1. What was installed — list every file created or modified
2. Verification results — confirm all 6 checks passed
3. Key commands for the stack:
   • How to run tests
   • How to run the linter
   • How to make a commit (hooks fire automatically)
4. TDD reminder: "Write tests first. Red (failing test) → Green (passing) → Refactor. Never write implementation before a test exists."
5. Suggested next steps:
   • Fill in the [bracketed placeholders] in CLAUDE.md
   • Review and expand the Architecture section
   • Add the first real feature with a test
   • Make the first commit to initialize git history