---
name: spec-driven-solution-architecture
description: >
  Produces a per-epic Solution Architecture Document through a spec-driven
  workflow with structural anti-skip enforcement. This skill is the meso/per-epic
  architect phase: it consumes the System Architecture Document, decomposes an
  epic into components, interface contracts, a data model, and features with
  feasibility verdicts. Use when the user runs /create-solution-architecture
  after the system-architecture phase. Do NOT use for constitutional/system-wide
  decisions (use spec-driven-system-architecture) or per-feature implementation
  design (use spec-driven-development-architecture).
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
  - Task
  - Bash(git:*)
  - Bash(devforgeai-validate:*)
  - Skill
model: opus
effort: High
version: "1.0.0"
last-updated: "2026-05-18"
topics: solution architecture, component decomposition, interface contracts, data model, integration design, feature decomposition, feasibility, epic, anti-skip
---

# Spec-Driven Solution Architecture

Translate the **System Architecture Document** into a concrete **per-epic
technical design** — a Solution Architecture Document describing the component
decomposition, the interface contracts between those components, the solution
data model, the integration design, and the epic's feature decomposition with
feasibility verdicts. Governed by **ADR-068**.

This skill owns the **Solution Architect** role: the meso / per-epic phase of the
modernized DevForgeAI pipeline — the technical-design layer that was absent
before (Gap A of ARCH-GAPS-001).

```
/create-system-architecture (constitution) → /create-solution-architecture (THIS SKILL, once per epic)
  → /create-development-architecture (per-feature implementation design)
```

**Input contract:** `system-architecture-output.schema.json` v1.0 — the System
Architecture Document, carried in a `<script type="application/json"
id="system-architecture-data">` data island inside its HTML file.
**Output contract:** `solution-architecture-output.schema.json` v1.0 — emitted as
a self-contained HTML document with an embedded JSON data island
(`<script type="application/json" id="solution-architecture-data">`).

**The constitution is THE LAW.** Components, layers, and contracts MUST respect
`architecture-constraints.md` and `tech-stack.md`. If ambiguous or conflicting:
HALT and use AskUserQuestion.

---

## Execution Model

See **`.claude/rules/core/anti-skip-behavior.md`** for the canonical execution
contract (expand inline; do not wait passively or offer execution options;
honor every step of every phase; Self-Check violation taxonomy; Token-
Optimization-Bias prohibition; governed by ADR-076). After invocation,
execute Phase 00 Initialization immediately. Note: do not consume the
System Architecture content from conversation memory — Phase 01 MUST read
it from disk.

---

## Anti-Skip Enforcement Contract

Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the `devforgeai-validate` phase gates, the `settings.json`-registered `.claude/hooks/` scripts, and `.claude/hooks/phase-steps-registry.json` (ADR-076). Behavioral residue: `.claude/rules/core/anti-skip-behavior.md`.

Layer 4 (CLI phase-gate) **is wired** for this workflow as of gh#282: the `solution-architecture` schema is registered in `phase_state.py` `WORKFLOW_SCHEMAS` (gh#280/#289), and Phase 00 + every phase file call `phase-init` / `phase-check` / `phase-record` / `phase-complete`. Step- and subagent-count enforcement stays deferred (empty `steps_required` / `subagents_required`, per the ADR-110 / ADR-073 precedent); the active enforcers are the boundary gate (`pre-phase-complete-boundary-check.sh`, PreToolUse exit 2 when a phase file was never `Read()` — ADR-132; `phase-entry-validator.sh` is now PostToolUse telemetry) and the phase-03 reference-manifest gate (`pre-phase-record-reference-check.sh`, ADR-091, exit 2) for the one constitutional read `architecture-constraints.md`. The 7× own-output-schema reads stay informational — bare-by-design — because the produced artifact is validated downstream by the `validate-solution-architecture-output` command (ADR-084); promoting them to `[MANDATORY]` would duplicate that validator (gh#282, ADR-131).

---

## Parameter Extraction

Extract from conversation context:

