---
name: pstack-prototype
preamble-tier: 3
version: 0.2.0
description: |
  High-fidelity prototype workflow. Monorepo: lands in apps/lab/<name>/.
  Output: working prototype + DESIGN.md + preview deploy. Uses the project's
  existing design system; calls gstack's audit skills (/qa-only, /design-review)
  for verification but never gstack's design-generation skills (which would
  impose foreign visual patterns). Asks about graduating to component+storybook.
  Use when asked to "prototype", "spike a UI", "/pstack-prototype", or
  "explore an idea".
triggers:
  - /pstack-prototype
  - prototype this
  - high-fidelity prototype
  - spike a UI
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Skill
---

# pstack-prototype

Build the smallest thing that proves an idea, with design rationale captured.

## Skills orchestrated

| Skill | When |
|---|---|
| `superpowers:brainstorming` | Step 2 — frame the hypothesis and scope |
| gstack `/qa-only` | Step 5 — verify the prototype actually works (report-only; we fix manually since prototypes are messy by design) |
| gstack `/design-review` | Step 5 — visual polish audit against the project's design system |

## Design-system rule

**Use the project's existing design system. Do not invent new visual choices.**
Look for and reuse:
- A shared component library (e.g., a `packages/ui` or `@org/components` package)
- Design tokens / variables (e.g., `packages/design-system`, `tailwind.config`, theme files)
- An existing `DESIGN.md` in the repo root or `docs/`

If none of those exist, ask the user before introducing anything new. A
prototype is not the right place to bootstrap a design system — that's
gstack's `/design-consultation` for greenfield projects, run separately.

**Skills explicitly NOT called from here:**
- `/design-shotgun` — generates AI design variants; would use AI-chosen tokens, not yours
- `/design-consultation` — creates a NEW design system; conflicts with existing one
- `/design-html` — renders Pretext-native patterns; foreign to your component library

These tools impose patterns. Pstack-prototype reuses yours.

## Steps

### 1. Detect repo type

```bash
test -f turbo.json -o -f pnpm-workspace.yaml -o -f lerna.json && echo monorepo || echo single
```

- **Monorepo:** prototype lands in `apps/lab/<name>/` (existing pattern).
- **Single-app:** prototype lands in `prototypes/<name>/`. NOTE: this pattern is roadmap'd in IDEAS.md — flag if rough.

### 2. Brainstorm scope

Invoke `superpowers:brainstorming` to clarify:
- What hypothesis are we testing?
- What's the smallest visible thing that would prove (or disprove) it?
- What's explicitly out of scope?

### 3. Build

- Skip TDD. Skip review ceremony. Skip ADRs.
- Get to a working visible thing as fast as possible.
- **Use the project's existing component library / design system** (see "Design-system rule" above). Import existing components, reuse design tokens, follow established patterns.

### 4. Design rationale

Create `apps/lab/<name>/DESIGN.md` (or `prototypes/<name>/DESIGN.md`) from
`${CLAUDE_SKILL_DIR}/../../templates/design.md`. Capture:
- What we tested
- Visual / interaction notes (screenshots welcome)
- Technical decisions and why
- What worked / didn't work

### 5. Verify (functional + visual)

Once the prototype runs in a browser:

**Functional check** — invoke gstack `/qa-only` to walk through the prototype
and report what breaks. Report-only because prototypes are intentionally
messy; we don't want auto-fixes that drift from the original hypothesis.
Surface the report to the user; they decide which findings are blockers vs.
acceptable scrappiness.

**Visual check** — invoke gstack `/design-review` to audit the prototype
against the project's design system. This skill observes, doesn't impose —
it catches deviations (spacing inconsistencies, off-system colors, type
hierarchy issues) but doesn't introduce new patterns.

Skip both if the prototype isn't running locally yet (e.g., backend-only
experiment without a UI).

### 6. Deploy preview

For monorepo with Vercel: ensure the lab app is wired into the preview deploy.
Provide deploy URL or branch URL to the user.

### 7. Graduation prompt

Ask:

> "Prototype validated? Three options:
>   1. Graduate to a real feature → I'll run `/pstack-plan` with this prototype as starting context.
>   2. Extract as a component (with Storybook stories) → component goes into shared package.
>   3. Archive — we learned but won't ship this. Capture key learnings in `docs/research/`."

If 1: invoke `pstack-plan` with the prototype's DESIGN.md as input.
If 2: scaffold component + storybook story files; fill from prototype code.
If 3: invoke `pstack-research` to capture the learnings.

## Do not

- Do not commit during the prototype phase — let it stay messy until graduation decided.
- Do not file a GitHub issue for the prototype itself; only when it graduates.
- Do not invent visual choices. Reuse the project's design system.
- Do not call gstack's design-generation skills (`/design-shotgun`, `/design-consultation`, `/design-html`) — they impose patterns rather than observing yours. Only call the audit-side ones (`/design-review`, `/plan-design-review`).