specflow-cc 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,12 +5,40 @@ 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.3.0] - 2026-01-21
+
+### Added
+
+- File path links in command output (`📄 File: .specflow/specs/SPEC-XXX.md`)
+- `/clear` hints before fresh context commands (audit, review)
+
+### Changed
+
+- All command outputs now include direct links to spec files
+- Workflow hints remind users to clear context before auditor/reviewer steps
+
+---
+
+## [1.2.0] - 2026-01-20
+
+### Fixed
+
+- Command format: `/sf run` → `/sf:run` (matches Claude Code syntax)
+
+### Changed
+
+- `/sf:audit` now shows alternative next steps when APPROVED with recommendations
+- `/sf:review` now shows alternative next steps when APPROVED with minor suggestions
+- User can choose to proceed or apply optional feedback first
+
+---
+
 ## [1.1.0] - 2026-01-20
 
 ### Added
 
 #### Analysis Commands
-- `/sf scan [--focus]` - Deep codebase analysis for tech debt, concerns, and improvement opportunities
+- `/sf:scan [--focus]` - Deep codebase analysis for tech debt, concerns, and improvement opportunities
 
 #### Agents
 - `codebase-scanner` - Analyzes codebase and writes structured SCAN.md report

package/README.md

@@ -41,28 +41,28 @@ npx specflow-cc --local
 
 ```bash
 # 1. Initialize project (once per project)
-/sf init
+/sf:init
 
 # 2. Create a specification
-/sf new "Add user authentication with JWT"
+/sf:new "Add user authentication with JWT"
 
 # 3. Audit the specification (fresh context)
-/sf audit
+/sf:audit
 
 # 4. Revise if needed
-/sf revise
+/sf:revise
 
 # 5. Execute when approved
-/sf run
+/sf:run
 
 # 6. Review implementation (fresh context)
-/sf review
+/sf:review
 
 # 7. Fix if needed
-/sf fix
+/sf:fix
 
 # 8. Complete and archive
-/sf done
+/sf:done
 ```
 
 ## Commands
@@ -71,60 +71,60 @@ npx specflow-cc --local
 
 | Command | Description |
 |---------|-------------|
-| `/sf init` | Initialize project, analyze codebase |
-| `/sf new [description]` | Create new specification |
-| `/sf audit` | Audit specification (fresh context) |
-| `/sf revise [instructions]` | Revise spec based on audit |
-| `/sf run` | Execute specification |
-| `/sf review` | Review implementation (fresh context) |
-| `/sf fix [instructions]` | Fix based on review |
-| `/sf done` | Complete, commit, and archive |
-| `/sf status` | Show current state and next step |
+| `/sf:init` | Initialize project, analyze codebase |
+| `/sf:new [description]` | Create new specification |
+| `/sf:audit` | Audit specification (fresh context) |
+| `/sf:revise [instructions]` | Revise spec based on audit |
+| `/sf:run` | Execute specification |
+| `/sf:review` | Review implementation (fresh context) |
+| `/sf:fix [instructions]` | Fix based on review |
+| `/sf:done` | Complete, commit, and archive |
+| `/sf:status` | Show current state and next step |
 
 ### Navigation
 
 | Command | Description |
 |---------|-------------|
-| `/sf list` | List all specifications |
-| `/sf show [ID]` | Show specification details |
-| `/sf next` | Switch to next priority task |
+| `/sf:list` | List all specifications |
+| `/sf:show [ID]` | Show specification details |
+| `/sf:next` | Switch to next priority task |
 
 ### To-Do Management
 
 | Command | Description |
 |---------|-------------|
-| `/sf todo [text]` | Add idea or future task |
-| `/sf todos` | List all todos with priorities |
-| `/sf plan [ID]` | Convert todo into specification |
-| `/sf priority` | Interactive prioritization |
+| `/sf:todo [text]` | Add idea or future task |
+| `/sf:todos` | List all todos with priorities |
+| `/sf:plan [ID]` | Convert todo into specification |
+| `/sf:priority` | Interactive prioritization |
 
 ### Decomposition
 
 | Command | Description |
 |---------|-------------|
