Project Setup

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 13 managed rules + 3 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 7 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 6 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

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:

   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:

   ⛔ Rule source not found. Auto-loop rules cannot be installed.
   
   Remediation (choose one):
   1. Install the plugin — run these two slash commands one after the other (they are
      Claude Code commands, not shell commands, so `&&` chaining does not apply):
      /plugin marketplace add sd0xdev/sd0x-harness
      /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 13 managed rules:

   Rule	Purpose
   auto-loop.md	Auto review loop (behaviour-layer contract; hooks remind, nothing blocks)
   codex-invocation.md	Codex independent research requirement
   discretion.md	Instruction tiers: Anchor / Default / Guidance
   scope-discipline.md	Scope axis orthogonal to severity; out-of-scope deferral
   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
   context-management.md	Data-driven context monitoring
   override-contract.md	Resolution order and heading tables for the user-owned override files (path-scoped to .claude/rules/*-project.md)

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

   • auto-loop-project.md · testing-project.md · git-workflow-project.md — user-owned override templates, copied when absent and stamped Based on: <base> @ <installed base hash> exactly as /install-rules Phase 4.5 does (never a byte copy of the shipped stamp)

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 each override template (auto-loop-project.md, testing-project.md, git-workflow-project.md — user-owned) 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 → for each override template, check whether its line is also present, in the form the template uses — @rules/auto-loop-project.md after auto-loop.md, @rules/git-workflow-project.md after git-workflow.md, and the plain `rules/testing-project.md` reference after `rules/testing.md` (path-scoped: a legacy @rules/testing.md or @rules/testing-project.md line counts as present but is rewritten to the template's plain reference, since an @ import loads it at launch):
   • Present → skip that template (configured)
   • Base line present, override line missing → insert the override's line from CLAUDE.template.md ## Rules directly after its base line (e.g. - @rules/git-workflow-project.md -- Project-specific git overrides (user-owned)). A path-scoped template (testing-project.md) and its base are inserted as the template's plain rules/<file> references, never as @ imports — an import would load them at launch
   • Base line missing too → insert both lines from CLAUDE.template.md ## Rules — the base line, then the override line — at the end of the file's ## Rules list. An installed override whose base is unreferenced is not configured; never report it as present
3. Not found but file exists → append ## Rules block at end of file (16 rule references — 11 @rules/ imports and 5 path-scoped plain references (13 managed + 3 override templates) 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 the ### Auto-Loop section (up to the next ## heading) + ## 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:

   ⛔ Hook source not found. The reminder-layer hooks cannot be installed.
   
   Remediation (choose one):
   1. Install the plugin — run these two slash commands one after the other (they are
      Claude Code commands, not shell commands, so `&&` chaining does not apply):
      /plugin marketplace add sd0xdev/sd0x-harness
      /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 (reminder hooks 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 7 hooks (exclude namespace-hint.sh — plugin-only):

   Hook	Event	Matcher	Purpose
   pre-edit-guard.sh	PreToolUse	Edit|Write|NotebookEdit	Block editing .env/.git
   pre-bash-codex-launch-guard.sh	PreToolUse	Bash	Block a Codex dispatch launched with its progress redirected away from the task panel
   post-edit-format.sh	PostToolUse	Edit|Write|NotebookEdit	Auto-format reminder
   post-skill-auto-loop.sh	PostToolUse	Skill	Post-review reminder (next gate)
   stop-guard.sh	Stop	—	Reminder: open gates at stop (markdown, exit 0)
   user-prompt-review-guard.sh	UserPromptSubmit	—	Per-prompt [AUTO_LOOP_STATE] fact line
   post-compact-auto-loop.sh	SessionStart	compact	Re-inject auto-loop reminders 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|NotebookEdit", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-edit-guard.sh"}]},
      {"matcher": "Bash", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-bash-codex-launch-guard.sh"}]}
    ],
    "PostToolUse": [
      {"matcher": "Edit|Write|NotebookEdit", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-format.sh"}]},
      {"matcher": "Skill", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-skill-auto-loop.sh"}]}
    ],
    "Stop": [
      {"matcher": "", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-guard.sh"}]}
    ],
    "UserPromptSubmit": [
      {"matcher": "", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/user-prompt-review-guard.sh"}]}
    ],
    "SessionStart": [
      {"matcher": "compact", "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-compact-auto-loop.sh"}]}
    ]
  }
}

Note: Environment variables are 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)