init

What this skill does

<!-- Governing: ADR-0015 (Markdown-Native Configuration), ADR-0020 (Governing Comment Reform), ADR-0024 (qmd as hard dependency), ADR-0025 (.sdd/ directory rationale), SPEC-0002 REQ "Project Initialization", SPEC-0014 REQ "Migration from JSON to CLAUDE.md", SPEC-0019 REQ "qmd Preflight Enforcement", SPEC-0019 REQ "qmd Assumption in Consumer Skills", SPEC-0019 REQ ".sdd Gitignore Enforcement" -->

# Initialize SDD Plugin

Set up the project's `CLAUDE.md` with architecture context so Claude sessions are design-aware. This skill uses **componentized convergence** — each component independently checks its own state and converges. No single gate blocks other components. Running init N times produces the same result as running it once.

Starting v5.0.0, init also enforces a hardware/install precondition: the `qmd` CLI MUST be available on PATH (per ADR-0024). If qmd is missing, init refuses to operate so users discover the dependency at setup, not three skills deep into a workflow.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

**Module support**: If `$ARGUMENTS` contains `--module <name>`, resolve the module root using the Workspace Detection pattern from `references/shared-patterns.md`. All CLAUDE.md reads and writes in the steps below target the module's `CLAUDE.md` at the module root instead of the project root. If workspace detection finds no modules and `--module` is provided, error: "No modules detected. Run `/sdd:init` without `--module` first to set up workspace."

### Step -1: qmd Preflight (v5.0.0+)

<!-- Governing: ADR-0024, SPEC-0019 REQ "qmd Preflight Enforcement" -->

Before any other check or mutation, verify that the `qmd` CLI is available on PATH. Starting with v5.0.0, qmd is a hard dependency — every qmd-aware consumer skill (per SPEC-0019) assumes qmd is present, so init MUST refuse to operate without it.

1. Run `command -v qmd >/dev/null 2>&1`. If exit is non-zero, output the canonical error message and stop:

   ```
   The `qmd` CLI is required by the SDD plugin starting with v5.0.0 but was not found on PATH.

   Install with one of:
     npm install -g @tobilu/qmd
     bun install -g @tobilu/qmd

   See https://github.com/tobi/qmd for details. Re-run `/sdd:init` after installing.
   ```

   The exit signal MUST be visible enough that downstream tooling (CI, install scripts) can detect the missing dependency. Do NOT modify CLAUDE.md, `.gitignore`, or any other file when this preflight fails.

2. If qmd is present, optionally run `qmd status` to detect whether the GGUF models are downloaded. Model download is qmd's responsibility on first embed, NOT an init prerequisite — proceed even if models are absent. Note the upcoming ~2GB download in the Step 5 final report so users on bandwidth-constrained networks can plan.

3. Re-running `/sdd:init` after a successful install is idempotent — qmd is present, the preflight passes silently, and no spurious changes are introduced to CLAUDE.md or `.gitignore`.

### Step 0: Component Status Scan

Before making any changes, read the current state and build a component checklist. This step is purely diagnostic — no mutations.

**Checks to perform:**

| Component | Check | Status Values |
|-----------|-------|---------------|
| JSON Config | Does `.claude-plugin-design.json` exist in the project root? | `needs-migration` / `absent` |
| Legacy Headings | Does CLAUDE.md contain `### Design Plugin Configuration` or `### Design Plugin Skills`? (v3 headings) | `needs-migration` / `absent` |
| CLAUDE.md | Does `CLAUDE.md` exist at the project root? | `exists` / `missing` |
| Architecture Context | Does CLAUDE.md contain `## Architecture Context`? | `present` / `missing` |
| Path References | Does CLAUDE.md contain both `docs/adrs/` and `docs/openspec/specs/`? | `both-present` / `partial` / `missing` |
| Skills Table | Does the skills table contain ALL plugin-owned skills discovered by enumerating `skills/*/SKILL.md` in the plugin directory (see Step 2b)? Compare skill names (the `/sdd:*` values in the first column). | `up-to-date` / `outdated` / `missing` |
| Workflow Section | Does the Workflow section contain the same steps as the canonical template? | `up-to-date` / `outdated` / `missing` |
| Session Coordination | Does CLAUDE.md contain `### Session Coordination`? | `present` / `missing` |
| SDD Plugin Config | Does CLAUDE.md contain `### SDD Configuration`? | `present` / `missing` |
| Permissions | Does `.claude/settings.local.json` contain broad wildcard patterns for `git` and the detected tracker? (e.g., `Bash(git *)`, `Bash(gh *)`, `mcp__gitea__*`) | `configured` / `needs-update` |
| qmd Assumption Note | Does CLAUDE.md (or canonical template) include the v5 note "qmd-aware consumer skills MAY assume qmd is present"? | `present` / `missing` |
| `.sdd/` Gitignore | Does `.gitignore` contain a `.sdd/` entry? (Required for v5.0.0+ — see ADR-0025 / SPEC-0019 REQ ".sdd Gitignore Enforcement") | `present` / `missing` |
| Workspace Modules | Does `### Workspace Modules` exist? (only check if `.gitmodules` exists) | `present` / `missing` / `n/a` |

