project-setup

Installation

SKILL.md

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 5 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

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)
`--guard-mode warn`	Execute	Execute	Execute	Execute (STOP_GUARD_MODE=warn)	Report

Phase 1: Detect Project Environment

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

Detection Steps

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.
Read manifest — Extract project name, dependencies, scripts (Node.js: package.json; others: ecosystem manifest)
Detect Package Manager — Lockfile detection (Node.js only): pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm (priority order per references/detection-rules.md)
Detect Framework — From dependencies. See references/detection-rules.md#framework
Detect Database — From dependencies. See references/detection-rules.md#database
Detect Entrypoints — Glob framework-specific candidates. See references/detection-rules.md#entrypoints
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.

Read CLAUDE.template.md (if not found, fallback to CLAUDE.md)
Remove ... sections NOT matching detected ecosystem
Remove remaining block markers (, )
Execute Edit for each placeholder (using replace_all: true)
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

Read .claude/CLAUDE.md
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.
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):

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

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

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

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

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

Create override template (unmanaged, not manifest-tracked):
- auto-loop-project.md — user-owned override template (see Phase 3.6 in /install-rules)
Conflict strategy:

Scenario Action

File does not exist Install

File exists, content identical Skip

File exists, content differs Skip + warn as conflict
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:

Grep .claude/CLAUDE.md for @rules/auto-loop.md
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
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)
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:

Glob: ~/.claude/plugins/**/sd0x-dev-flow/hooks/pre-edit-guard.sh
Glob: ${REPO_ROOT}/node_modules/sd0x-dev-flow/hooks/pre-edit-guard.sh
Plugin-relative fallback: @hooks/pre-edit-guard.sh

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

⛔ 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

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

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

chmod +x each installed script.
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:

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

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

6.5.2 Copy Scripts

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

Script	Purpose	Dependencies
`precommit-runner.js`	Precommit runner for `/precommit`, `/precommit-fast`	`lib/utils.js`
`verify-runner.js`	Verify runner for `/verify`	`lib/utils.js`
`lib/utils.js`	Shared utilities	None

Conflict strategy: same as Phase 5.2.

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

6.5.3 Update Manifest

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

Variable	Default	Condition	Description
`STOP_GUARD_MODE`	`strict`	Always (override: `--guard-mode warn`)	Stop-guard enforcement mode
`CLAUDE_CODE_AUTO_COMPACT_WINDOW`	`320000`	1M context model detected	Auto-compact window size (tokens) — delays compaction to preserve more context

Legacy Recommendations (auto-upgrade prompt)

When an existing setting matches a previously recommended value (not the current one), flag it as Upgrade in the interactive table so the user can explicitly confirm the change. Never rewrite silently.

Variable	Legacy value(s)	Current recommended	Retired on
`CLAUDE_CODE_AUTO_COMPACT_WINDOW`	`456000`	`320000`	2026-04-17

6.7.2 Large Context Model Detection

Determine whether CLAUDE_CODE_AUTO_COMPACT_WINDOW should be recommended:

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)")
Detected → include CLAUDE_CODE_AUTO_COMPACT_WINDOW: "320000" in recommendations with note: "1M context model detected"
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
User declines → omit CLAUDE_CODE_AUTO_COMPACT_WINDOW from recommendations

6.7.3 Interactive Flow

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

Build recommendations table showing effective current value:

## Environment Variables

Only one row per variable appears at a time; the examples below are **alternatives** for the same variable, selected by its current state.

Example A — first-time install (variable not yet set):

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

Example B — upgrade path (variable already set to a legacy value):

| Variable | Current (effective) | Source | Recommended | Action |
|----------|---------------------|--------|-------------|--------|
| CLAUDE_CODE_AUTO_COMPACT_WINDOW | 456000 | settings.json | 320000 | **Upgrade** (legacy value, retired 2026-04-17) |

Present to user for confirmation — user may accept all, modify values, or skip specific vars. For rows marked Upgrade, display the retirement date and reason so the user can make an informed decision.
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 current recommended → Skip
- If key exists and value matches a Legacy value listed in 6.7.1 → Upgrade (surface retirement date + reason; apply only after user confirmation, never silently overwrite)
- If key exists and value is user-custom (neither current nor legacy) → Update (only after user confirmation; default to preserving)
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 | 320000 | settings.json | ✅ Added (1M model) — or ✅ Upgraded (456000 → 320000, legacy retired 2026-04-17) when upgrading |

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

Condition	Check	Required
CLAUDE.md behavior text	`Required Checks` section exists	✅
`@rules/` references	`@rules/auto-loop.md` in `.claude/CLAUDE.md`	✅
Rule files	`.claude/rules/auto-loop.md` exists	✅
Hook enforcement	`stop-guard` in `.claude/settings.json`	✅
Script runners	`.claude/scripts/precommit-runner.js` exists	✅ (unless `--lite` or `--detect-only`)
Guard mode	`env.STOP_GUARD_MODE` = `strict` in target settings file	✅ (unless `--guard-mode warn`)
Auto-compact window	`env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` in target settings file	✅ (1M model only)

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 | ✅ 5/5 installed + settings merged |
| Scripts | ✅ 3/3 runner scripts installed |
| Env Config | ✅ STOP_GUARD_MODE=strict, AUTO_COMPACT_WINDOW=320000 (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

References

See detection rules: detection-rules.md

Related skills

More from sd0xdev/sd0x-dev-flow

Installs

Repository

sd0xdev/sd0x-dev-flow

GitHub Stars

155

First Seen

Mar 9, 2026

Security Audits

Gen Agent Trust HubWarn

SnykPass

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