/init

description: Bootstraps a project for Claude Code or Codex — generates routed project guidance from detected structure, reconciles existing docs, and offers test infrastructure. Claude Code can also install formatter hooks. Writes .claude/, CLAUDE.md, AGENTS.md and subproject docs/; may append to README/.gitignore and, with approval, install dev dependencies. Preserves existing guidance through review and recorded ownership. Use for initial setup or upgrades.
disable-model-invocation: true

Initialize Project for Claude Code or Codex

File semantics

Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/managed-files.md` before writing. Three classes govern every file this skill writes.

Under Codex, preserve existing hooks/settings throughout this run; the Generated-file overwrite rule below does not apply to hooks.

• **Generated** — hooks installed by init and `.claude/docs/coding-guidelines.md`: refresh, adopt, record, and offer Merge / Keep existing / Replace exactly as managed-files.md specifies. Never overwrite unrelated `.claude/hooks/*` files.
• **Customizable** — all `CLAUDE.md` files, `testing.md`, `styling.md`, `architecture.md`, `skill-writing-guidelines.md`: never silently overwrite. When the file exists, review-and-propose — compare against the template and detected state, apply only user-approved changes, preserve user-added content unless an approved proposal removes it.
• **settings.json** — always merge, never overwrite: preserve `permissions` and any other custom sections. Do not create it when no hooks are installed and it doesn't already exist.

New files of any class are written directly — no confirmation prompts. **Preserve when unsure:** keep non-derivable conventions, constraints, and rationale at their root or package scope, even above size targets. Only direct source contradiction makes a claim Outdated; redundancy or a suspected old-model workaround is a simplification candidate, removed only with approval. Approving a previewed proposal approves its listed removals — don't ask again. The same semantics apply to subproject docs in monorepos and to each repo's `.claude/` in multi-repo workspaces.

CLAUDE.md authoring rules

Spend CLAUDE.md's context on what reading the repository does not give the model.

• **Spend it on gotchas** that clear the template's Gotchas bar, plus why a non-obvious decision was made. Write fewer real ones rather than padding to a count — an empty Gotchas section is valid, and better than restated obviousness.
• **Never restate what the filesystem shows.** No directory listings, no "the stack is TypeScript" when `package.json` says so, no per-file roles. One line of identity and stack at the top is the whole allowance.
• Commands do belong here: which of a dozen scripts is the real build/test/lint entry point, with the detected package-manager prefix, is not inferable.
• Target <= 60 lines. The limit is soft: condense template-generated content first; if user-added content still pushes it over, exceed the limit and note the overage in the Step 7 summary.
• Only universally-applicable content — task-specific material distracts the model and degrades instruction-following.
• Progressive disclosure: the Documentation table routes a kind of change to the one doc that governs it, so a typo fix does not load the architecture doc.
• `file:line` references, not code snippets — snippets go stale.
• Defer mechanical style to the project's configured formatter when present. Preserve existing conventions that tooling does not enforce; Codex and projects declining hooks still need the documented formatter command.

Step 1: Detect Project Context

Empty-directory check

A directory is **near-empty** when it contains at most `.git` (file or directory), `.gitignore`, `LICENSE`, and/or a stub `README.md` (under 5 lines of non-empty content), with no manifest files at any depth and no source directories (`src/`, `lib/`, `app/`, `pkg/`, `cmd/`). If 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, then continue with full init setup"
• **Continue anyway** — "Proceed with init as-is (I'll add code myself later)"

On **Scaffold**: read and execute `$CLAUDE_PLUGIN_ROOT/skills/init/references/new-project-scaffolding.md`. If it returns an unsupported-stack signal, apply `$CLAUDE_PLUGIN_ROOT/skills/init/references/unsupported-stack-fallback.md` (steps 1-4) to find the stack's official scaffolding CLI; if that reaches graceful skip, instead create a minimal project manually (manifest + hello-world entry point + `.gitignore`) with user approval. After scaffolding, discard all prior detection state and restart Step 1's project detection from scratch.

Project detection (inline or agent)

`$CLAUDE_PLUGIN_ROOT/skills/init/agents/project-analyzer.md` defines detection — its tasks, reference files, and Detection Results shape. For a small single project — one root manifest, no workspace config, roughly under 100 source files (a fresh scaffold always qualifies) — **run it yourself**, reading its reference files directly; the findings stay in context for the gotchas and commands Step 4 writes. Otherwise launch 1 `general-purpose` agent with that prompt, prepended with the "Agent Constraints" section of `$CLAUDE_PLUGIN_ROOT/references/shared-agent-constraints.md`. Assemble the prompt per "Prompt assembly at dispatch time" in `$CLAUDE_PLUGIN_ROOT/references/agent-architecture.md` — the agent reads the detection references itself via the absolutized paths its prompt carries.

If detection reports the structure as **ambiguous**, resolve via `AskUserQuestion`: ask the user to confirm whether this is a monorepo and identify subproject directories.

Checkpoint

If detection reports an **Unsupported stack**, first run steps 1-3 of `$CLAUDE_PLUGIN_ROOT/skills/init/references/unsupp