specflow-cc 1.0.0

package/commands/sf/history.md

@@ -0,0 +1,268 @@
+---
+name: sf:history
+description: View completed specifications from archive
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+<purpose>
+Display completed specifications from the archive. Shows completion dates, audit/review cycle counts, and decisions made. Allows viewing full details of archived specifications to learn from past work.
+</purpose>
+
+<context>
+@.specflow/archive/SPEC-*.md
+@.specflow/STATE.md
+</context>
+
+<arguments>
+- `[ID]` — Specification ID to show details for (e.g., SPEC-001). Optional — shows list if omitted.
+</arguments>
+
+<workflow>
+
+## Step 1: Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized.
+
+Run `/sf init` first.
+```
+Exit.
+
+## Step 2: Check Archive
+
+```bash
+ls .specflow/archive/SPEC-*.md 2>/dev/null | wc -l
+```
+
+**If 0 (empty archive):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ COMPLETED SPECIFICATIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No completed specifications yet.
+
+Complete your first spec to see it here.
+
+**Workflow:**
+1. `/sf new "task"` — Create specification
+2. `/sf audit` → `/sf run` → `/sf review`
+3. `/sf done` — Archives the specification
+```
+Exit.
+
+## Step 3: Branch Based on Arguments
+
+**If specific ID provided:** Go to Step 4a (Detailed View)
+**If no ID provided:** Go to Step 4b (List View)
+
+## Step 4a: Detailed Archive View
+
+### Check Spec Exists
+
+```bash
+[ -f ".specflow/archive/{ID}.md" ] && echo "FOUND" || echo "NOT_FOUND"
+```
+
+**If NOT_FOUND:**
+```
+Specification {ID} not found in archive.
+
+It may be:
+- Still in progress: `/sf show {ID}`
+- Never existed: `/sf list` to see all specs
+
+Use `/sf history` to see archived specifications.
+```
+Exit.
+
+### Parse Archived Specification
+
+Read `.specflow/archive/{ID}.md` and extract:
+- Frontmatter: id, type, status, priority, complexity, created
+- Title from first heading
+- Context section (summary)
+- Audit History section
+- Review History section (if exists)
+- Files created/modified (from Requirements)
+
+### Calculate Statistics
+
+- Duration: created → archived (from last audit/review date)
+- Audit cycles: count audit entries
+- Review cycles: count review entries
+- Decisions: from Audit History responses
+
+### Extract Decisions from STATE.md
+
+Read `.specflow/STATE.md` Decisions table and filter by spec ID.
+
+### Display Detailed View
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ {ID}: {Title} (Archived)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Created:** {created date}
+**Completed:** {completion date}
+**Duration:** {days} days
+**Type:** {type}
+**Complexity:** {complexity}
+
+---
+
+## Summary
+
+{Context section content, first paragraph}
+
+## Audit History
+
+| Version | Date       | Result         |
+|---------|------------|----------------|
+| v1      | 2024-01-11 | Needs Revision |
+| v2      | 2024-01-12 | Approved       |
+
+**Total audits:** {N} | **First-pass:** {Yes/No}
+
+## Review History
+
+| Version | Date       | Result         |
+|---------|------------|----------------|
+| v1      | 2024-01-15 | Approved       |
+
+**Total reviews:** {N} | **First-pass:** {Yes/No}
+
+## Decisions Made
+
+{If decisions found:}
+| Decision                          | Rationale                    |
+|-----------------------------------|------------------------------|
+| Use jose instead of jsonwebtoken  | Better TypeScript support    |
+| httpOnly cookies for tokens       | XSS protection               |
+
+{If no decisions:}
+No major decisions recorded for this specification.
+
+## Files Created/Modified
+
+{If files listed in Requirements:}
+**Created:**
+- src/middleware/auth.ts
+- src/services/auth.ts
+- src/types/auth.ts
+
+**Modified:**
+- src/app/api/route.ts
+
+{If files not explicitly listed:}
+See specification for details.
+
+---
+
+**Note:** Archived specifications are read-only.
+
+**View full spec:** Read `.specflow/archive/{ID}.md`
+```
+Exit.
+
+## Step 4b: List All Archived
+
+### Parse All Archived Specs
+
+For each file in `.specflow/archive/SPEC-*.md`:
+- Extract id, title, type, complexity, created
+- Count audit entries (Audit v1, v2, etc.)
+- Count review entries (if any)
+- Get completion date (last audit/review date)
+
+### Sort by Completion Date
+
+Most recent first.
+
+### Calculate Summary Statistics
+
+- Total completed
+- Average audit cycles
+- Average review cycles
+- First-pass audit rate
+- First-pass review rate
+
+### Display List
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ COMPLETED SPECIFICATIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| ID       | Title                     | Completed  | Type     | Audits | Reviews |
+|----------|---------------------------|------------|----------|--------|---------|
+| SPEC-005 | Settings page             | 2024-01-19 | feature  | 1      | 1       |
+| SPEC-002 | API rate limiting         | 2024-01-18 | feature  | 1      | 2       |
+| SPEC-001 | User authentication       | 2024-01-15 | feature  | 2      | 1       |
+
+---
+
+## Summary
+
+**Total completed:** {N} specifications
+
+| Metric                 | Value  |
+|------------------------|--------|
+| Average audit cycles   | {N.N}  |
+| Average review cycles  | {N.N}  |
+| First-pass audit rate  | {N}%   |
+| First-pass review rate | {N}%   |
+
+## By Type
+
+| Type     | Count |
+|----------|-------|
+| feature  | {N}   |
+| refactor | {N}   |
+| bugfix   | {N}   |
+
+## By Complexity
+
+| Complexity | Count |
+|------------|-------|
+| small      | {N}   |
+| medium     | {N}   |
+| large      | {N}   |
+
+---
+
+**View details:** `/sf history SPEC-001`
+
+**Insights:**
+{If first-pass audit rate < 50%:}
+- Consider more thorough initial specs (low first-pass audit rate)
+
+{If average audits > 2:}
+- Specs may need better scoping upfront
+
+{If all metrics good:}
+- Great spec quality! Keep up the discipline.
+```
+
+</workflow>
+
+<success_criteria>
+- [ ] Initialization verified
+- [ ] Empty archive handled gracefully
+- [ ] List view shows all archived specs with key metrics
+- [ ] Detail view shows full history and decisions
+- [ ] Audit/review cycles counted correctly
+- [ ] Summary statistics calculated
+- [ ] Sorted by completion date (most recent first)
+- [ ] Insights provided based on data
+</success_criteria>

