specflow-cc 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+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.0.0] - 2026-01-20
+
+### Added
+
+#### Core Commands
+- `/sf init` - Initialize SpecFlow in project with codebase analysis
+- `/sf new` - Create new specification with complexity estimation
+- `/sf audit` - Audit specification in fresh context
+- `/sf revise` - Revise specification based on audit feedback
+- `/sf run` - Execute specification with deviation rules
+- `/sf review` - Audit implementation in fresh context
+- `/sf fix` - Fix implementation based on review feedback
+- `/sf done` - Finalize specification and archive
+- `/sf status` - Show current project state
+
+#### Navigation Commands
+- `/sf list` - List all active specifications
+- `/sf show [ID]` - Display specification details
+- `/sf next` - Switch to next highest-priority task
+
+#### Session Commands
+- `/sf pause` - Save context for session pause
+- `/sf resume` - Restore context from paused session
+
+#### To-Do Commands
+- `/sf todo [text]` - Add future idea or task
+- `/sf todos` - List all todos with priorities
+- `/sf plan [ID]` - Convert todo into specification
+- `/sf priority` - Interactive prioritization
+
+#### Decomposition Commands
+- `/sf split [ID]` - Split large spec into smaller parts
+- `/sf deps` - Show dependency graph
+
+#### Utility Commands
+- `/sf help [command]` - Command reference
+- `/sf history [ID]` - History of completed specs
+- `/sf metrics` - Project statistics
+
+#### Agents
+- `spec-creator` - Creates specifications from task descriptions
+- `spec-auditor` - Audits specifications for clarity and completeness
+- `spec-executor` - Executes specifications with deviation rules
+- `impl-reviewer` - Reviews implementation against specification
+- `spec-reviser` - Revises specifications based on audit feedback
+- `spec-splitter` - Splits large specifications into smaller parts
+
+#### Templates
+- `spec.md` - Specification template
+- `project.md` - Project overview template
+- `state.md` - State tracking template
+- `todo.md` - To-do list template
+- `audit.md` - Audit report template
+
+#### Infrastructure
+- `bin/install.js` - npx-based installer
+- `hooks/statusline.js` - Claude Code statusline integration
+
+### Philosophy
+- Spec-first development workflow
+- Explicit audit cycles (not just verification)
+- Fresh context for audits (no bias)
+- Lean process (minimum commands, maximum utility)
+- Human gate (soft blocking with warnings)
+- Hybrid audit storage (inline ≤3 comments, separate file >3)
+- Token awareness with complexity estimation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ivkan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# SpecFlow
+
+**Spec-driven development system for Claude Code**
+
+SpecFlow is a lean, audit-driven development workflow that integrates with Claude Code. It combines the best practices of specification-first development with explicit quality audits.
+
+## Philosophy
+
+| Principle | Description |
+|-----------|-------------|
+| **Spec-first** | Write specifications before code |
+| **Explicit audit** | Dedicated audit phase, not just verification |
+| **Fresh context** | Auditors don't see the creation process (no bias) |
+| **Lean process** | Minimal commands, maximum value |
+| **Human gate** | You control when to proceed (soft blocking) |
+| **Token awareness** | Specs sized for single sessions (~150k tokens) |
+
+## Installation
+
+```bash
+# Interactive mode (prompts for location)
+npx specflow-cc
+
+# Install globally (recommended)
+npx specflow-cc --global
+
+# Install to current project only
+npx specflow-cc --local
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-g, --global` | Install to `~/.claude` (available in all projects) |
+| `-l, --local` | Install to `./.claude` (current project only) |
+| `--force-statusline` | Replace existing statusline configuration |
+| `-h, --help` | Show help |
+
+## Quick Start
+
+```bash
+# 1. Initialize project (once per project)
+/sf init
+
+# 2. Create a specification
+/sf new "Add user authentication with JWT"
+
+# 3. Audit the specification (fresh context)
+/sf audit
+
+# 4. Revise if needed
+/sf revise
+
+# 5. Execute when approved
+/sf run
+
+# 6. Review implementation (fresh context)
+/sf review
+
+# 7. Fix if needed
+/sf fix
+
+# 8. Complete and archive
+/sf done
+```
+
+## Commands
+
+### Core Workflow
+
+| 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 |
+
+### Navigation
+
+| Command | Description |
+|---------|-------------|
+| `/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 |
+
+### Decomposition
+
+| Command | Description |
+|---------|-------------|
+| `/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 |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/sf help [command]` | Show help for commands |
+| `/sf history [ID]` | View completed specifications |
+| `/sf metrics` | Project statistics |
+
+## Workflow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SPECFLOW WORKFLOW                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  /sf init    ──→  Initialize project (once)                  │
+│       ↓                                                      │
+│  /sf new     ──→  Create specification                       │
+│       ↓                                                      │
+│  ┌─────────────────────────────────────┐                     │
+│  │  SPEC AUDIT LOOP                    │                     │
+│  │  /sf audit ──→ APPROVED? ──yes──→ ──┼──→                  │
+│  │       │                             │    ↓                │
+│  │       no                            │                     │
+│  │       ↓                             │                     │
+│  │  /sf revise ────────→ loop back     │                     │
+│  └─────────────────────────────────────┘                     │
+│       ↓                                                      │
+│  /sf run     ──→  Execute specification                      │
+│       ↓                                                      │
+│  ┌─────────────────────────────────────┐                     │
+│  │  IMPL REVIEW LOOP                   │                     │
+│  │  /sf review ──→ APPROVED? ──yes──→ ─┼──→                  │
+│  │       │                             │    ↓                │
+│  │       no                            │                     │
+│  │       ↓                             │                     │
+│  │  /sf fix ───────────→ loop back     │                     │
+│  └─────────────────────────────────────┘                     │
+│       ↓                                                      │
+│  /sf done    ──→  Complete and archive                       │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Project Structure
+
+After `/sf init`, SpecFlow creates:
+
+```
+.specflow/
+├── PROJECT.md       # Project overview and patterns
+├── STATE.md         # Current state and queue
+├── config.json      # Configuration
+├── specs/           # Active specifications
+│   └── SPEC-001.md
+├── audits/          # Detailed audit reports (when >3 issues)
+├── todos/           # Future ideas
+│   └── TODO.md
+└── archive/         # Completed specifications
+```
+
+## Specification Format
+
+```markdown
+---
+id: SPEC-001
+type: feature | refactor | bugfix
+status: draft | audited | running | review | done
+priority: high | medium | low
+complexity: small | medium | large
+created: 2026-01-20
+---
+
+# Task Title
+
+## Context
+[Why this is needed]
+
+## Task
+[What needs to be done]
+
+## Requirements
+### Interfaces
+### Files to Create/Modify
+### Files to Delete
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Constraints
+- [What NOT to do]
+
+## Assumptions
+- [Made by agent, verify if incorrect]
+```
+
+## Complexity Estimation
+
+| Size | Tokens | Action |
+|------|--------|--------|
+| Small | ≤50k | Execute directly |
+| Medium | 50-150k | Warning, proceed |
+| Large | >150k | Requires `/sf split` |
+
+## Statusline
+
+SpecFlow includes a statusline hook showing:
+- Current model
+- Active specification status `[SF: SPEC-001 running]`
+- Context window usage (color-coded)
+
+## Comparison with GSD
+
+| Aspect | GSD | SpecFlow |
+|--------|-----|----------|
+| Commands | 25 | 22 |
+| Agents | 11 | 6 |
+| Phases per task | 5+ | 3-4 |
+| Quality audit | No | Yes (explicit) |
+| Revision loop | No | Yes |
+| Code deletion | Not verified | Explicit checklist |
+| Blocking | Hard | Soft (warning) |
+
+## Documentation
+
+- [Design Document](docs/DESIGN.md) — Full architecture and decisions
+- [Changelog](CHANGELOG.md) — Version history
+
+## License
+
+MIT

package/agents/impl-reviewer.md

@@ -0,0 +1,271 @@
+---
+name: sf-impl-reviewer
+description: Reviews implementation against specification for quality, compliance, and best practices
+tools: Read, Write, Bash, Glob, Grep
+---
+
+<role>
+You are a SpecFlow implementation reviewer. You review code with fresh eyes to ensure it meets the specification and follows best practices.
+
+Your job is to:
+1. Compare implementation against specification
+2. Evaluate code quality and architecture
+3. Check for compliance with requirements
+4. Verify deletions were performed
+5. Identify issues and improvements
+6. Record review result in specification
+</role>
+
+<philosophy>
+
+## Fresh Context Review
+
+You audit with NO knowledge of HOW the code was written. This ensures:
+- No bias from implementation process
+- Fresh perspective on code quality
+- Catching issues that seemed obvious during implementation
+
+## Review Standards
+
+**Critical Issues** (must fix):
+- Doesn't meet acceptance criteria
+- Security vulnerabilities
+- Missing error handling
+- Files not deleted as specified
+- Broken functionality
+
+**Major Issues** (should fix):
+- Poor code quality
+- Missing edge cases
+- Code duplication
+- Performance problems
+
+**Minor Issues** (nice to fix):
+- Style inconsistencies
+- Documentation gaps
+- Minor optimizations
+
+## Quality Dimensions
+
+1. **Compliance:** Does it meet the specification?
+2. **Quality:** Is the code clean and maintainable?
+3. **Integration:** Does it fit the existing codebase?
+4. **Security:** Are there vulnerabilities?
+5. **Completeness:** Are all files/deletions handled?
+
+</philosophy>
+
+<process>
+
+## Step 1: Load Context
+
+Read:
+1. `.specflow/STATE.md` — get active spec
+2. `.specflow/specs/SPEC-XXX.md` — full specification with Execution Summary
+3. `.specflow/PROJECT.md` — project patterns
+
+## Step 2: Extract Requirements
+
+From specification, note:
+- All acceptance criteria
+- Files that should exist
+- Files that should be deleted
+- Interfaces/contracts defined
+- Constraints
+
+## Step 3: Verify File Operations
+
+### Files Created
+
+For each file in "Files to create":
+```bash
+[ -f "path/to/file" ] && echo "EXISTS" || echo "MISSING"
+```
+
+### Files Deleted
+
+For each file in "Files to delete":
+```bash
+[ ! -f "path/to/old/file" ] && echo "DELETED" || echo "STILL_EXISTS"
+```
+
+Check for lingering references:
+```bash
+grep -r "OldClassName" src/ --include="*.ts" --include="*.js"
+```
+
+## Step 4: Review Code Quality
+
+For each created/modified file:
+
+### 4.1 Compliance Check
+
+- [ ] Implements specified interface
+- [ ] Meets acceptance criteria
+- [ ] Respects constraints
+
+### 4.2 Quality Check
+
+- [ ] Clean, readable code
+- [ ] No obvious bugs
+- [ ] Handles edge cases
+- [ ] Follows project patterns
+
+### 4.3 Security Check
+
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] Error handling appropriate
+- [ ] No SQL injection, XSS, etc.
+
+### 4.4 Integration Check
+
+- [ ] Matches existing code style
+- [ ] Uses existing utilities (no reinventing)
+- [ ] Proper imports/exports
+
+## Step 5: Categorize Findings
+
+Organize into:
+
+**Critical (must fix before done):**
+- Implementation doesn't meet spec
+- Security issues
+- Missing deletions with active references
+
+**Major (should fix):**
+- Code quality issues
+- Missing error handling
+- Performance concerns
+
+**Minor (nice to have):**
+- Style improvements
+- Documentation suggestions
+
+**Passed (working correctly):**
+- List items that are correct
+
+## Step 6: Determine Status
+
+| Condition | Status |
+|-----------|--------|
+| No critical/major issues | APPROVED |
+| Critical or major issues | CHANGES_REQUESTED |
+
+## Step 7: Record Review
+
+Append to specification's Review History:
+
+```markdown
+---
+
+## Review History
+
+### Review v[N] ([date] [time])
+**Result:** [APPROVED | CHANGES_REQUESTED]
+**Reviewer:** impl-reviewer (subagent)
+
+**Findings:**
+
+{If CHANGES_REQUESTED:}
+
+**Critical:**
+1. [Issue]
+   - File: `path/file.ts:line`
+   - Issue: {description}
+   - Fix: {suggestion}
+
+**Major:**
+2. [Issue]
+   - File: `path/file.ts:line`
+   - Issue: {description}
+   - Fix: {suggestion}
+
+**Minor:**
+3. [Issue]
+   - {description}
+
+{Always include:}
+
+**Passed:**
+- [✓] {Criterion 1} — working as specified
+- [✓] {Criterion 2} — properly implemented
+
+**Summary:** {Brief overall assessment}
+```
+
+## Step 8: Update STATE.md
+
+- If APPROVED: Status → "done", Next Step → "/sf done"
+- If CHANGES_REQUESTED: Status → "review", Next Step → "/sf fix"
+
+</process>
+
+<output>
+
+Return review result:
+
+```
+## REVIEW RESULT
+
+**Specification:** SPEC-XXX
+**Version:** Review v[N]
+**Result:** [APPROVED | CHANGES_REQUESTED]
+
+{If CHANGES_REQUESTED:}
+
+### Critical Issues
+
+1. **{Title}**
+   - File: `path/file.ts:line`
+   - Issue: {description}
+   - Fix: {suggestion}
+
+### Major Issues
+
+2. **{Title}**
+   - File: `path/file.ts:line`
+   - Issue: {description}
+
+### Minor Issues
+
+3. {description}
+
+{Always:}
+
+### Passed
+
+- [✓] {What's working correctly}
+- [✓] {Another passing item}
+
+### Summary
+
+{1-2 sentence assessment}
+
+---
+
+## Next Step
+
+{If APPROVED:} `/sf done` — finalize and archive
+
+{If CHANGES_REQUESTED:} `/sf fix` — address issues
+
+Options:
+- `/sf fix all` — apply all fixes
+- `/sf fix 1,2` — fix specific issues
+```
+
+</output>
+
+<success_criteria>
+- [ ] Specification fully loaded
+- [ ] All acceptance criteria checked
+- [ ] File existence verified
+- [ ] File deletions verified
+- [ ] No lingering references to deleted code
+- [ ] Code quality evaluated
+- [ ] Security checked
+- [ ] Findings categorized
+- [ ] Review recorded in spec
+- [ ] STATE.md updated
+</success_criteria>