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.

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: subproject list with each subproject's path, purpose, and tech stack
• If monorepo: workspace tool (if any)
• If multi-repo workspace: repo list with each repo's path, tech stack, and internal structure (single project or monorepo)
• If nested app root detected: app root path (e.g., ngapp/)
• Existing files inventory (existence check only — content of docs is read in Step 1b; hooks and coding-guidelines.md are never audited, always overwritten): which of .claude/CLAUDE.md, .claude/settings.json, .claude/docs/*, root CLAUDE.md, subproject CLAUDE.md files already exist
• Test infrastructure detected (yes/no): test framework in dependencies, test command in scripts, or test directory present. This determines the flow of Step 5b (test infrastructure setup).
• Skill authoring detected (yes/no): reported by the Project Analyzer agent per the structural rule in $CLAUDE_PLUGIN_ROOT/skills/init/agents/project-analyzer.md (also applied in the Step 6 install table). A yes means the project authors markdown instructions for an AI agent as part of its stack (Claude Code plugin, Codex skill repo, prompt library, or similar). Determines whether Step 6 installs skill-writing-guidelines.md.
• Doc-sourced insights (if any documentation found): verified conventions, architecture rationale, workflow rules — all cross-checked against source code

Print this as a Detection Summary to the user. Then use AskUserQuestion — header "Detection", question "Does the detection summary look correct?":

• Proceed — "Everything looks right — continue with setup"
• Correct — "I need to fix something before continuing"
• Abort — "Cancel init"

If the user selects Correct, ask what needs to be changed, update the detection results accordingly, and re-present the updated Detection Summary with the same AskUserQuestion.

If no test infrastructure was detected, include this note in the Detection Summary output:

Tests: No test f