specflow-cc 1.0.0

package/commands/sf/metrics.md

@@ -0,0 +1,319 @@
+---
+name: sf:metrics
+description: Show project statistics and quality metrics
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+<purpose>
+Calculate and display project statistics including completion rates, quality metrics (audit/review cycles), complexity distribution, and actionable insights. Helps understand project health and identify areas for improvement.
+</purpose>
+
+<context>
+@.specflow/PROJECT.md
+@.specflow/STATE.md
+@.specflow/specs/SPEC-*.md
+@.specflow/archive/SPEC-*.md
+@.specflow/todos/TODO.md
+</context>
+
+<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: Gather Data
+
+### Count Specifications
+
+```bash
+# Active specs
+ACTIVE=$(ls .specflow/specs/SPEC-*.md 2>/dev/null | wc -l)
+
+# Archived specs
+ARCHIVED=$(ls .specflow/archive/SPEC-*.md 2>/dev/null | wc -l)
+
+# Total
+TOTAL=$((ACTIVE + ARCHIVED))
+```
+
+### Parse Active Specs
+
+For each `.specflow/specs/SPEC-*.md`:
+- Extract status from frontmatter
+- Extract complexity from frontmatter
+- Extract type from frontmatter
+- Count audit entries
+
+Group by status:
+- draft
+- audited
+- running
+- review
+- (done specs are in archive)
+
+### Parse Archived Specs
+
+For each `.specflow/archive/SPEC-*.md`:
+- Extract complexity
+- Extract type
+- Count audit cycles (Audit v1, v2, etc.)
+- Count review cycles
+- Check if first-pass audit (only 1 audit = first-pass)
+- Check if first-pass review (only 1 review = first-pass)
+
+### Parse To-Dos
+
+```bash
+# Count todos
+TODO_COUNT=$(grep -c "^## TODO-" .specflow/todos/TODO.md 2>/dev/null || echo 0)
+
+# Count converted (todos that became specs - check STATE.md decisions)
+# This is approximated by todos with "converted" or spec reference
+```
+
+### Get Project Start Date
+
+Read `.specflow/PROJECT.md` for initialized date, or use earliest spec creation date.
+
+## Step 3: Calculate Metrics
+
+### Completion Metrics
+
+```
+Total created: TOTAL
+Completed: ARCHIVED
+In progress: ACTIVE (non-draft)
+Draft: count where status = draft
+Completion rate: (ARCHIVED / TOTAL) × 100%
+```
+
+### Quality Metrics
+
+```
+Avg audit cycles: sum(audits) / ARCHIVED
+Avg review cycles: sum(reviews) / ARCHIVED
+First-pass audit rate: (specs with 1 audit / ARCHIVED) × 100%
+First-pass review rate: (specs with 1 review / ARCHIVED) × 100%
+```
+
+### Complexity Distribution
+
+```
+Small: count where complexity = small
+Medium: count where complexity = medium
+Large: count where complexity = large
+```
+
+### Type Distribution
+
+```
+Feature: count where type = feature
+Refactor: count where type = refactor
+Bugfix: count where type = bugfix
+```
+
+### To-Do Metrics
+
+```
+Total items: TODO_COUNT
+Pending: count without conversion
+Converted: count with conversion
+Conversion rate: (converted / total) × 100%
+```
+
+## Step 4: Generate Insights
+
+Based on calculated metrics, generate 2-4 actionable insights:
+
+**If first-pass audit rate < 50%:**
+- "Consider more thorough initial specifications"
+
+**If avg audit cycles > 2:**
+- "Specs may benefit from better scoping upfront"
+
+**If large specs > 20% of total:**
+- "Consider splitting large specs earlier (/sf split)"
+
+**If first-pass review rate > 70%:**
+- "Good implementation quality — specs are well-defined"
+
+**If completion rate < 50% and TOTAL > 5:**
+- "Many specs in progress — consider completing before starting new"
+
+**If TODO_COUNT > 5 and conversion rate < 30%:**
+- "Backlog growing — consider /sf priority or /sf plan"
+
+**If all metrics good:**
+- "Project health is excellent — keep up the discipline!"
+
+## Step 5: Display Metrics
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PROJECT METRICS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Project:** {project name from PROJECT.md}
+**Initialized:** {date}
+**Period:** {days} days
+
+---
+
+## Specifications
+
+| Metric              | Value    |
+|---------------------|----------|
+| Total created       | {N}      |
+| Completed           | {N}      |
+| In progress         | {N}      |
+| Draft               | {N}      |
+| Completion rate     | {N}%     |
+
+## Status Breakdown
+
+| Status    | Count |
+|-----------|-------|
+| done      | {N}   |
+| review    | {N}   |
+| running   | {N}   |
+| audited   | {N}   |
+| draft     | {N}   |
+
+## Complexity Distribution
+
+| Size   | Count | % of Total |
+|--------|-------|------------|
+| Small  | {N}   | {N}%       |
+| Medium | {N}   | {N}%       |
+| Large  | {N}   | {N}%       |
+
+## Type Distribution
+
+| Type     | Count | % of Total |
+|----------|-------|------------|
+| feature  | {N}   | {N}%       |
+| refactor | {N}   | {N}%       |
+| bugfix   | {N}   | {N}%       |
+
+## Quality Metrics
+
+{If ARCHIVED > 0:}
+| Metric                   | Value |
+|--------------------------|-------|
+| Avg audit cycles         | {N.N} |
+| Avg review cycles        | {N.N} |
+| First-pass audit rate    | {N}%  |
+| First-pass review rate   | {N}%  |
+
+### Audit Results
+
+| Result             | Count | %     |
+|--------------------|-------|-------|
+| Approved (1st try) | {N}   | {N}%  |
+| Approved (2+ tries)| {N}   | {N}%  |
+
+### Review Results
+
+| Result             | Count | %     |
+|--------------------|-------|-------|
+| Approved (1st try) | {N}   | {N}%  |
+| Approved (2+ tries)| {N}   | {N}%  |
+
+{If ARCHIVED = 0:}
+*No completed specifications yet — quality metrics will appear after first completion.*
+
+## To-Do Backlog
+
+{If TODO.md exists and has items:}
+| Metric         | Value |
+|----------------|-------|
+| Total items    | {N}   |
+| Pending        | {N}   |
+| Converted      | {N}   |
+| Conversion rate| {N}%  |
+
+{If no todos:}
+No to-do items.
+
+Add ideas: `/sf todo "idea"`
+
+---
+
+## Insights
+
+{List 2-4 insights based on analysis}
+
+- {Insight 1}
+- {Insight 2}
+- {Insight 3}
+
+---
+
+*Metrics calculated from project data*
+*Period: {start date} — {today}*
+```
+
+## Step 6: Handle Insufficient Data
+
+**If TOTAL = 0:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PROJECT METRICS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Project:** {project name}
+**Initialized:** {date}
+
+---
+
+## Insufficient Data
+
+No specifications created yet.
+
+Create your first specification to start tracking metrics:
+
+`/sf new "task description"`
+
+---
+
+## What Metrics Will Track
+
+Once you have specifications:
+- Completion rates
+- Audit/review cycle efficiency
+- Complexity distribution
+- Quality trends
+
+**Tip:** The more specs you complete, the more valuable these insights become.
+```
+
+</workflow>
+
+<success_criteria>
+- [ ] Initialization verified
+- [ ] All specs (active + archived) counted
+- [ ] Status breakdown calculated
+- [ ] Complexity distribution calculated
+- [ ] Type distribution calculated
+- [ ] Audit cycles averaged (if archived exists)
+- [ ] Review cycles averaged (if archived exists)
+- [ ] First-pass rates calculated
+- [ ] To-do metrics included
+- [ ] Actionable insights generated
+- [ ] Insufficient data handled gracefully
+</success_criteria>

