specflow-cc 1.5.3 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to SpecFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-01-25
+
+### Added
+
+#### Commands
+- `/sf:quick` — Fast track for trivial tasks (skip full audit/review workflow)
+- `/sf:verify` — Interactive user acceptance testing after implementation
+- `/sf:discuss --pre "topic"` — Pre-specification discussion with feature-type-specific questions
+- `/sf:new --discuss PRE-XXX` — Create spec with prior discussion context
+
+#### Features
+- **Model profiles** — Control cost vs quality (`quality`, `balanced`, `budget`) in config.json
+- **Pre-spec discussion** — Identifies gray areas based on feature type (visual, API, CLI, data, refactor)
+- **Feature-type question banks** — 5-10 targeted questions per feature type
+- **STATE.md size management** — Automatic decision archiving when exceeding 100 lines
+- **Wave-based parallel execution** — Large specs auto-decompose into parallel waves
+- **Orchestrator/worker architecture** — Fresh context per execution task
+
+#### Agents
+- Enhanced `spec-executor-orchestrator` — Pre-computed waves, checkpoint support
+- Enhanced `spec-executor-worker` — Atomic commits, state verification
+- Enhanced `discusser` — Feature-type detection, question banks, PRE-XXX file format
+
+### Changed
+
+- README completely rewritten for better user experience
+- `/sf:done` workflow now includes optional `/sf:verify` step
+- Pause/resume supports orchestrated execution checkpoints
+- Queue position is now source of truth for `/sf:next`
+
+---
+
 ## [1.5.3] - 2026-01-22
 
 ### Changed

package/README.md

@@ -1,37 +1,302 @@
+<div align="center">
+
 # SpecFlow
 
 **Spec-driven development for Claude Code**
 