| Parameter | Source | Default |
|-----------|--------|---------|
| `$EPIC_ID` | `/create-solution-architecture` argument matching `^EPIC-[0-9]{3,}$` | null → resolved in Phase 02 |
| `$SYSARCH_REF` | `--system-architecture=<path or SYSARCH-NNN>` argument | null → auto-detect in Phase 01 |
| `$RESUME_ID` | `--resume SOLARCH-NNN` argument | null (new session) |
| `$MODE` | Derived from above | "new" or "resume" |

---

## Phase 00: Initialization [INLINE — Bootstraps State]

This phase runs inline because it creates the state that all other phases depend on.

### Step 0.1: Parse Arguments

```
IF conversation contains "--resume SOLARCH-":
  Extract SOLARCH_ID from argument
  MODE = "resume"
ELSE:
  MODE = "new"
  EPIC_ID = extracted argument matching ^EPIC-[0-9]{3,}$, or null
  SYSARCH_REF = extracted value of --system-architecture=<...>, or null
```

### Step 0.2: Handle Resume Mode

```
IF MODE == "resume":
  checkpoint_path = "devforgeai/workflows/${SOLARCH_ID}-solarch-checkpoint.json"
  Glob(pattern=checkpoint_path)
  IF found:
    Read(file_path=checkpoint_path)
    CURRENT_PHASE = checkpoint.progress.current_phase
    Display: "Resuming ${SOLARCH_ID} from Phase ${CURRENT_PHASE}"
    GOTO Phase Orchestration Loop at CURRENT_PHASE
  ELSE:
    Display: "No checkpoint found for ${SOLARCH_ID}."
    AskUserQuestion: start new vs. abort
```

### Step 0.3: Generate Solution Architecture ID (New Session)

```
IF MODE == "new":
  Glob(pattern="devforgeai/specs/architecture/SOLARCH-*.solution-architecture.html")
  Glob(pattern="devforgeai/workflows/SOLARCH-*-solarch-checkpoint.json")
  SOLARCH_ID = "SOLARCH-{NNN+1}"   # zero-padded to 3 digits minimum
```

The `SOLARCH-NNN` id satisfies the `^SOLARCH-[0-9]{3,}$` pattern in
`solution-architecture-output.schema.json`.

### Step 0.4: Create Checkpoint File

```
checkpoint = {
  "checkpoint_version": "1.0",
  "solarch_id": SOLARCH_ID,
  "epic_id": EPIC_ID,
  "sysarch_ref": SYSARCH_REF,
  "created_at": "<ISO 8601 timestamp>",
  "progress": { "current_phase": 1, "phases_completed": [], "total_phases": 8 },
  "phases": {
    "01": {"status": "pending"}, "02": {"status": "pending"},
    "03": {"status": "pending"}, "04": {"status": "pending"},
    "05": {"status": "pending"}, "06": {"status": "pending"},
    "07": {"status": "pending"}, "08": {"status": "pending"}
  }
}

Write(file_path="devforgeai/workflows/${SOLARCH_ID}-solarch-checkpoint.json",
      content=JSON.stringify(checkpoint))
```

**VERIFY:** `Glob(pattern="devforgeai/workflows/${SOLARCH_ID}-solarch-checkpoint.json")`
returns exactly 1 file. IF not found: HALT — "Initial checkpoint was NOT created."

### Step 0.4b: Initialize CLI Phase-State (gh#282)

```bash
devforgeai-validate phase-init ${SOLARCH_ID} --workflow=solution-architecture --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Phase-state initialized — proceed |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — phase-state could not be initialized |

This writes `devforgeai/workflows/${SOLARCH_ID}-solution-architecture-phase-state.json`,
which **coexists** with the skill's own `${SOLARCH_ID}-solarch-checkpoint.json` (Step
0.4) — the CLI file backs the boundary/reference hooks; the checkpoint backs resume.
Do NOT unify or migrate them.

### Step 0.5: Display Initialization Banner

```
Display:
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  DevForgeAI Solution Architecture Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session: ${SOLARCH_ID}
Mode: ${MODE}
Epic: ${EPIC_ID | "to be framed in Phase 02"}
Phases: 8 (System Arch Ingestion > Epic Framing > Components >
           Interfaces > Data Model > Integration > Features > Document)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
