init

# Initialize Project for Claude Code

Analyze the project and set up Claude Code for optimal performance: generate CLAUDE.md with supporting docs (WHAT/WHY/HOW, progressive disclosure), install auto-format hooks per detected stack, set up test infrastructure (framework, coverage tooling, testing docs), and sync existing documentation against source code. Supports single projects, monorepos, and multi-repo workspaces.

## Before You Start

Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/claude-md-best-practices.md`. Key constraints:
- Every CLAUDE.md <= 60 lines
- Use file:line references, not code snippets
- Only universally-applicable instructions
- Preserve user content: when re-running on an existing project, never silently drop content from CLAUDE.md that cannot be derived from the codebase. When unsure whether content is outdated, preserve it. Only mark content as outdated when source code directly contradicts it — and confirm with the user before removing user-added items.

**Write generated files directly.** Files under `.claude/` (docs, hooks, CLAUDE.md) are plugin-generated content. Write new files immediately without asking for permission or confirming with the user — do not use `AskUserQuestion` for file writes. Only pause to confirm when **replacing** a file that contains user-customized content (identified as "User-added" in the audit). Generated content (hooks, `coding-guidelines.md`, templates) is always overwritten silently — these are not user-authored files. Exception: `settings.json` must always be merged, never overwritten — see Step 5. The same rule applies to subproject docs in monorepos and per-repo `.claude/` files in multi-repo workspaces.

## Step 1: Detect Project Context

### Empty-directory detection

Before any project detection, check if the current directory is empty or near-empty. A directory is **near-empty** when it contains at most `.git/`, `.gitignore`, `LICENSE`, and/or a stub `README.md` (under 5 lines of non-empty content) — and **no manifest files** (`package.json`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `*.csproj`, `*.sln`, `pubspec.yaml`, `pyproject.toml`, `CMakeLists.txt`) exist at any depth, and **no directories commonly used for source code** (`src/`, `lib/`, `app/`, `pkg/`, `cmd/`) are present.

If the directory is empty or near-empty, use `AskUserQuestion` — header "Empty Project", question "This directory appears to be empty. Would you like to scaffold a new project?":
- **Scaffold new project** — "Set up a new project from scratch (choose stack, generate hello-world app, then continue with full init setup)"
- **Continue anyway** — "Proceed with init as-is (I'll add code myself later)"

If the user chooses **Scaffold new project**: read and execute `$CLAUDE_PLUGIN_ROOT/skills/init/references/new-project-scaffolding.md`. If the scaffolding procedure returns an **unsupported-stack signal**, read and apply `$CLAUDE_PLUGIN_ROOT/skills/init/references/unsupported-stack-fallback.md` (steps 1–4) — search the web for the user's chosen stack's official scaffolding CLI command, apply the validation and approval rules from the fallback reference. If the fallback reaches step 5 (graceful skip), instead of skipping, create a minimal project manually (manifest file + entry point with hello-world code + `.gitignore`) with user approval. After scaffolding completes, discard all prior detection state and restart Step 1 from "Project detection" below — re-detect the now-populated project from scratch.

If the user chooses **Continue anyway**: proceed with normal Step 1 detection below.

### Project detection (agent-assisted)

Delegate codebase analysis to a detection agent to keep the main context clean for CLAUDE.md generation.

Read `$CLAUDE_PLUGIN_ROOT/skills/init/agents/shared-constraints.md` for agent constraints.
Read `$CLAUDE_PLUGIN_ROOT/skills/init/agents/project-analyzer.md` for the full prompt template, detection algorithms, and return format for the Project Analyzer Agent.

Read these reference files and provide their content to the agent as context before the agent prompt:
- `$CLAUDE_PLUGIN_ROOT/skills/init/references/tech-stack-detection.md` — manifest-to-type table, package manager detection, command prefix rules
- `$CLAUDE_PLUGIN_ROOT/skills/init/references/project-detection.md` — full detection algorithm

Launch 1 `general-purpose` Agent tool call using the prompt from project-analyzer.md, prepended with the shared constraints and reference file contents above.

| Agent | Role | Runs when |
|-------|------|-----------|
| 1 — Project Analysis | Manifest reading, tech-stack detection, structure detection, doc insight extraction, existing files inventory, test infrastructure check | Always |

Wait for the agent to complete. Use the agent's **Detection Results** to populate the Step 1 Checkpoint below.

**Ambiguous structure handling:** If the agent's Detection Results report the project structure as "ambiguous" (supporting signals but insufficient evidence), use `AskUserQuestion` to resolve: ask the user to confirm whether this is a monorepo and identify subproject directories. Update the Detection Results accordingly before proceeding to the checkpoint.

Factual contradictions in existing docs (wrong commands, outdated tech references, etc.) are detected and addressed in Step 6b. Doc-sourced insights from the agent's results flow into generated files in Steps 4-6b.

### Step 1 Checkpoint

Before proceeding, confirm you have all of the following. If any are missing, re-examine the project:

- **Project name** (from manifest or README)
- **Tech stack(s)** (languages, frameworks, from manifest dependencies)
- **Package manager** (detected from lock files / config — e.g., npm, pnpm, yarn, uv, poetry, pip)
- **Build/test/lint commands** (from manifest scripts, prefixed with the detected package manager)
- **Project structure**: single project, confirmed monorepo, multi-repo workspace, or ambiguous (awaiting user input)
- If monorepo: