| 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.
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).
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. Phase 04 requires api-designer and Phase 07 requires requirements-analyst + architect-reviewer — now enforced at phase-complete by subagent-dispatch-reconcile.sh Condition C (ISSUE-726; graduates the ADR-110/ADR-073 enforcement deferral). 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)
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:
- LOAD PHASE:
Read(file_path=".claude/skills/spec-driven-solution-architecture/phases/{phase_file}")
— Read the phase file FRESH. Do NOT skip this step.
- 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.
- EXECUTE STEPS: Follow EVERY step's EXECUTE-VERIFY-RECORD triplet in the phase
file, IN ORDER. Do NOT compress or skip steps.
- EXIT CRITERIA: Verify ALL mandatory exit conditions listed in the phase file
before proceeding.
- UPDATE CHECKPOINT: Set
phases[phase_id].status = "completed", add to
phases_completed, advance current_phase.
- VERIFY CHECKPOINT:
Read() the checkpoint — confirm the update persisted.
- 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:
- HALT immediately
- Use AskUserQuestion to explain the deviation and get user consent
- Only proceed with explicit user approval
- Record the deviation in the checkpoint under a
deviations key
Without user consent, no deviation is permitted.
