@codename_inc/spectre 4.0.0 → 5.0.0

package/README.md

@@ -65,7 +65,7 @@ Session continuity deep dive: [`docs/codex-sessionstart-memory.md`](./docs/codex
 
 ## 🔁 How It Works
 
-- run one of the kickoff prompts in Claude Code - `/spectre:scope` is the main command for building new features, but also `/spectre:kickoff` for high ambiguity new features (includes web research), `/spectre:research` for codebase research "how might we build …” style Qs, or `/spectre:ux_spec` to define user flows, components, and layout for a new feature.
+- run one of the kickoff prompts in Claude Code - `/spectre:scope` is the main command for building new features, but also `/spectre:kickoff` for high ambiguity new features (includes web research), `/spectre:research` for codebase research "how might we build …” style Qs, or `/spectre:ux` to define user flows, components, and layout for a new feature.
 
 - follow the prompts/instructions to create the related canonical document and Claude Code will suggest the next step in the SPECTRE workflow automatically (e.g., going from `scope` to `plan` to `tasks` and so on)
 
@@ -281,7 +281,7 @@ Although I do sometimes use @spectre:web-research for web research. It's like mi
 
 - start /spectre:scope to get crisp on what's in/out. this is non-negotiable unless the feature is a one line ask.
 
-  - if the feature's ux/user flow is unclear to me, or I want to make sure to really nail it, i run /spectre:ux_spec. Its similar to /spectre:scope but focuses on getting clear on the core user flows.
+  - if the feature's ux/user flow is unclear to me, or I want to make sure to really nail it, i run /spectre:ux. Its similar to /spectre:scope but focuses on getting clear on the core user flows.
 
 - /spectre:plan to build out a well researched technical design or set of tasks
 
@@ -367,7 +367,7 @@ I use /spectre:fix for pretty much all bugs I run into.
 | --- | --- |
 | `/spectre:sweep` | Light cleanup pass — lint, test, descriptive commits |
 | `/spectre:learn` | Capture knowledge for future sessions |
-| `/spectre:ux_spec` | UX specification for UI-heavy features |
+| `/spectre:ux` | UX specification for UI-heavy features |
 | `/spectre:fix` | Investigate bugs & implement fixes |
 
 ## 📁 Repository Structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codename_inc/spectre",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "type": "module",
   "bin": {
     "spectre": "./bin/spectre.js"

package/plugins/spectre/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "spectre",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Agentic coding workflow with session memory. spectre guides you through Scope, Plan, Execute, Clean, Test, Rebase, and Extract phases."
 }

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

@@ -94,7 +94,7 @@ This is how the creator of SPECTRE uses it daily:
 ### Building a Feature (the main loop)
 
 1. **`/spectre:scope`** — Get crisp on what's in/out. Non-negotiable unless it's a one-liner.
-   - If UX is unclear: run `/spectre:ux_spec` first for user flows and components
+   - If UX is unclear: run `/spectre:ux` first for user flows and components
 
 2. **`/spectre:plan`** — Build a well-researched technical design or task set
    - Once you have scope/plan/tasks, run `/spectre:handoff` for a fresh context window
@@ -147,7 +147,7 @@ Brain dump context, walk away, review the PR. Zero confirmation gates — scope,
 | `/spectre:scope` | Starting any new feature — interactive scoping with IN/OUT boundaries |
 | `/spectre:kickoff` | High-ambiguity projects — includes web research for best practices |
 | `/spectre:research` | Need deep codebase understanding before planning |
-| `/spectre:ux_spec` | UI-heavy features that need screen layouts, user flows, component states |
+| `/spectre:ux` | UI-heavy features that need screen layouts, user flows, component states |
 
 ### Phase: Plan — Research & Task Breakdown
 
@@ -213,7 +213,7 @@ Brain dump context, walk away, review the PR. Zero confirmation gates — scope,
 -> `/spectre:scope` (always start here unless it's trivial)
 
 **Feature has complex UI?**
--> `/spectre:ux_spec` after scope, before plan
+-> `/spectre:ux` after scope, before plan
 
 **High ambiguity / new project?**
 -> `/spectre:kickoff` (includes web research)
@@ -283,7 +283,7 @@ SPECTRE generates these documents in `docs/tasks/{branch_name}/`:
 | Document | Generated By | Purpose |
 |----------|-------------|---------|
 | `concepts/scope.md` | `/spectre:scope` | What's IN and OUT |
-| `specs/ux.md` | `/spectre:ux_spec` | User flows, components, interactions |
+| `specs/ux.md` | `/spectre:ux` | User flows, components, interactions |
 | `specs/plan.md` | `/spectre:create_plan` | Technical design and phasing |
 | `specs/tasks.md` | `/spectre:create_tasks` | Concrete tasks with acceptance criteria |
 | `reviews/code_review.md` | `/spectre:code_review` | Severity-based code review findings |

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

@@ -0,0 +1,314 @@
+---
+name: prototype
+description: 👻 | Generate a self-contained HTML prototype to validate a feature visually before planning - primary agent
+user-invocable: true
+---
+
+# prototype
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# prototype: Make the Feature Visible Before You Plan It
+
+Produce a self-contained, clickable HTML artifact that makes a feature visible — resolving ambiguity before scope, validating flows before plan, or anchoring stakeholder review. Output: single portable HTML file the user can open locally or host anywhere, saved to `{OUT_DIR}/prototypes/{name}_{MMDDYY}.html`.
+
+## ARGUMENTS
+
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+
+## Invocation Modes
+
+Detect mode from environment markers, ARGUMENTS, and existing docs. **Order matters** — check from most context to least:
+
+- **Complete ux.md exists** (post-ux) — full Stage 2 spec is on disk. The prototype's job is to **render the spec**, not synthesize it. Default fidelity: **high-fi**. Skip all intake except visual anchor. Treat ux.md as authoritative — don't invent screens, don't contradict documented states or copy. On completion, recommend `/spectre:plan` or `/spectre:create_tasks`.
+- **`FROM_UX=true`** — invoked mid-flow from `ux` Stage 1 → Stage 2 gate. Only approved flows exist (no detailed spec yet). Skip flow-discovery intake. Default fidelity: **mid-fi**. On completion, point user back to `ux` Stage 2.
+- **`--explore` flag in ARGUMENTS** — pre-scope discovery. Concept is unvalidated. Default fidelity: **low-fi**. On completion, recommend `/spectre:scope` as next step.
+- **scope.md exists for this branch** (no ux.md) — post-scope validation. Default fidelity: **mid-fi**. On completion, recommend `/spectre:ux` or `/spectre:plan` based on feature complexity.
+- **Standalone, no context** — ask the user what they're prototyping. Default fidelity: **mid-fi**.
+
+---
+
+# STAGE 1: Intake & Fidelity Alignment
+
+**Goal**: Confirm what we're prototyping, at what fidelity, and what visual anchor to use. Keep this tight — 2 to 4 questions, never a form.
+
+## Step 1 — Immediate Reply & Detect Context
+
+- **Action** — ImmediateReply: Respond before any tools.
+  - **If** `FROM_UX=true` → acknowledge ux context, read approved flows from `{OUT_DIR}/ux.md`, **SKIP to Step 3**
+  - **Else If** ARGUMENTS empty → probe: "What are we prototyping? A quick description is enough — I'll figure out the fidelity from context."
+  - **Else** → proceed to Step 2
+  - **CRITICAL**: No tool calls in this step except reading ux output when `FROM_UX=true`.
+
+## Step 2 — Read Available Context & Classify ux.md
+
+- **Action** — DetectExistingDocs: Check for relevant inputs before asking the user anything.
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - Look for: `docs/tasks/{branch_name}/concepts/scope.md`, `docs/tasks/{branch_name}/specs/prd.md`, `docs/tasks/{branch_name}/ux.md`
+  - Read whichever exist FULLY (no offset/limit)
+
+- **Action** — ClassifyUxDoc: If `ux.md` exists, classify its completeness — this drives fidelity AND how much intake to skip.
+  - **Complete** — contains all of: Screens, Layouts, Components, Interactions, States, Content sections (the Stage 2 deliverables from `/spectre:ux`). Treat as authoritative. Skip flow-discovery questions. Set mode = **post-ux**.
+  - **Flows-only** — contains user flows / journeys but missing Stage 2 sections. Treat flows as approved input but expect to make UI decisions. Set mode = **flows-only ux**.
+  - **Absent** — fall back to scope.md / prd.md / standalone modes.
+
+## Step 3 — Recommend Fidelity, Confirm Anchor
+
+Pick fidelity from signals available:
+
+| Signal present | Recommends |
+|---|---|
+| `--explore` flag, or no scope/prd | **Low-fi** — grayscale, layout-only, no typography polish |
+| scope.md exists, no design system anchor | **Mid-fi** — real colors, basic type, simplified components (default) |
+| scope.md + flows-only ux.md, or brand/design system anchor | **Mid-fi to High-fi** — depends on anchor strength |
+| **Complete ux.md** (post-ux) | **High-fi** — full design tokens, realistic data, micro-interactions; render the spec faithfully |
+
+### Intake by mode
+
+**Post-ux mode** (complete ux.md) — present a tight confirmation, ask one question:
+
+> **Prototype plan** — rendering complete UX spec
+>
+> Source: `{path to ux.md}` ({N} screens, {M} components, {K} states specified)
+> Fidelity: **high-fi** (default — full spec is on disk; I'll render it faithfully, not invent)
+>
+> One thing I need: **visual anchor** — brand colors, font stack, an existing app/URL to match, or a named aesthetic (e.g. "Linear-style", "Notion-quiet", "Stripe-clean"). If the spec already specifies design tokens, reply "use the spec." If you skip this, I'll commit to a deliberate named aesthetic and call it out at the top of the file.
+
+**All other modes** — present recommendation + request anchor + confirm framing:
+
+> **Prototype plan**
+>
+> I'm reading this as: **{inferred feature/flow}**
+> Recommended fidelity: **{low-fi | mid-fi | high-fi}** — {one-line reason}
+> Primary flow: **{name}** (from {scope.md | ux.md flows | your description})
+>
+> Two things I need from you:
+> 1. **Override fidelity?** Or "looks good."
+> 2. **Visual anchor** — brand colors, font stack, an existing app/URL to match, or a named aesthetic (e.g. "Linear-style", "Notion-quiet", "Stripe-clean"). If you skip this, I'll commit to a deliberate named aesthetic and call it out at the top of the file so you can redirect.
+
+**Wait for response.** If user pushes back on fidelity or feature framing, adjust and re-confirm.
+
+---
+
+# STAGE 2: Parallel Research & Generation
+
+**Gate**: Only proceed after Stage 1 confirmation (or `FROM_UX=true`).
+
+## Step 4 — Dispatch Parallel Subagents
+
+Spawn three subagents in parallel. Each has a focused job.
+
+### `@spectre:web-research` — Visual Reference Discovery
+
+Prompt template:
+
+> Research visual design patterns and UI conventions for **{feature type}**. Specifically:
+>
+> 1. Find 2–3 living examples or screenshots of similar UI patterns in well-regarded products. Return URLs and visual descriptions.
+> 2. Identify the established UX convention for this interaction type (wizard, dashboard, list+detail, modal flow, etc.) and any recent (2025–2026) refinements.
+> 3. If the user specified an aesthetic anchor ({anchor_text}), find representative color palettes (hex), typography choices (font families with fallbacks), and one or two distinctive design moves that define the aesthetic.
+> 4. Return concrete decisions — colors, fonts, layout patterns — not general advice.
+>
+> Length: under 400 words. Cite sources.
+
+**Why**: Grounds generation in specific references. Without this step the model defaults to its own distribution (Inter + purple gradients). This is the anti-slop forcing function.
+
+### `@spectre:analyst` — Flow & Content Extraction
+
+Use one of two prompt templates based on mode detected in Step 2.
+
+**Extraction mode** — post-ux (complete ux.md present):
+
+> Read **{path to ux.md}** fully. The Stage 2 spec is authoritative — your job is to **extract** structured data for HTML rendering, NOT to synthesize new screens, states, or content.
+>
+> Return a render brief organized by ux.md section:
+>
+> 1. **Screens** — verbatim from the Screens section: name, purpose, navigation relationships
+> 2. **Layouts** — verbatim from Layouts: per-screen header/main/footer + responsive breakpoints
+> 3. **Components** — verbatim from Components: each element's purpose, location, all documented states (default, hover, active, disabled, loading, error)
+> 4. **Interactions** — verbatim from the Interactions table: Element | Action | Result
+> 5. **States** — verbatim from the States table: State | Trigger | Appearance | Available Actions
+> 6. **Content** — verbatim copy from the Content section: page titles, button labels, empty-state messages, error messages, confirmation dialogs. Use this copy EXACTLY in the prototype — do not paraphrase.
+> 7. **Edge cases & a11y** — note any documented constraints (limits, null/long data, keyboard actions, focus management) the prototype should reflect
+>
+> If the spec specifies a state or content value, the prototype must match it. If the spec is silent on a detail, flag it as a "filled assumption" so it appears in the prototype's metadata header. Never invent screens that aren't in the spec.
+
+**Synthesis mode** — flows-only ux, scope-only, or standalone:
+
+> Read these documents fully: **{list of paths — scope.md, prd.md, ux.md flows section if present}**. Extract a content skeleton for an HTML prototype:
+>
+> 1. **Primary flow** — entry → action → outcome, with decision points
+> 2. **Required UI states per screen** — every screen needs at minimum: happy path, empty state, error or edge state. Some screens also need: loading, success
+> 3. **Stated constraints** — any layout, behavior, or content constraints from the docs
+> 4. **Realistic content** — actual product names, plausible numbers, real-looking copy. NO Lorem ipsum. NO "Card Title." If domain-specific data is unclear, invent plausible values that match the feature's domain.
+> 5. **Component inventory** — every recurring UI element that will need a named CSS class (button, card, input, badge, etc.)
+>
+> Return a structured flow brief: screen list, per-screen state list, realistic content for each, component inventory.
+
+**Why**: This is the content skeleton. In post-ux mode, the spec already did this work — re-synthesizing risks contradicting documented decisions. In all other modes, skipping synthesis produces prototypes with Lorem ipsum and inconsistent component styling.
+
+### `@spectre:patterns` — Existing Codebase Anchor (only if applicable)
+
+Skip this agent if there is no existing app to anchor to. Otherwise:
+
+> Find existing UI patterns in this codebase that the prototype should match or extend: design tokens (colors, spacing, type), component conventions (button styles, card layouts), and any established interaction patterns. Return file references with the actual values (hex codes, class names, etc.) — not just paths.
+
+**Why**: When prototyping inside an existing app, the prototype should look like a plausible new screen of that app, not a designer's blank canvas.
+
+## Step 5 — Generate the HTML Artifact
+
+Wait for ALL subagents to complete. Synthesize their outputs, then generate a single self-contained HTML file. Use `@spectre:dev` to produce the file (or inline if the synthesis is straightforward).
+
+### Hard constraints on the generated HTML
+
+**File structure** (every prototype includes these in order):
+
+1. **`<!DOCTYPE html>` + minimal `<head>`** with `<meta viewport>` and an inline `<style>` block
+2. **Metadata comment block** at the very top of `<head>`:
+   ```html
+   <!--
+     SPECTRE PROTOTYPE
+     Feature: {feature name}
+     Fidelity: {low-fi | mid-fi | high-fi}
+     Generated: {YYYY-MM-DD}
+     Branch: {branch_name}
+     Flow covered: {primary flow}
+     Screens/states: {comma-separated list}
+     Visual anchor: {named aesthetic or reference URL}
+     Source spec: {path to ux.md if post-ux mode, else "none — synthesized from {scope.md | description}"}
+     Key assumptions: {bullet list of design decisions and content assumptions}
+     Filled assumptions: {only in post-ux mode — items the spec was silent on that the prototype filled in; review these against the spec}
+     NOT included: {explicit list of what was deliberately left out}
+     Next step: /spectre:plan  OR  resume /spectre:ux Stage 2
+   -->
+   ```
+3. **Design tokens comment block** in `<head>`:
+   ```html
+   <!-- DESIGN TOKENS
+     Primary: #{hex}
+     Accent: #{hex}
+     Surface: #{hex}
+     Text: #{hex}
+     Font: {family}, served from {CDN or system}
+     Border-radius: {value}
+     Spacing unit: {value}
+   -->
+   ```
+   Also encode these as CSS custom properties on `:root` so they're reusable in the stylesheet.
+4. **Navigation bar** (only if multi-screen) — vanilla JS section toggling via `display:block/none`. No routing, no framework.
+5. **One `<section>` per screen.** Every screen must include the happy path AND at least one of: empty state, error state, loading state. Skipping these is the most common prototype failure mode.
+6. **Inline `<script>`** at end of body for interactions (tab switching, form submit interception, modal toggle, accordion). Vanilla JS only.
+
+**Size budget**: under 300KB. No base64 photos. No Chart.js or other large libraries. Use inline SVG and CSS-drawn shapes for any illustrations. Tailwind via CDN is acceptable for mid/high-fi; skip for low-fi.
+
+**Asset rules** (keep the file portable so users can open locally, email it, host on a gist, or push to any static host):
+- No `<img src="https://...">` that can 404 — use inline SVG, data URIs, or CSS shapes
+- No local relative paths (`./image.png`, `../style.css`) — they break the moment the file moves
+- Fonts: Google Fonts CDN (single family, two weights max) or system fonts. No custom WOFF files.
+
+### Negative constraints (embed these explicitly in the @spectre:dev prompt)
+
+When delegating to `@spectre:dev`, the prompt MUST include these as forbidden patterns:
+
+- **No generic AI aesthetic.** Do not use Inter or Roboto by default. Do not use purple gradients on white. Commit to a named, deliberate aesthetic and call it out in the metadata.
+- **No Lorem ipsum or placeholder filler.** All text must be realistic for the domain. "Card Title", "User Name", "Description goes here" are forbidden.
+- **No happy-path-only screens.** Every screen must show at least one non-happy state (empty, error, or edge).
+- **No broken interactivity.** Every `onclick`, `<form>`, or interactive element must respond visually. No `href="#"` that causes page jumps. No event handlers that throw console errors.
+- **No external image dependencies that can break.** Inline SVG only.
+- **No inconsistent component instances.** Define every recurring component as a named CSS class ONCE and reuse it. Do not re-style inline. If a card appears five times, it uses the same class five times.
+- **No page-thinking when flow-thinking is required.** Screens appear in the order a user encounters them, not in the order they're easy to build.
+- **No file-size bloat.** No base64 photos. No Chart.js, D3, or other heavyweight libraries. SVG and CSS only.
+
+### Output location
+
+- **Action** — DetermineOutputDir:
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - **If** `FROM_UX=true` or `FROM_KICKOFF=true` → use the existing task directory
+  - **Else If** user specifies path → use that
+  - **Else** → `OUT_DIR=docs/tasks/{branch_name}`
+  - `mkdir -p "$OUT_DIR/prototypes"`
+
+- **Action** — SaveArtifact: Write file to `{OUT_DIR}/prototypes/{feature_slug}_{MMDDYY}.html`
+
+## Step 6 — Self-Check Portability
+
+Before reporting completion, sanity-check the artifact against the portability rules:
+
+- File size under 300KB
+- No `<img src="http...">` external images
+- No local relative paths (`./`, `../`, `/local/`)
+- All recurring components share a named CSS class (no inline-styled duplicates)
+- Every screen includes at least one non-happy state
+
+Surface any violations as caveats in the handoff. Don't silently ship a broken portable file.
+
+## Step 7 — Present & Handoff
+
+- **Action** — PresentForReview:
+
+  > **Prototype complete**: `{path}` ({size} KB, {N} screens, {fidelity})
+  >
+  > **Visual anchor**: {named aesthetic}
+  > **Key assumptions made** (also embedded in file header):
+  > - {bullet 1}
+  > - {bullet 2}
+  > - {bullet 3}
+  > **NOT included**: {explicit list}
+  >
+  > Open the file in a browser to review (`open {path}` on macOS, or drag into any browser tab). The file is fully self-contained — share it however you like (email, gist, static host, etc.). Reply with feedback to iterate, or pick a next step below.
+
+- **Action** — SurfaceFilledAssumptions (post-ux mode only): If `mode = post-ux` AND any filled assumptions exist (items the spec was silent on that the prototype filled in), append a closing-the-loop block:
+
+  > **Filled assumptions** — ux.md was silent on these; I made calls to render the spec. Review and tell me which to promote into the spec:
+  >
+  > 1. {assumption} → I chose **{decision}** ({why, one line})
+  > 2. {assumption} → I chose **{decision}** ({why, one line})
+  > 3. {assumption} → I chose **{decision}** ({why, one line})
+  >
+  > Reply with numbers to update ux.md (e.g. `1, 3`), `all` to add all, or `skip` to leave the spec as-is.
+
+  If user picks updates:
+  - Edit `ux.md` directly: place each chosen item in the appropriate section (Components / States / Content / Edge Cases / Interactions).
+  - Re-run the Step 6 portability check (no regen needed unless user also requested HTML changes).
+  - Re-present with a one-line diff per added item: `ux.md ← added: {item} (in {section})`.
+
+- **Action** — RenderFooter: Render Next Steps using `@skill-spectre:spectre-guide` skill, with mode-specific recommendation:
+  - **If `FROM_UX=true`** → recommend: "Resume `/spectre:ux` Stage 2 with this prototype as input"
+  - **If `--explore`** → recommend: `/spectre:scope` with the prototype as anchor
+  - **If post-scope** → recommend: `/spectre:ux` (if flows still need detail) or `/spectre:plan` (if ready to build)
+  - **Else** → standard Next Steps options
+
+---
+
+## Iteration Loop
+
+If the user replies with feedback after Step 7:
+- Small visual tweaks (color, copy, layout) → edit the HTML directly
+- Structural changes (add screen, change flow) → re-run Step 4 subagents with the deltas and regenerate
+- **Spec contradicts prototype** (post-ux mode) → ask which is authoritative for each contradiction, then update ux.md AND the HTML together so they stay paired; re-run Step 6 portability check
+- After any edit, re-run the Step 6 self-check before re-presenting
+
+---
+
+## Success Criteria
+
+- [ ] Immediate reply sent; mode detected (FROM_UX, --explore, post-scope, or standalone)
+- [ ] Existing context docs (scope.md, prd.md, ux.md) read FULLY before asking questions
+- [ ] Fidelity recommended with rationale; user confirmed or overrode
+- [ ] Visual anchor captured (named aesthetic or reference) — never left as generic default
+- [ ] Three subagents dispatched in parallel: web-research (references), analyst (flow + content), patterns (existing codebase anchor, if applicable)
+- [ ] ALL subagents completed before generation
+- [ ] HTML artifact is single self-contained file under 300KB
+- [ ] Metadata comment block at top of `<head>` includes feature, fidelity, assumptions, NOT-included list
+- [ ] Design tokens block present and encoded as CSS custom properties on `:root`
+- [ ] Every screen includes happy path + at least one non-happy state (empty, error, or edge)
+- [ ] No Lorem ipsum, no placeholder filler — realistic domain content throughout
+- [ ] No external image dependencies (inline SVG only)
+- [ ] All recurring components use a single named CSS class (no inline re-styling)
+- [ ] All interactive elements respond visually; no console errors; no `href="#"` jump links
+- [ ] Saved to `{OUT_DIR}/prototypes/{slug}_{MMDDYY}.html`
+- [ ] Portability self-check run (size, external images, relative paths, component reuse, state coverage); violations surfaced as caveats
+- [ ] (post-ux mode only) Filled assumptions surfaced in chat with offer to update ux.md; selected items written to ux.md with diff summary
+- [ ] Next Steps footer rendered with mode-appropriate recommendation

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

@@ -1,6 +1,6 @@
 ---
 name: scope
-description: 👻 | Interactively scope a feature or improvement, generating a complete Scope document that clarifies what's IN and OUT -- primary agent
+description: 👻 | Interactively scope a feature or improvement, generating a complete Scope document with IN, OUT, and ANTI-SCOPE boundaries -- primary agent
 user-invocable: true
 ---
 
@@ -12,104 +12,144 @@ Treat the current command arguments as this workflow's input. When invoked from
 
 # scope: Interactive Feature Scoping
 
-Collaborative workflow for structuring unstructured thoughts into clear scope boundaries through contextual brainstorming and targeted clarifications. Focuses on user value and scope boundaries before technical considerations. Output: comprehensive scope document with clear boundaries, user value, and key decisions saved to `{OUT_DIR}/concepts/scope.md`.
+Collaborative workflow for structuring unstructured thoughts into clear scope boundaries through a grounded hypothesis and targeted clarifications. Focuses on user value and scope boundaries before technical considerations. Output: scope document with clear boundaries (IN / OUT / ANTI-SCOPE), user value, load-bearing assumptions, and key decisions saved to `{OUT_DIR}/concepts/scope.md`.
 
 ## ARGUMENTS
 
-<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
 
-## Step 1: Immediate Reply & Gather Context
+## Step 1: Immediate Reply & Context Pickup
 
 - **Action** — ImmediateReply: Respond before any tools.
-  - **If** `FROM_KICKOFF=true` → acknowledge kickoff context, read `KICKOFF_DOC`, extract (Core Problem, User Value, Decisions Made, Remaining Ambiguities, Key Code Refs), **SKIP to Step 3**
-  - **Else If** ARGUMENTS empty → probe for context enthusiastically
-  - **Else** → proceed to Step 2
-  - **CRITICAL**: No tool calls except reading kickoff doc when FROM_KICKOFF=true
+  - **If** `FROM_KICKOFF=true` → acknowledge kickoff context, read `KICKOFF_DOC`, extract (Core Problem, User Value, Decisions Made, Remaining Ambiguities, Key Code Refs), **SKIP to Step 4**
+  - **Else If** ARGUMENTS empty → probe for context enthusiastically and **WAIT** for user
+  - **Else** → proceed with the steps below
+  - **CRITICAL**: No tool calls in this step except reading the kickoff doc when `FROM_KICKOFF=true`.
 
-## Step 2: Interactive Scope Exploration
+- **Action** — DetectExistingArtifacts: Before proposing a hypothesis, check for prior context that may already answer questions.
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - Look for: `docs/tasks/{branch_name}/concepts/scope.md`, `docs/tasks/{branch_name}/task_context.md`
+  - **If** prior `scope.md` exists → read fully; treat this invocation as a re-scope. Surface what was already settled and ask only about what's new or changed.
+  - **If** captured project knowledge is available (via `/spectre:apply`-style memory or session logs) → surface decisions/patterns/gotchas relevant to this area before asking the user.
+
+## Step 2: Ground the Hypothesis (Fast)
+
+**SKIP IF FROM_KICKOFF=true** — kickoff already grounded.
+
+- **Action** — FastGround: Run ONE fast lookup to ground the hypothesis in repo reality. Pick the most informative single call:
+  - **`@spectre:finder` for one targeted query** — when you need to know what files/components exist for this area
+  - **One `grep` or `glob`** — when you need to verify a specific assumption ("does X already exist?")
+
+  **Constraints**:
+  - **One call only.** This is grounding, not research. Tech research is `/spectre:plan`'s job.
+  - **Fast.** If the call would take more than a few seconds, skip it and ask the user instead.
+  - If you need more than one signal, that's a sign this should be a `/spectre:kickoff` rather than a `/spectre:scope`.
+
+## Step 3: Interactive Scope Exploration
 
 **SKIP IF FROM_KICKOFF=true**
 
-- **Action** — ExploreScope: Collaborative dialogue focused on boundaries and user experience.
+- **Action** — ExploreScope: Collaborative dialogue focused on boundaries, user experience, and anti-scope.
 
-  **CRITICAL**: Focus on WHAT, not HOW. Defer all technical/implementation questions until scope boundaries are finalized. Only ask technical questions if the scope itself is inherently technical (e.g., "migrate database from X to Y").
+  **CRITICAL**: Focus on WHAT, not HOW. Defer all technical/implementation questions to `/spectre:plan`. Only ask technical questions if the scope itself is inherently technical (e.g., "migrate database from X to Y").
 
-  **PATTERN**: Lead with a rich initial exploration. In your FIRST response, propose concrete hypotheses AND ask 5-8 questions across multiple dimensions. Give the user a full landscape to react to, not a single thread to follow.
+  **PATTERN**: Lead with a grounded hypothesis (informed by Step 2's lookup) AND ask 5–8 questions across multiple dimensions. Mark each question as **(blocking)** or *(optional)* so the user can skim and skip.
 
   **FIRST RESPONSE FORMAT**:
 
-  > Here's my initial read on this, plus questions to help us explore the bounds:
+  > Here's my read on this, grounded in {one-line of what Step 2 surfaced}:
   >
-  > **My hypothesis**: [problem statement, who it affects, proposed IN/OUT]
+  > **Hypothesis**: [problem statement, who it affects, proposed IN / OUT / ANTI-SCOPE]
   >
-  > **Questions to explore**:
-  > 1. [User problem question]
-  > 2. [UX flow question]
-  > 3. [Boundary edge question]
-  > 4. [Alternative approach question]
-  > 5. [Success criteria question]
-  > 6. [Edge case question]
-  > ...
+  > **Questions**:
+  > 1. **(blocking)** [User problem question]
+  > 2. **(blocking)** [Boundary edge question]
+  > 3. **(blocking)** [Anti-scope question]
+  > 4. *(optional)* [UX flow question]
+  > 5. *(optional)* [Alternative approach question]
+  > 6. *(optional)* [Edge case question]
+  > 7. *(optional)* [Success criteria question]
   >
-  > Answer any/all that spark thoughts. Skip what's obvious.
+  > Answer the blocking ones; skip optional if obvious.
 
-  **Question types to include** (aim for 5-8 total, mix from these):
+  **Question types** (mix from these; lean on blocking for boundaries and anti-scope):
 
   - **User & Problem**: Who feels this most? What triggers the need? What's the cost of not solving it?
   - **UX & Feel**: Should this feel fast or thorough? Guided or flexible? What's the ideal flow?
-  - **Boundaries**: What about [adjacent thing]—IN or OUT? If unlimited time, what else? What's essential for v1?
+  - **Boundaries (IN/OUT)**: What about [adjacent thing]—IN or OUT? What's essential for v1?
+  - **Anti-Scope**: What problem are we *intentionally not solving* here? (Different from OUT — anti-scope clarifies the philosophical edge of the feature, not just deferred work.)
   - **Alternatives**: I could see this as [A] or [B]. Which direction?
-  - **Edge cases**: What happens when [unusual situation]? Should we handle [error state]?
-  - **Success**: What makes you say "this shipped well"? What's the one thing we can't get wrong?
+  - **Edge cases**: What happens when [unusual situation]?
+  - **Success**: What makes you say "this shipped well"?
 
-  **DO NOT ask about**: implementation approach, technical trade-offs, architecture, or integration details until boundaries are confirmed.
+  **DO NOT ask about**: implementation approach, technical trade-offs, architecture, or integration details — those belong in `/spectre:plan`.
 
 - **Action** — IterateBoundaries: After user responds, refine boundaries and ask targeted follow-ups on gaps.
 
-  > **Current Boundaries**: ✅ **IN**: \[list\] ❌ **OUT**: \[list\] ⚠️ **Unsure**: \[edge cases\]
+  > **Current Scope**:
+  > ✅ **IN**: [list]
+  > ❌ **OUT**: [list]
+  > 🚫 **ANTI-SCOPE**: [problems we're intentionally not solving]
+  > ⚠️ **Unsure**: [edge cases]
   >
   > Any items to move? Add exclusions? Clarify edges? Reply 'looks good' to continue.
 
-- **Wait** — User confirms Scope boundaries are accurate
+- **Wait** — User confirms scope boundaries are accurate.
 
-## Step 3: Generate Targeted Clarifications
+## Step 4: Targeted Clarifications
 
 - **Action** — DetermineOutputDir:
-
   - **If** FROM_KICKOFF → use same dir as kickoff doc
   - **Else** → `OUT_DIR = user_specified || docs/tasks/{branch_name}`
-  - `mkdir -p "$OUT_DIR"`
+  - `mkdir -p "$OUT_DIR/concepts" "$OUT_DIR/clarifications"`
 
-- **Action** — GenerateTargetedQuestions: Create 3-6 questions based ONLY on remaining scope ambiguities from Step 2 (or kickoff's "Remaining Ambiguities").
+- **Action** — DetectClarificationMethod: Check if `AskUserQuestion` tool is available.
+  - **If available** → use inline clarification flow (Path A)
+  - **If not available** → use file-based clarification flow (Path B)
 
-  **CRITICAL**: Only ask about unresolved scope ambiguities. Technical questions (architecture, trade-offs, integration) belong in `/spectre:plan`, not here.
+### Path A: Inline Clarifications (AskUserQuestion available)
 
-- **Action** — SaveClarifications: Create `{OUT_DIR}/clarifications/scope_clarifications_{timestamp}.md`:
+- **Action** — AskInline: Generate 3–6 questions based ONLY on remaining scope ambiguities from Step 3 (or kickoff's "Remaining Ambiguities").
+  - Ask the most critical first (up to 4 at a time, the tool limit).
+  - For trade-off decisions, present options with concise pros/cons.
+  - If more than 4 questions, ask in batches — most important first.
 
+  **CRITICAL**: Only ask about unresolved scope ambiguities. Technical questions belong in `/spectre:plan`, not here.
+
+### Path B: File-Based Clarifications (no AskUserQuestion)
+
+- **Action** — GenerateTargetedQuestions: Create 3–6 questions in `{OUT_DIR}/clarifications/scope_clarifications_{YYYY-MM-DD_HHMMSS}.md`:
   - Header: concept name, confirmed boundaries so far
-  - Questions: Each focused on a scope edge case with `<response></response>` block
+  - Each question with a `<response></response>` block
 
 - **Action** — PromptUser: "Saved clarifications to `{path}`. Answer in `<response>` blocks. Reply 'Read it' when ready."
 
-- **Wait** — User replies
+- **Wait** — User replies.
 
-- **Action** — ReadClarifications: Read file, use responses (proceed with assumptions if empty)
+- **Action** — ReadClarifications: Read the file; use responses (proceed with intelligent assumptions if blocks are empty).
 
-## Step 4: Create Scope Document
+## Step 5: Create Scope Document
 
-- **Action** — CreateScopeDoc: Generate `{OUT_DIR}/concepts/scope.md` (use scoped filename if exists).
+- **Action** — CreateScopeDoc: Generate `{OUT_DIR}/concepts/scope.md` (use scoped filename if one exists).
 
   **Priority**: User value and boundaries BEFORE technical details.
 
-  **Sections**: The Problem (pain, impact, current state) → Target Users (primary, secondary, needs) → Success Criteria (outcomes, metrics) → User Experience (journeys, principles, trade-offs) → Scope Boundaries (in/out/maybe/future) → Constraints (platform, perf, a11y, scale) → Integration (touches, avoids, dependencies) → Decisions (from clarifications + rationale) → Risks (UX, scope creep, open questions) → Next Steps (`/spectre:plan` or `/spectre:create_tasks`, complexity S/M/L)
-
-## Step 5: Light Technical Context (Optional)
+  **Sections**:
 
-**Only if scope identifies specific technical/architecture integration points.**
+  1. **The Problem** — pain, impact, current state
+  2. **Target Users** — primary, secondary, needs
+  3. **Success Criteria** — outcomes; prefer measurable assertions over prose
+  4. **User Experience** — journeys, principles, trade-offs
+  5. **Scope Boundaries** — IN / OUT / ANTI-SCOPE / Maybe / Future
+  6. **Load-Bearing Assumptions** — assumptions that, if wrong, invalidate this scope. Each assumption gets a short *"if this is false, …"* consequence so future-you can recognize when to come back.
+  7. **Constraints** — platform, perf, a11y, scale (user-provided only)
+  8. **Decisions** — from clarifications + rationale
+  9. **Risks** — UX, scope creep, open questions
+  10. **Next Steps** — `/spectre:plan` or `/spectre:create_tasks`, complexity S/M/L
 
-- **Action** — IdentifyTouchpoints: Identify desired areas of research, and dispatch parallel @analyst subagents to research each area. Surface-level only (component names, NOT implementation). List features this interacts with, constraints worth documenting, areas to avoid.
-
-- **Action** — UpdateScopeDoc: Add findings to Integration & Constraints sections if relevant.
+  **Note on ANTI-SCOPE vs OUT**:
+  - **OUT** = we're not building it (yet, or for this release).
+  - **ANTI-SCOPE** = we're intentionally not solving this *problem* — it clarifies the philosophical edge of what this feature is for.
 
 ## Step 6: Final Review & Next Steps
 
@@ -117,12 +157,18 @@ Collaborative workflow for structuring unstructured thoughts into clear scope bo
 
   > **Scope Complete**: `{OUT_DIR}/concepts/scope.md`
   >
-  > **Final Boundaries**: ✅ **IN**: \[from doc\] ❌ **OUT**: \[from doc\] ⚠️ **Maybe/Future**: \[from doc\]
+  > **Final Boundaries**:
+  > ✅ **IN**: [from doc]
+  > ❌ **OUT**: [from doc]
+  > 🚫 **ANTI-SCOPE**: [from doc]
+  > ⚠️ **Maybe/Future**: [from doc]
+  >
+  > **Load-Bearing Assumptions** (top 1–3 — if any prove false, return to scope): [from doc]
   >
-  > Docs saved: `{OUT_DIR}/concepts/scope.md`, `{OUT_DIR}/clarifications/scope_clarifications_{timestamp}.md`
+  > Docs saved: `{OUT_DIR}/concepts/scope.md`, clarifications under `{OUT_DIR}/clarifications/`
   >
-  > Reply with any edits, updates, or clarifications — otherwise pick a next step:
+  > Reply with edits — otherwise pick a next step:
 
 - **Action** — RenderFooter: Render Next Steps using `@skill-spectre:spectre-guide` skill.
 
-  > **NOTE**: Do NOT wait for explicit approval. Present next steps immediately inline with the review. User can reply with scope edits OR jump straight into a next step command. If user replies with edits, apply them to the scope doc and re-present.
+  > **NOTE**: Do NOT wait for explicit approval. Present next steps inline with the review. The user can reply with scope edits OR jump straight into a next step command. If they reply with edits, apply them to the scope doc and re-present.