```

Set CURRENT_PHASE = 1. **GOTO Phase Orchestration Loop at Phase 01.**

---

## Phase Orchestration Loop

For each phase from CURRENT_PHASE to 8:

1. **LOAD PHASE:** `Read(file_path=".claude/skills/spec-driven-solution-architecture/phases/{phase_file}")`
   — Read the phase file FRESH. Do NOT skip this step.
2. **LOAD REFERENCES:** Each phase file specifies which references to load from
   `.claude/skills/spec-driven-solution-architecture/references/`. Load them ALL via
   `Read()`. Do NOT skip or summarize.
3. **EXECUTE STEPS:** Follow EVERY step's EXECUTE-VERIFY-RECORD triplet in the phase
   file, IN ORDER. Do NOT compress or skip steps.
4. **EXIT CRITERIA:** Verify ALL mandatory exit conditions listed in the phase file
   before proceeding.
5. **UPDATE CHECKPOINT:** Set `phases[phase_id].status = "completed"`, add to
   `phases_completed`, advance `current_phase`.
6. **VERIFY CHECKPOINT:** `Read()` the checkpoint — confirm the update persisted.
7. **DISPLAY TRANSITION:** Show phase completion and the next phase name.

---

## Phase Table

| Phase | Name | File | Subagents |
|-------|------|------|-----------|
| 01 | System Architecture Ingestion & Validation | `phases/phase-01-system-architecture-ingestion.md` | — |
| 02 | Epic Framing | `phases/phase-02-epic-framing.md` | — |
| 03 | Component Decomposition | `phases/phase-03-component-decomposition.md` | — |
| 04 | Interface & Contract Design | `phases/phase-04-interface-contract-design.md` | **api-designer** |
| 05 | Data Model Design | `phases/phase-05-data-model-design.md` | — |
| 06 | Integration Design | `phases/phase-06-integration-design.md` | — |
| 07 | Feature Decomposition | `phases/phase-07-feature-decomposition.md` | **requirements-analyst**, **architect-reviewer** (BLOCKING) |
| 08 | Solution Architecture Document | `phases/phase-08-solution-architecture-document.md` | — |

No phase is conditional — all 8 run on every invocation.

---

## State Persistence

- **Checkpoint:** `devforgeai/workflows/${SOLARCH_ID}-solarch-checkpoint.json`
- **Updated:** After every phase completion
- **Verified:** Via `Glob()` after every write
- **Resume:** Read checkpoint, set `CURRENT_PHASE` from `progress.current_phase`,
  resume loop

---

## Workflow Completion Validation

```
IF len(phases_completed) < 8:
    HALT "WORKFLOW INCOMPLETE — ${len(phases_completed)}/8 phases accounted for"

Verify: Glob("devforgeai/specs/architecture/${SOLARCH_ID}-*.solution-architecture.html")
        returns the Solution Architecture Document
Verify: the document contains a <script id="solution-architecture-data"> island
Verify: the embedded JSON has a non-empty handoff.recommended_approach
```

IF any verification fails: HALT and report the missing artifact.

---

## Success Criteria

- All 8 phases executed (no skipping)
- System Architecture Document read from disk and validated against
  `system-architecture-output.schema.json` v1.0 (Phase 01) — never consumed from
  conversation memory
- An `epic_ref` framed and recorded (Phase 02)
- `components`, `interface_contracts`, `data_model`, and `feature_decomposition`
  populated and internally consistent (Phases 03–07)
- Every feature carries a feasibility verdict; the architect-reviewer pass is
  BLOCKING (Phase 07)
- Solution Architecture Document on disk as self-contained HTML with a
  schema-valid JSON data island
- `handoff.recommended_approach` populated for `/create-development-architecture`
- All ambiguities resolved via AskUserQuestion

---

## Deviation Protocol

If you need to deviate from ANY phase step:
1. HALT immediately
2. Use AskUserQuestion to explain the deviation and get user consent
3. Only proceed with explicit user approval
4. Record the deviation in the checkpoint under a `deviations` key

**Without user consent, no deviation is permitted.**