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 11 managed rules + 1 override template
    ├─ 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 4 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 3 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 (STOP_GUARD_MODE + model-aware vars)
    ├─ 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

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

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, fallback to CLAUDE.md)
2. Remove <!-- block:X -->...<!-- /block --> sections NOT matching detected ecosystem
3. Remove remaining block markers (<!-- block:... -->, <!-- /block -->)
4. Execute Edit for each placeholder (using replace_all: true)
5. Write to .claude/CLAUDE.md (create directory if needed)

If .claude/CLAUDE.md does not exist, create it from the rendered template.

Phase 4: Verify CLAUDE.md

1. Read .claude/CLAUDE.md
2. Grep: \{[A-Z_]+\} — confirm no remaining auto-detected placeholders. Exclude ${...} shell variable matches (e.g., ${CLAUDE_PLUGIN_ROOT}) from the count — these are intentional env var references, not unfilled placeholders.
3. Output summary table with all placeholder values and remaining count

If --detect-only or --lite, skip to Phase 7.

Phase 5: Install Rules + Backfill CLAUDE.md

Skip if: --no-rules or --lite or --detect-only.

5.1 Locate Plugin Rules Directory

Find the plugin's rules/ directory using this priority (short-circuit on first match):

1. Glob search — search known Claude plugin locations:

   Copy

   Glob: ~/.claude/plugins/**/sd0x-dev-flow/rules/auto-loop.md
   Glob: ${REPO_ROOT}/node_modules/sd0x-dev-flow/rules/auto-loop.md
   

2. Plugin-relative fallback — try reading @rules/auto-loop.md to confirm accessibility. If readable, derive the rules directory.

3. Not found → hard error for this phase (do not silently skip). Output explicit failure with remediation steps:

   Copy

   ⛔ Rule source not found. Auto-loop rules cannot be installed.
   
   Remediation (choose one):
   1. Install the plugin: /plugin marketplace add sd0xdev/sd0x-dev-flow && /plugin install sd0x-dev-flow@sd0xdev-marketplace
   2. Copy rules manually from a machine that has the plugin installed
   3. Re-run with --no-rules to skip (rules layer will be missing)
   

   Then skip Phase 5 and continue to Phase 6. Phase 7 will report this as ⚠️ Partial.

5.2 Copy Rules

1. mkdir -p ${REPO_ROOT}/.claude/rules/

2. Copy all 11 managed rules:

   Rule	Purpose
   auto-loop.md	Auto review loop enforcement
   codex-invocation.md	Codex independent research requirement
   fix-all-issues.md	Zero tolerance for unfixed issues
   framework.md	Framework conventions
   testing.md	Test structure and requirements
   security.md	OWASP security checklist
   git-workflow.md	Git branch and commit conventions
   logging.md	Structured logging standards
   docs-writing.md	Documentation writing conventions
   docs-numbering.md	Document numbering scheme
   self-improvement.md	Self-improvement loop

3. Create override template (unmanaged, not manifest-tracked):

   • auto-loop-project.md — user-owned override template (see Phase 3.6 in /install-rules)

4. Conflict strategy:

   Scenario	Action
   File does not exist	Install
   File exists, content identical	Skip
   File exists, content differs	Skip + warn as conflict

5. After copying, collect hashes and write manifest:

   • Compute git hash-object --no-filters for each managed rule (installed + already-identical skipped)
   • Read .sd0x/install-state.json (create {} if not exists)
   • Update schema_version: 1, installed_at, plugin_version (source priority: .claude-plugin/plugin.json → package.json → "unknown"), rules key — hash for each file in managed state (both newly installed and already-identical). Structure: rules[filename] = { "hash": "<sha1>" }
   • Preserve ALL other top-level keys from existing manifest (e.g. hook_scripts, scripts, sd0x_version, agents_md_hash, hooks_installed — do NOT drop unknown keys)
   • Write updated manifest via Write tool

Note: /project-setup uses fresh-install semantics (install new / skip identical / warn on conflict; no smart merge). For smart merge (section merge, legacy migration, --legacy-strategy), run /install-rules directly. After rule installation, /install-rules automatically creates auto-loop-project.md (user-owned override template) if it doesn't exist. See skills/install-rules/SKILL.md.

