Init

Initialize Project Configuration

Initialize project-owned context without expanding the always-loaded root AGENTS.md.

Ownership

• .claude/docs/DESIGN.md owns macro requirements and design.
• .claude/STATE.md owns the active main agent, thin repository identity, and cross-session working state.
• Root AGENTS.md is template-owned and must not be edited by this skill. Never create a CLAUDE.md: Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists.
• PROGRESS.md is maintained by /checkpointing.

Steps

1. Collect stack evidence

Run:

python3 .claude/skills/init/detect_stack.py

The script reports evidence, not conclusions. It never infers a command: evidence.tools names the [tool.*] tables declared in pyproject.toml, evidence.scripts carries the verbatim package.json script strings, and evidence.dependencies gives each dependency's name, its raw spec, the manifest it came from, and the key it was declared under (project.dependencies, project.optional-dependencies.dev, dependency-groups.lint, devDependencies.x, …). You decide from that evidence which commands and libraries are real; do not copy a command the repository does not declare.

Read these fields before writing anything:

• warnings — a manifest that could not be read, decoded, or parsed. Non-empty means the evidence is partial, even though the exit code is 0.
• evidence.parsed_manifests / evidence.unparsed_manifests — "parsed and empty" versus "present but not parsed for dependencies" (Cargo.toml, go.mod, setup.py, Makefile, Dockerfile).
• manifests — every checked filename with an explicit true/false, so "checked and absent" is never mistaken for "never checked".
• agent_bootstrap — agents_md, no_claude_md_shadow, state_md, claude_agents_dir, claude_skills_dir, cli_subagent_contract.

Exit codes: 0 normal · 1 bad arguments, including a --project-root that is not a directory · 2 the agent bootstrap is invalid — ok: false and error name the failed markers. Exit 2 covers the root AGENTS.md contract, the absence of a shadowing CLAUDE.md, shared state, the CLI-subagent contract, and both native runtime directories (.claude/agents and .claude/skills must be real directories; a missing one silently disables all native agent and skill discovery). Stop and repair the installation — bash scripts/check.sh diagnoses the same layout — before writing context.

2. Ask for missing context

Ask the user for the project purpose, code-language preference, and additional conventions only when repository evidence does not already answer them.

3. Populate DESIGN.md

DESIGN.md is written through the typed writer, never by hand: it is a user-owned document, and update_design.py supplies the dry-run preview, the atomic replace, the concurrent-modification hash guard, per-cell | escaping, and validation of the composed document before it replaces the original.

Write the input JSON to .claude/logs/init-design-input.json and use only the typed keys:

python3 .claude/skills/_shared/update_design.py --input .claude/logs/init-design-input.json
# Read the preview at preview_file, then apply:
python3 .claude/skills/_shared/update_design.py --input .claude/logs/init-design-input.json --apply --require-change

Completion test — result == "applied" and (decisions_appended > 0 or any rows_appended value > 0 or sections_updated non-empty). --require-change turns a no-op into exit 2, so an all-duplicate or all-empty input can never be reported as populated. Exit 2 also means the DESIGN.md structure is invalid; exit 3 means DESIGN.md changed underneath the writer — re-read and retry.

Fill only claims supported by repository evidence or the user's answers, and do not fabricate requirements. Later incremental design changes go through /design-tracker, which uses the same writer.