-| `/sf split [ID]` | Split large spec into smaller parts |
-| `/sf deps` | Show dependency graph |
+| `/sf:split [ID]` | Split large spec into smaller parts |
+| `/sf:deps` | Show dependency graph |
 
 ### Session Management
 
 | Command | Description |
 |---------|-------------|
-| `/sf pause` | Save context for later |
-| `/sf resume` | Restore saved context |
+| `/sf:pause` | Save context for later |
+| `/sf:resume` | Restore saved context |
 
 ### Analysis
 
 | Command | Description |
 |---------|-------------|
-| `/sf scan [--focus]` | Deep codebase analysis for concerns and tech debt |
+| `/sf:scan [--focus]` | Deep codebase analysis for concerns and tech debt |
 
 ### Utilities
 
 | Command | Description |
 |---------|-------------|
-| `/sf help [command]` | Show help for commands |
-| `/sf history [ID]` | View completed specifications |
-| `/sf metrics` | Project statistics |
+| `/sf:help [command]` | Show help for commands |
+| `/sf:history [ID]` | View completed specifications |
+| `/sf:metrics` | Project statistics |
 
 ## Workflow Diagram
 
@@ -133,44 +133,44 @@ npx specflow-cc --local
 │                    SPECFLOW WORKFLOW                         │
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
-│  /sf init    ──→  Initialize project (once)                  │
+│  /sf:init    ──→  Initialize project (once)                  │
 │       ↓                                                      │
-│  /sf new     ──→  Create specification                       │
+│  /sf:new     ──→  Create specification                       │
 │       ↓                                                      │
 │  ┌─────────────────────────────────────┐                     │
 │  │  SPEC AUDIT LOOP                    │                     │
-│  │  /sf audit ──→ APPROVED? ──yes──→ ──┼──→                  │
+│  │  /sf:audit ──→ APPROVED? ──yes──→ ──┼──→                  │
 │  │       │                             │    ↓                │
 │  │       no                            │                     │
 │  │       ↓                             │                     │
-│  │  /sf revise ────────→ loop back     │                     │
+│  │  /sf:revise ────────→ loop back     │                     │
 │  └─────────────────────────────────────┘                     │
 │       ↓                                                      │
-│  /sf run     ──→  Execute specification                      │
+│  /sf:run     ──→  Execute specification                      │
 │       ↓                                                      │
 │  ┌─────────────────────────────────────┐                     │
 │  │  IMPL REVIEW LOOP                   │                     │
-│  │  /sf review ──→ APPROVED? ──yes──→ ─┼──→                  │
+│  │  /sf:review ──→ APPROVED? ──yes──→ ─┼──→                  │
 │  │       │                             │    ↓                │
 │  │       no                            │                     │
 │  │       ↓                             │                     │
-│  │  /sf fix ───────────→ loop back     │                     │
+│  │  /sf:fix ───────────→ loop back     │                     │
 │  └─────────────────────────────────────┘                     │
 │       ↓                                                      │
-│  /sf done    ──→  Complete and archive                       │
+│  /sf:done    ──→  Complete and archive                       │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 ```
 
 ## Project Structure
 
-After `/sf init`, SpecFlow creates:
+After `/sf:init`, SpecFlow creates:
 
 ```
 .specflow/
 ├── PROJECT.md       # Project overview and patterns
 ├── STATE.md         # Current state and queue
-├── SCAN.md          # Codebase scan results (from /sf scan)
+├── SCAN.md          # Codebase scan results (from /sf:scan)
 ├── config.json      # Configuration
 ├── specs/           # Active specifications
 │   └── SPEC-001.md
@@ -222,7 +222,7 @@ created: 2026-01-20
 |------|--------|--------|
 | Small | ≤50k | Execute directly |
 | Medium | 50-150k | Warning, proceed |
-| Large | >150k | Requires `/sf split` |
+| Large | >150k | Requires `/sf:split` |
 
 ## Statusline
 

package/agents/codebase-scanner.md

@@ -7,7 +7,7 @@ tools: Read, Bash, Grep, Glob, Write
 <role>
 You are a SpecFlow codebase scanner. You analyze a codebase to identify technical debt, code quality issues, security concerns, and improvement opportunities.
 
