/to-architecture

name: to-architecture
description: 'Capture an initiative''s technical shape into a roadmap''s `## Architecture` section — components, interfaces between items, per-item sketches — writing the roadmap too when none exists.'
argument-hint: '[<roadmap-slug> | initiative]'
disable-model-invocation: true
user-invocable: true
allowed-tools: 'Bash(bash *skills/_lib/preflight.sh* *) Bash(bash *skills/_lib/write-task.sh* *) Bash(bash *skills/_lib/roadmap-items.sh* *) Bash(bash *skills/_lib/detect-project.sh* *) Bash(bash *skills/validate/validate.sh* *)'

Fix an initiative's **technical shape** — which components it builds or changes, what crosses between items, a module-level sketch per item, the technical ordering — into the `## Architecture` section of `.task/roadmap/<slug>.md`. The roadmap's items stay behavioral; a spec pins decisions with rationale; this section is the layer between them, the one a component map would otherwise leak into a spec from. Initiative-level counterpart to `to-plan`: as `to-plan` adds `## Plan` to a task, this adds `## Architecture` to a roadmap, and writes the roadmap itself when none exists yet. Planners — `to-plan` on an item, and `roadmap-to-workflow`'s per-item plan agent — follow it as the intended shape.

**Input:** `$ARGUMENTS` — optional. Recognized forms:

• `<roadmap-slug>` or a path to an existing `.task/roadmap/<slug>.md` — add the section to that roadmap, or revise the one it has.
• (empty) — the roadmap this conversation is clearly about, or a fresh capture from the discussion (see Step 1).
• anything else — a rough description of the initiative, or a reference back to a prior discussion ("capture the architecture we settled").

**Format contract:** [docs/contract.md § Roadmap architecture section](../../docs/contract.md#roadmap-architecture-section) owns the section's shape, and [§ Roadmap file format](../../docs/contract.md#roadmap-file-format-taskroadmapslugmd) the file around it. This file describes the authoring flow.

Instructions

Step 0: Setup gate

The entry state, gathered before this skill reached you — no tool call of your own:

!`bash "${CLAUDE_PLUGIN_ROOT}/skills/_lib/preflight.sh" architecture`

[docs/contract.md § Helpers](../../docs/contract.md#helpers) owns that block's shape. Read it, then act:

1. `AI_DIR:` is the pipeline root: `.task/roadmap/<slug>.md` below means `$AI_DIR/roadmap/<slug>.md`, **never a cwd-relative path** ([contract § Setup-gate categories](../../docs/contract.md#setup-gate-categories)). 2. **`CONFIG: absent`** → this skill is intake-capable: read `${CLAUDE_PLUGIN_ROOT}/skills/_lib/setup.md` and follow it — it owns the sub-steps and the `.task/CLAUDE.md` template — then continue. No confirmation chip; a wrong detected value is fixed by editing the file. 3. **`CONFIG: present`** → leave the file untouched: it is user-owned, and only a missing `.task/.gitignore` is recreated, by the preflight above itself; `task.root` is written by first-run setup and not restored afterwards. 4. `ROADMAPS:` lists the roadmaps that already exist, with progress — Step 1 resolves its target against it, and a fresh capture's slug-collision check reads the same list. `SPECS:` lists the specs Step 2 may cite.

If that block arrived unexpanded — the command line itself rather than its output — the preprocessing did not fire: run that command yourself and continue exactly as above.

There is no full-scan validate call here: Step 5 validates the one file it writes, and pre-existing artifacts are checked on demand with `validate.sh all`, never as an entry gate.

Step 1: Resolve the target and mode

Take the **first** case that matches:

1. `$ARGUMENTS` holds a `ROADMAPS:` slug, or a path to a roadmap file → that roadmap is the target: **enrich** when it has no `## Architecture` yet, **revise** when it has one. 2. No positional reference, but this conversation is clearly about one existing roadmap — it was just captured with `/task:to-roadmap`, or the user names it by title or slug → that roadmap, enrich or revise as above. More than one plausible match → ask via `AskUserQuestion` (convention (c)) rather than guessing. 3. Nothing matches → **fresh**: there is no roadmap yet. Read `${CLAUDE_PLUGIN_ROOT}/skills/_lib/roadmap-capture.md` and follow its `## Core` — the too-small precondition, then steps 1–5 — with Step 0's `AI_DIR:` and `ROADMAPS:` as its inputs and **this skill as the caller**: technical shape surfacing in its decision routing is carried into this run's section, not recommended as a follow-up. When its slug-collision chip fires, it offers **Enrich existing** too; that answer switches this run to enrich (or revise) on the existing file. When the precondition stops the run as too small, nothing is written and the too-small message is the whole output — one task's technical shape is `/task:to-plan`'s `## Plan`. Otherwise, once Core has written and validated the file, continue at Step 2 on it; Core's self-check findings go into the Step 6 digest.

**Stop — nothing left to plan.** If the target's `ROADMAPS:` line reads `unchecked=none`, every item is already checked off and no planner will read a new section: stop without writing. `→ Next: \`/task:to-roadmap\` to capture the next initiative, or describe new work in chat.`

**Hard stop — a roadmap run in progress.** If the user says a `/task:roadmap-to-workflow` run is active on the target, stop without writing: its mark stage rewrites the file and would drop this edit, and its waves were computed at launch, so an added dependency would not apply anyway. `→ Next: \`/task:to-architecture <slug>\` once the run has finished.`

Step 2: Load the technical context

One parallel batch where the reads are independent:

• The target roadmap, in full — its intro, `Spec:` headers, phases, every item's ready description, and the existing `## Architecture` in revise mode.
• `bash "${CLAUDE_PLUGIN_ROOT}/skills/_lib/roadmap-items.sh" <slug>` — number, dependencies and title fo