@gordon.gan/specflow 1.0.0 → 1.0.2

package/skills/{specflow-done → specflow-archive}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: specflow-done
+name: specflow-archive
 description: "Archive change + merge specs + git branch cleanup"
 ---
 
-# SpecFlow: Done
+# SpecFlow: Archive
 
 > **HARD GATE**: Tests must pass before archive options are presented.
 
@@ -11,11 +11,11 @@ description: "Archive change + merge specs + git branch cleanup"
 
 - An active change must exist with completed implementation.
 - `specflow` CLI must be available on PATH.
-- **Phase must be `built`** in `.specflow.yaml`. This is set automatically when `/specflow:build` Phase B completes. `specflow change archive` refuses to archive changes whose phase is not `built` unless the caller passes `--force` explicitly. Do NOT pass `--force` from this skill — the flag is reserved for explicit user discretion. If archive fails with a phase check error, route the user back to `/specflow:build` to complete the missing phase transition rather than forcing past the guard.
+- **Phase must be `built`** in `.specflow.yaml`. This is set automatically when `/specflow:apply` Phase B completes. `specflow change archive` refuses to archive changes whose phase is not `built` unless the caller passes `--force` explicitly. Do NOT pass `--force` from this skill — the flag is reserved for explicit user discretion. If archive fails with a phase check error, route the user back to `/specflow:apply` to complete the missing phase transition rather than forcing past the guard.
 
 ## Stage 1: Test Gate
 
-Run the project test suite for all affected modules. If implementation was done in a git worktree (common after `/specflow:build`), run tests inside that worktree.
+Run the project test suite for all affected modules. If implementation was done in a git worktree (common after `/specflow:apply`), run tests inside that worktree.
 
 If tests fail:
 - Report failures to the user.
@@ -30,7 +30,7 @@ All tests must pass. Only proceed once green.
 
 If implementation happened on a feature branch / worktree, finish the branch FIRST so the main branch is clean before `specflow change archive` writes its outputs.
 
-Read the file at `.claude/specflow/prompts/done/branch-finish.md` and follow its instructions to:
+Read the file at `.claude/specflow/prompts/archive/branch-finish.md` and follow its instructions to:
 - Detect the base branch
 - Present 4 options to the user:
   1. **Merge to base branch** — merge the feature branch (no-ff or squash), delete branch, remove worktree

