| name | spec-driven-design |
| description | Create Web, GUI, or Terminal design specifications in story, standalone, or extract mode from a customizable brief, brand, and visual direction; generate design.md, implementation artifacts, and web artifacts when the selected target is Web. Invoke explicitly with $spec-driven-design. |
Spec-Driven Design
Run one deterministic design workflow. This Codex implementation owns design
specification, artifact generation, local rendered review, and deterministic
validation.
Invocation contract
- Invoke explicitly as
$spec-driven-design.
- Resolve bundled resources relative to this skill directory.
- Inspect and edit files, run commands, request user input, view local images,
and dispatch subagents only when repository instructions require them.
- Treat a non-zero
devforgeai-validate result as blocking. Never record a step
whose verifier or material artifact failed.
Modes and identifiers
| Mode | Input | Identifier | Workflow |
|---|
| story | exactly STORY-NNN | supplied story ID | design |
| standalone | brief or --standalone | DESIGN-STANDALONE | design |
| extract | --extract <path> [--web-artifact=<repository-relative-html>] | DESIGN-EXTRACT | design-extract |
Reject conflicting modes, malformed story IDs, missing extract paths, and path
traversal. Story identifiers are exactly three digits. Set MODE, IDENTIFIER,
and WORKFLOW, then run:
For extract mode, --web-artifact is optional and may appear exactly once. The
invocation hook binds its repository-relative path and SHA-256. Never infer a
lint target from other discovered HTML files.
devforgeai-validate phase-init "$IDENTIFIER" \
--workflow="$WORKFLOW" --mode="$MODE" --project-root=.
An exit other than 0 or the documented already-exists resume result blocks the
workflow.
Phase router
Before each phase, inspect its linked file completely. Execute its required
steps, verify named outputs, record only verified receipts, and run the shared
validator before phase-complete.
Story and standalone route:
phases/phase-01-context-validation.mdphases/phase-02-story-analysis.mdphases/phase-03-interactive-discovery.mdphases/phase-04-template-loading.mdphases/phase-05-code-generation.mdphases/phase-06-documentation.mdphases/phase-07-specification-validation.mdphases/phase-08-feedback-completion.md
Extract route:
phases/phase-01-context-validation.mdphases/phase-02a-mockup-extraction.mdphases/phase-06-documentation.mdphases/phase-07-specification-validation.mdphases/phase-08-feedback-completion.md
At every phase boundary run both commands and require exit 0:
devforgeai-validate validate-design-phase "$IDENTIFIER" \
--workflow="$WORKFLOW" --mode="$MODE" --phase="$PHASE" --project-root=.
devforgeai-validate phase-complete "$IDENTIFIER" \
--workflow="$WORKFLOW" --phase="$PHASE" --project-root=.
Required outputs
All modes produce devforgeai/specs/ui/design.md and
devforgeai/specs/ui/UI-SPEC-SUMMARY.md. Story and standalone modes also
produce the selected implementation artifact. A Web target includes a runnable
web artifact; GUI and Terminal targets use the approved source-tree location.
Record the dynamic output on step 5.5:
devforgeai-validate phase-record "$IDENTIFIER" --workflow=design \
--phase=05 --step=5.5 --artifact="$OUTPUT_PATH" --project-root=.
The CLI rejects a missing, empty, absolute, or traversing artifact path.
Shared resources
contracts/design-context-handoff-contract.yamlreferences/design-source-of-truth-schema.mdreferences/accessibility-guidelines.mdreferences/web-best-practices.mdreferences/gui-best-practices.mdreferences/tui-best-practices.mdscripts/validate_design_md.py
Stop only after phase 08 completes. The registered Stop hook independently
blocks a recognized or initialized invocation that remains unfinished.
