specflow-cc 1.14.2 → 1.16.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.16.0] - 2026-03-23
+
+### Added
+
+- **Brownfield / Delta Specifications** — spec-creator now detects existing implementations and generates a `## Delta` section describing only what changes, preserving what already works
+- **Delta validation in spec-auditor** — auditor validates delta sections for completeness and correctness in brownfield specs
+- **Changes Applied subsection** in `/sf:done` — delta spec completion summaries now include a dedicated section listing what was actually changed
+
+### Fixed
+
+- **Init re-initialization safety** — `/sf:init` now safely handles re-initialization without overwriting existing `.specflow/` state
+- **Deviations subsection disambiguation** — delta completion template no longer collides subsection names when both Deviations and Delta Deviations are present
+
+## [1.15.0] - 2026-03-11
+
+### Fixed
+
+- **TODO lifecycle cleanup** — TODOs now reliably removed when converted to specs via `/sf:plan` and completed via `/sf:done`
+  - `spec-creator` agent writes `source: TODO-XXX` in spec frontmatter when created from a todo
+  - `/sf:plan` Step 7 marked as CRITICAL with mandatory verification (re-reads TODO.md after removal)
+  - `/sf:done` adds Step 7.5 safety net: checks spec `source:` field and cleans up any remaining TODO
+  - Spec template updated with optional `source:` frontmatter field
+
 ## [1.14.1] - 2026-03-05
 
 ### Added

package/agents/spec-auditor.md

@@ -267,6 +267,44 @@ Set NEEDS_DECOMPOSITION if ANY of:
 - Recommend `/sf:run --parallel` mode
 - Set status to NEEDS_DECOMPOSITION (if no critical issues)
 
+## Step 3.6: Delta Validation
+
+**Detection:** Check if spec frontmatter contains `delta: true`.
+
+**If no delta field or delta is false:** Skip this check entirely.
+
+**If delta is true:**
+
+a. Verify `## Delta` section exists. If missing: Critical issue "Spec marked as delta but no Delta section found."
+
+b. Validate ADDED entries:
+   - For each file in ADDED: use Glob/Grep to check if file already exists in the codebase
+   - If file exists: Critical issue "Delta ADDED file `{path}` already exists. Should this be MODIFIED instead?"
+
+c. Validate MODIFIED entries:
+   - For each file in MODIFIED: use Glob/Grep to check if file exists in the codebase
+   - If file does NOT exist: Critical issue "Delta MODIFIED file `{path}` not found. Should this be ADDED instead?"
+   - Check that each MODIFIED entry has at least one sub-bullet describing the change
+   - If no sub-bullets: Warning "MODIFIED entry `{path}` lacks change description"
+
+d. Validate REMOVED entries:
+   - For each file in REMOVED: use Glob/Grep to check if file exists in the codebase
+   - If file does NOT exist: Warning "Delta REMOVED file `{path}` not found. Already removed or wrong path?"
+
+e. Cross-reference: Check that every file mentioned in `## Requirements` is also listed in `## Delta`
+   - Before comparing, normalize all paths: strip any leading `./` and any trailing `/` from both sides so that `./agents/foo.md`, `agents/foo.md`, and `agents/foo.md/` all resolve to the same key.
+   - Files in Requirements but not in Delta (after normalization): Warning "File `{path}` in Requirements but not in Delta section"
+   - Files in Delta but not in Requirements (after normalization): Warning "File `{path}` in Delta but no detailed requirements specified"
+
+**Record in audit output:**
+
+If delta was present, add to audit summary:
+```
+Delta validation: {pass_count}/{total_count} entries valid
+```
+
+If no delta: omit this line.
+
 ## Step 3.7: Goal-Backward Validation
 
 **Detection:** Check if Goal Analysis section exists in the spec.

package/agents/spec-creator.md

@@ -104,6 +104,22 @@ Then derive requirements that ensure ALL truths are achievable.
 - If complexity is clearly "small" (single file, simple change), Goal Analysis is optional
 - For medium/large specs, include Goal Analysis in the generated specification
 
