/project-setup

name: project-setup
description: "Project configuration initialization. Use when: first-time setup, auto-detecting framework, replacing CLAUDE.md placeholders. Not for: ongoing config checks (use claude-health), skill creation (use skill-creator). Output: configured CLAUDE.md + project settings + rules + hooks."
allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*), Bash(diff:*), Bash(chmod:*), Bash(jq:*), Bash(bash:*)
# context: shared (default) — intentionally NOT fork because Phase 2 requires user confirmation

Project Setup

Trigger

• Keywords: project setup, init, initialize, configure project, setup CLAUDE.md, customize placeholders

When NOT to Use

• CLAUDE.md placeholders are already fully replaced (no `{...}` remaining)
• Non Node.js/TypeScript project without a recognized manifest file -- run with `--detect-only` to see what can be auto-detected. Manual configuration may be needed for: {FRAMEWORK}, {CONFIG_FILE}, {BOOTSTRAP_FILE}. Script commands ({TEST_COMMAND}, etc.) can often be detected from manifest files
• Only want to modify a single placeholder -- just Edit CLAUDE.md directly

Workflow

Phase 1: Detect project environment
    │
    ├─ Read package.json (dependencies, devDependencies, scripts)
    ├─ Detect lockfile (pnpm-lock.yaml / yarn.lock / package-lock.json)
    ├─ Detect entrypoints (glob src/)
    └─ Compile results
    │
Phase 2: Confirm detection results
    │
    ├─ Present detection results table
    └─ Wait for user confirmation or corrections
    │
Phase 3: Write to .claude/CLAUDE.md (unless --detect-only)
    │
    ├─ Read CLAUDE.template.md, filter ecosystem blocks
    └─ Replace placeholders, write to .claude/CLAUDE.md
    │
Phase 4: Verify CLAUDE.md
    │
    ├─ Read .claude/CLAUDE.md to confirm no remaining placeholders
    └─ Output placeholder summary
    │
Phase 5: Install Rules + Backfill CLAUDE.md (unless --no-rules or --lite)
    │
    ├─ Locate plugin rules dir (3-level fallback)
    ├─ mkdir -p .claude/rules/ → copy 14 managed rules + 2 override templates
    ├─ Backfill: ensure .claude/CLAUDE.md has @rules/ references
    └─ Output rules install report
    │
Phase 6: Install Hooks (unless --no-hooks or --lite)
    │
    ├─ Locate plugin hooks dir (3-level fallback)
    ├─ mkdir -p .claude/hooks/ → copy 6 hooks + chmod +x
    ├─ Merge hook definitions into .claude/settings.json
    └─ Output hooks install report
    │
Phase 6.5: Install Scripts (unless --lite or --detect-only)
    │
    ├─ Locate plugin scripts dir (3-level fallback)
    ├─ mkdir -p .claude/scripts/lib → copy 5 scripts
    ├─ Update manifest .sd0x/install-state.json
    └─ Output scripts install report
    │
Phase 6.7: Configure Environment Variables (unless --detect-only or --lite)
    │
    ├─ Detect model context size (1M → recommend auto-compact window)
    ├─ Build env var catalog (model-aware vars; flag retired STOP_GUARD_MODE for removal)
    ├─ Present recommendations, wait for user confirmation
    ├─ Merge into .claude/settings.json env object
    └─ Output env config report
    │
Phase 7: Final Verification Report
    │
    ├─ Summarize all phases
    ├─ Closed-loop check (CLAUDE.md + rules + hooks + env)
    └─ Output next steps

Flag Short-Circuit Semantics

| Flag | Phase 1-2 | Phase 3-4 | Phase 5-6.5 | Phase 6.7 | Phase 7 | |------|-----------|-----------|-----------|-----------|---------| | (none) | Execute | Execute | Execute | Execute | Full report | | `--detect-only` | Execute | Skip | Skip | Skip | Detection results only | | `--lite` | Execute | Execute | Skip | Skip | CLAUDE.md only | | `--no-rules` | Execute | Execute | Skip rules | Execute | Report | | `--no-hooks` | Execute | Execute | Skip hooks | Execute | Report | | `--env-only` | Skip | Skip | Skip | Execute | Env report only (skill-level directive) |

Phase 1: Detect Project Environment

Execute the following detections in order; see `references/detection-rules.md` for detailed rules:

Detection Steps

1. **Detect Ecosystem** — Glob for manifest files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `build.gradle`, `pom.xml`, `Gemfile`). Priority order in `references/detection-rules.md`. 2. **Read manifest** — Extract project name, dependencies, scripts (Node.js: `package.json`; others: ecosystem manifest) 3. **Detect Package Manager** — Lockfile detection (Node.js only): `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, else npm (priority order per `references/detection-rules.md`) 4. **Detect Framework** — From dependencies. See `references/detection-rules.md#framework` 5. **Detect Database** — From dependencies. See `references/detection-rules.md#database` 6. **Detect Entrypoints** — Glob framework-specific candidates. See `references/detection-rules.md#entrypoints` 7. **Detect Scripts** — From manifest scripts field. See `references/detection-rules.md#scripts`. Missing scripts → `# N/A (no script found)`

For non-Node.js ecosystems, skip Node-specific steps and use ecosystem-specific detection from `references/detection-rules.md`.

Phase 2: Confirm Detection Results

Present a table of all 9 auto-detected placeholders with `| Placeholder | Detected Value | Source |` columns. Additional manual placeholders (`{TICKET_PATTERN}`, `{ISSUE_TRACKER_URL}`, `{TARGET_BRANCH}`) may remain if not auto-detectable — these are acceptable and should be noted as "manual" in Phase 4 verification. Wait for user confirmation before proceeding to Phase 3.

Phase 2.5: Select Ecosystem Blocks

Based on detected manifest (from Phase 1.0):

| Manifest | Ecosystem tag | |----------|--------------| | `package.json` | `node-ts` | | `pyproject.toml` | `python` | | `go.mod` | `go` | | `Cargo.toml` | `rust` | | `Gemfile` | `ruby` | | `pom.xml` / `build.gradle` | `java` |

Phase 3: Write to .claude/CLAUDE.md

**Prerequisite**: User has confirmed, and not in `--detect-only` mode.

1. Read `CLAUDE.template.md` (if not found, fallbac