Spectre UX
Designspectre-uxSpectre UX is an Agent Skill for design published in the Codename-Inc/spectre repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
👻 | Define user flows, components, and UX behavior — generates the UX spec for a feature - primary agent
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Codename-Inc/spectre/blob/HEAD/plugins/spectre/skills/spectre-ux/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/spectre-ux, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
ux
Input Handling
Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded $ARGUMENTS value.
ux: Define Exactly How the Feature Works
Transform product requirements into a definitive behavioral specification. Two stages: align on user flows, then generate detailed spec. Output: ux.md ready for implementation.
$ARGUMENTS
STAGE 1: Flow Discovery & Alignment
Goal: Align on HOW the feature works before specifying details.
Step 1 — Understand the Feature
- Read scope and requirements in this precedence (read whichever exist FULLY, no offset/limit):
docs/tasks/{branch}/concepts/scope.md— the canonical scope doc (preferred)docs/tasks/{branch}/specs/prd.md— if a PRD was generated separatelydocs/tasks/{branch}/task_summary.md— if present- If none exist → ask the user for scope context (or recommend
/spectre:scopefirst) before proceeding.
- Research patterns: Dispatch
@spectre:patternsto find existing screens/components similar to what we're building. Note conventions, reusable elements, and any design tokens. - Identify user segments: List the user segments this feature serves — first-time vs returning, anonymous vs signed-in, free vs paid, role-based variants. UX often diverges across segments and missing this is a common cause of rework.
- Identify journeys: List user goals, entry points, and completion states.
Step 2 — Present User Flows
Write each flow as a narrative walkthrough.
Per flow include: Goal, Entry point, Journey steps (User sees → User does → System responds), Decision points with branches, Success state, Questions where ambiguity exists.
Per user segment: Call out where flows diverge (e.g., "First-time users see X tour; returning users skip directly to Y").
After writing all flows, propose a specific take rather than asking open-ended:
User Flows — Proposed
I've mapped {N} flows across {M} user segments: {list with one-line summaries}
Key segmentation calls: [where flows diverge by user state and why]
Push back on anything wrong, missing, or over-/under-segmented. Reply with feedback or "Flows approved" to proceed.
Wait for approval. If feedback → revise and re-present. If approved → Stage 2.
STAGE 2: Detailed Specification
Gate: Only proceed after explicit flow approval.
Step 3 — Clarify Remaining Details
Review approved flows for gaps: component behaviors, edge cases, state definitions, segment variants.
If significant gaps, ask 3–5 targeted questions (empty states, error handling, loading, limits, segment differences). Save to clarifications/ux_clarifications_{timestamp}.md, prompt user to read, incorporate answers.
Step 4 — Write the Specification
Generate complete spec with these sections:
Required Sections
- Overview — What this feature is, problem it solves, primary user goal (1 paragraph)
- User Segments — Each segment served, what's different about their UX (e.g., first-time onboarding, role-based permissions, free vs paid limits, anon vs signed-in)
- Screens — Every screen: name, purpose (1 line), navigation relationships
- Flows — Formalized from Stage 1 with alternate paths (validation fail, cancel, network error). Include per-segment branches where they diverge.
- Layouts — Per screen: header/main/footer structure + responsive behavior (desktop >1024, tablet 768–1024, mobile <768)
- Components — Each interactive element: purpose, location, applicable states (see State Vocabulary below)
- Interactions — Table format: Element | Action | Result (exhaustive)
- States — Table format: State | Trigger | Appearance | Available Actions
- Content — Exact copy: page titles, buttons, empty states, error messages, confirmation dialogs
- Edge Cases — Limits/boundaries, null/long data handling, permissions, offline/network failures, segment-specific edge cases
- Accessibility — Tab order, keyboard actions (Enter/Space/Escape), screen reader announcements, focus management
State Vocabulary
Use these state categories where applicable. Not every component needs every state — pick what's relevant for the feature.
- Visual states (per interactive element): default, hover, focus, active/pressed, disabled
- Data states (per data view): empty, loading, partial-loaded, loaded, error, stale/refreshing
- Form states: pristine, dirty, touched, submitting, submitted-success, submitted-error, validation-error per field
- Selection states: none, single, multi, partial-selection, all-selected
- Sync states (collaborative or async UI): optimistic, pending, conflict, resolved
- Network states (where relevant): online, offline, reconnecting
Save to docs/tasks/{branch}/ux.md
Prompt:
UX Specification Complete
Written to
{path}. Please review: Any behaviors wrong or missing? Edge cases not covered? Segment differences captured?Want a prototype to validate visually before approving?
/spectre:prototypewill render this spec (high-fi, no synthesis) and flag assumptions where I had to fill in details — catches issues prose review misses. Replyprototypeto run it now.Otherwise, reply with feedback, or "Approved" to finalize.
Wait for approval, feedback, or prototype request. If user replies prototype, invoke /spectre:prototype (the post-ux mode auto-detects the complete ux.md). Once prototype completes and any spec updates from filled assumptions are applied, return here for final approval.
Step 5 — Handoff
Confirm completion with summary: screens specified, segments addressed, flows documented, components with states, edge cases and accessibility covered.
Read .spectre/next_steps_guide.md and render Next Steps footer:
Next Steps | Phase: Scope | Status: UX Complete
Recommendation: {contextual next action — if no prototype was generated, suggest /spectre:prototype to validate the spec visually before /plan}
Options: /spectre:prototype (validate spec visually), /spectre:create_plan, /spectre:create_tasks, /spectre:tdd