+## Step 2.7: Brownfield Detection
+
+Determine if the task is brownfield (modifying existing code) or greenfield (creating new functionality from scratch).
+
+Detection heuristic:
+- Task description mentions existing files, modules, or features → brownfield
+- Task type is "refactor" → always brownfield
+- Task type is "bugfix" → always brownfield
+- Task description uses terms like "extend", "add to", "change", "update", "remove from", "refactor" → brownfield
+- Task description mentions creating entirely new commands/agents/features with no existing counterpart → greenfield
+
+**Note:** The `type` values "refactor" and "bugfix" above must match the valid frontmatter `type` values actually used in this project. Before implementing, scan existing spec files (e.g., `ls .specflow/specs/`) and note which `type` values appear. If "refactor" or "bugfix" are not present in the schema, map the heuristic to the closest equivalent types that are. For any task `type` not recognized by the heuristic, fall back to keyword-based detection on the task description rather than failing or treating the task as greenfield by default.
+
+If brownfield: set `delta: true` in frontmatter and generate Delta section in Step 5.
+If greenfield: proceed with existing Requirements format (no change).
+
 ## Step 3: Critical Questions (if needed)
 
 If the task has genuine ambiguity that affects approach, use AskUserQuestion.
@@ -139,17 +155,40 @@ If no specs exist in either directory, start with SPEC-001.
 
 Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 
-1. **Frontmatter:** id, type, status (draft), priority, complexity, created
+1. **Frontmatter:** id, type, status (draft), priority, complexity, created, source (if `<todo_context>` provided — set to the TODO ID, e.g., `source: TODO-006`), and optionally `delta: true` (only for brownfield tasks detected in Step 2.7)
 2. **Title:** Clear, action-oriented
 3. **Context:** Why this is needed
    - **If `<prior_discussion>` provided:** Add "Prior Discussion" subsection linking to PRE-XXX or DISC-XXX with key decisions
 4. **Task:** What to do
-5. **Requirements:** Files, interfaces, deletions
-6. **Acceptance Criteria:** Specific, measurable
-7. **Validation Checklist** (medium/large specs only): 3-5 concrete verification steps with expected outcomes. Each item = action + expected result. Examples: "Run `npm test` — all pass", "POST /api/users with invalid email — returns 422", "Open settings page — new toggle visible"
-8. **Constraints:** What NOT to do
-9. **Assumptions:** What you assumed (clearly marked)
-   - **If `<prior_discussion>` provided:** Decisions from discussion are facts, not assumptions
+5. **Delta section (brownfield tasks only):** When `delta: true`, add a `## Delta` section immediately after Context:
+
+   ```markdown
+   ## Delta
+
+   ### ADDED
+   - `path/to/new-file.md` — Description of what this new file provides
+
+   ### MODIFIED
+   - `path/to/existing-file.md` — Description of what changes and why
+     - Section X: Add Y
+     - Section Z: Replace W with V
+
+   ### REMOVED
+   - `path/to/obsolete-file.md` — Why this file is no longer needed
+   ```
+
+   Rules for Delta section:
+   - Each subsection (ADDED/MODIFIED/REMOVED) is optional; omit if empty
+   - At least one subsection must be present
+   - MODIFIED entries include bullet points describing specific changes within the file
+   - The existing `## Requirements` section remains and contains the detailed specifications for each change (the Delta section is a summary/index)
+
+6. **Requirements:** Files, interfaces, deletions
+7. **Acceptance Criteria:** Specific, measurable
+8. **Validation Checklist** (medium/large specs only): 3-5 concrete verification steps with expected outcomes. Each item = action + expected result. Examples: "Run `npm test` — all pass", "POST /api/users with invalid email — returns 422", "Open settings page — new toggle visible"
+9. **Constraints:** What NOT to do
+10. **Assumptions:** What you assumed (clearly marked)
+    - **If `<prior_discussion>` provided:** Decisions from discussion are facts, not assumptions
 
 ## Step 5.5: Generate Implementation Tasks (for medium and large specs)
 

package/commands/sf/done.md

@@ -175,7 +175,58 @@ mkdir -p .specflow/archive
 Update frontmatter:
 - status → "done"
 