Display the scan results before proceeding so the user can see what will change.

### Step 1: Legacy v3 Migration

This step handles two v3 → v4 migrations: the `### Design Plugin Configuration` / `### Design Plugin Skills` headings (renamed in v4) and the legacy `.claude-plugin-design.json` file (deprecated by ADR-0015, removed in v4).

#### 1a: Legacy Heading Rewrite

**Precondition**: Legacy Headings status is `needs-migration`.

If CLAUDE.md does not contain either legacy heading, skip this sub-step.

If CLAUDE.md contains a `### Design Plugin Configuration` heading, rewrite it in place to `### SDD Configuration`. The body content (subsections like `#### Tracker`, `#### Branch Conventions`, etc.) is preserved as-is — only the h3 heading line changes.

If CLAUDE.md contains a `### Design Plugin Skills` heading, rewrite it in place to `### SDD Skills`. The skills table below the heading is left untouched (Step 2 will refresh stale `/design:*` rows to `/sdd:*` if needed).

**No AskUserQuestion** — heading rewrite is deterministic and lossless.

#### 1b: JSON Config Migration

**Precondition**: JSON Config status is `needs-migration`.

If `.claude-plugin-design.json` does not exist, skip this sub-step entirely.

If `.claude-plugin-design.json` exists:

1. Read the JSON file and parse its contents.

2. Translate each JSON key-value pair into the equivalent CLAUDE.md markdown format. The translation maps the JSON structure to the `### SDD Configuration` section:

   - `"tracker"` and `"tracker_config"` → `#### Tracker` subsection with bold-key list items (e.g., `- **Type**: github`, `- **Owner**: myorg`, `- **Repo**: myproject`)
   - `"branches"` → `#### Branch Conventions` subsection (e.g., `- **Enabled**: true`, `- **Prefix**: feature`, `- **Epic Prefix**: epic`, `- **Slug Max Length**: 50`)
   - `"pr_conventions"` → `#### PR Conventions` subsection (e.g., `- **Enabled**: true`, `- **Close Keyword**: Closes`, `- **Ref Keyword**: Part of`, `- **Include Spec Reference**: true`)
   - `"review"` → `#### Review` subsection (e.g., `- **Max Pairs**: 2`, `- **Merge Strategy**: squash`, `- **Auto Cleanup**: false`)
   - `"worktrees"` → `#### Worktrees` subsection (e.g., `- **Base Dir**: .claude/worktrees/`, `- **Max Agents**: 3`, `- **Auto Cleanup**: false`, `- **PR Mode**: ready`)
   - `"projects"` → `#### Projects` subsection (e.g., `- **Default Mode**: per-epic`, `- **Views**: All Work, Board, Roadmap`, `- **Columns**: Todo, In Progress, In Review, Done`, `- **Iteration Weeks**: 2`)
   - Omit keys with `null` values (they will use defaults).
   - Only generate subsections for JSON keys that are actually present.

3. If CLAUDE.md already has a `### SDD Configuration` section, merge the new values into existing subsections (CLAUDE.md values take precedence on conflicts — do not overwrite existing keys). Otherwise