---
name: spec-driven-development-architecture
description: >
  Produces a per-feature Development Architecture Document through a spec-driven
  workflow with structural anti-skip enforcement. This skill is the micro/per-feature
  architect phase: it consumes the Solution Architecture Document and produces
  implementation-ready design — layer placement, design patterns, module structure,
  dependency wiring, test-strategy hooks, and story seeds for /create-story. Use when
  the user runs /create-development-architecture after the solution-architecture
  phase. This skill produces DESIGN ONLY — it does NOT write story files (use
  /create-story) and does NOT write production code (that is the backend-architect
  subagent inside /dev).
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: development architecture, layer placement, design patterns, module structure, dependency wiring, test strategy, story seeds, feature, anti-skip
---

# Spec-Driven Development Architecture

Translate the **Solution Architecture Document** into a concrete **per-feature
implementation-ready design** — a Development Architecture Document describing the
layer-placement map (each component → architectural layer + source-tree path), the
design patterns prescribed for the feature, the module structure, the dependency
wiring (DI graph), the per-component test-strategy hooks, and the `SEED-NNN` story
seeds that `/create-story` consumes. Governed by **ADR-069**.

This skill owns the **Development Architect** role: the micro / per-feature phase of
the modernized DevForgeAI pipeline — the implementation-design layer that
`backend-architect` previously improvised uncharted inside `/dev`, per story, under
TDD time pressure, with no review gate (Gap E of ARCH-GAPS-001).

```
/create-solution-architecture (per epic) → /create-development-architecture (THIS SKILL, once per feature)
  → /create-story (story files with acceptance criteria)
```

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

**Scope boundary — design only.** This skill produces the Development Architecture
Document and nothing else. It writes NO story files (that is `/create-story`) and
NO production code (that is the `backend-architect` subagent inside `/dev`). The
`story_seeds` it emits are SEEDS — inputs for `/create-story` — not story files.

**The constitution is THE LAW.** Layer placement, patterns, module structure, and
wiring MUST respect `architecture-constraints.md`, `source-tree/`,
`coding-standards.md`, and `anti-patterns.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
Solution 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#281: the `development-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 / phase-04 reference-manifest gate (`pre-phase-record-reference-check.sh`, ADR-091). The output-conformance gate (`validate-development-architecture-output`) does not yet exist, so the output-schema reads stay informational — bare-by-deferral (gh#281, ADR-130).

---

## Parameter Extraction

Extract from conversation context:

| Parameter | Source | Default |
|-----------|--------|---------|
| `$FEATURE_ID` | `/create-development-architecture` argument matching `^F-[0-9]{2,}$` | null → resolved in Phase 02 |
| `$SOLARCH_REF` | `--solution-architecture=<path or SOLARCH-NNN>` argument | null → auto-detect in Phase 01 |
| `$RESUME_ID` | `--resume DEVARCH-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 DEVARCH-":
  Extract DEVARCH_ID from argument
  MODE = "resume"
ELSE:
  MODE = "new"
  FEATURE_ID = extracted argument matching ^F-[0-9]{2,}$, or null
  SOLARCH_REF = extracted value of --solution-architecture=<...>, or null
```

### Step 0.2: Handle Resume Mode

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

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

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

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

### Step 0.4: Create Checkpoint File

```
checkpoint = {
  "checkpoint_version": "1.0",
  "devarch_id": DEVARCH_ID,
  "feature_id": FEATURE_ID,
  "solarch_ref": SOLARCH_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/${DEVARCH_ID}-devarch-checkpoint.json",
      content=JSON.stringify(checkpoint))
```

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

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

```bash
devforgeai-validate phase-init ${DEVARCH_ID} --workflow=development-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/${DEVARCH_ID}-development-architecture-phase-state.json`,
which **coexists** with the skill's own `${DEVARCH_ID}-devarch-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 Development Architecture Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session: ${DEVARCH_ID}
Mode: ${MODE}
Feature: ${FEATURE_ID | "to be framed in Phase 02"}
Phases: 8 (Solution Arch Ingestion > Feature Framing > Layer Placement >
           Patterns > Modules & Wiring > Test Hooks > Story Seeds > 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-development-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-development-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 | Solution Architecture Ingestion & Validation | `phases/phase-01-solution-architecture-ingestion.md` | — |
| 02 | Feature Framing | `phases/phase-02-feature-framing.md` | — |
| 03 | Layer Placement Mapping | `phases/phase-03-layer-placement-mapping.md` | — |
| 04 | Design Pattern Selection | `phases/phase-04-design-pattern-selection.md` | — |
| 05 | Module Structure & Dependency Wiring | `phases/phase-05-module-structure-wiring.md` | — |
| 06 | Test Strategy Hooks | `phases/phase-06-test-strategy-hooks.md` | — |
| 07 | Story Seed Generation | `phases/phase-07-story-seed-generation.md` | **architect-reviewer** (BLOCKING) |
| 08 | Development Architecture Document | `phases/phase-08-development-architecture-document.md` | — |

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

---

## State Persistence

- **Checkpoint:** `devforgeai/workflows/${DEVARCH_ID}-devarch-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/${DEVARCH_ID}-*.development-architecture.html")
        returns the Development Architecture Document
Verify: the document contains a <script id="development-architecture-data"> island
Verify: the embedded JSON has a non-empty handoff.recommended_build_order array
```

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

---

## Success Criteria

- All 8 phases executed (no skipping)
- Solution Architecture Document read from disk and validated against
  `solution-architecture-output.schema.json` v1.0 (Phase 01) — never consumed from
  conversation memory
- A `feature_ref` framed and recorded, resolving to a feature in the source
  Solution Architecture's `feature_decomposition` (Phase 02)
- `layer_placement_map`, `design_patterns`, `module_structure`, `dependency_wiring`,
  and `test_strategy_hooks` populated and internally consistent (Phases 03–06)
- `test_strategy_hooks` derived in-skill from `test-plan.ai.yaml` (Phase 06)
- The `architect-reviewer` design-review pass is BLOCKING; every BLOCKING finding
  resolved (Phase 07)
- `story_seeds` populated — ≥ 1 `SEED-NNN` (Phase 07)
- Development Architecture Document on disk as self-contained HTML with a
  schema-valid JSON data island
- `handoff.recommended_build_order` populated with ≥ 1 `SEED-NNN` for `/create-story`
- 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.**