-Add completion summary section to the spec:
+Check if the spec frontmatter contains `delta: true`.
+
+**If delta spec (`delta: true`):** Add the following completion summary section, which includes a "Changes Applied" subsection populated from the spec's `## Delta` section content:
+
+```markdown
+---
+
+## Completion
+
+**Completed:** {date} {time}
+**Total Commits:** {count from Execution Summary}
+**Review Cycles:** {count of Review v[N] entries}
+
+### Outcome
+
+{1-2 sentence summary of what was delivered}
+
+### Key Files
+
+- `{path}` — {what it does/why it matters}
+
+### Changes Applied
+
+**Added:**
+- `path/to/new-file.md` — {brief description}
+
+**Modified:**
+- `path/to/existing-file.md` — {brief description of changes}
+
+**Removed:**
+- `path/to/obsolete-file.md` — {brief description}
+
+{Omit any subsection (Added/Modified/Removed) if it has no entries.}
+
+{If a /sf:review was performed before /sf:done, include this subsection noting differences between what the Delta section specified and what was actually implemented. If no deviations were found or no review was performed, omit this subsection entirely:}
+
+### Deviations from Delta
+
+- `path/to/file.md` — {description of how actual implementation differed from Delta entry}
+
+### Patterns Established
+
+{List any new patterns, conventions, or architectural decisions introduced.
+If none: "None — followed existing patterns."}
+
+### Spec Deviations
+
+{Any deviations from the original spec during implementation (unrelated to delta changes).
+If none: "None — implemented as specified."}
+```
+
+**If NOT a delta spec:** Add the standard completion summary section (no "Changes Applied" or "Deviations from Delta" subsections):
 
 ```markdown
 ---
@@ -219,6 +270,20 @@ If significant decisions found, add to STATE.md Decisions table:
 | {date} | SPEC-XXX | {decision description} |
 ```
 
+## Step 7.5: Clean Up Source TODO (safety net)
+
+Check if the spec frontmatter contains a `source:` field (e.g., `source: TODO-006`).
+
+**If `source:` field exists:**
+
+1. Read `.specflow/todos/TODO.md`
+2. Check if the referenced TODO-XXX entry still exists in the file
+3. **If it exists** — remove it (the entire block from `## TODO-XXX` heading through the next `---` separator, inclusive)
+4. Update `*Last updated:` timestamp with note: `TODO-XXX cleaned up (completed via SPEC-YYY)`
+5. Write the updated TODO.md
+
+**If no `source:` field or TODO already removed:** Skip — no action needed.
+
 ## Step 8: Archive Specification
 
 Move spec to archive:
@@ -364,6 +429,7 @@ git commit -m "docs(sf): complete SPEC-XXX"
 - [ ] Spec status updated to "done"
 - [ ] Completion section added
 - [ ] Decisions extracted (if any)
+- [ ] Source TODO cleaned up (if `source:` field exists in spec)
 - [ ] Spec moved to archive
 - [ ] STATE.md updated (cleared active, removed from queue)
 - [ ] Final commit created

package/commands/sf/init.md

@@ -20,19 +20,88 @@ Initialize SpecFlow in the current project. Analyzes the codebase to understand
 
 <workflow>
 
+## Step 0: Parse Arguments
+
+Check whether the user invoked `/sf:init --force`. Look at the invocation string for the `--force` flag. Set a mental variable `FORCE_MODE` to true or false accordingly.
+
 ## Step 1: Check if Already Initialized
 
 ```bash
 [ -d .specflow ] && echo "EXISTS" || echo "NOT_EXISTS"
 ```
 
-**If EXISTS:**
+**If NOT_EXISTS:** proceed to Step 2.
+
+**If EXISTS:** scan for existing data files and directories.
+
+```bash
+# Check each file/directory individually
+[ -f .specflow/PROJECT.md ] && echo "HAS_PROJECT_MD" || true
+[ -f .specflow/STATE.md ] && echo "HAS_STATE_MD" || true
+[ -f .specflow/config.json ] && echo "HAS_CONFIG_JSON" || true
+[ -f .specflow/todos/TODO.md ] && echo "HAS_TODO_MD" || true
+[ "$(ls -A .specflow/specs 2>/dev/null)" ] && echo "HAS_SPECS" || true
+[ "$(ls -A .specflow/archive 2>/dev/null)" ] && echo "HAS_ARCHIVE" || true
+```
+
+Collect which items exist. If ANY of the above are found:
+
+**If FORCE_MODE is false (no `--force` flag):**
+
+Print this warning (substituting actual found items):
+
+```
+WARNING: SpecFlow data already exists in this project.
+
+The following files/directories would be overwritten:
+[list each found item, one per line, e.g.:]
+  - .specflow/PROJECT.md
+  - .specflow/STATE.md
+  - .specflow/config.json
+  - .specflow/todos/TODO.md
+  - .specflow/specs/ (contains files)
+  - .specflow/archive/ (contains files)
+
+Re-running init will overwrite these files. Use `/sf:init --force` to reset.
+
+Tip: Run `/sf:status` to see current state.
+```
+
+Exit. Do NOT proceed.
+
+**If FORCE_MODE is true (`--force` was passed):**
+
+Print a warning listing all files that will be overwritten, then create a timestamped backup.
+
+```
+WARNING: --force flag detected. Existing SpecFlow data will be backed up and overwritten.
+
+The following files/directories will be backed up:
+[list each found item]
+```
+
+Create the backup directory with a timestamp:
+
+```bash
+BACKUP_DIR=".specflow/backup-$(date +%Y-%m-%d-%H%M%S)"
+mkdir -p "$BACKUP_DIR"
+echo "Backup directory: $BACKUP_DIR"
 ```
