Vp

Visual Prototype Command

Shared task context

Resolve the repository and task with ../setup/references/task-context.md. Reuse the linked discovery/plan and task entrypoint; create the prototype only when visual validation is useful or explicitly requested. Link the playground and approval sidecar from the task record.

Purpose

Create an interactive HTML playground so the user can see and approve a feature's design before committing to technical decomposition. This bridges the gap between discovery (/nf) and implementation planning (/ct).

Works for both UI-facing tasks (mobile/web screen mockups) and backend tasks (architecture diagrams with Mermaid.js).

Routing — wrong skill?

• Feature discovery/interview → /nf
• Technical decomposition → /ct
• Implementation/coding → /si
• Brainstorming ideas → /brainstorm
• Quick one-off diagram → /generate-web-diagram
• Component lookup → /component-library

GATE 0: Task Discovery

1. Locate task directory: use the shared resolver. An explicit path or linked task is authoritative; if several scoped candidates remain, ask the user rather than selecting by recency.

2. Check for discovery document:

   • Look for discovery-[feature-name].md in task directory

• If found: read it, extract feature overview, how it works, scope boundaries, key requirements, and constraints. If the discovery doc uses an older format, map equivalent sections such as requirements, UI/UX specs, and technical considerations. Proceed to GATE 1.
• If NOT found: offer the user a choice via AskUserQuestion:
  • Run /nf first (recommended) — full discovery interview for complex features
  • Quick prototype — describe the feature briefly, create an exploratory mockup

3. Quick prototype mode (if user chose it):
   • Ask 3-5 targeted questions via AskUserQuestion:
     • What is the feature in one sentence?
     • What are the key screens or components? (UI) / What are the main services and entities? (Backend)
     • What's the primary user flow or data flow?
     • Any specific constraints or must-haves?
   • Label the output as an "Exploratory Prototype" (not yet validated by discovery)
   • Skip directly to GATE 2 after collecting answers

GATE 1: Task Type Detection

Read the discovery document holistically. The question is not "which keywords appear more" — it's "what does the user need to validate visually?"

UI_FACING — the user needs to see how the feature looks and feels:

• Screens, layouts, interactions, navigation flows
• The discovery doc has a substantive "How It Works" section or equivalent UI/UX flow description
• The value of the prototype is seeing the visual design

BACKEND — the user needs to see how the feature is structured:

• Services, data flow, API contracts, entity relationships
• The discovery doc focuses on technical architecture and DDD layers
• The value of the prototype is understanding the system design

MIXED — both UI and architecture are significant:

• Offer to create both, or ask which the user wants to validate first

Confirm the detected type with the user via AskUserQuestion before proceeding.

If UI_FACING and no project design system is documented, add a second AskUserQuestion offering 3–4 concrete visual directions (one-line each) so the user anchors the aesthetic instead of inheriting model defaults.

GATE 2: Playground Generation

Invoke the playground skill with the appropriate template.

• UI-facing tasks: read references/ui-playground-template.md for the full prompt template
• Backend tasks: read references/backend-playground-template.md for the full prompt template

For UI tasks, pass project-specific visual context to the playground when available:

• Design system or component library name
• Theme tokens, CSS variables, Tailwind config, or style guide paths
• Existing screens or components that the prototype should visually align with
• Brand cues or visual tone

If no project-specific design context exists, first propose 3–4 distinct visual directions as one-line rationales (e.g. "editorial-serif", "utility-mono", "soft-neumorphic", "dense-enterprise"). Ask the user to pick one via AskUserQuestion before generating the playground. Avoid defaulting to a cream/serif/warm-accent house style unless the user explicitly picks it.

Required states — apply to every screen and every flow in the prototype, not just the first:

• Error states: what does the user see when validation fails, a request errors, or input is invalid?
• Constraint flows: what options are available, disabled, or hidden based on context? Show pre-submission guidance, not just post-submission errors.
• Empty states: what appears when there's no data yet? Include actionable guidance (not just "nothing here").
• Success feedback: after a create/update/delete action, what confirms it worked?

If the feature involves entity creation, the prototype must show where the entity appears after creation — on the current screen and on any cross-surface management page.

Fallback: if the playground skill is not available, generate the HTML file directly:

• Self-contained single file (inline CSS/JS, no external deps)
• Dark theme, single state object pattern, live preview updates
• Include a "Copy Prompt" button for implementation notes

After playground is created:

open [TASK_DIRECTORY]/playground-[feature-name].html

Treat the opened playground as a review artifact, not approval. Continue to GATE 3 and obtain the user's explicit decision before describing the design as approved or handing it to /ct.

GATE 3: User Approval

Iterative approval loop — allows refinement without restarting.

1. Present to user: "Playground created and opened in browser. Please explore and provide your decision."

2. Use AskUserQuestion with options:

   • Approve — design matches the intended feel; proceed to /ct
   • Request Changes — close, but needs specific tweaks (stay in /vp)
   • Reject — wrong direction entirely; discovery needs to be revisited

3. Handle each decision:

   APPROVED: capture any final notes, proceed to GATE 4.

   CHANGES_REQUESTED:

   • Capture specific change requests
   • Re-invoke playground skill with modifications
   • Regenerate playground file
   • Return to step 1 (loop until approved or rejected)

   REJECTED:

   • Capture rejection reason
   • Write rejection to vp-approval.md (see GATE 4 format)
   • Advise: "Discovery needs refinement. Consider running /nf again with additional context."
   • STOP

GATE 4: Documentation Update

Write approval status to a separate sidecar file (keeps the discovery doc clean):

File: [TASK_DIR]/vp-approval.md

# Visual Prototype Approval

**Status**: APPROVED | CHANGES_REQUESTED | REJECTED
**Date**: [TODAY]
**Prototype**: `playground-[feature-name].html`
**Iteration**: [number of revision cycles]

## User Feedback
[Captured feedback from approval loop]

## Key Decisions Confirmed
- [Decisions validated during prototype review]

## Notes for Technical Decomposition
[Clarifications discovered during prototype review]

Output

Files created in the resolved task directory:

• playground-[feature-name].html (new or revised)
• vp-approval.md (new or revised)

Next step: run /ct to create technical decomposition based on the approved visual prototype.

Reference Files

Read these as needed — they contain prompt templates and detailed guidance:

Handoff — Next Steps

After visual prototype is approved, present to the user:

Visual prototype approved for [feature-name]:
- Playground: [resolved task]/playground-[feature-name].html
- Approval: [resolved task]/vp-approval.md

Next steps:
→ Create tech plan: /ct [feature-name]

Completion

The prototype workflow is complete only after the playground exists, the user has selected Approve, Request Changes, or Reject, and the corresponding loop or vp-approval.md sidecar has been written. Update the resolved task record with the artifact link, revision decision and next action. Approval authorizes the documented prototype handoff; it does not authorize implementation unless that action was also requested.