5.3 Backfill CLAUDE.md (Closed-Loop Guarantee)

Ensure .claude/CLAUDE.md contains @rules/ references so the auto-loop engine can activate:

1. Grep .claude/CLAUDE.md for @rules/auto-loop.md
2. Found → check if @rules/auto-loop-project.md also present:
   • Both present → skip (fully configured)
   • auto-loop.md present, auto-loop-project.md missing → insert - @rules/auto-loop-project.md -- Project-specific auto-loop overrides (user-owned) after auto-loop.md line
3. Not found but file exists → append ## Rules block at end of file (12 @rules/ references (11 managed + 1 override template) from CLAUDE.template.md ## Rules section)
4. File does not exist (edge case: Phase 3 was skipped) → extract from CLAUDE.template.md: ## Required Checks through ### Auto-Loop Rule sections + ## Rules section → create minimal .claude/CLAUDE.md

When extracting from template, remove ecosystem block markers and leave unresolved placeholders as {PLACEHOLDER}.

5.4 Output Rules Report

## Rules Install Report

**Source**: <plugin-rules-path>
**Target**: <repo-root>/.claude/rules/

| Rule | Status |
|------|--------|
| auto-loop.md | ✅ Installed |
| ... | ... |

**Installed**: N / **Skipped**: M / **Conflicts**: K
**Manifest**: .sd0x/install-state.json
**CLAUDE.md backfill**: ✅ @rules/ references present

Phase 6: Install Hooks

Skip if: --no-hooks or --lite or --detect-only.

6.1 Locate Plugin Hooks Directory

Same 3-level fallback as Phase 5.1, but search for hooks/pre-edit-guard.sh:

1. Glob: ~/.claude/plugins/**/sd0x-dev-flow/hooks/pre-edit-guard.sh

2. Glob: ${REPO_ROOT}/node_modules/sd0x-dev-flow/hooks/pre-edit-guard.sh

3. Plugin-relative fallback: @hooks/pre-edit-guard.sh

4. Not found → hard error for this phase (do not silently skip). Output explicit failure with remediation steps:

   Copy

   ⛔ Hook source not found. Auto-loop enforcement layer cannot be installed.
   
   Remediation (choose one):
   1. Install the plugin: /plugin marketplace add sd0xdev/sd0x-dev-flow && /plugin install sd0x-dev-flow@sd0xdev-marketplace
   2. Copy hooks manually from a machine that has the plugin installed
   3. Re-run with --no-hooks to skip (enforcement layer will be missing)
   

   Then skip Phase 6 and continue to Phase 7. Phase 7 will report this as ⚠️ Partial.

6.2 Copy Hook Scripts

1. mkdir -p ${REPO_ROOT}/.claude/hooks/

2. Copy 5 hooks (exclude namespace-hint.sh — plugin-only):

   Hook	Event	Matcher	Purpose
   pre-edit-guard.sh	PreToolUse	Edit|Write	Block editing .env/.git
   post-edit-format.sh	PostToolUse	Edit|Write	Auto-format + track changes
   post-tool-review-state.sh	PostToolUse	Bash|mcp__codex__codex|mcp__codex__codex-reply	Parse review results
   stop-guard.sh	Stop	—	Check review + precommit completed
   post-compact-auto-loop.sh	SessionStart	compact	Re-inject auto-loop rules after compaction

3. chmod +x each installed script.

4. Conflict strategy: same as Phase 5.2.

6.3 Merge Hook Definitions into Settings

Target: ${REPO_ROOT}/.claude/settings.json

Hook definition mapping (uses $CLAUDE_PROJECT_DIR for portability):

{
  "hooks": {
    "PreToolUse": [
      {"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-edit-guard.sh"}]}
    ],
    "PostToolUse": [
      {"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-format.sh"}]},
      {"matcher": "Bash|mcp__codex__codex|mcp__codex__codex-reply", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-tool-review-state.sh"}]}
    ],
    "Stop": [
      {"matcher": "", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-guard.sh"}]}
    ],
    "SessionStart": [
      {"matcher": "compact", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-compact-auto-loop.sh"}]}
    ]
  }
}

Note: Environment variables (including STOP_GUARD_MODE) are now configured in Phase 6.7 (independent of hook installation). Phase 6.3 only handles hook definition merging.