package/skills/specflow-explore/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: specflow-explore
+description: "Think-before-propose exploration — problem space, options, scope (OpenSpec explore + Superpowers brainstorming)"
+---
+
+# SpecFlow: Explore
+
+> **HARD GATE**: User must confirm explored direction before handoff to propose.
+> **NOT refine**: From-scratch exploration when requirements are fuzzy. Refine attacks existing propose artifacts.
+
+## Purpose
+
+Explore is the **think-before-propose** pass: investigate the problem, read relevant code, compare options, and narrow scope — then capture the outcome in `explore.md` for `/specflow:propose` to consume.
+
+Integrates:
+
+- **OpenSpec `/opsx:explore`** — conversation-first, read codebase, compare tradeoffs, no contract artifacts
+- **Superpowers `brainstorming`** — one-question-at-a-time, 2–3 options with pros/cons, YAGNI, recommended direction
+
+## When to Use
+
+Use explore when:
+
+- You know the problem but not the solution
+- Requirements are fuzzy or scope is uncertain
+- You need to investigate the codebase before committing to a change
+- You want to compare architectural options with tradeoffs
+
+Skip explore when you already know exactly what to build — run `/specflow:propose` directly.
+
+## Prerequisites
+
+- `specflow/` exists (suggest `specflow init` if missing)
+- `specflow` CLI available on PATH
+
+## Stage 1: Create or Reuse Change
+
+If no active change directory exists for this work:
+
+```bash
+specflow change new <name>
+```
+
+The CLI sets `phase=plan` in `.specflow.yaml`. Explore does not change phase — `explore.md` with `Status: confirmed` signals that exploration completed.
+
+If `explore.md` already exists and is confirmed, suggest `/specflow:propose` instead of re-exploring unless the user wants to revise.
+
+If `proposal.md` already exists, explore is too late — suggest `/specflow:refine` for deepening.
+
+## Also Valid: Re-explore Mid-Change
+
+If stuck during `/specflow:apply` or `/specflow:refine` on a sub-problem, run explore again for that scoped decision. Update `explore.md` with the new findings, confirm direction, then return to the paused workflow. Do NOT skip refine or apply phase gates for the main change.
+
+## Stage 2: Run Exploration Session
+
+Read the file at `.claude/specflow/prompts/explore/explore-session.md` and follow its instructions.
+
+Key behaviors:
+
+1. **Bring the problem, not the solution** — redirect premature solutioning
+2. **Read the codebase** on the relevant path before recommending
+3. **Ask clarifying questions** one at a time (Superpowers style)
+4. **Propose 2–3 approaches** with tradeoffs and a recommendation
+5. **Allow bail-out** if the idea is not worth building
+
+Do NOT write proposal, specs, design, tasks, or implementation code during explore.
+
+## Stage 3: Write explore.md
+
+Save to: `specflow/changes/<name>/explore.md`
+
+Start from the template at `.claude/specflow/templates/explore.md` (package source: `templates/explore.md`). Use the exact section structure defined in `explore-session.md`. Set `Status: draft` while iterating; set `Status: confirmed` only after the user confirms in Stage 4.
+
+## Gate: Direction Confirmation (HARD GATE)
+
+Present a concise summary:
+
+- Problem in one line
+- Recommended direction
+- MVP scope and non-goals
+- Suggested capabilities for propose
+
+Ask explicitly:
+
+> "Confirm this explored direction for handoff to `/specflow:propose`?"
+
+Do NOT mark `Status: confirmed` or suggest propose until the user explicitly confirms.
+
+## Stage 4: Handoff
+
+On confirmation:
+
+1. Update `explore.md` → `Status: confirmed`
+2. Tell the user to run `/specflow:propose` (same change name)
+3. Explain that propose will read `explore.md` and skip Q&A already resolved there
+
+## Not Covered by Explore
+
+- No proposal/specs/design/tasks (propose owns those)
+- No multi-round artifact attack (refine owns that)
+- No implementation (apply owns that)
+- No CLI beyond `change new` (explore is AI-orchestrated)

package/skills/specflow-fix/SKILL.md

@@ -34,7 +34,7 @@ Perform root-cause analysis:
 
 ## Stage 4: TDD Fix
 
-Read the file at `.claude/specflow/prompts/build/tdd.md` and follow its instructions.
+Read the file at `.claude/specflow/prompts/apply/tdd.md` and follow its instructions.
 
 1. Write a failing test that reproduces the bug
 2. Implement the minimal fix to pass the test
@@ -63,7 +63,7 @@ If the fix addresses a genuinely new scenario that existing specs did not cover,
 
 Before archive, invoke `specflow change phase fix-<desc> --set built` to mark the fix as built.
 
-Rationale: a fix change is created with `phase=plan` (same as any other change) but the fix flow covers the equivalent of the plan → refine → build pipeline end-to-end inside Stages 3–6 (debug → TDD → review → verify). Archive rejects non-`built` phases unless `--force` is passed, so setting the phase explicitly here keeps the guard meaningful without needing `--force`.
+Rationale: a fix change is created with `phase=plan` (same as any other change) but the fix flow covers the equivalent of the propose → refine → apply pipeline end-to-end inside Stages 3–6 (debug → TDD → review → verify). Archive rejects non-`built` phases unless `--force` is passed, so setting the phase explicitly here keeps the guard meaningful without needing `--force`.
 
 ### Stage 7b: Run Archive
 

package/skills/{specflow-plan → specflow-propose}/SKILL.md

@@ -1,15 +1,15 @@
 ---
