@gordon.gan/specflow 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [
@@ -17,14 +17,14 @@
     "code-generation"
   ],
   "license": "MIT",
-  "author": "bstzyf",
-  "homepage": "https://github.com/bstzyf/specflow",
+  "author": "Gordon-Gan-Jiang",
+  "homepage": "https://github.com/Gordon-Gan-Jiang/specflow",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bstzyf/specflow.git"
+    "url": "git+https://github.com/Gordon-Gan-Jiang/specflow.git"
   },
   "bugs": {
-    "url": "https://github.com/bstzyf/specflow/issues"
+    "url": "https://github.com/Gordon-Gan-Jiang/specflow/issues"
   },
   "bin": {
     "specflow": "./bin/specflow.js"
@@ -60,9 +60,6 @@
     "js-yaml": "^4.1.0",
     "zod": "^3.24.4"
   },
-  "optionalDependencies": {
-    "code-review-graph": "github:tirth8205/code-review-graph"
-  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.3",

package/prompts/{build → apply}/ecc-java-reviewer.md

@@ -101,7 +101,7 @@ If any CRITICAL security issue is found, stop and escalate to `security-reviewer
 - **Missing `@Transactional` awareness**: MongoDB multi-document transactions require an explicit `ClientSession` — Panache MongoDB does not auto-manage transactions like Hibernate ORM; document the consistency guarantees
 
 ### MEDIUM -- NoSQL General
-- **Schema evolution without migration strategy**: Changing document shapes without a versioned migration plan (e.g. a `schemaVersion` field or migration script) — leads to runtime deserialization failures on old documents
+- **Schema evolution without migration strategy**: Changing document shapes without a versioned migration propose (e.g. a `schemaVersion` field or migration script) — leads to runtime deserialization failures on old documents
 - **Storing large blobs in documents**: Embedding large binary data directly in documents instead of using GridFS or external storage — causes memory pressure and hits the 16 MB BSON limit
 - **Overly nested documents**: Deeply nested document structures that should be modelled as separate collections with references — query and update complexity grows exponentially
 - **Missing TTL or expiry policy**: Time-sensitive data (sessions, tokens, caches) stored without a TTL index — leads to unbounded collection growth

package/prompts/{build → apply}/language-router.md

@@ -8,12 +8,12 @@ Detection checks only the project root; do not recurse into subdirectories.
 
 | Priority | Detection Signal (project root only) | Language ID | Reviewer File |
 |----------|--------------------------------------|-------------|---------------|
-| 1 | `./tsconfig.json` | `typescript` | `prompts/build/ecc-typescript-reviewer.md` |
-| 2 | `./pyproject.toml` OR `./requirements.txt` OR `./setup.py` | `python` | `prompts/build/ecc-python-reviewer.md` |
-| 3 | `./go.mod` | `go` | `prompts/build/ecc-go-reviewer.md` |
-| 4 | `./Cargo.toml` | `rust` | `prompts/build/ecc-rust-reviewer.md` |
-| 5 | `./build.gradle.kts` OR `./settings.gradle.kts` | `kotlin` | `prompts/build/ecc-kotlin-reviewer.md` |
-| 6 | `./pom.xml` OR `./build.gradle` (non-.kts) | `java` | `prompts/build/ecc-java-reviewer.md` |
+| 1 | `./tsconfig.json` | `typescript` | `prompts/apply/ecc-typescript-reviewer.md` |
+| 2 | `./pyproject.toml` OR `./requirements.txt` OR `./setup.py` | `python` | `prompts/apply/ecc-python-reviewer.md` |
+| 3 | `./go.mod` | `go` | `prompts/apply/ecc-go-reviewer.md` |
+| 4 | `./Cargo.toml` | `rust` | `prompts/apply/ecc-rust-reviewer.md` |
+| 5 | `./build.gradle.kts` OR `./settings.gradle.kts` | `kotlin` | `prompts/apply/ecc-kotlin-reviewer.md` |
+| 6 | `./pom.xml` OR `./build.gradle` (non-.kts) | `java` | `prompts/apply/ecc-java-reviewer.md` |
 | 7 | (no match) | `unknown` | `prompts/shared/code-reviewer-prompt.md` |
 
 ## Fallback

package/prompts/{build → apply}/phase-a-plan.md

@@ -1,4 +1,4 @@
-> **HARD GATE**: User must confirm the rewritten plan before Phase B execution begins. Do NOT proceed to implementation until the user has reviewed and approved the rewritten tasks.md.
+> **HARD GATE**: User must confirm the rewritten propose before Phase B execution begins. Do NOT proceed to implementation until the user has reviewed and approved the rewritten tasks.md.
 
 <!-- SOURCE: skills/writing-plans/SKILL.md (with build Phase A rewrite semantics) -->
 
@@ -7,14 +7,14 @@
 ## Purpose Declaration
 
 **This prompt is for REWRITING an existing tasks.md into writing-plans precision.**
-**NOT for generating tasks.md from scratch.** The tasks.md already exists from the `plan` or `refine` phase. Your job is to take a coarse-grained first-iteration plan (or a refine-updated version of it) and transform each checkbox into a 2-5 minute atomic task that a fresh subagent can execute without additional context.
+**NOT for generating tasks.md from scratch.** The tasks.md already exists from the `plan` or `refine` phase. Your job is to take a coarse-grained first-iteration propose (or a refine-updated version of it) and transform each checkbox into a 2-5 minute atomic task that a fresh subagent can execute without additional context.
 
-**Announce at start:** "I'm using specflow:build Phase A to rewrite the existing plan into writing-plans precision."
+**Announce at start:** "I'm using specflow:apply Phase A to rewrite the existing propose into writing-plans precision."
 
 **Context:** This should be run in the dedicated worktree created by specflow:refine.
 
 **Plan location (input and output):** `specflow/changes/<change-name>/tasks.md`
-- (User preferences for plan location override this default)
+- (User preferences for propose location override this default)
 
 ## Input Order
 
@@ -22,7 +22,7 @@ Phase A MUST read inputs in the following order before making any analysis decis
 
 1. **Read `design.md`** — this must be finalized (refine phase should have closed any ambiguity). This is the authoritative source of technical decisions: interfaces, error handling strategy, data flow, file structure.
 2. **Read `specs/**/*.md`** (the delta specs for this change) — these are the behavioral requirements. Every spec scenario must map to at least one atomic task.
-3. **Read existing `tasks.md`** — this is the coarse first-iteration plan (from `/specflow:plan`) or the refine-updated version. Its top-level group structure (`## N. <Group Name>`) is the starting point for rewrite.
+3. **Read existing `tasks.md`** — this is the coarse first-iteration propose (from `/specflow:propose`) or the refine-updated version. Its top-level group structure (`## N. <Group Name>`) is the starting point for rewrite.
 4. **Analyze** all three documents jointly, THEN decide one of the 3 outcomes below. Do not start rewriting until you have classified the situation.
 
 ## Three Possible Outcomes
@@ -75,14 +75,14 @@ Old → New mapping:
 Choices:
   A) Accept reorganization — I will rewrite tasks.md using the new groups.
   B) Keep original grouping — I will force writing-plans precision to fit the existing groups.
