setup · diff

git:20261018.251706e to git:20261019.b396b4d

33 added, 6 removed. Audit A to A.

---

name: setup

description: Use when the user wants to set up a new project or add enforcement tooling (TDD, secret scanning, file size limits, git hooks, CLAUDE.md templates) to an existing project. Also use when the user says "bootstrap", "scaffold", "set up my project", or "add quality enforcement".

---

## Resource Resolution Preamble

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

```bash

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):**

```bash

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:

- - Python: `pyproject.toml` with `[build-system]` and `[tool.pytest.ini_options]`

- 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):**

```bash

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'`.

+ ```bash

+ 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(pytest:*)` for Python, `Bash(go test:*)` for Go). 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., PEP 8 for Python, Go naming conventions for Go)

+ 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):**

```bash

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

+ - **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.

---

## 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:**

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

```bash

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