spec-driven-design

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:

1. phases/phase-01-context-validation.md
2. phases/phase-02-story-analysis.md
3. phases/phase-03-interactive-discovery.md
4. phases/phase-04-template-loading.md
5. phases/phase-05-code-generation.md
6. phases/phase-06-documentation.md
7. phases/phase-07-specification-validation.md
8. phases/phase-08-feedback-completion.md

Extract route:

1. phases/phase-01-context-validation.md
2. phases/phase-02a-mockup-extraction.md
3. phases/phase-06-documentation.md
4. phases/phase-07-specification-validation.md
5. phases/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.yaml
• references/design-source-of-truth-schema.md
• references/accessibility-guidelines.md
• references/web-best-practices.md
• references/gui-best-practices.md
• references/tui-best-practices.md
• scripts/validate_design_md.py

Stop only after phase 08 completes. The registered Stop hook independently blocks a recognized or initialized invocation that remains unfinished.