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/unsupported-stack-fallback.md to find its package manager and build/test/lint commands; the Detection gate below is its step-4 approval. Print the Detection Results. If a field of its return format came back empty or absent (project name through Gotchas), fill that specific gap yourself — don't re-run the detection the agent just did. An empty Gotchas list is a legitimate answer, not a gap: fill it only if you already know of one this project has. If no test infrastructure was detected, append:

Tests: No test framework, test script, or test directory detected — Step 5b will offer to install one.

Then use AskUserQuestion — header "Detection", question "Do the detection results look correct?":

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

On Correct: ask what to change, update the detection results, and re-present the same gate.

Step 1b: Documentation audit (only when the inventory found existing docs)

$CLAUDE_PLUGIN_ROOT/skills/init/agents/documentation-auditor.md defines the audit — factual status, simplification candidates, and its Audit Report shape. When the inventory found only a handful of small docs, run it yourself: reading six files and classifying them is a handful of tool calls, and the content stays in context for the Step 2 edits that follow. Delegate to 1 general-purpose agent with that prompt when the doc surface is large enough to be worth isolating, prepended with the same "Agent Constraints" section plus the Detection Results from Step 1 (same prompt-assembly rule). Either way, present the Audit Report to the user.

Before asking, show the concrete proposed edits and, for each file the audit recommends rebuilding, its replacement diff, marking retained constraints, moves, and removals with reasons. If nothing needs changing and the user did not ask for a rebuild, keep the existing docs and continue without an audit question.

Use AskUserQuestion — header "Audit", question "How would you like to handle the documentation audit findings?":

• Update all — "Apply every previewed correction and simplification in place, including its listed removals"
• Selective — "Pick which findings to apply by number" (then ask for the numbers; unapproved findings are left as-is)
• Rebuild guidance — "Rebuild the named files from current project facts and retained project knowledge; review removals before replacing"

Steps 2-6 apply this choice; Step 6b runs independently. Rebuild guidance drafts each named Customizable file from detected facts, the current template, and the project knowledge the audit extracted — not from the old outline, and not by reinserting every old section. It replaces only those files: a CLAUDE.md rebuild leaves testing and architecture docs alone. A replacement not yet previewed needs its diff approved before writing. Keep the originals, including uncommitted edits, recoverable outside instruction paths until Step 7 passes.

Step 2: Handle Existing Files

Apply the audit choice through the File semantics classes: no approved change → skip the file; Outdated or simplification candidate → apply only approved changes, preserve everything else; Missing → create normally; Rebuild guidance → write the approved drafts. Refresh Generated files only under the ownership rules above. No audit is not permission to replace an existing file.

Relocate when scope changes (e.g., root .claude/docs/testing.md → subproject-scoped in a monorepo): move the content, remove the old file. Only coding-guidelines.md and skill-writing-guidelines.md stay at root. If a root-level CLAUDE.md exists outside .claude/, carry its non-derivable content into .claude/CLAUDE.md, then suggest removing it.

Step 3: Create Directory Structure

mkdir -p .claude/docs .claude/hooks
# Monorepo: also mkdir -p <subproject>/docs per subproject
# Multi-repo workspace: run inside each repo (each gets its own .claude/)

Step 4: Create CLAUDE.md

Fill every template placeholder with real detected values — no [placeholder] text may survive (Step 7 verifies). Every template HTML comment except a CLAUDE.md template's line-1 identity comment is an instruction to init (here and in Step 6): apply what holds, then delete the comment. When updating an existing CLAUDE.md without an approved rebuild: edit in place per File semantics — never regenerate from template.

Single project — template $CLAUDE_PLUGIN_ROOT/skills/init/templates/single-project-claude.md:

• Gotchas: from the agent's Gotchas findings and doc-sourced insights. Keep only what survives the template's own bar; drop the section entirely when nothing does.
• Documentation table: the Code row always; one row per non-guideline doc that actually exists — none on a first run, since Steps 5b/6 add entries as they create docs.
• Nested app root → point every command at that subdirectory (cd <path> && …) and name it once, in the identity line.
• No manifest detected → omit unknown commands and unsupported claims; say which setup information remains unavailable. Never emit a placeholder as a runnable command.

Monorepo — template $CLAUDE_PLUGIN_ROOT/skills/init/templates/monorepo-claude.md:

• Subproject table (path, purpose, stack); root/workspace-wide commands only; workspace-level gotchas only, with package-specific ones pushed down to Step 4b.
• Workspace tool detected → "managed by [tool]"; none → "Monorepo with [N] packages" without naming a tool.
• More than 6 subprojects → group by category in root CLAUDE.md; create or reconcile .claude/docs/architecture.md for the full workspace map and route it from root CLAUDE.md. This root map is an explicit exception to subproject-only architecture placement.
• Root-as-project: also route its root-scoped docs in the Documentation table.

Multi-repo workspace — run the full init flow (Steps 3-7) independently inside each repo, as if init were invoked there (single-project or monorepo template as appropriate; each repo's .claude/ is version-controlled and self-contained). Then create a lightweight workspace-root CLAUDE.md (NOT inside .claude/) from $CLAUDE_PLUGIN_ROOT/skills/init/templates/multi-repo-claude.md — tell the user it is local-only and not version-controlled.

Step 4b — subproject CLAUDE.md files (monorepo only): for each subproject except root-as-project/root-as-member (root CLAUDE.md covers those), use $CLAUDE_PLUGIN_ROOT/skills/init/templates/subproject-claude.md: commands run from its directory, that package's own gotchas, local docs/ routes, parent monorepo named in the opening line.

Step 4c — Codex pointers (root AGENTS.md): When the project shows Codex use — a .codex/ directory or an existing root AGENTS.md — or this session runs under Codex, append the applicable block below or refresh an existing optimus:pointer block, preserving everything outside it. For a single project or monorepo, use the project block at its root. For a multi-repo workspace, use the project block in every child repo and the workspace block at the workspace root. The explicit nested-file routing is necessary because Codex does not automatically load CLAUDE.md files.

Project or child repo:

<!-- optimus:pointer -->
Agent instructions for this project live in `.claude/CLAUDE.md`. Read it first; it routes to the docs under `.claude/docs/`. Before working in a subdirectory, also read the applicable nested `CLAUDE.md` files for package-specific commands, constraints, and doc routes; they are not loaded automatically.
<!-- /optimus:pointer -->

Multi-repo workspace root:

<!-- optimus:pointer -->
Agent instructions for this workspace live in `CLAUDE.md`. Read it first; it maps the child repositories. Before working in a child repo, read its `.claude/CLAUDE.md` and the applicable nested `CLAUDE.md` files.
<!-- /optimus:pointer -->

Step 5: Install Formatter Hooks

Under Codex, skip hook installation; document the project's existing formatter/check command in CLAUDE.md's Commands for use at task boundaries, noting its editor/CI integration.

Otherwise read $CLAUDE_PLUGIN_ROOT/skills/init/references/formatter-setup.md and install the applicable hooks so files are auto-formatted after every Edit/Write.

Step 5b: Test Infrastructure Setup

Read $CLAUDE_PLUGIN_ROOT/skills/init/references/test-infra-provisioning.md.

If test infrastructure was detected in Step 1: run the reference's health check, coverage-gap check, and provisioning.

If not detected: use AskUserQuestion — header "Test Infrastructure", question "No test framework was detected. Would you like to install one?":

• Yes (strongly recommended) — "Install a test framework and coverage tooling. /optimus:tdd, /optimus:unit-test, and /optimus:deep stop without one."
• No — "Skip test infrastructure setup — some optimus skills will have reduced functionality"

On Yes: follow the reference's installation section, then its health check and provisioning. On No: skip all provisioning; Step 7's summary carries the declined-infra note.

Step 6: Create Documentation Files

coding-guidelines.md (Generated) — create in .claude/docs/ from $CLAUDE_PLUGIN_ROOT/skills/init/templates/docs/coding-guidelines.md, replacing [PROJECT NAME], or reconcile the existing file under the ownership rules. Preserve project-specific guidance in place or in an approved, routed document.

Conditional docs (Customizable; testing.md was handled in Step 5b). Fill all placeholders with actual project details:

Placement: single project — everything in .claude/docs/. Monorepo — styling.md/architecture.md go in each subproject's docs/, applying the detection rules per subproject; retain the root workspace-map exception from Step 4 when needed. skill-writing-guidelines.md is installed once at root when any subproject has a skill-authoring stack; root-as-project's scoped docs go in .claude/docs/; a subproject gets its own docs/coding-guidelines.md (Customizable, routed from its CLAUDE.md) only if its conventions differ significantly from root.

Update the Documentation tables: after creating styling.md/architecture.md, add a row to the Documentation table of the CLAUDE.md that scopes it, keyed by the kind of change it governs — "UI, CSS, visual changes", "Module structure or data flow" (testing.md rows were added in Step 5b, keyed "Tests").

Step 6b: Sync Existing Documentation

Skip when the project has no docs of its own (no README.md, CONTRIBUTING.md, ARCHITECTURE.md, or docs/ files).

Cross-check README.md (root, and each subproject's in monorepos), CONTRIBUTING.md, ARCHITECTURE.md, and docs/ files that overlap generated topics against source code (manifests, lock files, directory structure). Fix only claims directly contradicted by source — wrong commands or package manager, tech no longer in deps, renamed directories, stale subproject lists, removed dependencies. Surgical, never editorial: leave prose, tone, structure, and imprecise-but-not-wrong descriptions untouched; never add sections or create files; touch nothing outside the project root.

If contradictions found: present a Sync Report (file, current content, proposed fix, source evidence), then use AskUserQuestion — header "Sync", question "How would you like to handle the documentation sync findings?": Apply all / Selective (ask which correction numbers) / Skip sync. Apply only approved changes. If none found, report that and continue.

Step 7: Verify and Report

When Step 5 ran, verify the hooks and settings against their sources before reporting:

• Hooks written this run match their source — each newly copied template hook is byte-identical to its template (diff them), except explicitly approved customizations; custom fallback hooks follow unsupported-stack-fallback.md's validation rules. A preexisting hook the user kept is outside this comparison and must remain untouched.
• settings.json survived the merge — every format hook this skill installed has a matching hooks.PostToolUse entry resolving to that installed file. Preserve preexisting entries, including commands outside .claude/hooks/, except exact migrations the user approved. Hooks owned by another skill are out of scope: /optimus:permissions registers restrict-paths.sh under PreToolUse, not PostToolUse. Compare pre/post settings to detect dropped user entries; don't normalize unrelated hooks into this skill's template shape.

Then sweep template-derived content for surviving [placeholder] text and unresolved template HTML comments — retain each file's line-1 identity comment, the optimus:pointer markers in AGENTS.md, and user-authored content. Fix any failure before reporting.

For reconciled guidance, diff each file against its original and the approved proposal: every prior constraint or rationale is kept at its scope, moved behind a working route, or approved for removal, and the only unproposed additions are Documentation-table rows for docs created this run and the optimus:pointer block. Commands must match detected configuration, doc links and nested CLAUDE.md/Codex routes must resolve, and nothing unapproved may change, including AGENTS.md outside its pointer block. Fix discrepancies before recording completion.

Write the plugin version to .claude/.optimus-version after all checks pass — version string only (e.g., 3.0.0), read from $CLAUDE_PLUGIN_ROOT/.claude-plugin/plugin.json; per repo in multi-repo workspaces. Only init ever writes this file. Then update and verify the ownership record for files/settings installed this run, including this version marker.

Summary — present the final report using this exact format:

### Optimus Init Complete

| Category | Details |
|----------|---------|
| **Project** | [project name] — [tech stack summary] |
| **Structure** | [Single project / Monorepo with N packages / Multi-repo workspace with N repos] |
| **Files created** | [count] files ([list]) |
| **Formatters** | [hooks installed, or "None"] |
| **Test infra** | [Pre-existing: framework / Installed: framework / Not installed] |
| **Guidance audit** | [kept / edited / rebuilt, per existing file; unresolved simplification candidates — or "No existing guidance"] |
| **Doc sync** | [N corrections applied / No contradictions found / Skipped] |

[Monorepo: add subproject breakdown rows. Multi-repo: per-repo results + reminder to commit each repo's .claude/ separately.]

Broken baseline: if the Step 5b health check recorded failing tests, append — baseline broken ([N] failing) to the Test-infra value (per subproject/repo where applicable) and add immediately after the table:

Baseline broken — init does not fix failing tests by design. Ask the agent to triage the failing tests before running skills that need a green baseline.

Conditional warnings after the table:

• Scaffolding created <name>/ → "New project root: the project now lives in <name>/ — start future sessions from that directory, or the generated project guidance and hooks will not load."
• Test framework installed from scratch → "Important: the project has no test files yet, so the test command passes with 0 tests — a false safety net. /optimus:unit-test writes initial tests and establishes real coverage."
• Test infrastructure declined → "Note: test infrastructure was not installed — /optimus:tdd, /optimus:unit-test, and /optimus:deep will stop, and /optimus:code-review and /optimus:refactor lose their test checks. Re-run /optimus:init to install it later."

Close with one line: if the project root has no HOW-TO-RUN.md, recommend /optimus:how-to-run; otherwise, if test infrastructure exists, recommend /optimus:unit-test — in a fresh conversation either way. With neither, the declined-infra note is the close.