-You are spawned by `/sf scan` with a focus area:
+You are spawned by `/sf:scan` with a focus area:
 - **concerns** — Technical debt, bugs, security issues
 - **quality** — Code quality, conventions, test coverage gaps
 - **arch** — Architecture problems, structure issues

package/agents/impl-reviewer.md

@@ -196,8 +196,8 @@ Append to specification's Review History:
 
 ## Step 8: Update STATE.md
 
-- If APPROVED: Status → "done", Next Step → "/sf done"
-- If CHANGES_REQUESTED: Status → "review", Next Step → "/sf fix"
+- If APPROVED: Status → "done", Next Step → "/sf:done"
+- If CHANGES_REQUESTED: Status → "review", Next Step → "/sf:fix"
 
 </process>
 
@@ -246,13 +246,13 @@ Return review result:
 
 ## Next Step
 
-{If APPROVED:} `/sf done` — finalize and archive
+{If APPROVED:} `/sf:done` — finalize and archive
 
-{If CHANGES_REQUESTED:} `/sf fix` — address issues
+{If CHANGES_REQUESTED:} `/sf:fix` — address issues
 
 Options:
-- `/sf fix all` — apply all fixes
-- `/sf fix 1,2` — fix specific issues
+- `/sf:fix all` — apply all fixes
+- `/sf:fix 1,2` — fix specific issues
 ```
 
 </output>

package/agents/spec-auditor.md

@@ -100,7 +100,7 @@ Separate findings into:
 
 **Critical (blocks implementation):**
 - Numbered list: 1, 2, 3...
-- Must be fixed before `/sf run`
+- Must be fixed before `/sf:run`
 
 **Recommendations (improvements):**
 - Numbered list continuing from critical
@@ -138,8 +138,8 @@ N+1. [recommendation]
 ## Step 7: Update STATE.md
 
 Update status:
-- If APPROVED: Status → "audited", Next Step → "/sf run"
-- If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf revise"
+- If APPROVED: Status → "audited", Next Step → "/sf:run"
+- If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf:revise"
 
 </process>
 
@@ -168,7 +168,7 @@ Return formatted audit result:
 
 ### Next Step
 
-`/sf revise` — address critical issues
+`/sf:revise` — address critical issues
 
 ---
 
@@ -180,7 +180,7 @@ Return formatted audit result:
 
 ### Next Step
 
-`/sf run` — implement specification
+`/sf:run` — implement specification
 ```
 
 </output>

package/agents/spec-creator.md

@@ -24,7 +24,7 @@ Ask ONLY questions that:
 - Cannot be reasonably assumed from PROJECT.md context
 - Have mutually exclusive answers (not "yes/no/maybe")
 
-Everything else becomes an assumption that can be corrected during `/sf revise`.
+Everything else becomes an assumption that can be corrected during `/sf:revise`.
 
 ## Spec Quality
 
@@ -40,7 +40,7 @@ Good specifications are:
 |------|--------|---------------|
 | small | ≤50k | Single file, simple feature |
 | medium | 50-150k | Multiple files, moderate feature |
-| large | >150k | Many files, complex feature — needs /sf split |
+| large | >150k | Many files, complex feature — needs /sf:split |
 
 </philosophy>
 
@@ -111,7 +111,7 @@ Mark as small/medium/large in frontmatter.
 Update `.specflow/STATE.md`:
 - Set Active Specification to new spec
 - Set Status to "drafting"
-- Set Next Step to "/sf audit"
+- Set Next Step to "/sf:audit"
 - Add spec to Queue
 
 </process>
@@ -136,11 +136,11 @@ Return structured result:
 - .specflow/specs/SPEC-XXX.md
 
 ### Next Step
-`/sf audit` — audit specification before implementation
+`/sf:audit` — audit specification before implementation
 
 {If complexity is large:}
 ### Warning