package/commands/sf/new.md

@@ -0,0 +1,171 @@
+---
+name: sf:new
+description: Create a new specification from task description
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<purpose>
+Create a new specification from a task description. Asks critical questions if needed, estimates complexity, and creates a well-structured SPEC-XXX.md file.
+</purpose>
+
+<context>
+@.specflow/PROJECT.md
+@.specflow/STATE.md
+@~/.claude/specflow-cc/templates/spec.md
+@~/.claude/specflow-cc/agents/spec-creator.md
+</context>
+
+<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: Parse Arguments
+
+Extract task description from command arguments.
+
+**If no description provided:**
+Use AskUserQuestion:
+- header: "Task"
+- question: "What do you want to build?"
+- options: (freeform text input)
+
+## Step 3: Spawn Spec Creator Agent
+
+Launch the spec-creator subagent with context:
+
+```
+Task(prompt="
+<task_description>
+{user's task description}
+</task_description>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<current_state>
+@.specflow/STATE.md
+</current_state>
+
+Create a specification following the spec-creator agent instructions.
+", subagent_type="sf-spec-creator", description="Create specification")
+```
+
+## Step 4: Handle Agent Response
+
+The agent will:
+1. Ask critical questions (0-3) if needed
+2. Create SPEC-XXX.md
+3. Update STATE.md
+4. Return structured result
+
+## Step 5: Display Result
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SPECIFICATION CREATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**ID:** SPEC-XXX
+**Title:** [title]
+**Type:** [feature | refactor | bugfix]
+**Complexity:** [small | medium | large]
+
+### Assumptions Made
+
+- [List assumptions agent made]
+
+### File
+
+`.specflow/specs/SPEC-XXX.md`
+
+---
+
+## Next Step
+
+`/sf audit` — audit specification before implementation
+
+{If complexity is large:}
+
+### Warning
+
+Specification is large (>150k tokens estimated).
+Consider `/sf split SPEC-XXX` to decompose into smaller specs.
+```
+
+</workflow>
+
+<fallback>
+
+**If agent spawning fails**, execute inline:
+
+## Inline Spec Creation
+
+### Get Next Spec Number
+
+```bash
+LAST=$(ls .specflow/specs/SPEC-*.md 2>/dev/null | sort -V | tail -1 | grep -oP 'SPEC-\K\d+')
+NEXT=$(printf "%03d" $((${LAST:-0} + 1)))
+echo "SPEC-$NEXT"
+```
+
+### Analyze Task
+
+Based on task description:
+- Determine type: feature/refactor/bugfix
+- Identify likely files to modify
+- Estimate complexity
+
+### Write Specification
+
+Create `.specflow/specs/SPEC-XXX.md` with:
+- Frontmatter (id, type, status: draft, priority: medium, complexity, created)
+- Context section
+- Task section
+- Requirements section
+- Acceptance criteria
+- Constraints
+- Assumptions
+
+### Update STATE.md
+
+```markdown
+## Current Position
+
+- **Active Specification:** SPEC-XXX
+- **Status:** drafting
+- **Next Step:** /sf audit
+```
+
+Add to Queue table.
+
+</fallback>
+
+<success_criteria>
+- [ ] SpecFlow initialization verified
+- [ ] Task description obtained
+- [ ] SPEC-XXX.md created with all sections
+- [ ] Complexity estimated (small/medium/large)
+- [ ] Assumptions documented
+- [ ] STATE.md updated with new spec
+- [ ] User knows next step is /sf audit
+</success_criteria>

package/commands/sf/next.md

@@ -0,0 +1,182 @@
+---
+name: sf:next
+description: Find and activate the highest priority actionable specification
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<purpose>
+Find the highest priority specification that needs action, set it as active in STATE.md, and show its summary with the recommended next action. Helps quickly jump back into work.
+</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: Find All Specifications
+
+```bash
+ls -1 .specflow/specs/SPEC-*.md 2>/dev/null
+```
+
+**If no specs found:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ NO ACTIONABLE TASKS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No specifications ready for work.
+
+**Options:**
+- `/sf new "description"` — create new specification
+- `/sf todos` — view idea backlog
+```
+Exit.
+
+## Step 3: Parse and Score Specifications
+
+For each spec, read frontmatter and calculate priority score:
+
+### Status Priority (higher = more urgent)
+| Status | Score | Reason |
+|--------|-------|--------|
+| review | 100 | Needs immediate attention (almost done) |
+| running | 90 | In progress, continue |
+| audited | 80 | Ready to implement |
+| revision_requested | 70 | Needs revision |
+| auditing | 60 | Audit in progress |
+| draft | 50 | Needs audit |
+
+### Priority Modifier
+| Priority | Modifier |
+|----------|----------|
+| high | +30 |
+| medium | +20 |
+| low | +10 |
+
+### Final Score
+`score = status_score + priority_modifier`
+
+For ties, prefer older specs (lower ID number).
+
+## Step 4: Select Best Candidate
+
+Choose spec with highest score.
+
+**If no actionable specs** (all done or blocked):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ NO ACTIONABLE TASKS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+All specifications are either completed or blocked.
+
+**Options:**
+- `/sf new "description"` — create new specification
+- `/sf todos` — view idea backlog
+- `/sf list` — see all specifications
+```
+Exit.
+
+## Step 5: Update STATE.md
+
+Update `.specflow/STATE.md`:
+- Set **Active Specification** to selected spec
+- Set **Status** based on spec's current status
+- Set **Next Step** based on recommended action
+
+## Step 6: Determine Recommended Action
+
+| Status | Recommended Command | Description |
+|--------|---------------------|-------------|
+| draft | `/sf audit` | Audit specification |
+| auditing | Continue audit | Complete the audit |
+| revision_requested | `/sf revise` | Address audit comments |
+| audited | `/sf run` | Implement specification |
+| running | Continue or `/sf review` | Complete implementation |
+| review | `/sf fix` or `/sf done` | Address review or finalize |
+
+## Step 7: Display Next Task
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ NEXT TASK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**{ID}:** {Title}
+**Priority:** {priority} | **Status:** {status} | **Complexity:** {complexity}
+
+---
+
+## Summary
+
+{First 2-3 sentences from Context or Task section}
+
+## Acceptance Criteria
+
+{List acceptance criteria with checkboxes}
+
+---
+
+{If there are outstanding issues from audit/review:}
+## Outstanding Issues
+
+From {audit/review} v{N}:
+1. {issue}
+2. {issue}
+
+---
+
+**Ready to {action description}:** `{recommended_command}`
+
+{If more specs in queue:}
+**Queue:** {N} more specs waiting
+```
+
+## Step 8: Show Context Tips
+
+**If status is revision_requested:**
+```
+**Tip:** Review audit comments with `/sf show {ID}` before revising.
+```
+
+**If status is review:**
+```
+**Tip:** Check implementation against acceptance criteria.
+```
+
+**If complexity is large:**
+```
+**Tip:** Consider `/sf split {ID}` to break into smaller specs.
+```
+
+</workflow>
+
+<success_criteria>
+- [ ] Initialization verified
+- [ ] All specs scanned and scored
+- [ ] Highest priority actionable spec selected
+- [ ] STATE.md updated with new active spec
+- [ ] Summary displayed with acceptance criteria
+- [ ] Clear recommended action provided
+- [ ] Queue status shown
+</success_criteria>