-Write specs first, audit them, then implement. Quality through explicit review cycles.
+**Stop debugging AI-generated code. Start reviewing specifications.**
+
+[![npm version](https://img.shields.io/npm/v/specflow-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/specflow-cc)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+<br>
+
+```bash
+npx specflow-cc --global
+```
+
+<br>
+
+https://github.com/user-attachments/assets/3f516907-8657-4ea4-bc0c-6319998a09db
+
+<br>
+
+*"The audit caught 4 issues before I wrote a single line of code."*
+
+*"Fresh context review found a bug I would have shipped to production."*
+
+*"Finally, a workflow where Claude explains what it will do before doing it."*
+
+<br>
+
+[Why This Exists](#why-this-exists) · [How It Works](#how-it-works) · [Commands](#commands) · [Configuration](#configuration)
+
+</div>
+
+---
+
+## Why This Exists
+
+Claude Code is powerful. But "just build it" leads to:
+
+- Code that doesn't match what you imagined
+- Assumptions you didn't know were made
+- Bugs that only appear after 2000 lines are written
+- Hours spent debugging instead of building
 
-## Installation
+The fix isn't better prompting. It's **making Claude think before it codes.**
+
+SpecFlow enforces a simple principle: **write the spec first, audit it, then implement.** Every specification gets reviewed in a fresh context — no bias from creation. Every implementation gets reviewed against the spec — no "it works on my machine."
+
+The result: fewer surprises, cleaner code, and a paper trail of decisions.
+
+---
+
+## Why SpecFlow?
+
+Most AI coding workflows suffer from **"Yes-Man Syndrome"** — you ask for a feature, the AI nods and writes code. 500 lines later, you discover hallucinated APIs, missing edge cases, or security holes.
+
+SpecFlow fixes this with **Fresh Context Auditing**:
+
+| Aspect | Standard AI Coding | SpecFlow |
+|--------|-------------------|----------|
+| **Context** | Single window (grows, degrades) | Fresh context per phase |
+| **Quality Control** | Self-correction (biased) | Independent Auditor (unbiased) |
+| **Verification** | "Looks good to me" | Verified against contract |
+| **Execution** | Linear, single agent | Atomic waves, parallel agents |
+| **Result** | Hidden bugs ship | Issues caught before code exists |
+
+> The auditor has no memory of your conversation. It only sees the spec. If the spec says "use the flux capacitor API" — the auditor asks "what is that?"
+
+---
+
+## Who This Is For
+
+Developers who want Claude Code to:
+
+- **Explain before implementing** — See the plan before code exists
+- **Catch issues early** — Audits find problems when they're cheap to fix
+- **Stay consistent** — Same quality whether it's your first task or fiftieth
+- **Document decisions** — Know why code was written the way it was
+
+If you've ever said "that's not what I meant" after Claude finished coding, this is for you.
+
+---
+
+## Getting Started
 
 ```bash
 npx specflow-cc --global
 ```
 
-## Quick Start
+Then in any project:
 
 ```bash
-/sf:init                    # Initialize project (once)
+/sf:init                    # Initialize (once per project)
 /sf:new "add user auth"     # Create specification
-/sf:audit                   # Audit spec (fresh context)
-/sf:run                     # Implement
-/sf:review                  # Review implementation
-/sf:done                    # Complete and archive
 ```
 
-## Workflow
+Verify installation with `/sf:help`.
+
+### Quick Mode
+
+For trivial tasks that don't need full specification:
+
+```bash
+/sf:quick "fix typo in header"
+```
 
+Same quality principles, faster path.
+
+---
+
+## How It Works
+
+### 1. Create Specification
+
+```
+/sf:new "add OAuth login"
+```
+
+The system asks clarifying questions, then creates a structured specification:
+
+- **Goal Analysis** — What success looks like
+- **Requirements** — What must be built
+- **Acceptance Criteria** — How to verify it works
+- **Constraints** — What to avoid
+
+You review the spec. If something's wrong, you catch it now — not after 500 lines of code.
+
+**Creates:** `.specflow/specs/SPEC-XXX.md`
+
+---
+
+### 2. Audit Specification
+
+```
+/sf:audit
+```
+
+**This is where SpecFlow is different.**
+
+A fresh agent — with no memory of how the spec was created — reviews it for:
+
+- Ambiguous requirements
+- Missing edge cases
+- Unrealistic scope
+- Contradictions
+
+The auditor doesn't know your assumptions. It only sees the spec. If something is unclear, it will ask.
+
+**Why fresh context matters:** The agent that wrote the spec "knows what it meant." A fresh auditor only knows what's written. This catches gaps you'd otherwise miss.
+
+If issues are found, `/sf:revise` applies the feedback. Loop until approved.
+
+**Creates:** Audit record in spec, recommendations if needed
+
+---
+
+### 3. Implement
+
+```
+/sf:run
+```
+
+Now — and only now — code gets written.
+
+The executor has:
+- A clear, audited specification
+- Defined acceptance criteria
+- Explicit constraints
+
+No guessing. No "I'll figure it out as I go." The spec is the source of truth.
+
+For large specs, the system automatically:
+- Splits work into parallel waves
+- Spawns fresh executors per task
+- Commits atomically per unit of work
+
+**Creates:** Implementation + Execution Summary in spec
+
+---
+
+### 4. Review Implementation
+
+```
+/sf:review
 ```
-/sf:new  →  /sf:audit  →  /sf:run  →  /sf:review  →  /sf:done
-              ↓                          ↓
-         /sf:revise                  /sf:fix
+
+Another fresh agent reviews what was built against what was specified:
+
+- Does the code meet acceptance criteria?
+- Were all files created/deleted as planned?
+- Any security issues or code quality problems?
+
+Same principle as audit: fresh eyes catch what familiar eyes miss.
+
+If issues are found, `/sf:fix` addresses them. Loop until approved.
+
+**Creates:** Review record in spec
+
+---
+
+### 5. Verify (Optional)
+
+```
+/sf:verify
+```
+
+Automated checks confirm code exists and tests pass. But does it actually *work*?
+
+This step walks you through manual verification:
+
+- "Can you log in with OAuth?"
+- "Does the redirect work?"
+- "Is the session persisted?"
+
+You confirm each item. If something's broken, the system helps diagnose and creates fix plans.
+
+**Creates:** Verification record
+
+---
+
+### 6. Complete
+
+```
+/sf:done
+```
+
+Archives the specification. Records decisions. Clears state for the next task.
+
+Your spec becomes documentation: why the code exists, what decisions were made, how it was verified.
+
+---
+
+## The Full Workflow
+
+```
+                        /sf:quick (trivial tasks)
+                              ↓
+/sf:new  →  /sf:audit  →  /sf:run  →  /sf:review  →  /sf:verify  →  /sf:done
+              ↓                          ↓              ↓
+         /sf:revise                  /sf:fix      (optional UAT)
          (if needed)                 (if needed)
 ```
 
 **Key principle:** Audits and reviews run in fresh context — no bias from creation.
 
+---
+
+## Why It Works
+
+### Fresh Context Auditing
+
+The agent that creates a spec "knows what it meant." That's dangerous — unclear writing seems clear to the writer.
+
+SpecFlow audits in a **separate context**. The auditor only sees the specification text. If requirements are ambiguous, the auditor will flag them — because it genuinely doesn't know the intent.
+
+This catches:
+- Assumptions that weren't written down
+- Edge cases the creator forgot
+- Scope that's larger than it appears
+
+### Spec as Contract
+
+The specification isn't a suggestion. It's a contract:
+
+| Section | What it defines |
+|---------|-----------------|
+| Goal Analysis | What success looks like |
+| Requirements | What must exist |
+| Acceptance Criteria | How to verify completion |
+| Constraints | What to avoid |
+| Files to Create/Modify | Exact scope |
+
+The executor implements the contract. The reviewer verifies compliance. No drift.
+
+### Atomic Execution
+
+Large specifications automatically decompose into waves:
+
+```
+Wave 1: [task-1] [task-2] [task-3]  ← parallel
+Wave 2: [task-4] [task-5]           ← parallel, depends on wave 1
+Wave 3: [task-6]                    ← sequential
+```
+
+Each task runs in fresh context. Each task commits atomically. If something fails, you know exactly which task and can fix just that piece.
+
+### Decision Trail
+
+Every specification records:
+- Audit feedback and responses
+- Review findings and fixes
+- Verification results
+
+Six months later, you can read the spec and understand not just *what* was built, but *why* — and what was explicitly decided against.
+
+---
+
 ## Commands
 
 ### Core Flow
@@ -39,108 +304,176 @@ npx specflow-cc --global
 | Command | Description |
 |---------|-------------|
 | `/sf:init` | Initialize project |
-| `/sf:new` | Create specification |
+| `/sf:new "task"` | Create specification |
 | `/sf:audit` | Audit spec (fresh context) |
-| `/sf:revise` | Revise based on audit (see below) |
-| `/sf:run` | Implement spec |
-| `/sf:review` | Review implementation |
-| `/sf:fix` | Fix based on review |
+| `/sf:revise` | Revise based on audit feedback |
+| `/sf:run` | Implement specification |
+| `/sf:review` | Review implementation (fresh context) |
+| `/sf:fix` | Fix based on review feedback |
+| `/sf:verify` | Interactive user acceptance testing |
 | `/sf:done` | Complete and archive |
 
+**Quick mode:**
+
+```bash
+/sf:quick "fix button color"    # Skip full workflow for trivial tasks
+```
+
 **Revise options:**
+
 ```bash
-/sf:revise              # Interactive — show issues, ask what to fix
+/sf:revise              # Interactive — choose what to fix
 /sf:revise all          # Apply all feedback
-/sf:revise 1,2          # Fix only items 1 and 2
-/sf:revise "custom..."  # Arbitrary revision instructions
+/sf:revise 1,2          # Fix specific items
+/sf:revise "custom..."  # Custom instructions
 ```
 
 ### Research & Clarification
 
 | Command | Description |
 |---------|-------------|
-| `/sf:research "topic"` | Research topic, save findings |
-| `/sf:discuss "topic"` | Clarify requirements (multi-question) |
-| `/sf:discuss "question?"` | Quick clarification (single question) |
+| `/sf:research "topic"` | Research and save findings |
+| `/sf:discuss "topic"` | Multi-question clarification |
+| `/sf:discuss "question?"` | Single question |
+| `/sf:discuss --pre "topic"` | Pre-spec discussion with feature-type questions |
 | `/sf:scan` | Analyze codebase for issues |
 
+**Pre-spec discussion** identifies gray areas before creating a spec:
+
+```bash
+/sf:discuss --pre "add export feature"   # Asks feature-type-specific questions
+/sf:new --discuss PRE-001 "add export"   # Creates spec with discussion context
+```
+
 ### Navigation
 
 | Command | Description |
 |---------|-------------|
 | `/sf:status` | Current state and next step |
 | `/sf:list` | All specifications |
-| `/sf:next` | Switch to priority task |
+| `/sf:next` | Switch to highest priority task |
 | `/sf:show` | View spec details |
+| `/sf:history` | View archived specs |
+| `/sf:metrics` | Project statistics |
 
 ### Backlog
 
 | Command | Description |
 |---------|-------------|
-| `/sf:todo` | Add future idea |
+| `/sf:todo "idea"` | Capture idea for later |
 | `/sf:todos` | List all todos |
 | `/sf:plan` | Convert todo to spec |
-| `/sf:priority` | Reprioritize |
+| `/sf:priority` | Reprioritize queue |
 
 ### Utilities
 
 | Command | Description |
 |---------|-------------|
 | `/sf:split` | Break large spec into parts |
-| `/sf:deps` | Show dependencies |
+| `/sf:deps` | Show spec dependencies |
 | `/sf:pause` | Save session context |
 | `/sf:resume` | Restore session |
 | `/sf:help` | Command reference |
 
+---
+
+## Configuration
+
+Settings live in `.specflow/config.json`.
+
+### Model Profiles
+
+Control cost vs quality:
+
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+| Profile | Spec Creation | Execution | Review |
+|---------|---------------|-----------|--------|
+| `quality` | Opus | Opus | Sonnet |
+| `balanced` | Opus | Sonnet | Sonnet |
+| `budget` | Sonnet | Sonnet | Haiku |
+
+Use `quality` for critical features, `budget` for routine tasks.
+
+---
+
 ## Project Structure
 
 ```
 .specflow/
-├── PROJECT.md      # Project context
-├── STATE.md        # Current state
-├── specs/          # Active specs
+├── PROJECT.md      # Project context (patterns, conventions)
+├── STATE.md        # Current state and queue
+├── config.json     # Settings
+├── specs/          # Active specifications
 ├── research/       # Research documents
 ├── discussions/    # Clarification records
-├── audits/         # Audit reports
-└── archive/        # Completed specs
+└── archive/        # Completed specifications
 ```
 
+---
+
 ## Typical Session
 
 ```bash
-# Check where you are
+# Check current state
 /sf:status
 
-# Research if needed
-/sf:research "auth options"
+# Trivial fix — use quick mode
+/sf:quick "fix typo in README"
+
+# Feature work — full workflow
+/sf:discuss --pre "add OAuth"           # Clarify gray areas first
+/sf:new --discuss PRE-001 "add OAuth"   # Create spec with context
+/sf:audit                                # Fresh context audit
+/sf:revise all                           # Apply feedback if needed
+/sf:run                                  # Implement
+/sf:review                               # Fresh context review
+/sf:verify                               # Manual verification
+/sf:done                                 # Archive
+```
 
-# Create spec with research context
-/sf:new --research RES-001 "add OAuth"
+---
 
-# Clarify assumptions if needed
-/sf:discuss SPEC-001
+## Troubleshooting
 
-# Audit (use /clear first for fresh context)
-/sf:audit
+**Commands not found?**
+- Restart Claude Code to reload commands
+- Verify files exist in `~/.claude/` (global) or `.claude/` (local)
+- Re-run `npx specflow-cc --global`
 
-# Implement
-/sf:run
+**Audit/review seems to miss obvious issues?**
+- Use `/clear` before `/sf:audit` or `/sf:review` to ensure fresh context
+- Check that spec has clear acceptance criteria
 
-# Quick clarification during implementation
-/sf:discuss "Should we use Redis or in-memory cache?"
+**Large spec taking too long?**
+- Use `/sf:split` to decompose into smaller specs
+- Or let the system auto-decompose during `/sf:run`
 
-# Review and complete
-/sf:review
-/sf:done
-```
+---
 
 ## Philosophy
 
-- **Spec-first** — Write specs before code
-- **Fresh audits** — Auditors don't see creation (no bias)
+- **Spec-first** — Think before coding
+- **Fresh audits** — Different context catches different issues
 - **Soft blocking** — Warnings, not hard stops
 - **Token-aware** — Specs sized for single sessions
+- **Cost-conscious** — Model profiles for budget control
+- **Decision trail** — Know why code exists
+
+---
 
 ## License
 
 MIT
+
+---
+
+<div align="center">
+
+**Claude Code writes the code. SpecFlow makes sure it's the right code.**
+
+</div>

package/agents/codebase-scanner.md

@@ -187,9 +187,12 @@ Based on this scan, consider creating specs for:
 1. **[Spec title]** — [brief description]
    - Priority: [High | Medium | Low]
    - Complexity: [small | medium | large]
+   Run: `/sf:new "[title]"`
 
 2. **[Spec title]** — [brief description]
-   ...
+   - Priority: [High | Medium | Low]
+   - Complexity: [small | medium | large]
+   Run: `/sf:new "[title]"`
 
 ---