Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Generate system architecture, machine-readable schemas, and UI mockups. Spawns planner + generator concurrently.
context
fork
Design Skill — System Architecture & UI Mockups
Ultracode tip: This is the most reasoning-heavy, divergent phase in the pipeline — exploring a wide space of architecture and schema alternatives. Run /effort ultracode before invoking it so the design space is explored as a judge-panel of approaches, then drop back to /effort high before the execution phases (/auto, /implement).
Usage
/design
No arguments. Reads from specs/stories/ and produces architecture documents, machine-readable schemas, and HTML mockups concurrently.
Overview
This is the third gate in the SDLC pipeline. Two agents run concurrently in a single message: a planner agent produces system architecture and machine-readable schemas, while the generator agent produces self-contained HTML mockups. After both complete, an evaluator agent (artifact mode) validates cross-phase traceability, schema correctness, and field-shape consistency between mockups and API contracts.
Prerequisites
specs/stories/ must exist and contain story files. If it does not, halt and tell the human to run /spec first.
Every story consumed by /design must have Readiness: ready. If any story is marked , halt and ask the human to approve a breakdown pass before generating architecture artifacts.
needs_breakdown
Step 0 — Brainstorm Architecture Direction
Before spawning agents, invoke superpowers:brainstorming to explore architectural trade-offs, technology choices, and design alternatives. This prevents the planner from committing to the first viable architecture without considering alternatives. Feed the brainstorming output into the planner agent's prompt.
Step 0.5 — Clarify Load-Bearing Design Decisions
Invoke .claude/skills/clarify/SKILL.md only for decisions that materially affect API contracts, data models, security/privacy, external integrations, deployment topology, or file ownership.
Use the clarification budget:
Ask at most 10 questions by default.
Continue to 15 only if the user explicitly asks.
Prefer existing code, CONTEXT.md, ADRs, stories, and manifest data over asking.
Record assumptions in architecture.md or api-contracts.md when risk is low.
Step 1 — Spawn Two Agents Concurrently
In a single message, invoke both agents using the Agent tool. Do not wait for the planner to finish before starting the generator.
Agent 1 — planner
Prompt:
Read all ready story files in specs/stories/ plus specs/stories/epics.md and specs/stories/dependency-graph.md. Ignore any story listed in specs/stories/backlog-needs-breakdown.md. Design the full system architecture for this project.
Write the following files to specs/design/:
architecture.md — High-level architecture overview: components, data flows, infrastructure topology, key design decisions and rationale.
For every major module, describe its public interface, invariants, error modes, and why it is deep enough to justify existing as a module. Avoid pass-through modules that only forward calls.
api-contracts.md — Every API endpoint in detail: method, path, request schema (headers, params, body), response schema (success and error shapes), authentication requirements, rate limits. Use a consistent format for each endpoint.
api-contracts.schema.json — OpenAPI 3.0 JSON Schema representing all endpoints defined in api-contracts.md. Must be valid and parseable.
data-models.md — Every data entity: field names, types, constraints, relationships, indexes, and example records.
data-models.schema.json — JSON Schema (draft-07 or later) for every entity in data-models.md. Must be valid and parseable.
folder-structure.md — Full proposed directory tree for the implementation, with a one-line annotation for each directory explaining its purpose.
component-map.md — A table mapping every ready story ID (from specs/stories/) to the specific files that will be created or modified to implement it. Include Produces: and Consumes: notes for cross-story interfaces, and identify the owning story for every shared file.
Spawn the generator agent for the mockup step, pointed at .claude/skills/design/references/ui-mockups.md for the full self-contained-HTML / CDN-React+Tailwind / aesthetic / data-fidelity guidance.
Prompt:
Read .claude/skills/design/references/ui-mockups.md, then read all ready story files in specs/stories/ and specs/design/api-contracts.md (if it exists; wait or proceed with story context if not yet available).
For every story with layer "UI", create a self-contained HTML mockup:
The mockup must be a single .html file with all CSS and JavaScript inlined (no external dependencies).
Use realistic mock data that matches the field names and types defined in api-contracts.md.
Show the primary happy-path state. Include at least one empty/error state as a toggle or commented section.
Label each interactive element with its API call (e.g., "POST /api/auth/register").
The filename must match the story ID: E{n}-S{n}.html
Write all mockups to specs/design/mockups/.
Step 1.9 — Emit the trace spine + Grounding Gate [HARD BLOCK — when specs/stories/story-traces.json exists]
After both agents complete, write specs/design/design-traces.json — one entry per design component (module/service/endpoint group from component-map.md), each tracing to the story ids it realizes:
Every component must trace to at least one story. A component realizing no story is scope creep or dead design; a story with no component will never be built. Prove it deterministically (when the spec emitted a trace spine):
specs/reviews/design-grounding.json is a hard gate independent of the rubric: any net_new (component tracing to no story) or dropped (story no component realizes) blocks. Resolve before Step 2. (Skip when story-traces.json does not exist.)
Step 2 — Phase Evaluation Gate
After both agents (planner + generator) complete, spawn the evaluator agent (artifact mode). This replaces and extends the previous field-shape validation.
Agent invocation:
Spawn Agent with subagent_type="evaluator" and prompt:
Cross-phase traceability: with a grounding verdict, confirm it; otherwise verify every story ID appears in component-map.md, every API-layer story has endpoints in api-contracts.schema.json, and every UI-layer story has a mockup in specs/design/mockups/.
Include field-shape check: Compare mockup field names against API contract field names. Flag mismatches.
Write result to specs/reviews/phase-design-eval.json
Ratchet loop (max 3 iterations):
If verdict is PASS — proceed to human approval with eval summary + traceability report.
If verdict is FAIL — revise design artifacts. May re-invoke planner or generator for specific fixes. Re-run evaluator.
Ratchet rule: weighted_average must be >= previous iteration. Revert on regression.
After 3 iterations — present best version with findings.
Machine-Readable Artifacts
Artifact
Purpose
api-contracts.schema.json
OpenAPI 3.0 schema — machine-readable by the evaluator for contract testing
data-models.schema.json
JSON Schema — used by builder agents to generate type-safe code
component-map.md
Maps stories to implementation files — used by builder agents for routing
The .schema.json files enable automated validation in later pipeline stages (the evaluator validates contracts and shapes against them).
Phase evaluation gate runs before human approval. The evaluator agent (artifact mode) validates:
Cross-phase traceability (every story has component-map entry, API endpoints, mockups)
Schema validity (OpenAPI + JSON Schema syntax)
Field-shape consistency (mockup fields match API contracts)
Component-map coverage and file ownership
Folder structure viability
Human approval is required before proceeding to /auto.
After presenting all artifacts and validation results, ask: "Does this architecture and these mockups look correct? Approve to proceed to /auto, or provide corrections."
/auto is the next step in the greenfield path (/brd → /spec → /design → /auto). /build is the wrapper that runs the whole pipeline starting from a BRD path; it is not intended to be invoked mid-pipeline after /design has already been approved.
Gotchas
API shape divergence. The planner and generator run concurrently and may independently invent field names. The evaluator (artifact mode) gate exists specifically to catch this. Never skip it.
Missing deployment.md. Builder agents need to know the target environment. This file is required, not optional.
Mock data must match API contracts. If a mockup shows a user_name field but the API contract defines username, the downstream evaluator will flag a mismatch.
No folder structure means builder agents guess. The folder-structure.md and component-map.md are the routing instructions for the build phase. Missing or vague entries cause agents to create files in wrong locations.
Unready stories must not get a component map.needs_breakdown stories are product-planning backlog, not implementation input.
Ambiguous ownership creates merge conflicts. Each file in component-map.md needs one owner. When multiple stories need a shared file, mark one story as owner and list the others under Consumes: or Declares additions:.
Schema files must be valid JSON. Run a syntax check on both .schema.json files before presenting for human review.
Concurrent execution requires a single message. Both Agent tool calls must appear in the same response. Do not run them sequentially.
