# Init

> Analyze project structure, populate .claude/docs/DESIGN.md, and write the thin Repository Identity section in .claude/STATE.md.

- Skill: `del-taiseiozaki/init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add del-taiseiozaki/init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/del-taiseiozaki/init/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: DeL-TaiseiOzaki (https://skillmd.com/u/del-taiseiozaki)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/del-taiseiozaki/init

---


# Initialize Project Configuration

Initialize project-owned context without expanding the always-loaded root
`CLAUDE.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` and `CLAUDE.md` are template-owned and must not be edited by
  this skill.
- `PROGRESS.md` is maintained by `/checkpointing`.

## Steps

### 1. Collect stack evidence

Run:

```bash
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`, `claude_md`, `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` router, the
`CLAUDE.md` main-agent contract, 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:

| DESIGN.md target | Input key | Row fields |
|------------------|-----------|-----------|
| `## 機能要件 (Functional Requirements)` | `requirements` | `id`, `requirement`, `priority`, `notes` |
| `## 非機能要件 (Non-Functional Requirements)` | `nfr` | `category`, `requirement`, `metric` |
| `## 技術選定 (Tech Stack & Rationale)` | `tech_choices` | `area`, `technology`, `rationale`, `alternatives` |
| `## アーキテクチャ (Architecture)` Agent Roles table | `agent_roles` | `agent`, `role`, `responsibilities` |
| `## Key Decisions` | `decisions` | `decision`, `rationale`, `alternatives` (date is stamped for you) |
| Prose sections (背景・目的, スコープ, 制約, TODO / Open Questions) | `section_updates` | `heading`, `content` |

```bash
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.

### 4. Update Repository Identity

`## Repository Identity` is also written through its typed writer, which
replaces only that section's body and aborts if `## Main Agent`,
`## Progress Tracker`, or any working block would be lost. Write
`.claude/logs/init-identity-input.json`:

```json
{"identity": "One sentence naming what this repository is."}
```

```bash
python3 .claude/skills/_shared/append_state_block.py --type repository-identity \
  --input .claude/logs/init-identity-input.json
python3 .claude/skills/_shared/append_state_block.py --type repository-identity \
  --input .claude/logs/init-identity-input.json --apply
```

The writer emits the `<!-- Managed by /init. Re-run /init to refresh. -->`
marker and the `docs/DESIGN.md` pointer itself, so the input carries the identity
sentence only. Do not add a heading, a `---`, or a second paragraph — the writer
rejects them (exit `1`). Confirm `result: "applied"`, `structure_ok: true`, and
`progress_tracker_preserved: true` (a real check: it aborts the write with exit
`2` when an existing tracker line was deleted or rewritten).

### 5. Re-verify and report

Re-run the closing gate, and report the JSON verdicts rather than a claim:

```bash
python3 .claude/skills/init/detect_stack.py
python3 .claude/skills/_shared/validate_doc.py --contract design-doc --file .claude/docs/DESIGN.md
python3 .claude/skills/_shared/validate_doc.py --contract state-doc --file .claude/STATE.md
```

All three must exit `0` with `ok: true`. `detect_stack.py` confirms shared state
and the native runtime directories are intact; the two contracts confirm the documents
this skill just wrote still have the sections every other skill reads them for —
`exit 2` names the missing section. Checking the two documents directly is
stricter than inferring their health from the detector, which is why the detector
alone is no longer the gate.

Then review `.claude/rules/` for irrelevant stack-specific rules, but do
not remove them without user approval. Report the evidence you used and the
evidence you rejected, the two updated files, any `warnings`, and your
recommendations in Japanese.