-name: specflow-plan
+name: specflow-propose
 description: "First-iteration deep analysis -- proposal + specs + design + tasks"
 ---
 
-# SpecFlow: Plan
+# SpecFlow: Propose
 
 > **HARD GATE**: User must confirm proposal before specs generation.
 
 ## Purpose
 
-Plan is the **first-iteration deep-analysis pass**: in a single invocation it produces all four change artifacts (`proposal.md`, delta `specs/`, `design.md`, `tasks.md`). The design and tasks are substantive first drafts — not placeholders — but `/specflow:refine` will later rewrite them across multiple rounds of iteration, and `/specflow:build` Phase A will regenerate `tasks.md` under strict writing-plans rules.
+Propose is the **first-iteration deep-analysis pass**: in a single invocation it produces all four change artifacts (`proposal.md`, delta `specs/`, `design.md`, `tasks.md`). The design and tasks are substantive first drafts — not placeholders — but `/specflow:refine` will later rewrite them across multiple rounds of iteration, and `/specflow:apply` Phase A will regenerate `tasks.md` under strict writing-plans rules.
 
 Treat every artifact here as "v1, to be iterated on" — depth matters, but so does moving through all four stages in one pass.
 
@@ -18,6 +18,33 @@ Treat every artifact here as "v1, to be iterated on" — depth matters, but so d
 - `specflow/specs/` directory should exist, indicating this is a specflow-initialized project. For a brand-new greenfield change with no existing specs, proceed — the prompt handles that case. If `specflow/` itself does not exist, suggest running `specflow init` first.
 - `specflow` CLI must be available on PATH.
 
+## Stage 0: Explore Handoff (when explore.md exists)
+
+Before creating a new change or generating a proposal, check for an existing exploration artifact:
+
+```bash
+ls specflow/changes/<name>/explore.md 2>/dev/null
+```
+
+**If `explore.md` exists with `Status: confirmed`:**
+
+1. Read `specflow/changes/<name>/explore.md` completely
+2. Do NOT re-ask questions already answered in explore (Problem Space, Options, Recommended Direction, MVP, Non-Goals)
+3. Map explore sections → proposal sections (see `prompts/propose/proposal.md` Step 1.5)
+4. Only ask clarifying questions for items listed under **Open Questions**
+5. Announce the handoff: "Reading confirmed explore.md — synthesizing proposal from explored direction"
+
+**If `explore.md` exists with `Status: draft`:**
+
+- REFUSE to proceed with proposal generation
+- Tell the user to finish `/specflow:explore` and confirm direction first
+
+**If requirements seem fuzzy and `explore.md` does NOT exist:**
+
+- Suggest `/specflow:explore` first, but do NOT block if the user insists on planning directly
+
+**If `proposal.md` already exists:** skip Stage 0.
+
 ## Stage 1: Create Change
 
 Run `specflow change new <name>` to initialize a new change directory.
