@codename_inc/spectre 4.0.0 → 5.1.0

package/plugins/spectre-codex/skills/ux/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: "ux"
+description: "👻 | Define user flows, components, and UX behavior — generates the UX spec for a feature - primary agent"
+user-invocable: true
+---
+
+# 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> $ARGUMENTS </ARGUMENTS>
+
+---
+
+# STAGE 1: Flow Discovery & Alignment
+
+**Goal**: Align on HOW the feature works before specifying details.
+
+## Step 1 — Understand the Feature
+
+1. **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 separately
+   - `docs/tasks/{branch}/task_summary.md` — if present
+   - **If none exist** → ask the user for scope context (or recommend `scope` first) before proceeding.
+2. **Research patterns**: Dispatch `@patterns` to find existing screens/components similar to what we're building. Note conventions, reusable elements, and any design tokens.
+3. **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.
+4. **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
+
+1. **Overview** — What this feature is, problem it solves, primary user goal (1 paragraph)
+2. **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)
+3. **Screens** — Every screen: name, purpose (1 line), navigation relationships
+4. **Flows** — Formalized from Stage 1 with alternate paths (validation fail, cancel, network error). Include per-segment branches where they diverge.
+5. **Layouts** — Per screen: header/main/footer structure + responsive behavior (desktop >1024, tablet 768–1024, mobile <768)
+6. **Components** — Each interactive element: purpose, location, applicable states (see State Vocabulary below)
+7. **Interactions** — Table format: Element | Action | Result (exhaustive)
+8. **States** — Table format: State | Trigger | Appearance | Available Actions
+9. **Content** — Exact copy: page titles, buttons, empty states, error messages, confirmation dialogs
+10. **Edge Cases** — Limits/boundaries, null/long data handling, permissions, offline/network failures, segment-specific edge cases
+11. **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?** `prototype` will render this spec (high-fi, no synthesis) and flag assumptions where I had to fill in details — catches issues prose review misses. Reply `prototype` to run it now.
+>
+> Otherwise, reply with feedback, or **"Approved"** to finalize.
+
+**Wait for approval, feedback, or prototype request.** If user replies `prototype`, invoke `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 prototype to validate the spec visually before /plan}
+Options: prototype (validate spec visually), create_plan, create_tasks, tdd
+```

package/plugins/spectre/skills/ux_spec/SKILL.md

@@ -1,100 +0,0 @@
----
-name: ux_spec
-description: Define the User Flows and generate a UX Spec - primary agent
-user-invocable: true
----
-
-# ux_spec
-
-## Input Handling
-
-Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
-
-# ux_spec: 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> $ARGUMENTS </ARGUMENTS>
-
----
-
-# STAGE 1: Flow Discovery & Alignment
-
-**Goal**: Align on HOW the feature works before specifying details.
-
-## Step 1 — Understand the Feature
-
-1. **Read requirements**: `docs/tasks/{branch}/task_summary.md` and `docs/tasks/{branch}/specs/prd.md`
-2. **Research patterns**: Find existing screens/components similar to what we're building, note conventions
-3. **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
-
-After writing all flows, prompt:
-
-> **User Flows for Review**
->
-> I've mapped {N} flows: {list with one-line summaries}
->
-> Please review: Are these the right flows? Any missing? Do journeys feel right? Answer flagged questions.
->
-> 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.
-
-If significant gaps, ask 3-5 targeted questions (empty states, error handling, loading, limits). 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
-
-1. **Overview** — What this feature is, problem it solves, primary user goal (1 paragraph)
-2. **Screens** — Every screen: name, purpose (1 line), navigation relationships
-3. **Flows** — Formalized from Stage 1 with alternate paths (validation fail, cancel, network error)
-4. **Layouts** — Per screen: header/main/footer structure + responsive behavior (desktop >1024, tablet 768-1024, mobile <768)
-5. **Components** — Each interactive element: purpose, location, states (default, hover, active, disabled, loading, error)
-6. **Interactions** — Table format: Element | Action | Result (exhaustive)
-7. **States** — Table format: State | Trigger | Appearance | Available Actions (empty, loading, loaded, error)
-8. **Content** — Exact copy: page titles, buttons, empty states, error messages, confirmation dialogs
-9. **Edge Cases** — Limits/boundaries, null/long data handling, permissions, offline/network failures
-10. **Accessibility** — Tab order, keyboard actions (Enter/Space/Escape), screen reader announcements, focus management
-
-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?
->
-> Reply with feedback, or **"Approved"** to finalize.
-
-**Wait for approval.**
-
-## Step 5 — Handoff
-
-Confirm completion with summary: screens specified, 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}
-Options: /create_plan, /create_tasks, /tdd
-```

package/plugins/spectre-codex/skills/ux_spec/SKILL.md

@@ -1,100 +0,0 @@
----
-name: "ux_spec"
-description: "Define the User Flows and generate a UX Spec - primary agent"
-user-invocable: true
----
-
-# ux_spec
-
-## Input Handling
-
-Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
-
-# ux_spec: 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> $ARGUMENTS </ARGUMENTS>
-
----
-
-# STAGE 1: Flow Discovery & Alignment
-
-**Goal**: Align on HOW the feature works before specifying details.
-
-## Step 1 — Understand the Feature
-
-1. **Read requirements**: `docs/tasks/{branch}/task_summary.md` and `docs/tasks/{branch}/specs/prd.md`
-2. **Research patterns**: Find existing screens/components similar to what we're building, note conventions
-3. **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
-
-After writing all flows, prompt:
-
-> **User Flows for Review**
->
-> I've mapped {N} flows: {list with one-line summaries}
->
-> Please review: Are these the right flows? Any missing? Do journeys feel right? Answer flagged questions.
->
-> 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.
-
-If significant gaps, ask 3-5 targeted questions (empty states, error handling, loading, limits). 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
-
-1. **Overview** — What this feature is, problem it solves, primary user goal (1 paragraph)
-2. **Screens** — Every screen: name, purpose (1 line), navigation relationships
-3. **Flows** — Formalized from Stage 1 with alternate paths (validation fail, cancel, network error)
-4. **Layouts** — Per screen: header/main/footer structure + responsive behavior (desktop >1024, tablet 768-1024, mobile <768)
-5. **Components** — Each interactive element: purpose, location, states (default, hover, active, disabled, loading, error)
-6. **Interactions** — Table format: Element | Action | Result (exhaustive)
-7. **States** — Table format: State | Trigger | Appearance | Available Actions (empty, loading, loaded, error)
-8. **Content** — Exact copy: page titles, buttons, empty states, error messages, confirmation dialogs
-9. **Edge Cases** — Limits/boundaries, null/long data handling, permissions, offline/network failures
-10. **Accessibility** — Tab order, keyboard actions (Enter/Space/Escape), screen reader announcements, focus management
-
-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?
->
-> Reply with feedback, or **"Approved"** to finalize.
-
-**Wait for approval.**
-
-## Step 5 — Handoff
-
-Confirm completion with summary: screens specified, 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}
-Options: /create_plan, /create_tasks, /tdd
-```