Merge strategy:

• Read existing settings file (create {} if not exists)
• Legacy migration: scan for bare .claude/hooks/<name>.sh paths → upgrade to "$CLAUDE_PROJECT_DIR"/.claude/hooks/<name>.sh
• For each event: append-only merge (skip if same command path exists)
• Coexistence detection: if hooks/hooks.json exists at repo root (= plugin source repo), warn that plugin hooks and installed hooks may coexist. Runtime arbitration handles dedup automatically
• Write updated settings back (hook definitions only — env vars deferred to Phase 6.7)

6.4 Output Hooks Report

## Hooks Install Report

**Source**: <plugin-hooks-path>
**Scripts**: <repo-root>/.claude/hooks/
**Settings**: <repo-root>/.claude/settings.json

| Hook | Script | Settings | Status |
|------|--------|----------|--------|
| pre-edit-guard.sh | ✅ Copied | ✅ Added | Installed |
| ... | ... | ... | ... |

**Installed**: N / **Skipped**: M / **Conflicts**: K

Phase 6.5: Install Scripts

Skip if: --lite or --detect-only.

6.5.1 Locate Plugin Scripts Directory

Same 3-level fallback as Phase 5.1, but search for scripts/precommit-runner.js:

1. Glob: ~/.claude/plugins/**/sd0x-dev-flow/scripts/precommit-runner.js
2. Glob: ${REPO_ROOT}/node_modules/sd0x-dev-flow/scripts/precommit-runner.js
3. Plugin-relative fallback: @scripts/precommit-runner.js

Not found → warn + skip Phase 6.5. Phase 7 will report ⚠️ Partial.

6.5.2 Copy Scripts

1. mkdir -p ${REPO_ROOT}/.claude/scripts/lib
2. Copy 3 scripts:

1. Conflict strategy: same as Phase 5.2.

6.5.3 Update Manifest

1. Read .sd0x/install-state.json (create {} if not exists)
2. Read plugin version from .claude-plugin/plugin.json or package.json
3. Update: schema_version: 1, installed_at, plugin_version, scripts key
4. Compute hash per file: git hash-object --no-filters .claude/scripts/<name>
5. Preserve all existing top-level keys (e.g. rules, hook_scripts, and any unknown keys)
6. Write back to .sd0x/install-state.json

6.5.4 Output Scripts Report

## Scripts Install Report

**Source**: <plugin-scripts-path>
**Target**: <repo-root>/.claude/scripts/

| Script | Status |
|--------|--------|
| precommit-runner.js | Installed/Skipped/Conflict |
| verify-runner.js | Installed/Skipped/Conflict |
| lib/utils.js | Installed/Skipped/Conflict |

**Installed**: N / **Skipped**: M / **Conflicts**: K

Phase 6.7: Configure Environment Variables

Skip if: --detect-only or --lite. Run exclusively with: --env-only (skip all other phases, jump directly to 6.7 → 7).

Purpose: Write recommended environment variables to .claude/settings.json env object, independent of hook installation. This phase runs even when --no-hooks is specified.

6.7.1 Env Var Catalog

6.7.2 Large Context Model Detection

Determine whether CLAUDE_CODE_AUTO_COMPACT_WINDOW should be recommended:

1. Self-awareness check: Claude can inspect its own system environment description for "1M context" indicators (e.g. model description includes "1M context" or "(with 1M context)")
2. Detected → include CLAUDE_CODE_AUTO_COMPACT_WINDOW: "456000" in recommendations with note: "1M context model detected"
3. Not detected or uncertain → ask user: "Are you using a 1M context model? (e.g. Claude Opus 4.6 1M)" — include in recommendations only on confirmation
4. User declines → omit CLAUDE_CODE_AUTO_COMPACT_WINDOW from recommendations

6.7.3 Interactive Flow

1. Read existing env values from both .claude/settings.local.json and .claude/settings.json (create {} if not exists). Runtime precedence: settings.local.json > settings.json

2. Build recommendations table showing effective current value:

   markdownCopy

   ## Environment Variables
   
   | Variable | Current (effective) | Source | Recommended | Action |
   |----------|---------------------|--------|-------------|--------|
   | STOP_GUARD_MODE | warn | settings.json | strict | Update |
   | CLAUDE_CODE_AUTO_COMPACT_WINDOW | (not set) | — | 456000 | Add (1M model) |
   