-  C) I will edit groups manually, then re-run /specflow:build.
+  C) I will edit groups manually, then re-run /specflow:apply.
 ```
 
 **Gate behavior:**
 - Wait for user choice A, B, or C before proceeding. There is no silent default.
 - On **A**: proceed with rewrite using the new group structure, then run Before/After Audit with the new groups reflected.
 - On **B**: proceed with rewrite preserving the original group structure (Outcome 1 path).
-- On **C**: halt Phase A and exit. User will manually edit groups and re-run `/specflow:build` later.
+- On **C**: halt Phase A and exit. User will manually edit groups and re-run `/specflow:apply` later.
 
 ---
 
@@ -113,7 +113,7 @@ Refine may update design.md, specs, or even proposal as needed.
 - Any **already-rewritten atomic tasks** in tasks.md MUST be preserved (do NOT discard).
 - **Not-yet-rewritten tasks** remain in their coarse form from the previous phase (do NOT discard, do NOT stub out).
 - Phase remains `refined` in `.specflow.yaml` (no transition).
-- When user re-runs `/specflow:build` after refine closes the gaps, Phase A re-examines tasks.md and continues rewriting from where it halted — it does not restart from scratch.
+- When user re-runs `/specflow:apply` after refine closes the gaps, Phase A re-examines tasks.md and continues rewriting from where it halted — it does not restart from scratch.
 
 ---
 
@@ -147,7 +147,7 @@ Before finalizing atomic tasks within a group, confirm which files will be creat
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For agentic workers:** REQUIRED SUB-SKILL: Use specflow:build Phase B (recommended) or specflow:build Phase B (inline mode) to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **For agentic workers:** REQUIRED SUB-SKILL: Use specflow:apply Phase B (recommended) or specflow:apply Phase B (inline mode) to implement this propose task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** [One sentence describing what this builds]
 
@@ -204,7 +204,7 @@ Verify: `git log -1 --oneline` shows the new commit
 
 ## Portable `Verify:` commands
 
-A `Verify:` line is only useful if the command actually runs in the target environment and behaves the way the plan predicts. Some test-runner invocations look portable but silently change behavior across language/runtime versions — avoid those.
+A `Verify:` line is only useful if the command actually runs in the target environment and behaves the way the propose predicts. Some test-runner invocations look portable but silently change behavior across language/runtime versions — avoid those.
 
 Concrete rules:
 
@@ -236,11 +236,11 @@ Every step must contain the actual content an engineer needs. These are **plan f
 
 ## Self-Review
 
-After completing the rewrite (before presenting the Before/After audit), look at the spec with fresh eyes and check the rewritten plan against it. This is a checklist you run yourself — not a subagent dispatch.
+After completing the rewrite (before presenting the Before/After audit), look at the spec with fresh eyes and check the rewritten propose against it. This is a checklist you run yourself — not a subagent dispatch.
 
 **1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
 
-**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
+**2. Placeholder scan:** Search your propose for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
 
 **3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks?
 
@@ -280,9 +280,9 @@ After the rewrite is complete and the Before/After audit has been presented:
 **Which approach?"**
 
 **If Subagent-Driven chosen:**
-- **REQUIRED SUB-SKILL:** Use specflow:build Phase B
+- **REQUIRED SUB-SKILL:** Use specflow:apply Phase B
 - Fresh subagent per task + two-stage review (spec + code)
 
 **If Inline Execution chosen:**
-- **REQUIRED SUB-SKILL:** Use specflow:build Phase B (inline mode)
+- **REQUIRED SUB-SKILL:** Use specflow:apply Phase B (inline mode)
 - Batch execution with checkpoints for review

package/prompts/{build → apply}/phase-b-execute.md

@@ -4,7 +4,7 @@
 
 # Subagent-Driven Development (Phase B)
 
-Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
+Execute propose by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
 
 **Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history -- you construct exactly what they need. This also preserves your own context for coordination work.
 
@@ -17,16 +17,16 @@ digraph when_to_use {
     "Have implementation plan?" [shape=diamond];
     "Tasks mostly independent?" [shape=diamond];
     "Stay in this session?" [shape=diamond];
-    "specflow:build Phase B" [shape=box];
-    "specflow:build Phase B (inline mode)" [shape=box];
+    "specflow:apply Phase B" [shape=box];
+    "specflow:apply Phase B (inline mode)" [shape=box];
     "Manual execution or brainstorm first" [shape=box];
 
     "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
     "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
     "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
     "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
-    "Stay in this session?" -> "specflow:build Phase B" [label="yes"];
-    "Stay in this session?" -> "specflow:build Phase B (inline mode)" [label="no - parallel session"];
+    "Stay in this session?" -> "specflow:apply Phase B" [label="yes"];
+    "Stay in this session?" -> "specflow:apply Phase B (inline mode)" [label="no - parallel session"];
 }
 ```
 