package/commands/sf/init.md

@@ -0,0 +1,217 @@
+---
+name: sf:init
+description: Initialize SpecFlow in current project — analyze codebase and create .specflow/ structure
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<purpose>
+Initialize SpecFlow in the current project. Analyzes the codebase to understand tech stack, patterns, and structure, then creates the `.specflow/` directory with PROJECT.md, STATE.md, and config.json.
+</purpose>
+
+<context>
+@~/.claude/specflow-cc/templates/project.md
+@~/.claude/specflow-cc/templates/state.md
+</context>
+
+<workflow>
+
+## Step 1: Check if Already Initialized
+
+```bash
+[ -d .specflow ] && echo "EXISTS" || echo "NOT_EXISTS"
+```
+
+**If EXISTS:**
+```
+SpecFlow already initialized in this project.
+
+Use `/sf status` to see current state.
+```
+Exit.
+
+## Step 2: Detect Tech Stack
+
+Scan for common configuration files:
+
+```bash
+# Package managers / Languages
+ls package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle Gemfile composer.json 2>/dev/null
+
+# Frameworks
+ls next.config.* nuxt.config.* vite.config.* angular.json vue.config.* 2>/dev/null
+
+# Database
+ls prisma/schema.prisma drizzle.config.* knexfile.* 2>/dev/null
+
+# Testing
+ls jest.config.* vitest.config.* pytest.ini 2>/dev/null
+```
+
+## Step 3: Analyze Project Structure
+
+```bash
+# Get top-level structure
+ls -la | head -20
+
+# Common source directories
+ls -d src app lib pages components 2>/dev/null
+```
+
+## Step 4: Detect Patterns
+
+Look for common patterns in the codebase:
+
+```bash
+# API routes pattern
+ls -d **/api/** app/api pages/api 2>/dev/null | head -5
+
+# Component patterns
+ls -d **/components/** 2>/dev/null | head -5
+
+# Check for TypeScript
+ls tsconfig.json 2>/dev/null
+```
+
+## Step 5: Create .specflow Directory
+
+```bash
+mkdir -p .specflow/specs .specflow/audits .specflow/archive .specflow/todos
+```
+
+## Step 6: Generate PROJECT.md
+
+Based on detected stack and patterns, create `.specflow/PROJECT.md`:
+
+```markdown
+# [Project Name from package.json or directory]
+
+## What This Is
+
+[Infer from README.md if exists, otherwise "Project initialized with SpecFlow"]
+
+## Core Value
+
+[To be defined by user]
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+[Fill based on detection]
+
+## Project Structure
+
+```
+[Simplified tree of main directories]
+```
+
+## Patterns & Conventions
+
+[List detected patterns]
+
+## Constraints
+
+[To be defined by user]
+
+---
+*Generated by SpecFlow on [date]*
+```
+
+## Step 7: Generate STATE.md
+
+Create `.specflow/STATE.md`:
+
+```markdown
+# SpecFlow State
+
+## Current Position
+
+- **Active Specification:** none
+- **Status:** idle
+- **Next Step:** /sf new
+
+## Queue
+
+| # | ID | Title | Priority | Status |
+|---|----|-------|----------|--------|
+
+## Decisions
+
+| Date | Specification | Decision |
+|------|---------------|----------|
+
+## Project Patterns
+
+[Patterns from PROJECT.md]
+
+## Warnings
+
+| Date | Specification | Reason |
+|------|---------------|--------|
+
+---
+*Last updated: [date]*
+```
+
+## Step 8: Generate config.json
+
+Create `.specflow/config.json`:
+
+```json
+{
+  "auto_commit": true,
+  "commit_format": "feat(sf-{id}): {description}",
+  "ask_questions": "critical_only",
+  "complexity_threshold": {
+    "small": 50000,
+    "medium": 150000
+  },
+  "audit_storage": "hybrid"
+}
+```
+
+## Step 9: Output Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SPECFLOW INITIALIZED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Project:** [name]
+**Stack:** [detected technologies]
+
+| File | Purpose |
+|------|---------|
+| `.specflow/PROJECT.md` | Project overview |
+| `.specflow/STATE.md` | Current state |
+| `.specflow/config.json` | Configuration |
+
+## Next Step
+
+`/sf new "your task description"` — create first specification
+
+---
+
+**Tip:** Review `.specflow/PROJECT.md` and fill in:
+- Core Value
+- Constraints
+- Any missing patterns
+```
+
+</workflow>
+
+<success_criteria>
+- [ ] .specflow/ directory created
+- [ ] .specflow/specs/ subdirectory created
+- [ ] .specflow/audits/ subdirectory created
+- [ ] .specflow/archive/ subdirectory created
+- [ ] PROJECT.md created with detected stack
+- [ ] STATE.md created with initial state
+- [ ] config.json created with defaults
+- [ ] User knows next step is /sf new
+</success_criteria>

package/commands/sf/list.md

@@ -0,0 +1,127 @@
+---
+name: sf:list
+description: List all specifications with status, priority, and complexity
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+---
+
+<purpose>
+Display all specifications from `.specflow/specs/` with their basic info: ID, title, status, priority, complexity. Helps navigate between tasks and understand project state.
+</purpose>
+
+<context>
+@.specflow/STATE.md
+</context>
+
+<workflow>
+
+## Step 1: Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized.
+
+Run `/sf init` to start.
+```
+Exit.
+
+## Step 2: Get Active Specification
+
+Read `.specflow/STATE.md` and extract Active Specification ID.
+
+## Step 3: Find All Specifications
+
+```bash
+ls -1 .specflow/specs/SPEC-*.md 2>/dev/null
+```
+
+**If no specs found:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SPECIFICATIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No specifications found.
+
+Create your first specification:
+`/sf new "task description"`
+```
+Exit.
+
+## Step 4: Parse Each Specification
+
+For each SPEC-XXX.md file, read the frontmatter and extract:
+- id
+- type
+- status
+- priority (default: medium)
+- complexity
+
+Also extract title from first `# [Title]` line.
+
+## Step 5: Count Archived Specs
+
+```bash
+ls -1 .specflow/archive/SPEC-*.md 2>/dev/null | wc -l
+```
+
+## Step 6: Sort Specifications
+
+Sort by:
+1. Priority: high → medium → low
+2. Then by creation date (oldest first, from ID number)
+
+## Step 7: Display List
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SPECIFICATIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| #  | ID       | Title              | Status   | Priority | Size   |
+|----|----------|--------------------|----------|----------|--------|
+| 1  | SPEC-003 | Auth middleware    | running  | high     | medium | ← active
+| 2  | SPEC-004 | User profile       | audited  | medium   | small  |
+| 3  | SPEC-005 | Settings page      | draft    | low      | small  |
+
+Total: 3 specs | {archived} complete | {in_progress} in progress
+
+---
+
+**Actions:**
+- `/sf show SPEC-XXX` — view details
+- `/sf next` — work on highest priority
+- `/sf new "task"` — create new specification
+```
+
+## Step 8: Show Status Legend (if helpful)
+
+If there are multiple statuses, show legend:
+
+```
+**Status Legend:**
+- draft: Needs audit
+- audited: Ready to implement
+- running: Implementation in progress
+- review: Needs review
+- done: Completed (in archive)
+```
+
+</workflow>
+
+<success_criteria>
+- [ ] Initialization verified
+- [ ] All specs from .specflow/specs/ listed
+- [ ] Frontmatter parsed (id, status, priority, complexity)
+- [ ] Titles extracted
+- [ ] Sorted by priority, then date
+- [ ] Active specification marked
+- [ ] Statistics shown (total, complete, in progress)
+- [ ] Clear next actions provided
+</success_criteria>