3. Present to user for confirmation — user may accept all, modify values, or skip specific vars

4. Apply confirmed changes to .claude/settings.json (default) or .claude/settings.local.json (with --local)

6.7.4 Merge Strategy

• Read existing settings file (create {} if not exists)
• Merge env vars into env object:
  • If key does not exist → Add
  • If key exists and value matches recommended → Skip
  • If key exists and value differs → Update (only after user confirmation)
• Preserve all existing env keys not in the catalog (do not drop unknown keys)
• Preserve all non-env keys in settings (hooks, etc.)
• Write updated settings back

Note: Runtime mode resolution for STOP_GUARD_MODE follows: env var > settings.local.json > settings.json > default warn. See hooks/stop-guard.sh for canonical precedence.

6.7.5 Interaction with Phase 6.3 and /install-hooks

• Phase 6.3 (within /project-setup) defers env writes to Phase 6.7
• /install-hooks (standalone command) retains its own env.STOP_GUARD_MODE write — it operates independently
• When both run in the same session, Phase 6.7 runs after Phase 6 and writes to the same target file
• --no-hooks skips Phase 6 but Phase 6.7 still runs → env vars are always configured

6.7.6 Output Env Config Report

## Environment Config Report

**Target**: <repo-root>/.claude/settings.json (or settings.local.json with --local)

| Variable | Value | Effective Source | Status |
|----------|-------|-----------------|--------|
| STOP_GUARD_MODE | strict | settings.json | ✅ Updated |
| CLAUDE_CODE_AUTO_COMPACT_WINDOW | 456000 | settings.json | ✅ Added (1M model) |

**Model**: Opus 4.6 (1M context) → auto-compact window recommended
**Precedence note**: Runtime resolves env > settings.local.json > settings.json > default

Phase 7: Final Verification Report

Summarize all phases and perform closed-loop check:

Closed-Loop Check

Output

## Project Setup Complete

| Phase | Status |
|-------|--------|
| Detection | ✅ Framework: X, PM: Y, DB: Z |
| CLAUDE.md | ✅ Configured (0 remaining placeholders) |
| Rules | ✅ 11/11 managed rules + 1 override template |
| Hooks | ✅ 4/4 installed + settings merged |
| Scripts | ✅ 3/3 runner scripts installed |
| Env Config | ✅ STOP_GUARD_MODE=strict, AUTO_COMPACT_WINDOW=456000 (1M) |

### Closed-Loop Status
✅ Auto-loop engine fully configured (strict mode)
(or ⚠️ Auto-loop engine configured (warn mode — stop-guard will not block))
(or ⚠️ Partial — missing: hooks (enforcement layer inactive))
(or ⚠️ Partial — missing: rules)
(or ⚠️ Partial — missing: scripts (runner not installed))
(or ℹ️ Auto-compact window not set — standard context model detected)

### Next Steps
- Run `/repo-intake` for a full project scan
- Use `HOOK_BYPASS=1` as emergency escape hatch
- Use `/install-rules --force` to upgrade rules later

Verification

• All 9 auto-detected placeholders detected or marked N/A
• User confirmed detection results before writing
• No remaining auto-detected {UPPER_CASE} placeholders in .claude/CLAUDE.md after setup (manual placeholders like {TICKET_PATTERN} are acceptable)
• .claude/rules/ contains 12 .md files (11 managed + 1 override template) (unless --no-rules or --lite)
• .claude/hooks/ contains 4 .sh files with execute permission (unless --no-hooks or --lite)
• .claude/settings.json contains hook definitions (unless --no-hooks or --lite)
• .claude/scripts/ contains precommit-runner.js, verify-runner.js, and lib/utils.js (unless --lite or --detect-only)
• .claude/CLAUDE.md contains @rules/auto-loop.md reference (unless --lite)
• env.STOP_GUARD_MODE is set in target settings file (unless --detect-only or --lite)
• env.CLAUDE_CODE_AUTO_COMPACT_WINDOW is set in target settings file when 1M model detected (unless --detect-only or --lite)

References

See detection rules: detection-rules.md