@@ -60,7 +60,7 @@ digraph process {
     "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
     "More tasks remain?" [shape=diamond];
     "Dispatch final code reviewer subagent for entire implementation" [shape=box];
-    "Use specflow:done" [shape=box style=filled fillcolor=lightgreen];
+    "Use specflow:archive" [shape=box style=filled fillcolor=lightgreen];
 
     "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent\n(Read .claude/specflow/prompts/shared/implementer-prompt.md)";
     "Dispatch implementer subagent\n(Read .claude/specflow/prompts/shared/implementer-prompt.md)" -> "Implementer subagent asks questions?";
@@ -79,7 +79,7 @@ digraph process {
     "Mark task complete in TodoWrite" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent\n(Read .claude/specflow/prompts/shared/implementer-prompt.md)" [label="yes"];
     "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
-    "Dispatch final code reviewer subagent for entire implementation" -> "Use specflow:done";
+    "Dispatch final code reviewer subagent for entire implementation" -> "Use specflow:archive";
 }
 ```
 
@@ -87,7 +87,7 @@ digraph process {
 
 Use the least powerful model that can handle each role to conserve cost and increase speed.
 
-**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
+**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the propose is well-specified.
 
 **Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
 
@@ -112,7 +112,7 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 1. If it's a context problem, provide more context and re-dispatch with the same model
 2. If the task requires more reasoning, re-dispatch with a more capable model
 3. If the task is too large, break it into smaller pieces
-4. If the plan itself is wrong, escalate to the human
+4. If the propose itself is wrong, escalate to the human
 
 **Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
 
@@ -125,9 +125,9 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 ## Example Workflow
 
 ```
-You: I'm using specflow:build Phase B to execute this plan.
+You: I'm using specflow:apply Phase B to execute this plan.
 
-[Read plan file once: specflow/changes/<change-name>/tasks.md]
+[Read propose file once: specflow/changes/<change-name>/tasks.md]
 [Extract all 5 tasks with full text and context]
 [Create TodoWrite with all tasks]
 
@@ -237,7 +237,7 @@ Done!
 - Skip reviews (spec compliance OR code quality)
 - Proceed with unfixed issues
 - Dispatch multiple implementation subagents in parallel (conflicts)
-- Make subagent read plan file (provide full text instead)
+- Make subagent read propose file (provide full text instead)
 - Skip scene-setting context (subagent needs to understand where task fits)
 - Ignore subagent questions (answer before letting them proceed)
 - Accept "close enough" on spec compliance (spec reviewer found issues = not done)
@@ -264,13 +264,13 @@ Done!
 ## Integration
 
 **Required workflow skills:**
-- **specflow:build Phase B (worktree)** - REQUIRED: Set up isolated workspace before starting
-- **specflow:build Phase A** - Creates the plan this skill executes
+- **specflow:apply Phase B (worktree)** - REQUIRED: Set up isolated workspace before starting
+- **specflow:apply Phase A** - Creates the propose this skill executes
 - **specflow:review** - Code review template for reviewer subagents
-- **specflow:done** - Complete development after all tasks
+- **specflow:archive** - Complete development after all tasks
 
 **Subagents should use:**
-- **specflow:build TDD** - Subagents follow TDD for each task
+- **specflow:apply TDD** - Subagents follow TDD for each task
 
 **Alternative workflow:**
-- **specflow:build Phase B (inline mode)** - Use for parallel session instead of same-session execution
+- **specflow:apply Phase B (inline mode)** - Use for parallel session instead of same-session execution

package/prompts/{build → apply}/phase-b-review.md

@@ -2,7 +2,7 @@
 
 # Two-Phase Review Routing
 
-Orchestration for the two-phase review process used during specflow:build Phase B. Each task's implementation goes through spec compliance first, then code quality.
+Orchestration for the two-phase review process used during specflow:apply Phase B. Each task's implementation goes through spec compliance first, then code quality.
 
 ## Overview
 
@@ -40,7 +40,7 @@ Task tool (general-purpose):
 
 ## Phase 2: Code Quality Review
 
-**Prompt source:** Read the `ReviewerFile` session context set after Stage B1b. Mapping details live in `.claude/specflow/prompts/build/language-router.md`. When `Language` is `unknown`, fall back to `.claude/specflow/prompts/shared/code-reviewer-prompt.md`.
+**Prompt source:** Read the `ReviewerFile` session context set after Stage B1b. Mapping details live in `.claude/specflow/prompts/apply/language-router.md`. When `Language` is `unknown`, fall back to `.claude/specflow/prompts/shared/code-reviewer-prompt.md`.
 
 **Purpose:** Verify the implementation is well-built -- clean, tested, maintainable, and language-appropriate when an ECC reviewer is selected.
 

package/prompts/{build → apply}/phase-b-worktree.md

@@ -207,9 +207,9 @@ Ready to implement auth feature
 
 **Called by:**
 - **specflow:refine** (Phase 4) - REQUIRED when design is approved and implementation follows
-- **specflow:build Phase B** - REQUIRED before executing any tasks
-- **specflow:build Phase B (inline mode)** - REQUIRED before executing any tasks
+- **specflow:apply Phase B** - REQUIRED before executing any tasks
+- **specflow:apply Phase B (inline mode)** - REQUIRED before executing any tasks
 - Any skill needing isolated workspace
 
 **Pairs with:**
-- **specflow:done** - REQUIRED for cleanup after work complete
+- **specflow:archive** - REQUIRED for cleanup after work complete

package/prompts/{build → apply}/plan-document-reviewer.md

@@ -2,17 +2,17 @@
 
 # Plan Document Reviewer Prompt Template
 
-Use this template when dispatching a plan document reviewer subagent.
+Use this template when dispatching a propose document reviewer subagent.
 
-**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.
+**Purpose:** Verify the propose is complete, matches the spec, and has proper task decomposition.
 
-**Dispatch after:** The complete plan is written.
+**Dispatch after:** The complete propose is written.
 
 ```
 Task tool (general-purpose):
-  description: "Review plan document"
+  description: "Review propose document"
   prompt: |
-    You are a plan document reviewer. Verify this plan is complete and ready for implementation.
+    You are a propose document reviewer. Verify this propose is complete and ready for implementation.
 
     **Plan to review:** [PLAN_FILE_PATH]
     **Spec for reference:** [SPEC_FILE_PATH]
@@ -24,7 +24,7 @@ Task tool (general-purpose):
     | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
     | Spec Alignment | Plan covers spec requirements, no major scope creep |
     | Task Decomposition | Tasks have clear boundaries, steps are actionable |
-    | Buildability | Could an engineer follow this plan without getting stuck? |
+    | Buildability | Could an engineer follow this propose without getting stuck? |
 
     ## Calibration
 

package/prompts/{build → apply}/tdd.md

@@ -4,7 +4,7 @@
 
 # Test-Driven Development (Build Variant)
 
-Per-task atomic TDD for the build phase. Each task in the plan follows Red-Green-Refactor strictly.
+Per-task atomic TDD for the apply phase. Each task in the rewritten plan follows Red-Green-Refactor strictly.
 
 ## Overview
 
@@ -16,7 +16,7 @@ Write the test first. Watch it fail. Write minimal code to pass.
 
 ## When to Use
 
-**Always during build phase tasks:**
+**Always during apply phase tasks:**
 - Each task in the implementation plan
 - Bug fixes discovered during implementation
 - Behavior changes within a task
@@ -124,7 +124,7 @@ Next failing test for next behavior in the task.
 
 ## Per-Task Commit Pattern
 
-Each task in the plan should follow this atomic cycle:
+Each task in the propose should follow this atomic cycle:
 
 1. Write failing test for first behavior -> verify RED
 2. Write minimal implementation -> verify GREEN

package/prompts/{done → archive}/branch-finish.md

@@ -8,7 +8,7 @@ Guide completion of development work by presenting clear options and handling ch
 
 **Core principle:** Verify tests -> Present options -> Execute choice -> Clean up.
 
-**Announce at start:** "I'm using specflow:done to complete this work."
+**Announce at start:** "I'm using specflow:archive to complete this work."
 
 ## The Process
 
@@ -197,8 +197,8 @@ git worktree remove <worktree-path>
 ## Integration
 
 **Called by:**
-- **specflow:build Phase B** (final step) - After all tasks complete
-- **specflow:build Phase B (inline mode)** (final step) - After all batches complete
+- **specflow:apply Phase B** (final step) - After all tasks complete
+- **specflow:apply Phase B (inline mode)** (final step) - After all batches complete
 
 **Pairs with:**
-- **specflow:build Phase B (worktree)** - Cleans up worktree created by that skill
+- **specflow:apply Phase B (worktree)** - Cleans up worktree created by that skill

package/prompts/explore/explore-session.md

@@ -0,0 +1,152 @@
+> **HARD GATE**: Do NOT write proposal, specs, design, tasks, or code during explore. Only `explore.md` is allowed output.
+
+<!-- SOURCE: OpenSpec docs/explore.md (conversation-first exploration) + Superpowers brainstorming (options, trade-offs, YAGNI) -->
+
+# Explore Session: Think Before Propose
+
+> This prompt is for **from-scratch exploration** when requirements are fuzzy.
+> NOT refine-phase brainstorming (that attacks existing propose artifacts).
+
+## Purpose
+
+Turn a vague worry into a sharp, buildable direction **before** any contract artifacts exist.
+
+Explore is a **conversation** that may read the codebase, compare options, and narrow scope. It commits you to nothing except the final `explore.md` the user confirms.
+
+## When to Explore
+
+Explore when any of these is true:
+
+- You know the **problem** but not the **solution**
+- You are choosing between approaches and want tradeoffs against real code
+- You are new to an area of the codebase
+- Requirements are fuzzy and need sharpening
+- Scope feels too big or too small
+- You're stuck during apply or refine on a sub-decision and need to compare options before continuing
+
+Skip explore when you already know exactly what to build — go straight to propose.
+
+## Process
+
+### Step 1 — Bring the problem, not the solution
+
+Ask the user to state the problem in their own words. Prefer:
+
+- "Checkout sometimes creates duplicate orders" ✅
+- "Add Redis cache" ❌ (pre-commits to an answer)
+
+If the user leads with a solution, reflect it back as a hypothesis and ask what problem it solves.
+
+### Step 2 — Investigate (OpenSpec explore)
+
+Before proposing fixes, **read the relevant code** when a codebase exists:
+
+- Search and read files on the critical path
+- Summarize what exists today in plain language
+- Name root causes or constraints tied to actual code — do not guess
+
+Present findings as:
+
+```markdown
+## What I Found
+- ...
+## Implications
+- ...
+```
+
+Use diagrams (mermaid or ascii) when they clarify architecture or flow.
+
+### Step 3 — Clarifying questions (Superpowers brainstorming)
+
+Ask **one question at a time**. Prefer multiple-choice when options are enumerable.
+
+Cover at least:
+
+1. **Who / what pain** — who is affected and what breaks today?
+2. **Success signal** — how will we know this worked? (measurable if possible)
+3. **Boundaries** — permissions, failure modes, non-functional concerns
+4. **Scope** — too broad, too narrow, or should split into multiple changes?
+
+Inject **YAGNI**: flag features that sound nice but are not required for the stated problem.
+
+### Step 4 — Propose 2–3 approaches
+
+For each non-trivial decision, present **at least 2 genuinely different options** (not cosmetic variants):
+
+| Option | Pros | Cons | Best when |
+|--------|------|------|-----------|
+| A | ... | ... | ... |
+| B | ... | ... | ... |
+
+Include a **recommended direction** with rationale tied to findings from Step 2.
+
+If exploration reveals the idea is not worth building, say so — that is a valid outcome. Offer to stop or narrow scope.
+
+### Step 5 — Draft explore.md
+
+Load the scaffold from `.claude/specflow/templates/explore.md` and write `specflow/changes/<name>/explore.md` using the exact sections below.
+
+### Step 6 — Gate: Direction confirmation (HARD GATE)
+
+Present a summary and ask explicitly:
+
+> "Confirm this explored direction so I can hand off to `/specflow:propose`? (yes / revise / abandon)"
+
+- **yes** → proceed to handoff
+- **revise** → update explore.md and re-present
+- **abandon** → note outcome; do not run propose
+
+Do NOT proceed to propose inside this skill unless the user confirms.
+
+## explore.md Format (CRITICAL)
+
+Use `templates/explore.md` as the scaffold (runtime: `.claude/specflow/templates/explore.md`). Section structure:
+
+```markdown
+# Explore: <change-name>
+
+**Status**: confirmed | draft
+**Explored**: YYYY-MM-DD
+
+## Problem Space
+<!-- Who / pain + Success signal -->
+
+## Evidence
+
+## What Exists Today
+### What I Found
+### Implications
+
+## Options Considered
+### Option A / B / (optional C) — Pros / Cons / Best when
+
+## Recommended Direction
+
+## MVP Scope
+
+## Non-Goals
+
+## Suggested Capabilities
+
+## Open Questions
+
+## Handoff Notes
+<!-- propose mapping hints -->
+```
+
+Do not omit sections without reason; for greenfield, leave **What Exists Today** empty or note "greenfield — no baseline code".
+
+## Tips for a Good Exploration
+
+- **Bring the problem, not the solution.** Redirect premature solutioning to investigation.
+- **Let it read first.** Point the AI at the relevant code path when helpful.
+- **It's okay to bail.** If the idea isn't worth building, say so — that is a valid outcome.
+- **Explore again mid-change.** Stuck during `/specflow:apply` or `/specflow:refine`? Re-run explore for the sub-problem, update `explore.md`, confirm, then return to the paused workflow.
+
+## Handoff to Propose
+
+After confirmation, tell the user:
+
+> Explore saved to `specflow/changes/<name>/explore.md`. Run `/specflow:propose` — propose will read explore.md and synthesize proposal without repeating resolved Q&A.
+
+Do NOT generate proposal, specs, design, or tasks in explore.

package/prompts/fix/debug.md

@@ -158,7 +158,7 @@ You MUST complete each phase before proceeding to the next.
    - Automated test if possible
    - One-off test script if no framework
    - MUST have before fixing
-   - Use specflow:test or specflow:build TDD for writing proper failing tests
+   - Use specflow:test or specflow:apply TDD for writing proper failing tests
 
 2. **Implement Single Fix**
    - Address the root cause identified
@@ -237,7 +237,7 @@ If you catch yourself thinking:
 
 ## Related Skills
 
-- **specflow:test** or **specflow:build TDD** - For creating failing test case (Phase 4, Step 1)
+- **specflow:test** or **specflow:apply TDD** - For creating failing test case (Phase 4, Step 1)
 - **specflow:verify** - Verify fix worked before claiming success
 
 ## Real-World Impact

package/prompts/{plan → propose}/design-draft.md

@@ -111,7 +111,7 @@ Save the document to:
 specflow/changes/<change-name>/design.md
 ```
 
-**Do NOT ask the user to confirm this draft at this stage.** The end-of-plan summary (handled by the orchestrating SKILL) will present all four plan-phase artifacts together for one cohesive user review. Write the best first-iteration design you can, save it, and move on to the next plan-phase artifact.
+**Do NOT ask the user to confirm this draft at this stage.** The end-of-propose summary (handled by the orchestrating SKILL) will present all four plan-phase artifacts together for one cohesive user review. Write the best first-iteration design you can, save it, and move on to the next plan-phase artifact.
 
 ## Remember
 

package/prompts/{plan → propose}/proposal.md

@@ -23,6 +23,36 @@ ls specflow/specs/ 2>/dev/null
 **If no specs exist:**
 - This is a greenfield change; note that no baseline specs need to be considered
 
+### Step 1.5: Explore Handoff (if explore.md exists)
+
+Check for a confirmed exploration artifact:
+
+```bash
+cat specflow/changes/<change-name>/explore.md 2>/dev/null
+```
+
+**If `explore.md` exists with `Status: confirmed`:**
+
+1. Read it completely before asking any proposal questions
+2. Do NOT re-ask topics already resolved in explore
+3. Synthesize `proposal.md` using this mapping:
+
+| explore.md section | proposal.md section |
+|--------------------|---------------------|
+| Problem Space + Evidence | `## Why` |
+| Recommended Direction + MVP Scope | `## What Changes` |
+| Suggested Capabilities | `## Capabilities` |
+| Non-Goals + Open Questions (impact) | `## Impact` |
+
+4. Only ask the user about items under **Open Questions** (one at a time)
+5. Present the mapping summary before writing: "explore §X → proposal §Y"
+
+**If `explore.md` exists but `Status: draft`:**
+
+- Stop and tell the user to finish `/specflow:explore` confirmation first
+
+**If no `explore.md`:** proceed to Step 2 (standard Q&A). If the user's request is still vague, suggest `/specflow:explore` before continuing.
+
 ### Step 2: Gather Proposal Information
 
 Ask the user (one question at a time):

package/prompts/{plan → propose}/specs.md

@@ -111,4 +111,4 @@ Save each spec file. Then present a summary:
 
 ## Next Step
 
-Once delta specs are approved, proceed to `/specflow:refine` for design work or `/specflow:build` for planning.
+Once delta specs are approved, proceed to `/specflow:refine` for design work or `/specflow:apply` for planning.