-Specification is large (>150k tokens estimated). Consider `/sf split SPEC-XXX` to decompose.
+Specification is large (>150k tokens estimated). Consider `/sf:split SPEC-XXX` to decompose.
 ```
 
 </output>

package/agents/spec-executor.md

@@ -182,7 +182,7 @@ Append to specification:
 ## Step 8: Update STATE.md
 
 - Status → "review"
-- Next Step → "/sf review"
+- Next Step → "/sf:review"
 
 </process>
 
@@ -216,7 +216,7 @@ Return execution result:
 
 ### Next Step
 
-`/sf review` — audit implementation
+`/sf:review` — audit implementation
 ```
 
 </output>

package/agents/spec-reviser.md

@@ -137,7 +137,7 @@ Set status to "auditing" (ready for re-audit).
 ## Step 7: Update STATE.md
 
 - Status → "auditing"
-- Next Step → "/sf audit"
+- Next Step → "/sf:audit"
 
 </process>
 
@@ -167,7 +167,7 @@ Return formatted revision result:
 
 ### Next Step
 
-`/sf audit` — re-audit revised specification
+`/sf:audit` — re-audit revised specification
 ```
 
 </output>

package/agents/spec-splitter.md

@@ -179,7 +179,7 @@ SPEC-XXXc
 
 ### Next Step
 
-`/sf audit SPEC-XXXa` — start with first sub-specification
+`/sf:audit SPEC-XXXa` — start with first sub-specification
 ```
 
 </output>

package/commands/sf/audit.md

@@ -32,7 +32,7 @@ Audit the active specification using a fresh context subagent. The auditor evalu
 ```
 SpecFlow not initialized.
 
-Run `/sf init` first.
+Run `/sf:init` first.
 ```
 Exit.
 
@@ -44,7 +44,7 @@ Read `.specflow/STATE.md` and extract Active Specification.
 ```
 No active specification to audit.
 
-Run `/sf new "task description"` to create one.
+Run `/sf:new "task description"` to create one.
 ```
 Exit.
 
@@ -56,7 +56,7 @@ Read the active spec file: `.specflow/specs/SPEC-XXX.md`
 ```
 Specification SPEC-XXX is already audited (status: {status}).
 
-Use `/sf run` to implement or `/sf status` to see current state.
+Use `/sf:run` to implement or `/sf:status` to see current state.
 ```
 Exit.
 
@@ -90,7 +90,7 @@ The agent will:
 
 ## Step 6: Display Result
 
-### If APPROVED:
+### If APPROVED (no recommendations):
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -104,9 +104,41 @@ The agent will:
 
 ---
 
+📄 File: .specflow/specs/SPEC-XXX.md
+
+---
+
 ## Next Step
 
-`/sf run` — implement specification
+`/sf:run` — implement specification
+```
+
+### If APPROVED (with optional recommendations):
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ AUDIT PASSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Specification:** SPEC-XXX
+**Status:** APPROVED
+
+### Recommendations (Optional)
+
+1. [Recommendation 1]
+2. [Recommendation 2]
+
+---
+
+📄 File: .specflow/specs/SPEC-XXX.md
+
+---
+
+## Next Steps
+
+Choose one:
+• `/sf:run` — implement specification as-is
+• `/sf:revise` — apply optional recommendations first ({N} items)
 ```
 
 ### If NEEDS_REVISION:
@@ -130,14 +162,18 @@ The agent will:
 
 ---
 
+📄 File: .specflow/specs/SPEC-XXX.md
+
+---
+
 ## Next Step
 
-`/sf revise` — address critical issues
+`/sf:revise` — address critical issues
 
 Options:
-- `/sf revise all` — apply all feedback
-- `/sf revise 1,2` — fix specific issues
-- `/sf revise [instructions]` — custom changes
+- `/sf:revise all` — apply all feedback
+- `/sf:revise 1,2` — fix specific issues
+- `/sf:revise [instructions]` — custom changes
 ```
 
 </workflow>
@@ -194,8 +230,8 @@ Append to spec's Audit History:
 
 ### Update STATE.md
 
-- If APPROVED: Status → "audited", Next Step → "/sf run"
-- If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf revise"
+- If APPROVED: Status → "audited", Next Step → "/sf:run"
+- If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf:revise"
 
 </fallback>
 

package/commands/sf/deps.md

@@ -33,7 +33,7 @@ Display the dependency graph between specifications. Shows which specs can be wo
 ```
 SpecFlow not initialized.
 