@@ -26,7 +53,7 @@ The CLI automatically sets `phase=plan` in `.specflow.yaml` on creation (no sepa
 
 ## Stage 2: Generate Proposal
 
-Read the file at `.claude/specflow/prompts/plan/proposal.md` and follow its instructions.
+Read the file at `.claude/specflow/prompts/propose/proposal.md` and follow its instructions.
 
 **Important**: That prompt file contains the required interactive Q&A flow, the exact proposal format (`## Why` / `## What Changes` / `## Capabilities` / `## Impact`), and the user confirmation gate. You MUST read it before writing the proposal — do not invent the format.
 
@@ -36,11 +63,11 @@ Generate the proposal document inside the change directory at `specflow/changes/
 
 Present the proposal to the user.
 **Ask the user to confirm the proposal.**
-Do NOT proceed to specs generation until the user explicitly confirms. This is the only mandatory hard gate in the plan flow — everything that follows flows through without interruption so the user can review the full first-iteration package at the end.
+Do NOT proceed to specs generation until the user explicitly confirms. This is the only mandatory hard gate in the propose flow — everything that follows flows through without interruption so the user can review the full first-iteration package at the end.
 
 ## Stage 3: Generate Specs
 
-Read the file at `.claude/specflow/prompts/plan/specs.md` and follow its instructions.
+Read the file at `.claude/specflow/prompts/propose/specs.md` and follow its instructions.
 
 Generate delta specs inside the change directory at `specflow/changes/<name>/specs/<capability>/spec.md`.
 
@@ -50,7 +77,7 @@ Briefly summarize the delta specs generated. Accept a quick acknowledgement from
 
 ## Stage 4: Generate Design (first-iteration)
 
-Read the file at `.claude/specflow/prompts/plan/design-draft.md` and follow its instructions.
+Read the file at `.claude/specflow/prompts/propose/design-draft.md` and follow its instructions.
 
 Generate `design.md` inside the change directory. This draft should be substantive: identify real architectural decisions, capture options considered, and record rationale. It is a first iteration — `/specflow:refine` will deepen it through multiple brainstorming rounds — but it is NOT a placeholder.
 
@@ -58,9 +85,9 @@ Generate `design.md` inside the change directory. This draft should be substanti
 
 ## Stage 5: Generate Tasks (first-iteration)
 
-Read the file at `.claude/specflow/prompts/plan/tasks-draft.md` and follow its instructions.
+Read the file at `.claude/specflow/prompts/propose/tasks-draft.md` and follow its instructions.
 
-Generate `tasks.md` inside the change directory. Produce a substantive first-iteration task breakdown (3–8 tasks typical), ordered with dependencies. Do not write placeholders like "TBD" or "implement feature". `/specflow:build` Phase A will rewrite this file under strict writing-plans rules, but this first draft feeds both `/specflow:refine` context and Phase A analysis.
+Generate `tasks.md` inside the change directory. Produce a substantive first-iteration task breakdown (3–8 tasks typical), ordered with dependencies. Do not write placeholders like "TBD" or "implement feature". `/specflow:apply` Phase A will rewrite this file under strict writing-plans rules, but this first draft feeds both `/specflow:refine` context and Phase A analysis.
 
 **No gate here.** Continue directly to Stage 6.
 
@@ -71,12 +98,12 @@ Present all four artifacts to the user with clear "first-iteration" labeling:
 - `proposal.md` — confirmed in Stage 2
 - Delta `specs/` under the change directory — the contract
 - `design.md` — **first-iteration draft**; `/specflow:refine` will deepen this across multiple rounds
-- `tasks.md` — **first-iteration draft**; `/specflow:build` Phase A will rewrite this under strict writing-plans rules
+- `tasks.md` — **first-iteration draft**; `/specflow:apply` Phase A will rewrite this under strict writing-plans rules
 
 Make the iteration expectation explicit: the user should not treat design/tasks as final. They are deliberate first drafts produced so downstream skills have real substance to work with.
 
 ### Next Step
 
-Suggest `/specflow:refine` to enter the multi-round refinement loop that rewrites `design.md` (and optionally updates the other artifacts) based on brainstorming. After refine completes, `/specflow:build` will consume the refined artifacts.
+Suggest `/specflow:refine` to enter the multi-round refinement loop that rewrites `design.md` (and optionally updates the other artifacts) based on brainstorming. After refine completes, `/specflow:apply` will consume the refined artifacts.
 
 No hard gate after Stage 6 — `/specflow:refine` owns the next overall validation gate.

package/skills/specflow-refine/SKILL.md

@@ -24,7 +24,7 @@ emits a round diff summary.
   - `tasks.md`
 - `specflow` CLI available on PATH (for `specflow validate` and the final phase transition).
 
-If any precondition fails, stop and instruct the user to run `/specflow:plan` first.
+If any precondition fails, stop and instruct the user to run `/specflow:propose` first.
 
 ## Stage 1: Pre-loop setup
 
@@ -115,7 +115,7 @@ Only reached after Stage 5 declared convergence AND the user did not request ano
    the phase as `refined`?"
 3. On explicit confirmation: invoke `specflow change phase <name> --set refined` to
    advance `.specflow.yaml` `phase` from `plan` to `refined`.
-4. Suggest `/specflow:build` as the next slash command.
+4. Suggest `/specflow:apply` as the next slash command.
 
 If the user declines to confirm and requests more exploration, treat it as a user-requested
 extra round (loop back to Stage 2, phase stays `plan`).
@@ -123,6 +123,6 @@ extra round (loop back to Stage 2, phase stays `plan`).
 ## Not covered by refine
 
 - No Phase A rewriting of `tasks.md` at writing-plans precision — that belongs to
-  `/specflow:build` Phase A.
-- No code scaffolding, no implementation, no worktree setup — build owns all of that.
+  `/specflow:apply` Phase A.
+- No code scaffolding, no implementation, no worktree setup — apply owns all of that.
 - Refine only updates artifacts and advances phase to `refined`; it never touches code.

package/skills/specflow-verify/SKILL.md

@@ -57,7 +57,7 @@ When Pass 1–3 all PASS:
 
 **Pass 4 verdict rules:**
 - Any CRITICAL finding → overall verify verdict is `FAIL`
-- Only HIGH findings (no CRITICAL) → overall verify verdict is `PASS with warnings`; list HIGH findings and require user acknowledgement before `/specflow:done`
+- Only HIGH findings (no CRITICAL) → overall verify verdict is `PASS with warnings`; list HIGH findings and require user acknowledgement before `/specflow:archive`
 - No CRITICAL or HIGH findings → overall verify verdict remains `PASS`
 
 ## Stage 3: Report

package/templates/explore.md

@@ -0,0 +1,89 @@
+# Explore: <change-name>
+
+<!-- SOURCE: OpenSpec /opsx:explore (conversation-first, read codebase) + Superpowers brainstorming (options, YAGNI) + SpecFlow propose handoff mapping -->
+<!-- Fill during /specflow:explore. Set Status: confirmed only after user confirms direction. -->
+
+**Status**: draft
+**Explored**: YYYY-MM-DD
+
+## Problem Space
+
+<!-- Who is affected? What breaks today? Cost of inaction if we do nothing? -->
+<!-- Prefer problem statements ("checkout duplicates orders") over pre-committed solutions ("add Redis"). -->
+
+**Who / pain:**
+<!-- e.g. ops team, end users checking out -->
+
+**Success signal:**
+<!-- How will we know this worked? Measurable if possible. -->
+
+## Evidence
+
+<!-- User quotes, metrics, logs, support tickets — or tag assumptions explicitly: -->
+<!-- Assumption — needs validation via ... -->
+
+## What Exists Today
+
+<!-- Summary from codebase investigation. Omit this section entirely for greenfield. -->
+<!-- OpenSpec explore Step 2: read critical path before recommending. -->
+
+### What I Found
+
+<!-- Plain-language summary of relevant code, data flow, constraints -->
+
+### Implications
+
+<!-- Root causes, coupling, risks tied to actual code — do not guess without reading -->
+
+## Options Considered
+
+<!-- At least 2 genuinely different approaches (not cosmetic variants). Include YAGNI flags for nice-to-haves. -->
+
+### Option A: <short name>
+
+- **Pros**:
+- **Cons**:
+- **Best when**:
+
+### Option B: <short name>
+
+- **Pros**:
+- **Cons**:
+- **Best when**:
+
+### Option C: <short name> (optional)
+
+- **Pros**:
+- **Cons**:
+- **Best when**:
+
+## Recommended Direction
+
+<!-- Chosen path and why it beat alternatives. Tie rationale to Evidence / What Exists Today. -->
+<!-- If exploration shows the idea is not worth building, say so here and stop — valid outcome. -->
+
+## MVP Scope
+
+<!-- Minimum slice to test the hypothesis. Smallest change that validates direction. -->
+
+## Non-Goals
+
+<!-- Explicit exclusions. Flag features that sound nice but are not required for the stated problem (YAGNI). -->
+
+## Suggested Capabilities
+
+<!-- kebab-case names for propose → proposal ## Capabilities. One bullet per capability. -->
+- `<capability>`: <brief description>
+
+## Open Questions
+
+<!-- Items for plan/refine to resolve. Do not leave empty if unknowns remain. -->
+- [ ] <question propose should ask>
+
+## Handoff Notes
+
+<!-- Optional hints for propose Step 1.5 mapping: -->
+<!-- Problem Space + Evidence → proposal ## Why -->
+<!-- Recommended Direction + MVP Scope → proposal ## What Changes -->
+<!-- Suggested Capabilities → proposal ## Capabilities -->
+<!-- Non-Goals + Open Questions (impact) → proposal ## Impact -->

package/skills/specflow-scan/SKILL.md

@@ -1,48 +0,0 @@
----
-name: specflow-scan
-description: "[PLANNED v0.3] Brownfield project scanner -- not yet functional"
----
-
-# SpecFlow: Scan (Planned — v0.3)
-
-> **NOT YET FUNCTIONAL.** The `specflow scan` CLI subcommand does not exist in v0.2.x. Invoking this skill would immediately fail when it tries to run `specflow scan`. The skill is kept registered so its slot is reserved in the command namespace; the implementation is planned for v0.3.
-
-## Behavior in v0.2.x
-
-If the user triggers `/specflow:scan` or `$specflow-scan`, do NOT attempt to run `specflow scan` (the CLI will return an unknown-command error). Instead respond:
-
-> "`/specflow:scan` / `$specflow-scan` is planned for v0.3 and not yet implemented in v0.2.x. For a brownfield project that has no `specflow/specs/` baseline yet, the workable alternative today is:
->
-> 1. Run `specflow init --ide both` (or `--ide all` / `--ide codex`) if not already done (creates `specflow/` and IDE assets under `.cursor/`, `.claude/`, and/or `.agents/`).
-> 2. Identify one capability area you are about to change (e.g. `user-auth`, `billing`).
-> 3. Run `/specflow:plan` or `$specflow-plan \"<your change description>\"` directly. In the proposal Q&A, describe the existing behavior in the affected area — plan will generate both the delta spec for your change and an implicit first pass at the capability's contract. After the first archive, the delta becomes the main spec baseline for that capability.
->
-> This is not a perfect substitute for a full code scan, but it keeps the spec-driven flow moving without waiting for v0.3."
-
-Then stop. Do not proceed to any Stage 1/2/3 behavior below — those describe the planned v0.3 flow.
-
-## Planned design (v0.3) — for reference, not currently executable
-
-### Planned Stage 1: Execute Scan
-
-Run `specflow scan` against the target project. If `--module` flag is provided, read the IDE-local prompt file:
-
-- Cursor: `.cursor/specflow/prompts/shared/dispatching-parallel-agents.md`
-- Claude: `.claude/specflow/prompts/shared/dispatching-parallel-agents.md`
-- Codex: `.agents/specflow/prompts/shared/dispatching-parallel-agents.md`
-
-Then scan modules in parallel; otherwise run a single pass.
-
-### Planned Stage 2: Present Results
-
-Scan produces `specflow/SCAN_REPORT.md`. Present a summary highlighting detected modules, identified specs and coverage gaps, and suggested next actions.
-
-### Planned Gate: User Confirmation
-
-Ask the user to confirm the scan results. Do NOT proceed until explicit confirmation. Confirmed results become the Source of Truth for all downstream commands.
-
-### Planned Stage 3: Finalize
-
-Once confirmed, the scan results are locked and the user can run `/specflow:plan` to begin requirements planning.
-
-The v0.3 design rationale, scope, and risks will be captured in a dedicated `openspec` change at v0.3 planning time.