sp-design

Invocation Syntax

• In this integration, invoke workflow skills with $sp-plan-style syntax.
• References such as /sp.plan, /sp.tasks, or next_command: /sp.plan are canonical workflow-state identifiers and handoff values.
• Preserve those canonical state tokens exactly in artifacts and workflow state; do not rewrite them to this integration's invocation syntax.

Workflow Contract Summary

• When to use: A project needs product-wide interface style, design-system tokens, platform UI rules, or design readiness review before specification, planning, tasks, or implementation.
• Primary objective: Produce, refine, synthesize, or audit the root DESIGN.md design-system contract without implementing UI code.
• Primary outputs: DESIGN.md, .specify/design/design-state.md, .specify/design/references.md, .specify/design/options.md, and .specify/design/review.md; stable design rules in .specify/memory/project-rules.md only when they should become shared project defaults.
• Default handoff: After user review, recommend exactly one next command: /sp.discussion, /sp.specify, /sp.plan, or the originally blocked workflow.
• Execution note: This summary is routing metadata only. Follow the full contract below end-to-end rather than inferring behavior from the description alone.

Blocked Exit Contract

If blocked after safe recovery, read and follow .specify/templates/workflow-blocker-template.md and its JSON schema. Never return only an error or “ask a human”; preserve state and keep agent-capable repair agent-owned. Set human_action_required: true only for authority, credentials, protected systems, human decisions/reviews, or physical access. Tailor steps, expected results, failure paths, evidence, and resume action to CI, visual review, or product decisions. Never claim completion.

For a feature runtime blocker, do not invent resume_argv or overwrite an existing blocker. The CLI returns a read-only show_argv and structured resolution_action; next_argv stays empty while evidence is missing. After the criteria are proven, attach sanitized evidence using the action's declared input and execute its base argv. It restores the same owner and keeps the full blocker audit.

sp-design: Design System Workflow

You are running sp-design. This is a design-system workflow, not an implementation workflow.

Objective

Produce, refine, synthesize, or audit the project's root DESIGN.md design-system contract so downstream UI work has a stable visual and interaction system before implementation starts.

Process

Follow the phase lock, intake, synthesis, review, and closeout steps below. Keep the work design-only unless the user explicitly starts a downstream implementation workflow after reviewing the design output.

Workflow Phase Lock

• Create or resume .specify/design/design-state.md before substantial design synthesis.
• Set durable state with:
  • active_command: sp-design
  • phase_mode: design-only
  • current_stage: context-intake
  • allowed_writes: DESIGN.md, .specify/design/design-state.md, .specify/design/references.md, .specify/design/options.md, .specify/design/review.md, .specify/memory/project-rules.md
  • forbidden_actions: edit source code, edit tests, write CSS/theme implementation files, create UI components, create feature specs, create plan artifacts, create task artifacts
• When resuming after compaction, read .specify/design/design-state.md before continuing.

Allowed Writes

• DESIGN.md
• .specify/design/design-state.md
• .specify/design/references.md
• .specify/design/options.md
• .specify/design/review.md
• stable design rules in .specify/memory/project-rules.md when they should become shared project defaults

Forbidden Writes

• source code
• UI components
• CSS or theme implementation files
• tests
• business feature specs
• plan or task artifacts outside the active design workflow

Modes

Infer the mode from the user's request:

• create: generate a new project design system from product context.
• synthesize: transform references into an original design system.
• refine: update an existing DESIGN.md.
• audit: inspect whether the current design system is enough for upcoming UI work.

If the mode is ambiguous, choose the smallest safe mode and state the assumption.

Intake

1. Read DESIGN.md if it exists. If it declares design_system.status: bootstrap, treat it as a starter to replace, not an approved constraint or evidence that design work is done.
2. Read .specify/design/references.md, .specify/design/options.md, and .specify/design/review.md if they exist.
3. Read README.md, project handbook files, existing UI surfaces, and existing design files. Use the command's shared Learning intake for project rules and reusable lessons.
4. Use project cognition to locate likely UI entry points, token/theme owners, reusable component owners, responsive/state patterns, visual or accessibility tests, and design assets; verify every selected route in live files before it becomes design evidence.
5. Classify the experience separately by work type, surface type (landing, product-workspace, hybrid, or existing-pattern-maintenance), and platform (web, mobile, desktop, tui, or cli).
6. If references are supplied as URLs, screenshots, text notes, existing design files, or imported summaries, assign each an explicit intent: exact, preserve-structure, inspiration, extract-tokens, or do-not-copy.
7. When built-in presets help, read one of the shipped preset files such as .specify/templates/design-library/workbench-precision.md or .specify/templates/design-library/workbench-precision.md and treat it as inspiration, not as a forced brand.

