Menu
Use when shape finds UI, domain, contract, interface, visual ambiguity, affects_ui, design_required, or no design reference before plan.
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.
Based on SOC occupation classification
| name | ship-design |
| description | Use when shape finds UI, domain, contract, interface, visual ambiguity, affects_ui, design_required, or no design reference before plan. |
| user-invocable | false |
| argument-hint | [entity-id | slug] |
Design intent capture stage for UI, domain, and contract/interface pitches. Runs between shape and plan when trigger fires. Named designer agent produces design artifacts or contract decisions captain can review before plan stage — preventing the 3-cross-review fix loop + captain dogfood failure that pitch-103 required (18 files / 3641 LOC Mega 1.5 spike from misaligned design intent).
Stage-skill count: adding ship-design makes 7/7 (ship-shape / ship / ship-plan / ship-execute / ship-verify / ship-review / ship-design = hard cap per Principle 2). No further stage-skills can be added without first folding or extracting an existing one.
Run before any design work. Stop and SendMessage(FO) if any check fails.
affects_ui: true OR domain: frontmatter registered in registry OR design_required: true OR contract_decision_required: true OR --design flag OR files match *.tsx|*.css|*.html. Design always runs — trivial-pass entities (none of these signals present) walk Phase 0 fast-path per D5 (see Phase 0 §Trivial-pass fast-path). There is no pipeline-level skip.status: — must be sharp. If design → design already ran (check for re-entry signal).### Hand-off to Design block (from ship-shape Phase 8). If absent → SendMessage(FO): "Missing Hand-off to Design — shape stage did not complete handoff."## Sharp Output → Problem cites a file:line. Read that file before Phase 1 — if missing → SendMessage(FO): "Exploration file not found: <path> — cannot distill design without source."superpowers:brainstorming in Design Report; proceed.answers_density from entity frontmatter. high → auto-load framework skills per ship-runtime-detect Step R6; skip FO ask. low|vacuum → SendMessage(FO) with proposed skill list; wait for confirmation.PRODUCT.md constraints and relevant ARCHITECTURE.md sections
before dispatching designers. Contract-bearing means any schema/API/domain,
data-flow, storage, runtime, component-boundary, or architecture-impact
signal. If either doc is missing, record the missing source in design.md
rather than inventing constraints.design-flow owns the contradiction-resolution Q-loop and design distillation flow (#106 T5.2). Do NOT re-teach this procedure. Invoke it; Layer B below provides the Shape Up framing (5-category classifier, per-app design-system.md targeting, Material/Atlassian Principles tier separation, L2 strictness DCs).
Fallback: if design-flow is unavailable (plugin not installed), fall back to superpowers:brainstorming for contradiction resolution. Document the fallback in design.md ## Design Report.
Design stage fires when ANY of:
affects_ui: true in entity frontmatter (UI trigger path; set by shape stage when pitch touches frontend)domain: frontmatter set in entity, registered in registry (specialist trigger path; set by ship-shape Phase 8.5 via registry-resolve.sh --classify; domain: set_at shape)design_required: true in entity frontmatter (contract-bearing trigger path for
schema/API/domain/architecture work that is not otherwise UI or registered
domain)contract_decision_required: true in entity frontmatter because shape emitted
open_contract_decisions[] for unresolved non-UI contract/interface choices
such as selector grammar, API vocabulary, tool protocol, DSL syntax, schema or
message formatFiles modified or architecture-impact cites path matching glob *.tsx | *.css | *.html--design flag on /shape invocationOtherwise: design always runs — trivial-pass entities walk the fast-path in Phase 0 (see below) instead of being skipped at the pipeline level.
Boolean predicate for FO and plan stage to determine gate type without runtime-only enum lookups (Principle 4 boolean-gate compliance):
UI-lane := (affects_ui == true) OR (Files-modified glob matches *.tsx|*.css|*.html)
non-UI-lane := (domain set) OR (design_required == true) OR (contract_decision_required == true)
trivial-pass := neither UI-lane nor non-UI-lane conditions hold
Mixed (both UI-lane and non-UI-lane signals true) → prefer UI gate (captain-gated; safe-side per shape artifact A3)
Note — domain-set-but-unregistered: If
domainis set but not registered in the registry (registry-resolve --validate exit 10 / 11), the entity is still non-UI-lane for gate purposes (domain-set is sufficient; registry membership is not a gate-classification concern). Phase 0 step 2 handles registry validation separately — emitting## Design Output → ### Router HALTblock when M1/M2 fires; the lane classification (FO-gated) does not change.
This is the single canonical reference for FO and plan stage lane classification. Cross-reference: INVARIANTS Principle 10 "Design Gate Domain Split".
designer@pitch-XX is a named teammate (Principle 6 Rule A). After completing the design stage, the same teammate may be called again at verify stage via SendMessage from the verifier agent (ship-verify Step 3.5).
Secondary role contract (triggered by ship-verify):
git diff <execute_base>..HEAD -- <ui_files>) + path to design artifacts (design.md / plugins/<app>/design/).BLOCKING / WARN / NIT with file:line citations. Return via SendMessage(to: "verifier").Why same named agent: D1-D6 captain decisions are held in this agent's active context from the design stage. A fresh agent would have to re-read the full design artifact bundle and could miss nuanced intent that was resolved interactively during the Q-loop.
Reads from:
## Sharp Output → Problem — exploration file cite (path:line), stated contradictions## Sharp Output → Done Criteria — UI-typed DCs that design must informPRODUCT.md — product constraints and capability promises that constrain
design decisionsARCHITECTURE.md — relevant architecture/domain/API/schema sections for
contract-bearing design workWrites to (entity-body-schema.yaml → stages.design):
## Design Output / ### Captain Decisions — D{N}|Captain decision tagged per contradiction## Design Output / ### Artifact Bundle Manifest — table of emitted files## Design Output / ### Constraints for Plan Stage — token / interaction constraints plan must honor## Design Output / ### Canonical Context — canonical_context rows naming
the PRODUCT.md / ARCHITECTURE.md sections read, update intent, and skip
rationale when no canonical doc change is required## Design Report — status / cost / iterations / captain_decisions count / reviewer_verdictEmits artifact bundle at plugins/<app>/design/:
design-system.md — canonical design foundations + components + patterns (map-layer registered)tokens.css — CSS custom properties (MUST be byte-equal across re-runs: load-bearing for L2 dogfood DC)design-system.html — visual gallery of all tokens in contextcomponents/<name>.html — one HTML specimen per component (visual fidelity required for captain ack)war-room.html (or app-equivalent) — composed mockup showing components in a real screenAll 5 categories below are UI / visual / IA / aesthetic work — they route to design-officer (standing teammate) in team mode, or to inline worker handling in bare mode. The separate domain / schema / contract / business-logic lane (triggered by domain: frontmatter) routes to schema-designer via the existing domain-registry path (Phase 0.5 §Domain path) and is NOT one of these 5 categories. Both paths can fire concurrently for an entity that needs both kinds of design work (e.g., new schema + new UI).
| Category | Trigger | Routing target | Active dispatch path |
|---|---|---|---|
| 0 — Distill from existing exploration | Shape cites exploratory HTML/markdown at file:line; contains ≥2 conflicting design directions | → design-officer (visual) | ui-designer distills existing exploration, invokes storyboard, design-flow, and design-review |
| Category A — Net-new design system | plugins/<app>/design/ directory absent; first-ever design for this app | → design-officer (visual) | ui-designer runs full chain: design-flow using design-brief, information-architecture, design-tokens, brief-to-tasks, then frontend-design and design-review |
| Category B — Component breakout | design-system.md exists; new component specimen needed | → design-officer (visual) | ui-designer uses frontend-design, design-tokens if tokens change, and design-review; load information-architecture only when component placement/navigation changes |
| Category C — Variation on existing component | design-system.md exists; variant on component spec | → design-officer (visual) | ui-designer preserves existing design canon, uses frontend-design, then design-review |
| Category D — One-off visual | Pitch-local mockup only; does NOT touch design-system.md | → design-officer (visual) | ui-designer uses frontend-design; add design-review only for high-risk UI or accessibility-sensitive changes |
Category A-D are active. Do not halt solely because the category is A, B, C, or D.
If required design skills are missing, record the fallback in Design Report and
continue with the narrowest viable route.
Routing decoupling: the "Routing target" column names who owns the visual exploration (design-officer in team mode, worker inline in bare mode). The "Active dispatch path" column names the skill chain the visual work runs through. design-officer (when alive) is the agent that drives the chain in team mode; the chain itself is unchanged. Domain work is never routed here — see Phase 0.5 §Domain path.
Before worker dispatch, write a design-dispatch-manifest block into
design.md or the design-stage draft. This is the contract between ship-design,
plan, and execute:
design-dispatch-manifest:
lanes:
- lane: ui
role: ui-designer
category: Category A|Category B|Category C|Category D|Category 0
required_skills: []
adopter_routing:
files: []
skills_needed: []
folder_guidance_files: []
folder_guidance_skills: []
codex_context_boundary: "root AGENTS.md/CLAUDE.md intentionally excluded from folder_guidance_files"
outputs: []
- lane: domain
role: domain-designer
domain: schema
panel_lane: domain-expert
required_skills: []
knowledge_module_path: ""
designer_section_anchor: ""
review_contract:
worktree: "<absolute worktree path>"
base_head: "<base>..<head>"
mode: read-only findings-only
outputs: []
- lane: contract-interface
role: contract/interface-designer
trigger: open_contract_decisions
decisions: []
examples: ["selector grammar", "API vocabulary", "tool protocol", "DSL syntax", "schema/message format"]
outputs: ["captain_decisions", "design_constraints", "open_decisions[] if unresolved"]
integration:
mode: single-designer|parallel
owner: ship-design
visual_verification:
fragment_level: render_fidelity_targets[]
whole_page: whole_page_visual_targets[]
Before dispatching any stage-internal designer, domain expert panel lane, contract/interface worker, or design cross-reviewer, render and include the shared worker-facing stewardship section:
bash "${CLAUDE_PLUGIN_ROOT:-plugins/ship-flow}/lib/render-science-officer-em-stewardship-contract.sh"
The resulting ### Science Officer (EM) Stewardship Contract block is part of
the assignment body. It carries results, guidelines, resources, accountability,
consequences. FO owns workflow clock, state, worktrees, dispatch mechanics, PR
lifecycle, and stage advancement. EM owns engineering judgment, delegation
quality, worker stewardship quality, risk/scope challenge, and technical
recommendations. EM does not mutate entity state, own worktrees, dispatch
workers, create or merge PRs, or advance stages. Verification is output-shape
evidence, not worker self-attestation.
Dispatch rules:
single-designer mode with one
ui-designer.single-designer mode with one domain-designer
routed through the registry specialist.single-designer mode with one
contract/interface-designer. It must present a trade-off table for each
open_contract_decisions[] item and capture a D{N}|Captain decision
before plan. Examples include selector grammar, API vocabulary, tool protocol,
DSL syntax, schema/message format, and mapper→native boundary contracts.parallel designer dispatch: dispatch ui-designer and domain-designer concurrently, then run an integration pass in ship-design
that merges outputs into one design.md handoff.parallel. Collapse to
single-designer only when one lane is trivial and the reason is recorded in
the manifest.file:line citations.Files modified, exploration
cites, or obvious UI surface path, run:
bash "${CLAUDE_PLUGIN_ROOT:-plugins/ship-flow}/lib/resolve-skill-routing.sh" \
--config=.claude/ship-flow/skill-routing.yaml \
--files=<comma-separated-ui-candidate-files>
skills_needed= into the UI lane required_skills, preserving the
Category skill chain first and de-duping in order. Record
folder_guidance_files=, folder_guidance_skills=, and
codex_context_boundary under adopter_routing..claude/ship-flow/skill-routing.yaml is absent on an adopter project,
write adopter_routing.status: missing-config and bounce to shape/onboard
for non-trivial UI work. Tiny one-file UI work may continue only with the
missing-routing warning recorded in Design Report.ui-designer dispatch prompt must include a ### Folder guidance required block with every folder_guidance_files path emitted by the
resolver. The designer must read those files and return a Context Read Receipt listing guidance files, routed skills, folder guidance skills, and
applied constraints. If the resolver emits no folder_guidance_files, write
none — resolver reported no folder_guidance_files; do not invent or require
a CLAUDE.md/AGENTS.md path. Example only: if an adopter's resolver output
includes folder_guidance_files=apps/refine-app/CLAUDE.md, include that path
plus routed/folder skills such as refine-expert, refine-gotchas,
antd-expert, react-patterns, and tailwind-expert.AGENTS.md and
CLAUDE.md remain runtime/session context; ship-design only enforces
non-root folder guidance reported by resolve-skill-routing.sh.Anchor: ship-design#contract-interface-designer
This is the registry target for portable contract/interface domains such as
agent-contract, api-vocabulary, selector-grammar, tool-protocol, dsl,
and message-format. It maps to the existing contract-interface lane rather
than a dedicated specialist scaffold. The lane resolves the open
contract/interface choice with a trade-off table, emits D{N}|Captain decision
markers, and hands plan structured design_constraints[] with
open_decisions[] empty or explicitly blocking.
Fragment-level ui-verify checks are necessary but not sufficient. They catch
precise token, selector, and computed-style failures, but they can still pass
when the final screen composition diverges from the design reference. For every
affects_ui: true lane, ship-design must emit both:
render_fidelity_targets[] — fragment-level ui-verify assertions for
selectors, tokens, and computed styles.whole_page_visual_targets[] — full-page screenshot parity targets for the
primary affected route or surface.Each whole_page_visual_targets[] item names {route, reference_artifact, capture, threshold, rationale_decision}. reference_artifact should point to
the composed mockup or reference screenshot, such as
plugins/<app>/design/<surface>.html or a committed reference image. capture
must say full-page screenshot unless the UI is an embedded fixed-size widget.
These targets feed plan-stage verify DCs and ship-verify whole-page visual
parity. Do not claim visual parity from fragment-level ui-verify alone.
Design Readiness Review is a risk-gated mod inside the design stage, not a standard stage. Run it after designer lanes merge and before hand-off to plan when any trigger applies:
multi-domain work, including UI + schema/API/domain changes.The mod dispatches low-model specialist reviewers derived mechanically from domain registry and adopter file-signal routing. Start with these reviewer derivation rules, then cap to the smallest useful team (normally 1-3 reviewers):
affects_ui: true or whole_page_visual_targets[] → reviewer ui.domain: schema, DB migration files, or Supabase schema paths → reviewer
schema.api.fmodel.refine,
expo, or supabase only when the matched route requires that specialist.Each reviewer loads the relevant domain knowledge module plus required skills
and returns PASS, WARN, or BLOCK with route_to: design|plan. Do not
hardcode a project-specific reviewer set. If no risk trigger applies, write
Design Readiness Review: skipped - no risk trigger in Design Report. Any
BLOCK must be resolved before plan.
Trivial-pass fast-path (check BEFORE any other routing — short-circuits if all conditions hold):
If ALL of the following hold:
affects_ui: false (or unset)domain: unset (or empty string)design_required: false (or unset)contract_decision_required: false (or unset)open_contract_decisions[]: empty or unset→ trivial-pass — do NOT dispatch any designer worker or build design-dispatch-manifest:
Emit minimal design.md:
## Design Report
status: trivial-pass
stage_cost: $0.00 (trivial-pass)
### Metrics
status: trivial-pass
duration_minutes: 0
iteration_count: 0
captain_decisions_count: 0
reviewer_verdict: PROCEED
Plus a ### Hand-off to Plan block:
design-skipped: true
design_constraints: []
open_decisions: []
artifact_paths: []
render_fidelity_targets: []
whole_page_visual_targets: []
Phase 9 emits unconditional PROCEED verdict (no cross-review dispatch needed).
Register design completion through the Phase 10 completion contract; do not enter plan directly.
Return to the First Officer. The FO owns the separate plan stage-entry transition and planner dispatch.
Per DC-8: design-skipped: true (not design-skipped: false with empty constraints) so plan Step 1.6 G14 semantics short-circuit correctly. Cross-reference: INVARIANTS Principle 11 "Design Stage Required".
affects_ui: and domain:. Record both.domain: is set: invoke registry-resolve to confirm specialist availability:
bash "${CLAUDE_PLUGIN_ROOT:-plugins/ship-flow}/lib/registry-resolve.sh" --validate --domain=<domain-name>
designer_section_anchor with registry-resolve.sh --domain=<domain-name>. If the anchor is ship-design#contract-interface-designer, skip the generic domain specialist path and let the contract-interface lane handle it; otherwise proceed to Phase 0.5 (specialist dispatch).specialist_missing) → emit ## Design Output → ### Router HALT block with all 3 options (skip / generalist-marker / file-specialist-first). SendMessage(FO): halt notice with domain name + options. STOP — captain acks one option in entity body, then re-runs design.knowledge_module_missing) → same as M1 path: emit HALT block, SendMessage(FO), STOP.domain: is unset AND affects_ui: true: proceed to UI category-classifier (Category 0/A/B/C/D logic at Phase 0 step 4).shape.md, with legacy spec.md fallback alias) and determine category per classifier table.design-dispatch-manifest:
affects_ui: true → add ui lane with the selected Category.ui lane, resolve adopter file-signal routing with
resolve-skill-routing.sh before dispatch; include skills_needed,
folder_guidance_files, folder_guidance_skills, and
codex_context_boundary in the manifest.domain: set → resolve the registry envelope. If
designer_section_anchor=ship-design#contract-interface-designer, do not
add a separate domain lane; this contract-interface anchor is handled
only by the contract-interface lane below. For all other anchors, add
domain lane with registry required_skills, skill_hints.*,
knowledge_module_path, and designer_section_anchor. Mark high-risk
domain lanes as panel_lane: domain-expert and require read-only findings
that become constraints for plan.contract_decision_required: true or open_contract_decisions[] non-empty → add contract-interface lane. The lane reads each open contract decision, produces a trade-off table, and converts the captain-selected option into ### Captain Decisions plus design_constraints[]. If the captain does not decide, carry it to open_decisions[] so plan blocks.integration.mode: parallel.integration.mode: single-designer.### Hand-off to Plan.Context Read Receipt. Missing
app-folder guidance citation when folder_guidance_files is non-empty, or
missing routed/folder skill such as refine-gotchas when emitted by the
resolver, is BLOCKING feedback to the ui-designer; do not defer this
correction to plan or execute. If folder_guidance_files is empty, do not
block on guidance-file absence.Two routing paths that coexist. Both can fire concurrently when an entity has both UI and domain signals (e.g., new feature with new schema + new UI). Domain work is delegated to a deterministic codebase-aware specialist; visual work is delegated to a standing taste-accumulating teammate.
schema-designer via domain-registry)Reached when Phase 0 step 2 returns exit 0 (domain registered + specialist_missing = false) and the resolved designer_section_anchor is not ship-design#contract-interface-designer. Routing target: schema-designer (or other domain specialist named in designer_section_anchor). Contract-interface anchors skip the generic domain specialist path to avoid a duplicate/contradictory lane beside contract_decision_required:true.
bash "${CLAUDE_PLUGIN_ROOT:-plugins/ship-flow}/lib/registry-resolve.sh" --domain=<domain-name>
designer_section_anchor, knowledge_module_path, required_skills,
and skill_hints.* from the output envelope.references/domain-knowledge/<domain>.md before specialist work (domain-specific constraints + anti-patterns + design checklist).domain-designer to specialist sub-section identified by designer_section_anchor
(e.g., ship-design#schema-designer once 113.3 ships). Include any
required_skills and relevant skill_hints.plan / skill_hints.execute
in the design handoff so plan stage can preserve them in skills_needed.
Specialist sub-section defines its own typed ## Design Output block
(e.g., ## Schema Design Output).
This contract-interface anchor exception does not make empty knowledge modules generally acceptable for unrelated anchors; non-contract-interface
domain specialist rows still follow M1/M2 validation and must provide their
required specialist and knowledge-module contract.## Domain Registry Validation with result: HALT-with-options or a non-ok registry status, but this design-stage validation now returns exit 0, emit ### Registry Validation Resolution in design.md:
prior_result: <status/result from shape>current_result: okresolution: superseded_by_design_stage_validationreason: <knowledge module/specialist now present, or adopter config corrected>
This preserves the stale HALT evidence instead of pretending it was never emitted, and tells plan stage to consume the current design/plan registry result.domain: frontmatter contains multiple names (comma-separated), use first match. v2 multi-domain dispatch is out of 113.1 scope.Schema specialist active as of 113.3: defaults.yaml now points schema to
designer_section_anchor: "ship-design#schema-designer", so schema-domain
pitches proceed to the specialist path instead of the M1 HALT path. Domains
without an anchor still use the M1 HALT-with-options surface.
design-officer via SendMessage)Reached when the entity matches any of the 5-Category classifier rows (UI / IA / aesthetic work). Routing target: design-officer — a standing teammate spawned by FO at boot from _mods/design-officer.md template (opus, session-scoped, taste accumulates across features within a session).
Why a separate path: domain work needs a deterministic specialist with codebase access (schema-designer fits). Visual work needs iterative captain dialogue + cross-feature taste accumulation (design-officer fits). Different cognitive modes, different agents. NOT competing paths — both run if an entity needs both.
Team-mode protocol (default when TeamCreate is available and FO is not in Degraded Mode):
to: design-officer
message: |
Entity {entity_id} ({title}) needs visual design exploration.
- Type: {variants | IA | tokens | review | full system} (derived from 5-Category classifier row)
- Category: {0 | A | B | C | D}
- Constraints: read shape.md `## Design Constraints` if present
- Entity folder: <path>
- Existing design.md: <state> (absent | partial | full prior draft)
Produce variants in <entity>/design-explore/ per
lib/design-methodology/{shotgun|consultation|html-generation}.md as appropriate.
SendMessage back when ready, or surface to captain for direct Shift+Down dialogue.
<entity>/design.md. Worker observes design.md update and resumes structural design work (constraints, lanes, render-fidelity targets, hand-off).### Hand-off to Plan machine-readable contract). design-officer is the upstream visual-exploration source, not the hand-off owner.Bare Mode Degrade (when TeamCreate is unavailable OR FO is in Degraded Mode → design-officer is NOT spawned):
plugins/ship-flow/lib/design-methodology/ files directly: ux-principles.md, plus shotgun.md / consultation.md / html-generation.md as needed per scope.<entity>/design-explore/variant-*.md from its own context, following shotgun.md discipline (3 differentiated concepts, anti-convergence, full specs per variant — no convergent thinking before the comparison step).<entity>/design.md and continues to Phase 4.Tradeoffs in bare mode: LOSE cross-feature taste accumulation (worker fresh per entity); LOSE live Shift+Down dialogue (async text only). KEEP per-entity design quality and hermetic policy. Bare-mode degrade is the design stage's safety net — never block on design-officer absence.
Spawn config source: plugins/ship-flow/_mods/design-officer.md (added by Phase 4 of this overhaul). FO consumes this mod template at boot to spawn the standing teammate.
Anchor: ship-design#schema-designer
This subsection is invoked only after Phase 0.5 resolves domain=schema,
registry-resolve.sh --validate --domain=schema exits 0, and the designer has
loaded plugins/ship-flow/references/domain-knowledge/schema.md. The schema
designer is still part of the ship-design stage skill; do not add a new stage
skill for this specialist.
Emit a typed schema block in design.md:
## Schema Design Output
### Layers touched
- L1 decider:
- L2 fstore:
- L3 view:
### Migration safety
- Additive / destructive:
- Backfill required:
- Event-saga implication:
### RBAC and tenancy
- tenant_id / ownership columns:
- RBAC subject:
### Projection / fstore rebuild
- Rebuild strategy:
- Stale-read tolerance:
### Hand-off constraints for Plan
- Required plan DCs:
- Verify-time intent checks:
Answer each schema-domain question before handing off to plan:
The specialist's ### Hand-off constraints for Plan must name concrete DCs the
plan stage can verify. Do not emit ## Intent Match Findings here; pitch 113.4
owns the verify-stage intent-match verifier. For 113.3, the design stage only
creates typed intent for later comparison.
## Problem.visual_inventory[] — section / claim / line-range for each decision.Skill: storyboard to capture 6-frame narrative of the user journey through this UI surface. Frames represent: (1) user encounter, (2) action, (3) system response, (4) state transition, (5) outcome, (6) follow-up state. Skill spec: deanpeters/Product-Manager-Skills storyboard@pm-skills.actor + action_or_state + expectation. Frame expectations become contract constraints downstream stages must satisfy (verifier checks rendered output against frames; review stage gates BLOCKING any frame the implementation cannot satisfy).storyboard_frames[] — feeds Phase 2 contradiction-detect (frame expectation vs visual_inventory mismatch is a contradiction class on top of pure visual conflicts) AND Phase 8 hand-off-to-plan (render_fidelity_targets extended with frame-by-frame expectations).storyboard plugin unavailable, capture 6 frames inline via numbered bullets in design.md; document as fallback in Design Report.affects_ui=true, so user-flow narrative is in scope by definition. If captain explicitly asserts "pure component refactor, no flow change" → skip with rationale recorded.visual_inventory[] entries for internal conflicts (different sections asserting different values for same property).contradictions[] item with claim_a + claim_b + cite_a + cite_b.design-exploration-spatial.html yielded 6 contradiction pairs (D1-D6). Non-trivial pitches expect ≥2 pairs.Skill: design-flow with contradictions[] as input for the contradiction-resolution Q-loop. Fallback: Skill: superpowers:brainstorming if design-flow unavailable — document in Design Report.**D{N}|Captain decision**: {claim} format at the decision point in design-system.md._debriefs/2026-04-27-01.md Issue 1. Do NOT proceed.plugins/<app>/design/design-system.md with canonical structure:
## 0. Purpose & Status## 1. Color System through ## 6. Motion (inject <!-- section:foundations --> before §1, <!-- /section:foundations --> before §7)## 7. Composition Principles (inject <!-- section:components --> before §7, <!-- /section:components --> before §9 or patterns boundary)## 8+ composition / vocabulary sections (inject <!-- section:patterns --> ... <!-- /section:patterns -->)**D{N}|Captain decision**: {resolution} at the exact decision point in prose.plugins/<app>/design/components/<name>.html.war-room.html (or app-equivalent composite screen) at plugins/<app>/design/.design-system.md + key HTML artifacts (tokens visual gallery + war-room mockup) to captain.Write <entity-folder>/design.md per entity-body-schema.yaml → stages.design:
## Design Output / ### Visible UI Design Output — for every affects_ui: true UI lane, include captain-visible layout, zones, states, affordance, and interaction decisions. Category A-D may scale the artifact bundle down, but may not produce an invisible or purely machine-readable handoff.## Design Output / ### Captain Decisions — list all D{N}|Captain decision entries with file:line contradiction cite. (Captain-readable narrative; rationale source for plan/verify cross-references via D{N}.)## Design Output / ### Artifact Bundle Manifest — table (Path / Type / Purpose) of all emitted files.## Design Report — status / stage_cost / iterations / contradictions_resolved / captain_decisions / reviewer_verdict.Require a ### Metrics subsection in ## Design Report.
Use grep-friendly key: value lines:
status: passed | gaps-noted | blocked | partial | trivial-passduration_minutes: wall-clock minutes for designiteration_count: Q-loop + review iterationscaptain_decisions_count: number of accepted captain decisionsreviewer_verdict: PROCEED | VETO | PROMPT_CAPTAINSingle-source-of-truth rule (G8 dedup, 2026-04-29): ### Hand-off to Plan (Phase 9 hand-off block) is the only structured contract plan stage reads. Do NOT duplicate design_constraints / render_fidelity_targets here in ## Design Output. Phase 8 holds captain-readable narrative + audit trail (Decisions, Manifest, Report); Phase 9 holds machine-readable contract (constraints, render-fidelity targets, artifact paths, open decisions). Plan Step 1.6 reads Phase 9 hand-off; cross-references back to Phase 8 Captain Decisions via D{N} markers when rationale needed.
Evaluate the Design Readiness Review triggers above. When triggered, dispatch
the smallest useful low-model expert team from the registry/routing output,
collect findings, and record a ## Design Readiness Review section in
design.md:
risk_triggers:
- multi-domain|migration|api-contract|fmodel|high-risk-ui|recent-debrief|captain-explicit
reviewers: ui, schema
derived_from:
- affects_ui:true
- domain:schema
- whole_page_visual_targets[]
verdict: PASS|WARN|BLOCK
findings:
- reviewer: schema
severity: PASS|WARN|BLOCK
route_to: design|plan
evidence: "<file:line, design artifact, or contract>"
This is a mod, not a standard stage: it never adds a new workflow status and it must be skipped for trivial/docs-only/single-lane work unless explicitly requested. It exists to stop bad design contracts before plan decomposes them.
Before marking design complete, run:
bash "${CLAUDE_PLUGIN_ROOT:-plugins/ship-flow}/lib/check-design-readiness-review.sh" <entity-folder>/design.md
The checker derives required reviewers from the design artifact and blocks when
a triggered review is missing, when a required reviewer is absent, or when the
verdict is BLOCK. When the checker prints status=warn, the design may
proceed, but the warning must remain visible in Design Report and downstream
plan notes.
Dispatch cross-review as a separate agent via Skill: design-review (#106 T5.2). This is an adversarial review — a fresh agent with no context from the design session evaluates the artifacts independently.
Fallback chain (Principle 6 Rule A): if design-review unavailable → dispatch fresh sonnet subagent with structured review prompt → if subagent also stalls → executer teammate inline review.
7-factor rubric adapted for design stage — rubric varies by lane type (per INVARIANTS Principle 6 Rule C #106 T1.3 + T6.4; lane-type from design-dispatch-manifest):
UI-lane rubric (applies when UI-lane == true per Lane determination predicate):
| Factor | Assert |
|---|---|
| Feasibility | captain Q-loop delivered ≥6 decisions for ≥6 contradictions? |
| Executable scope | design-system.md + components + composite mockup all emitted? |
| Quality | canonical section anchors + decision tags present? |
| DC adequacy | every captain decision has D{N}|Captain decision marker at decision point? |
| Canonical sync | design.md (entity) cites design-system.md (canonical) cite-pair? |
| Reverse-audit previous stage | does the design expose a gap in the preceding sharp/shape stage's ### Hand-off to Design block? Specifically: are all open_design_questions resolved in captain_decisions? Does render_fidelity_targets include token alignment checks for any Tailwind v4 theme_indirection detected? |
| Render Fidelity + captain-ack audit trail | (T6.4) does render_fidelity_targets in Hand-off to Plan include ≥1 token alignment check per D{N} decision? Are HTML specimens visual-only (not interactive stubs)? Is tokens.css byte-stable (no renamed properties)? |
non-UI-lane rubric (applies when UI-lane == false per Lane determination predicate; domain / contract-interface lanes):
| Factor | Assert |
|---|---|
| Feasibility | captain Q-loop delivered decisions for all open_contract_decisions[] entries? |
| Executable scope | all captain decisions captured as design_constraints[] entries? |
| Quality | canonical section anchors + decision tags present? |
| DC adequacy | every captain decision has D{N}|Captain decision marker at decision point? |
| Canonical sync | design.md (entity) cross-references source INVARIANTS / ARCHITECTURE sections? |
| Reverse-audit previous stage | does the design expose a gap in the preceding sharp/shape stage's ### Hand-off to Design block? Are all open_contract_decisions resolved in captain_decisions? |
| Constraint Coverage | every captain decision yields ≥1 design_constraint[] entry; every design_constraint[] carries rationale_decision: D{N} backref; open_decisions[] is empty or escalated (D4, entity 116). |
Pattern (reusable): future non-UI lanes (saga, API contract, fmodel event schema, etc.) follow this same structure — define a named 7th-factor replacement per lane type and add it to the Phase 9 verdict switch. New lane = new named factor + grep DC anchor. Constraint Coverage for domain-contract lanes is the reference implementation.
Verdict-emission predicate (applies to both lane types):
open_decisions[] is non-empty → emit PROMPT_CAPTAIN (overrides any otherwise-PROCEED finding). Coaching note (D3 + Principle 4 boolean-gate): unresolved decisions cannot be auto-resolved by FO; halt entity and surface to captain.Reverse-audit prompt template (T3.2 — paste verbatim into reviewer dispatch):
Reverse-audit: Read the entity's `### Hand-off to Design` block from the entity body.
(a) List every `open_design_questions` entry — is each resolved by a `D{N}|Captain decision` in design-system.md? (BLOCKING if any unresolved)
(b) Does `render_fidelity_targets` include at least one token alignment check (e.g., CSS var usage, not hardcoded hex) for any Tailwind v4 `theme_indirection` context? (WARNING if theme_indirection=tailwind-v4 but no token check present)
(c) Are all contradiction pairs from Phase 2 represented as `D{N}` decisions? (BLOCKING if contradiction count > captain_decisions count)
Coaching note: unresolved design questions here cascade into plan ambiguity and execute drift — enforces shape→design hand-off integrity.
Verdict: PROCEED / VETO (max 2 loops) / PROMPT_CAPTAIN. Each verdict MUST include a one-sentence coaching note per INVARIANTS Principle 6 Rule C ABC clause.
Register the completed design artifact without impersonating the next First Officer stage-entry receipt.
For a helper-compatible folder entity, index.md MUST contain the canonical
stage_outputs: frontmatter authority tail. Historical body tables are ignored. Run:
INDEX_MD="<entity-folder>/index.md"
H="$(if command -v sha256sum >/dev/null 2>&1; then sha256sum "$INDEX_MD" | awk '{print $1}'; else shasum -a 256 "$INDEX_MD" | awk '{print $1}'; fi)"
bash "${CLAUDE_PLUGIN_ROOT:-plugins/ship-flow}/lib/advance-stage.sh" \
--entity="$INDEX_MD" \
--new-status=design \
--stage-name=design \
--stage-file=design.md \
--if-hash="$H" \
--lease-file="$SHIP_FLOW_COMPLETION_LEASE_FILE" --lease-token="$SHIP_FLOW_COMPLETION_LEASE_TOKEN" --worker-id="$SHIP_FLOW_COMPLETION_WORKER_ID" \
--commit-as="design(<id>): register completion"
On exit 6 (stale hash): write ## Design Report status: blocked, reason: index.md stale hash; parallel session contaminated and return.
Do not migrate or auto-convert an incompatible ledger in this stage. Legacy flat entities without canonical stage_outputs authority MUST NOT invoke advance-stage.sh; historical body tables are non-authoritative and remain opaque.
This registers design completion; it does not enter plan. Return to the First Officer for a separate plan stage-entry transition.
Return the receipt verbatim. FO reclaims the lease: published runs path reconcile;
already-registered runs clean/no-lag. Only reconciled|ready may precede Contract 1.
affects_ui: true with design-skipped: true is invalid unless the entity handoff carries captain-approved-design-bypass: true with a one-line rationale.design.md (Principles)" / "design/ directory" / "ship-design SKILL".superpowers:brainstorming Q-loop → Principle 6 Rule B violation; delete re-teach.⚠️ INCOMPLETE markers + Design Report status: partial.Read the incoming ### Hand-off to Design block from the entity body (written by ship-shape Phase 8). Verify all open_design_questions and open_contract_decisions are resolved via captain_decisions before emitting. If a selector grammar/API vocabulary/protocol/schema choice remains undecided, put it in open_decisions[] and BLOCK plan rather than letting planner choose.
Emit ### Hand-off to Plan (structured fields per entity-body-schema.yaml → stages.design.hand_off_to_plan):
design_constraints[] — each item: {type, assertion, rationale_decision: D{N}, source_artifact} — type enum mandatory. UI design uses token-binding | layout | interaction; domain specialist design uses contract | schema-contract | filter-contract | api-contract | data-contract | domain-contract. rationale_decision: D{N} MUST cross-reference a **D{N}|Captain decision** in Phase 8 Captain Decisions (validated by validate-d-references.sh).ui_quality_contract — for UI/design-bearing work, emit the compact UI quality contract from plugins/ship-flow/references/ui-quality-contract.md. Include the groups copy, visual_hierarchy, color, typography, spacing, interaction_states, and source_safety. This complements design_constraints[], render_fidelity_targets[], and whole_page_visual_targets[]; it does not add a separate visual capture harness or external runtime dependency.visible_surface_map[] — for UI/design-bearing work, emit compact rows with required fields id, surface_type, route, selector_hint, visible_when, intent_summary, coverage, rationale_decision, plus mapped_by when coverage: mapped and na_rationale when coverage: explicit_na.
Coverage is all-or-block: every audit-eligible visible region, control, state indicator, and semantic badge must be mapped or explicit_na; any unmapped audit-eligible live surface becomes a BLOCKING verify finding. explicit_na is allowed only with a captain-decision backref and rationale.
If render_fidelity_targets[] or whole_page_visual_targets[] are emitted, visible_surface_map[] must not be omitted; this is the authoring guard against closed-list target omissions.open_decisions[] — any design decisions still pending captain input (ideally empty; non-empty → plan Step 1.6 BLOCKER).artifact_paths[] — paths to committed design artifacts (tokens.css, specimens, composite mockup).render_fidelity_targets[] — each item: {selector, css_property, expected_value, rationale_decision: D{N}} — feeds ship-verify Step 3.6 ui-verify YAML; rationale_decision: D{N} MUST cross-reference Phase 8.whole_page_visual_targets[] — each item: {route, reference_artifact, capture, threshold, rationale_decision: D{N}} — feeds plan visual-parity DCs and ship-verify whole-page screenshot comparison. Use this for whole-screen composition, spacing hierarchy, and whether the implemented page still resembles the design reference after fragments pass.For affects_ui: true, the handoff MUST include non-empty design_constraints[]
and render_fidelity_targets[], a ui_quality_contract, plus
whole_page_visual_targets[] for the primary affected route, plus a captain-visible
### Visible UI Design Output section in design.md. Category D may use a
single composite mockup or prose-plus-selector target instead of a full
design/ artifact bundle, but it still emits a visible UI design decision and
machine-readable verification target. For non-UI domain-only design,
whole_page_visual_targets[] may be omitted.
Design trivial-pass path (G14; INVARIANTS Principle 11 — design always runs): for a pure-mechanical entity (!affects_ui && !domain && !design_required && !contract_decision_required), design is NOT skipped — it runs this stage's Phase 0 trivial-pass fast-path. The entity body MUST contain ### Hand-off to Plan with single field design-skipped: true, emitted by this design stage's Phase 0 trivial-pass (Principle 11.3) when affects_ui: false, domain: is unset, design_required: false, contract_decision_required: false, and open_contract_decisions[] is empty. (Shape emits ### Hand-off to Design; design emits the Plan hand-off.) Plan Step 1.6 reads this marker to skip design-DC import explicitly (vs absence of the block, which is ambiguous).
If affects_ui: true, domain: is set, design_required: true, or
contract_decision_required: true, design-skipped: true is invalid by
default. The only valid bypass is an explicit captain marker:
design-skipped: true
captain-approved-design-bypass: true
bypass_rationale: "..."
Without that marker, return BLOCKER to the first officer/planner with reason
ui design handoff skipped; do not let plan infer "no UI surface."
Why D{N} backref enforced per item: plan Step 1.6 imports each constraint as a DC and carries rationale_decision: D{N}; without source-side enforcement, design can emit constraints that have no captain-decision anchor, breaking audit trail. validate-d-references.sh (lib) catches missing/dangling D{N} refs at design Phase 9 emit-time.
design-flow — Layer A delegate for contradiction-resolution Q-loop (Phase 3, #106 T5.2); fallback: superpowers:brainstormingdesign-review — adversarial cross-review agent (Phase 9, #106 T5.2); fallback: fresh sonnet subagentsuperpowers:brainstorming — Phase 3 fallback when design-flow unavailablesuperpowers:writing-skills — for v2 skill expansion (A/B/C/D categories)plugins/ship-flow/references/entity-body-schema.yaml → stages.design — entity body contract (added pitch-104 T5)plugins/ship-flow/references/flow-map-schema.yaml → maps.plugins/spacebridge/design/design-system.md — map-layer registration (added pitch-104 T2)docs/ship-flow/_debriefs/2026-04-27-01.md — D1-D6 captain decision origin; Issues 1 (fabricated PASS) + Observation (HTML > markdown)plugins/ship-flow/lib/__tests__/test-design-dogfood.sh — L2 strictness dogfood harness (added pitch-104 T6); --self-test mode proves assertion engine canonical-vs-canonical (mechanical CI). Real designer-agent dogfood = verify-stage manual invocation on plugins/spacebridge/design-exploration-spatial.html.plugins/ship-flow/INVARIANTS.md:110 — Principle 6 Rule A (named teammate), Rule B (Layer A), Rule C (cross-review gate)Use when writing a ship-flow plan for a shaped entity, especially implementation tasks, TDD needs, runtime commands, or scope anchoring. Layer A delegation: superpowers:writing-plans owns plan authoring; ship-flow:test-driven-development owns fallback TDD contracts.
Use when shaping vague, complex, or ambiguous ship-flow requests into a Shape Up pitch, including `/shape`, discussion, or skill-authoring work.
Use when ship-flow needs execute-stage implementation from an approved plan, including wave tasks, blocked work, or PR feedback re-entry. Layer A delegation: superpowers:subagent-driven-development owns wave dispatch discipline.
Use when `/ship` should run ship-flow for an entity id or good-enough raw requirement; vague inputs need shape clarification.
Use when verify passed and ship-flow needs review, PR readiness, PR body drafting, or canonical docs sync. Layer A delegation: pr-review-toolkit:review-pr owns PR review persona philosophy.
Use when verifying execute output before ship, including `/verify`, `/ship`, live worktree checks, UI DCs, e2e, reviewer panel, or NIT fixes. Layer A delegation: e2e-pipeline and ship-flow:ui-verify own UI DC verification; reviewer personas own haiku review.