-SpecFlow already initialized in this project.
 
-Use `/sf:status` to see current state.
+Copy all existing `.specflow/` content (except the backup directory itself) into the backup:
+
+```bash
+# Copy all existing .specflow content into backup
+# Use find to copy files while preserving structure, excluding backup dirs themselves
+find .specflow -maxdepth 1 -not -name "backup-*" -not -name ".specflow" | while read item; do
+  cp -r "$item" "$BACKUP_DIR/"
+done
+echo "Backup complete."
 ```
-Exit.
+
+Then proceed to Step 2.
+
+**If EXISTS but no data files found** (empty directory): proceed to Step 2.
 
 ## Step 2: Detect Tech Stack
 
@@ -162,6 +231,14 @@ mkdir -p .specflow/specs .specflow/audits .specflow/archive .specflow/todos .spe
 
 ## Step 6: Generate PROJECT.md
 
+**Defense-in-depth guard:** Before writing, check if `.specflow/PROJECT.md` already exists AND `--force` was NOT used. If both conditions are true, skip writing this file and note it was skipped.
+
+```bash
+[ -f .specflow/PROJECT.md ] && echo "PROJECT_MD_EXISTS" || echo "PROJECT_MD_MISSING"
+```
+
+If `PROJECT_MD_MISSING` OR `FORCE_MODE` is true: write the file.
+
 Based on detected stack and patterns, create `.specflow/PROJECT.md`:
 
 ```markdown
@@ -201,6 +278,14 @@ Based on detected stack and patterns, create `.specflow/PROJECT.md`:
 
 ## Step 7: Generate STATE.md
 
+**Defense-in-depth guard:** Before writing, check if `.specflow/STATE.md` already exists AND `--force` was NOT used. If both conditions are true, skip writing this file and note it was skipped.
+
+```bash
+[ -f .specflow/STATE.md ] && echo "STATE_MD_EXISTS" || echo "STATE_MD_MISSING"
+```
+
+If `STATE_MD_MISSING` OR `FORCE_MODE` is true: write the file.
+
 Create `.specflow/STATE.md`:
 
 ```markdown
@@ -237,6 +322,14 @@ Create `.specflow/STATE.md`:
 
 ## Step 8: Generate config.json
 
+**Defense-in-depth guard:** Before writing, check if `.specflow/config.json` already exists AND `--force` was NOT used. If both conditions are true, skip writing this file and note it was skipped.
+
+```bash
+[ -f .specflow/config.json ] && echo "CONFIG_JSON_EXISTS" || echo "CONFIG_JSON_MISSING"
+```
+
+If `CONFIG_JSON_MISSING` OR `FORCE_MODE` is true: write the file.
+
 Create `.specflow/config.json`:
 
 ```json

package/commands/sf/plan.md

@@ -147,11 +147,15 @@ Use the priority from the todo as the spec's initial priority.
 ", subagent_type="sf-spec-creator", model="{profile_model}", description="Create specification from todo")
 ```
 
-## Step 7: Remove Todo from List
+## Step 7: Remove Todo from List — CRITICAL
 
-After spec is successfully created, remove the todo entry from TODO.md.
+**This step is MANDATORY. Do NOT skip it after the agent returns.**
 
-Update `*Last updated:` timestamp.
+1. Read `.specflow/todos/TODO.md`
+2. Remove the entire todo block (from `## TODO-XXX` heading through the next `---` separator, inclusive)
+3. Update `*Last updated:` timestamp with note: `TODO-XXX converted to SPEC-YYY`
+4. Write the updated TODO.md
+5. **Verify** by reading TODO.md again — the converted todo MUST NOT appear
 
 **Important:** Only remove after confirmed spec creation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.14.2",
+  "version": "1.16.0",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"

package/templates/spec.md

@@ -5,6 +5,7 @@ status: draft | auditing | revision_requested | audited | running | review | don
 priority: high | medium | low
 complexity: small | medium | large
 created: YYYY-MM-DD
+source: TODO-XXX (optional — set when spec is created from a todo via /sf:plan)
 ---
 
 # [Task Title]