Synthesis Rules

• Write the project's own DESIGN.md as the final output.
• Present two or three project-specific design directions when creating or synthesizing a design system.
• Before proposing them, name the product subject, audience, and single user job.
• Each direction must state a visual thesis, content thesis, interaction thesis, signature element, platform fit, state strategy, safe system choices, and any deliberate creative risk with its gain and cost.
• Give every direction an inspectable visual artifact such as a moodboard, rendered static composition, or screenshot. Ask the user to approve the visual direction before writing or replacing DESIGN.md; a prose label alone is not approval.
• Ask the user to approve a direction; approval refers to its inspectable visual artifact and recorded tradeoffs, not only its name.
• Preserve existing project rules unless the user approves a design-system change that supersedes them.
• Do not copy external brand names, protected visual identity, proprietary token names, or third-party file text into the final design system.
• Normalize approved direction into spec-kit-design-v1 YAML front matter plus readable Markdown guidance.
• Set design_system.status: approved and record design_system.approval.status, the selected direction, and concrete product or repository source_refs, plus approval.visual_refs. Record product_context and direction_contract. Remove unresolved placeholders and generic starter choices that are not justified by those sources.

Output Contract

The workflow output is a root DESIGN.md contract plus supporting .specify/design/* state, references, options, and review artifacts when relevant.

Required DESIGN.md Shape

DESIGN.md must contain:

• YAML front matter with design_system.schema: spec-kit-design-v1
• design_system.status: approved plus approval direction and source refs
• product subject, audience, single job, and approved visual reference
• visual, content, and interaction theses plus one signature element
• design_system.name
• design_system.version
• design_system.platforms
• token categories for color, spacing, radius, and typography
• component required states and token references
• accessibility intent
• Markdown sections for Product Feel, Platforms, Component Rules, Anti-Patterns, UI QA Checklist, and Design Change Policy

Review

Before closeout:

1. Run uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify design lint --level ready when the CLI helper is available.
2. Write .specify/design/review.md with:
   • selected mode
   • inputs read
   • approved direction
   • approved visual reference
   • platforms covered
   • design-system risks
   • lint result
   • recommended next workflow
3. Ask the user to review the written design before downstream workflows consume it as locked input.

Closeout

Close with the design-system status, changed files, lint result, and exactly one recommended next command.

Guardrails

• Do not edit source code, tests, CSS/theme implementation files, UI components, feature specs, plan artifacts, or task artifacts from this command.
• Do not clone protected brands or copy third-party design files into DESIGN.md; synthesize project-owned design principles and tokens.
• Do not let downstream workflows treat an unaudited or contradictory DESIGN.md as locked input.

Project Learning

The CLI is the only agent-facing Learning read surface:

1. Run uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning start --command '<classic-command-name>' --format json before deeper non-trivial work.
2. Select summaries by applicability and triggers; use uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning list --command '<classic-command-name>' --format json only to filter or page.
3. Execute one matching card's show_argv. Do not parse Learning storage.

After minimal live inspection identifies a reused operation or changed entry point, rerun targeted recall with current code, tests, and task/contract evidence, for example uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning list --command '<classic-command-name>' --context 'operation_owner=<owner>' --context 'consumer_owner=<consumer>' --context 'outcome=<result-family>' --format json. Do not derive these facets from archived specifications. An exact operation-owner match may surface a cross-command candidate even when the new consumer differs; treat it as a candidate, expand one show_argv, verify it against live evidence, and do not auto-apply it.

When the entrypoint outcome audit is triggered, persist the live facets as learning_context, the contextual invocation as learning_search_refs, and returned refs as learning_candidate_refs. Record exactly one applied, not_applicable, or deferred item in learning_dispositions for every candidate. Do not silently ignore a candidate: applied Learning traces to requirement/consequence refs, not-applicable needs current evidence, and deferred needs an explicit deferral ref.

start, list, and show are read-only. Current repository evidence, .specify/memory/constitution.md, and explicit user direction override stale or candidate Learning.

At closeout, corrections, retries, route changes, recovery, false leads, hidden dependencies, validation/tooling/state/cognition gaps, constraints, and near misses are capture signals. Prefer uvx --from git+https://github.com/chenziyang110/spec-kit-plus.git@6fbbf08a0b6833bb783ec6b418d567776b197ae4 specify learning capture-auto from owning state; manual capture includes summary, problem, action, triggers, success criteria, avoid items, exceptions, and evidence.

• fast: skip unless the task escalates.
• accept, analyze, ask, auto, constitution, explain, implement-teams, taskstoissues, and team: consume-only; do not violate their write boundaries to capture.
• Other non-trivial workflows: consume before deeper work; capture reusable signals at closeout or record a no-learning decision.

The policy returned by the CLI is authoritative when prompt wording drifts.

[AGENT] For project-cognition-backed semantic intake, routing, audit, resume, or final-claim gates, read references/semantic-work-contract.md.

Detailed References

Read Reference index before applying shared semantic contracts.

• semantic work contract

Adaptive Artifact-Phase Execution

This partial governs artifact-producing adaptive phases such as sp-design, sp-plan, and sp-tasks. sp-implement has its own task-level adaptive controller; debug, map, PRD, and other workflows keep their command-specific execution contracts.

Select the execution mode before dispatch:

• light: low-risk, single-lane artifact work that is safe for leader-inline synthesis.
• standard: bounded planning or task-generation work where native subagents should be used when available.
• heavy: safety-critical, cross-boundary, high-risk, or hard-to-packetize work that requires safe native delegation before synthesis continues.

Record the adaptive decision fields exactly:

• execution_model: adaptive
• execution_mode: light | standard | heavy
• workflow_status: ready | blocked
• dispatch_shape: leader-inline | one-subagent | parallel-subagents | subagent-blocked
• execution_surface: leader-inline | native-subagents | none
• capability_degraded: false | true
• blocked_reason: required when blocked

Use choose_subagent_dispatch(command_name="plan" | "tasks", snapshot, workload_shape) as the shared policy contract. Derive workload_shape.lightweight_safe from workload shape and risk keys; do not invent a separate template-only boolean.

Dispatch rules:

• Light mode records dispatch_shape: leader-inline, execution_surface: leader-inline, workflow_status: ready, and capability_degraded: false.
• Standard mode uses native subagents when available: one validated lane records one-subagent; two or more isolated lanes record parallel-subagents.
• Standard mode may degrade to leader-inline only when native subagents are unavailable and no high-risk trigger is present; record capability_degraded: true.
• Heavy mode must use native subagents with safely packetized lanes. If native subagents are unavailable, or if the work cannot be packetized safely, record workflow_status: blocked, dispatch_shape: subagent-blocked, execution_surface: none, and blocked_reason.

Artifact-writing delegated lanes must use writable, execution-capable native subagents. If the runtime exposes role, sandbox, or permission choices, select a role/sandbox that can write the declared handoff file. Do not dispatch a read-only explorer, reviewer, or diagnostic lane when the lane must write a filesystem handoff; read-only lanes may provide supplemental evidence, but they do not satisfy one-subagent or parallel-subagents handoff requirements. The lane contract's allowed write scope must include the exact expected handoff path and must forbid unrelated writes unless the command explicitly assigns an additional generated artifact. If a delegated lane returns prose, idle state, or an unwritten handoff, stop or re-dispatch with a writable lane and the valid handoff path.

Delegated lanes still require structured handoffs before synthesis. If delegated lanes were used, consume the one lane manifest and every accepted lane result before final output; do not duplicate the same events into evidence-index and checkpoint logs. If no lanes were delegated, report the delegated-lane field as none.

Managed-team fallback is not part of adaptive plan/tasks dispatch. Do not route blocked adaptive planning or task generation to sp-teams, managed-team lifecycle language, or a durable team fallback from this command.

Codex Subagent Capability Discovery

• Execution model: preserve the workflow's existing subagent-mandatory, subagents-first, adaptive, or subagent-assisted policy.
• Dispatch shape: preserve the workflow's existing dispatch shape; use subagent-blocked only after the discovery step below fails or is unsafe.
• Execution surface: prefer native-subagents when the current runtime supports it; use none only after recording the unavailable or unsafe surface.
• Native subagent capability discovery: Before recording subagent-blocked, confirm the current runtime exposes spawn_agent, wait_agent, and close_agent; if they are not visible, use the active tool discovery mechanism for multi-agent or subagent tools first.
• Do not record subagent-blocked until this capability discovery step is complete and the exact unavailable or unsafe surface is recorded.
• Native subagent dispatch: Dispatch bounded subagents through spawn_agent.
• Join behavior: Rejoin with wait_agent, integrate, then close_agent.
• Preserve this workflow's existing packet, handoff, artifact, and result schema; this section only governs capability discovery before dispatch or blocked-state recording.