/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 under .claude/ and subproject docs/, preserving existing user 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. Record only files and settings entries this run actually installs; unknown ownership is preserved and reviewed. 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 only unchanged, recorded Optimus files with `refresh: "template"`. Customized files remain `refresh: "review"` even after approved edits update their recorded hash. Changed, review-only, or unrecorded existing files get that reference's Merge / Keep existing / Replace choice, preserving their content by default; an unrecorded file byte-identical to the current template is adopted silently. 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 sections.
• **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:** content not derivable from the codebase is never discarded, not even to meet size targets. Mark content outdated only when source code directly contradicts it, and confirm with the user before removing user-added items. The same semantics apply to subproject docs in monorepos and to each repo's `.claude/` in multi-repo workspaces.

CLAUDE.md authoring rules

Claude Code discovers CLAUDE.md natively; Codex reads it through the AGENTS.md pointer in Step 4c. Spend its context on what reading the repository does not give the model.

• **Spend it on gotchas.** Invariants a script or CI depends on, a command that must run from a specific directory, a file that looks editable but is generated, a convention the code deliberately breaks in one place, setup that fails in a non-obvious way, why a decision was made. Write fewer real ones rather than padding to a count — an empty Gotchas section is a valid outcome, and better than five lines of 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.
• Monorepo: root CLAUDE.md is an orchestrator — subproject table, workspace-wide commands, workspace-level gotchas only; each subproject's CLAUDE.md carries that package's gotchas (native discovery in Claude Code, explicit nested reads through the Codex pointer). Shared guidelines stay at root `.claude/docs/`; `testing.md`/`styling.md`/`architecture.md` are scoped per subproject.
• Multi-repo workspace: each repo is fully self-contained (own `.claude/`); the parent CLAUDE.md is a lightweight local-only map — nothing is shared at root.

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 (agent-assisted)

Read `$CLAUDE_PLUGIN_ROOT/skills/init/agents/project-analyzer.md` and launch 1 `general-purpose` agent with that prompt, prepended