-Run `/sf init` first.
+Run `/sf:init` first.
 ```
 Exit.
 
@@ -51,7 +51,7 @@ ls .specflow/specs/SPEC-*.md 2>/dev/null
 
 No specifications found.
 
-Create your first spec: `/sf new "task description"`
+Create your first spec: `/sf:new "task description"`
 ```
 Exit.
 
@@ -88,7 +88,7 @@ Build dependency map:
 ```
 Specification {ID} not found.
 
-Use `/sf list` to see available specifications.
+Use `/sf:list` to see available specifications.
 ```
 Exit.
 
@@ -128,12 +128,12 @@ None — no other specifications depend on this.
 {If blocked:}
 **Blocked by:** {blocking spec ID} must complete first.
 
-When {blocking ID} is done, run: `/sf run {ID}`
+When {blocking ID} is done, run: `/sf:run {ID}`
 
 {If ready:}
 **Ready:** All dependencies satisfied.
 
-Next: `/sf audit {ID}` or `/sf run {ID}`
+Next: `/sf:audit {ID}` or `/sf:run {ID}`
 
 {If done:}
 **Complete:** This specification is done.
@@ -212,11 +212,11 @@ SPEC-003 [audited] → SPEC-004 [draft]
 **Next actionable:**
 {List specs that are ready to work on, sorted by priority}
 
-- `/sf run SPEC-001b` (running)
-- `/sf audit SPEC-005` (audited)
-- `/sf audit SPEC-002` (draft)
+- `/sf:run SPEC-001b` (running)
+- `/sf:audit SPEC-005` (audited)
+- `/sf:audit SPEC-002` (draft)
 
-**Tip:** `/sf deps SPEC-XXX` for details on a specific spec.
+**Tip:** `/sf:deps SPEC-XXX` for details on a specific spec.
 ```
 
 </workflow>

package/commands/sf/done.md

@@ -31,7 +31,7 @@ Finalize the completed specification. Archives the spec, updates STATE.md, extra
 ```
 SpecFlow not initialized.
 
-Run `/sf init` first.
+Run `/sf:init` first.
 ```
 Exit.
 
@@ -43,7 +43,7 @@ Read `.specflow/STATE.md` and extract Active Specification.
 ```
 No active specification to finalize.
 
-Run `/sf new "task description"` to create one.
+Run `/sf:new "task description"` to create one.
 ```
 Exit.
 
@@ -89,7 +89,7 @@ Continue anyway?
 
 Use AskUserQuestion with options:
 - "Yes, finalize anyway" → continue, log warning
-- "No, run review first" → exit with `/sf review` suggestion
+- "No, run review first" → exit with `/sf:review` suggestion
 
 **If user proceeds anyway:**
 Log in STATE.md Warnings table:
@@ -147,7 +147,7 @@ mv .specflow/specs/SPEC-XXX.md .specflow/archive/
 
 - Active Specification → "none"
 - Status → "idle"
-- Next Step → "/sf new or /sf next"
+- Next Step → "/sf:new or /sf:next"
 
 ### Remove from Queue
 
@@ -213,13 +213,13 @@ git commit -m "docs(sf): complete SPEC-XXX
 {If queue has more specs:}
 **Next in queue:** SPEC-YYY — {title}
 
-Run `/sf next` to start the next specification.
+Run `/sf:next` to start the next specification.
 
 {If queue is empty:}
 Queue is empty.
 
-Run `/sf new "task"` to create a new specification
-or `/sf todos` to see pending ideas.
+Run `/sf:new "task"` to create a new specification
+or `/sf:todos` to see pending ideas.
 ```
 
 </workflow>
@@ -244,7 +244,7 @@ mv .specflow/specs/SPEC-XXX.md .specflow/archive/
 
 1. Set Active Specification to "none"
 2. Set Status to "idle"
-3. Set Next Step to "/sf new or /sf next"
+3. Set Next Step to "/sf:new or /sf:next"
 4. Remove from Queue table
 5. Add any extracted decisions