@gordon.gan/specflow 1.0.0

package/skills/specflow-plan/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: specflow-plan
+description: "First-iteration deep analysis -- proposal + specs + design + tasks"
+---
+
+# SpecFlow: Plan
+
+> **HARD GATE**: User must confirm proposal before specs generation.
+
+## Purpose
+
+Plan is the **first-iteration deep-analysis pass**: in a single invocation it produces all four change artifacts (`proposal.md`, delta `specs/`, `design.md`, `tasks.md`). The design and tasks are substantive first drafts — not placeholders — but `/specflow:refine` will later rewrite them across multiple rounds of iteration, and `/specflow:build` Phase A will regenerate `tasks.md` under strict writing-plans rules.
+
+Treat every artifact here as "v1, to be iterated on" — depth matters, but so does moving through all four stages in one pass.
+
+## Prerequisites
+
+- `specflow/specs/` directory should exist, indicating this is a specflow-initialized project. For a brand-new greenfield change with no existing specs, proceed — the prompt handles that case. If `specflow/` itself does not exist, suggest running `specflow init` first.
+- `specflow` CLI must be available on PATH.
+
+## Stage 1: Create Change
+
+Run `specflow change new <name>` to initialize a new change directory.
+
+The CLI automatically sets `phase=plan` in `.specflow.yaml` on creation (no separate phase call needed here).
+
+## Stage 2: Generate Proposal
+
+Read the file at `.claude/specflow/prompts/plan/proposal.md` and follow its instructions.
+
+**Important**: That prompt file contains the required interactive Q&A flow, the exact proposal format (`## Why` / `## What Changes` / `## Capabilities` / `## Impact`), and the user confirmation gate. You MUST read it before writing the proposal — do not invent the format.
+
+Generate the proposal document inside the change directory at `specflow/changes/<name>/proposal.md`.
+
+### Gate: Proposal Confirmation (HARD GATE)
+
+Present the proposal to the user.
+**Ask the user to confirm the proposal.**
+Do NOT proceed to specs generation until the user explicitly confirms. This is the only mandatory hard gate in the plan flow — everything that follows flows through without interruption so the user can review the full first-iteration package at the end.
+
+## Stage 3: Generate Specs
+
+Read the file at `.claude/specflow/prompts/plan/specs.md` and follow its instructions.
+
+Generate delta specs inside the change directory at `specflow/changes/<name>/specs/<capability>/spec.md`.
+
+### Gate: Specs Confirmation (optional light gate)
+
+Briefly summarize the delta specs generated. Accept a quick acknowledgement from the user ("looks good" / "continue") and proceed. If the user raises substantive objections, pause and revise — otherwise continue directly to Stage 4. This is an optional checkpoint, not a full hard gate; deeper scrutiny will happen in `/specflow:refine`.
+
+## Stage 4: Generate Design (first-iteration)
+
+Read the file at `.claude/specflow/prompts/plan/design-draft.md` and follow its instructions.
+
+Generate `design.md` inside the change directory. This draft should be substantive: identify real architectural decisions, capture options considered, and record rationale. It is a first iteration — `/specflow:refine` will deepen it through multiple brainstorming rounds — but it is NOT a placeholder.
+
+**No gate here.** Continue directly to Stage 5. The user will review everything together at Stage 6.
+
+## Stage 5: Generate Tasks (first-iteration)
+
+Read the file at `.claude/specflow/prompts/plan/tasks-draft.md` and follow its instructions.
+
+Generate `tasks.md` inside the change directory. Produce a substantive first-iteration task breakdown (3–8 tasks typical), ordered with dependencies. Do not write placeholders like "TBD" or "implement feature". `/specflow:build` Phase A will rewrite this file under strict writing-plans rules, but this first draft feeds both `/specflow:refine` context and Phase A analysis.
+
+**No gate here.** Continue directly to Stage 6.
+
+## Stage 6: Final Review
+
+Present all four artifacts to the user with clear "first-iteration" labeling:
+
+- `proposal.md` — confirmed in Stage 2
+- Delta `specs/` under the change directory — the contract
+- `design.md` — **first-iteration draft**; `/specflow:refine` will deepen this across multiple rounds
+- `tasks.md` — **first-iteration draft**; `/specflow:build` Phase A will rewrite this under strict writing-plans rules
+
+Make the iteration expectation explicit: the user should not treat design/tasks as final. They are deliberate first drafts produced so downstream skills have real substance to work with.
+
+### Next Step
+
+Suggest `/specflow:refine` to enter the multi-round refinement loop that rewrites `design.md` (and optionally updates the other artifacts) based on brainstorming. After refine completes, `/specflow:build` will consume the refined artifacts.
+
+No hard gate after Stage 6 — `/specflow:refine` owns the next overall validation gate.

package/skills/specflow-refine/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: specflow-refine
+description: "Technical deepening -- multi-round attacking review + 4 challenge behaviors + Superpowers 9-step"
+---
+
+# SpecFlow: Refine
+
+> **HARD GATE**: No implementation or scaffolding until user confirms refined artifacts.
+> Phase MUST advance to `refined` only with explicit user confirmation of the final state.
+
+Refine runs as an **internal auto-multi-round loop** within one invocation. Minimum 2 rounds
+unconditional; AI semantically judges convergence after round 2; no upper limit. Each round
+runs the Superpowers 9-step brainstorming process with 4 challenge behaviors injected,
+produces impact analysis, lets the user pick scope (A/B/C), writes & validates updates, and
+emits a round diff summary.
+
+## Prerequisites
+
+- Active change with `.specflow.yaml` `phase=plan` (refine refuses if phase is not `plan`).
+- All 4 plan-phase artifacts exist in `specflow/changes/<name>/`:
+  - `proposal.md`
+  - `specs/**/*.md` (at least one delta spec)
+  - `design.md`
+  - `tasks.md`
+- `specflow` CLI available on PATH (for `specflow validate` and the final phase transition).
+
+If any precondition fails, stop and instruct the user to run `/specflow:plan` first.
+
+## Stage 1: Pre-loop setup
+
+Read, in order:
+
+1. `specflow/changes/<name>/proposal.md`
+2. All files under `specflow/changes/<name>/specs/`
+3. `specflow/changes/<name>/design.md`
+4. `specflow/changes/<name>/tasks.md`
+5. `specflow/specs/` main baseline (for context on what this change diffs against)
+6. `.claude/specflow/prompts/refine/brainstorm.md` (the 9-step + 4 challenge behaviors process)
+7. `.claude/specflow/prompts/refine/update-artifacts.md` (impact analysis + format preservation)
+
+Summarize the current state of the 4 artifacts for the user in 3-5 bullets, then announce
+`Round 1 start` and enter the LOOP.
+
+## LOOP (Stages 2-4) — each iteration is one refine round
+
+Repeat Stages 2 → 3 → 4 for every round. Stage 5 decides whether to loop again.
+
+### Stage 2: Execute the 9-step brainstorming (per brainstorm.md)
+
+Follow `.claude/specflow/prompts/refine/brainstorm.md` Steps 1-4:
+
+- Step 1 — Examine existing artifacts (inject Challenge Behavior #1: challenge plan's
+  assumptions)
+- Step 2 — Ask clarifying questions (inject Challenge Behaviors #3 and #4: explore omitted
+  boundaries, question scope)
+- Step 3 — Propose 2-3 approaches with trade-offs (inject Challenge Behavior #2: propose
+  new options for every existing decision)
+- Step 4 — Present design sections for the updates this round proposes
+
+Each round MUST produce visible output for each of the 4 challenge behaviors. Do not let
+them be implicit — the user should see the behaviors fire.
+
+### Stage 3: Impact analysis + user scope choice (per update-artifacts.md)
+
+Hand off to `.claude/specflow/prompts/refine/update-artifacts.md`:
+
+- Apply routing rules to decide which files the round's conclusions affect.
+- Present the impact analysis block listing every affected file.
+- Wait for the user to pick scope A (apply all), B (primary only, defer cascades), or
+  C (defer entirely).
+
+Never begin writing without the user's explicit A/B/C choice.
+
+### Stage 4: Apply updates + validate + report round diff summary
+
+Still under update-artifacts.md:
+
+- Apply the writes implied by the user's scope choice, respecting per-artifact format
+  preservation rules.
+- Run `specflow validate` on any modified spec file. If validation fails, revert the file
+  to its pre-edit state and report the issue to the user; do not proceed until resolved.
+- Emit the round-end diff summary in the format defined by update-artifacts.md.
+- Announce `Round N end`.
+
+## Stage 5: Convergence check
+
+Apply this logic at the end of every round:
+
+- **If round < 2**: `round++`, unconditionally loop back to Stage 2. The 2-round minimum
+  is non-negotiable — do not ask the user whether to continue before round 2 completes.
+- **If round ≥ 2**: perform AI semantic convergence judgment per brainstorm.md Step 8:
+  - Are there still meaningful unaddressed challenges across the 4 behaviors?
+  - Are there open clarifying questions?
+  - Are there unresolved scope concerns?
+  - Is any artifact still stale relative to the discussion?
+  - Did the latest round introduce new considerations not yet propagated?
+  - If ANY answer is yes: NOT converged → `round++`, loop back to Stage 2.
+  - If ALL answers are no: converged → proceed to Stage 6.
+- **User override**: the user may request additional rounds at any time, even after AI
+  judges convergence. User override takes precedence — `round++` and loop back to Stage 2.
+
+Announce each round's convergence decision (and its reasoning) to the user as part of the
+Stage 4 round-end output.
+
+## Stage 6: Final confirmation
+
+Only reached after Stage 5 declared convergence AND the user did not request another round.
+
+1. Present a **cross-round summary**: what changed in each round, which artifacts now differ
+   from the plan-phase baseline, which decisions were resolved, which questions remained
+   open (if any).
+2. **HARD GATE**: Wait for the user's explicit confirmation of the final refined state.
+   A mere acknowledgement of a round's diff summary is NOT confirmation of the overall
+   refined state — ask explicitly: "Confirm this refined state is final and I should mark
+   the phase as `refined`?"
+3. On explicit confirmation: invoke `specflow change phase <name> --set refined` to
+   advance `.specflow.yaml` `phase` from `plan` to `refined`.
+4. Suggest `/specflow:build` as the next slash command.
+
+If the user declines to confirm and requests more exploration, treat it as a user-requested
+extra round (loop back to Stage 2, phase stays `plan`).
+
+## Not covered by refine
+
+- No Phase A rewriting of `tasks.md` at writing-plans precision — that belongs to
+  `/specflow:build` Phase A.
+- No code scaffolding, no implementation, no worktree setup — build owns all of that.
+- Refine only updates artifacts and advances phase to `refined`; it never touches code.

package/skills/specflow-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: specflow-review
+description: "Spec-aware code review with regression checking"
+---
+
+# SpecFlow: Review
+
+## Prerequisites
+
+- An active change must exist with specs and implementation work in progress.
+- Code changes must be present (staged or unstaged).
+
+## Stage 1: Dispatch Reviewer
+
+Read the file at `.claude/specflow/prompts/review/code-review.md` and follow its instructions.
+
+Dispatch the reviewer against the current code changes. The review must be spec-aware:
+- Check implementation against delta specs
+- Check for regressions against main specs
+- Verify naming and structural conventions
+
+## Stage 2: Severity Triage
+
+Categorize findings by severity:
+- **CRITICAL**: Blocks merge. Must be fixed before proceeding.
+- **HIGH**: Should be fixed. Requires justification to skip.
+- **MEDIUM**: Recommended fix. Can defer with acknowledgment.
+- **LOW**: Suggestions and style nits.
+
+## Stage 3: Report
+
+Present the triage report to the user.
+
+If any CRITICAL findings exist:
+- List them explicitly.
+- **CRITICAL findings block merge.** Inform the user that these must be resolved.
+
+If no CRITICAL findings:
+- Summarize HIGH/MEDIUM/LOW counts.
+- Inform the user the code is eligible to proceed.

package/skills/specflow-scan/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: specflow-scan
+description: "[PLANNED v0.3] Brownfield project scanner -- not yet functional"
+---
+
+# SpecFlow: Scan (Planned — v0.3)
+
+> **NOT YET FUNCTIONAL.** The `specflow scan` CLI subcommand does not exist in v0.2.x. Invoking this skill would immediately fail when it tries to run `specflow scan`. The skill is kept registered so its slot is reserved in the command namespace; the implementation is planned for v0.3.
+
+## Behavior in v0.2.x
+
+If the user triggers `/specflow:scan` or `$specflow-scan`, do NOT attempt to run `specflow scan` (the CLI will return an unknown-command error). Instead respond:
+
+> "`/specflow:scan` / `$specflow-scan` is planned for v0.3 and not yet implemented in v0.2.x. For a brownfield project that has no `specflow/specs/` baseline yet, the workable alternative today is:
+>
+> 1. Run `specflow init --ide both` (or `--ide all` / `--ide codex`) if not already done (creates `specflow/` and IDE assets under `.cursor/`, `.claude/`, and/or `.agents/`).
+> 2. Identify one capability area you are about to change (e.g. `user-auth`, `billing`).
+> 3. Run `/specflow:plan` or `$specflow-plan \"<your change description>\"` directly. In the proposal Q&A, describe the existing behavior in the affected area — plan will generate both the delta spec for your change and an implicit first pass at the capability's contract. After the first archive, the delta becomes the main spec baseline for that capability.
+>
+> This is not a perfect substitute for a full code scan, but it keeps the spec-driven flow moving without waiting for v0.3."
+
+Then stop. Do not proceed to any Stage 1/2/3 behavior below — those describe the planned v0.3 flow.
+
+## Planned design (v0.3) — for reference, not currently executable
+
+### Planned Stage 1: Execute Scan
+
+Run `specflow scan` against the target project. If `--module` flag is provided, read the IDE-local prompt file:
+
+- Cursor: `.cursor/specflow/prompts/shared/dispatching-parallel-agents.md`
+- Claude: `.claude/specflow/prompts/shared/dispatching-parallel-agents.md`
+- Codex: `.agents/specflow/prompts/shared/dispatching-parallel-agents.md`
+
+Then scan modules in parallel; otherwise run a single pass.
+
+### Planned Stage 2: Present Results
+
+Scan produces `specflow/SCAN_REPORT.md`. Present a summary highlighting detected modules, identified specs and coverage gaps, and suggested next actions.
+
+### Planned Gate: User Confirmation
+
+Ask the user to confirm the scan results. Do NOT proceed until explicit confirmation. Confirmed results become the Source of Truth for all downstream commands.
+
+### Planned Stage 3: Finalize
+
+Once confirmed, the scan results are locked and the user can run `/specflow:plan` to begin requirements planning.
+
+The v0.3 design rationale, scope, and risks will be captured in a dedicated `openspec` change at v0.3 planning time.

package/skills/specflow-snap/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: specflow-snap
+description: "Post-hoc change documentation from git diff"
+---
+
+# SpecFlow: Snap
+
+## Prerequisites
+
+- Git repository must have uncommitted or recent committed changes to document.
+- `specflow` CLI must be available on PATH.
+
+## Stage 1: Analyze Changes
+
+Run `git diff` and `git log` to capture what changed.
+
+Collect:
+- Files modified, added, removed
+- Commit messages (if committed)
+- Diff summary per file
+
+## Stage 2: Generate Change
+
+Create a new change with all tasks pre-marked as done:
+- Generate proposal from the diff summary
+- Generate delta specs inferred from the actual code changes
+- Generate tasks.md with all tasks marked complete
+
+## Stage 3: Infer Delta Specs
+
+From the code changes, infer what behavioral specs were added or modified.
+Write delta spec files inside the change directory.
+
+## Gate: User Confirmation
+
+Present the generated change documentation to the user.
+**Ask the user to confirm the inferred specs are accurate.**
+Do NOT archive until confirmed.
+
+## Stage 4: Mark Phase Built
+
+Before archive, invoke `specflow change phase <name> --set built` since snap produces a complete retroactive record equivalent to a built change. The CLI creates the snap change with `phase=plan`, but snap's entire flow (analyze → generate → infer → confirm) is post-hoc documentation of already-built work, so setting the phase explicitly satisfies the archive guard without needing `--force`.
+
+## Stage 5: Archive
+
+Once confirmed, run `specflow change archive <name>` to merge the inferred specs into main specs.

package/skills/specflow-test/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: specflow-test
+description: "Multi-level test execution with verification"
+---
+
+# SpecFlow: Test
+
+> **HARD GATE**: No "should work" claims -- verification evidence is required.
+
+## Prerequisites
+
+- An active change must exist with implementation work present.
+- Test framework must be configured in the project.
+
+## Stage 1: Detect Affected Modules
+
+Analyze the current change to identify which modules are affected.
+Determine the appropriate test scope (unit, integration, e2e).
+
+## Stage 2: Execute Tests
+
+Read the file at `.claude/specflow/prompts/test/tdd.md` and follow its instructions.
+
+Run the test suite for affected modules. Capture:
+- Pass/fail counts
+- Coverage metrics
+- Failure details with stack traces
+
+## Stage 3: Verify Results
+
+Read the file at `.claude/specflow/prompts/test/verification.md` and follow its instructions.
+
+Produce a verification report with concrete evidence:
+- Actual test output (not summaries)
+- Coverage numbers per module
+- Any flaky or skipped tests noted
+
+## On Failure: Debug Loop
+
+If tests fail:
+Read the file at `.claude/specflow/prompts/fix/debug.md` and follow its instructions.
+
+Diagnose the root cause. Fix and re-run. Repeat until green or escalate to user.
+
+## Stage 4: Report
+
+Present the verification report to the user.
+Every claim must be backed by evidence from test output.

package/skills/specflow-verify/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: specflow-verify
+description: "Dual validation -- delta specs + main specs regression"
+---
+
+# SpecFlow: Verify
+
+## Prerequisites
+
+- An active change must exist with delta specs and implementation.
+- `specflow` CLI must be available on PATH.
+- Main specs in `specflow/specs/` are optional: if present, regression is verified against them; if absent (greenfield project that has not archived any change yet), Pass 2 is explicitly skipped (see Stage 2 Pass 2 below). Never silently pass Pass 2 when the directory is missing — always report `skipped (no baseline)` so a main-specs deletion in a brownfield project cannot hide behind a green verify.
+
+## Stage 1: CLI Validation
+
+Run `specflow validate` to perform structural validation of specs.
+
+If validation fails, report errors and stop. The user must fix spec issues before proceeding.
+
+## Stage 2: Verification
+
+Read the file at `.claude/specflow/prompts/verify/verification.md` and follow its instructions.
+
+Perform three verification passes:
+
+### Pass 1: Delta Acceptance
+Verify that the implementation satisfies all delta specs in the active change.
+Check each spec scenario against actual behavior.
+
+### Pass 2: Regression
+Verify that existing main specs still pass.
+Flag any regressions introduced by the change.
+
+**Baseline-aware execution:**
+- Check whether `specflow/specs/` exists AND contains at least one `*.md` file under any capability subdirectory.
+- **If baseline present** — load every main spec, walk each `### Requirement:` and `#### Scenario:`, and verify the implementation still satisfies it. Report pass/fail per spec with concrete evidence (test output, code inspection).
+- **If baseline absent** — do NOT implicitly pass. Emit the exact line `Pass 2: skipped (no baseline — greenfield project or no archived changes yet)` and move on to Pass 3. The explicit marker prevents a deleted/moved `specflow/specs/` in a brownfield project from silently hiding real regressions.
+
+### Pass 3: Scope Creep
+Check that the implementation does not introduce behavior beyond what the delta specs describe.
+Flag any undocumented changes.
+
+### Pass 4: Security Scan (runs only after Pass 1–3 all PASS)
+
+Run Pass 4 only when Pass 1, Pass 2 (or its explicit `skipped (no baseline)` marker), and Pass 3 all produce PASS verdicts. If any earlier pass fails, emit `Pass 4: skipped (earlier passes failed)` and skip the security scan.
+
+When Pass 1–3 all PASS:
+
+1. Read `package.json` dependencies (if present) and check for Web framework indicators using prefix/substring matching on dependency keys: `express`, `fastify`, `next`, `koa`, `hapi`, `@nestjs/`, `remix-run`, `nuxt`, `sveltekit`, `astro`, `elysia`.
+2. If no Web framework indicator is found (or `package.json` does not exist), emit `Pass 4: skipped (non-web project detected)` and determine the overall verdict from Passes 1–3 alone.
+3. Compute changed files:
+   ```bash
+   git diff --name-only $(git merge-base HEAD $(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}' || echo main))
+   ```
+4. If the diff contains only non-code files (for example only `.md` files), emit `Pass 4: skipped (no code files in diff)` and determine the overall verdict from Passes 1–3 alone.
+5. Otherwise read `.claude/specflow/prompts/verify/ecc-security-reviewer.md` and run the security scan against changed code files only. Pre-existing issues outside the diff should be marked `(pre-existing, out of scope)` and must not affect the verdict.
+
+**Pass 4 verdict rules:**
+- Any CRITICAL finding → overall verify verdict is `FAIL`
+- Only HIGH findings (no CRITICAL) → overall verify verdict is `PASS with warnings`; list HIGH findings and require user acknowledgement before `/specflow:done`
+- No CRITICAL or HIGH findings → overall verify verdict remains `PASS`
+
+## Stage 3: Report
+
+Present a consolidated verification report:
+- Delta acceptance: pass/fail per spec
+- Regression: pass/fail summary, or `skipped (no baseline)` when applicable
+- Scope creep: any findings
+- Pass 4: Security Scan — pass/fail/skipped with findings
+- Overall verdict: `PASS`, `PASS with warnings`, or `FAIL` with reasons
+
+A `skipped` Pass 2 MUST appear verbatim in the report — do not fold it into the "pass" summary. The user needs to see that regression coverage was absent, not inferred as clean.
+
+**Overall verdict merge rules:**
+- `FAIL` if any of Pass 1–3 fails OR Pass 4 finds CRITICAL security issues
+- `PASS with warnings` if Pass 1–3 all pass and Pass 4 finds only HIGH-severity issues
+- `PASS` if Pass 1–3 all pass and Pass 4 finds no CRITICAL/HIGH issues or is skipped by rule

package/templates/design.md

@@ -0,0 +1,19 @@
+## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->

package/templates/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
+- `<name>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use existing spec names from specflow/specs/. Leave empty if no requirement changes. -->
+- `<existing-name>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->

package/templates/spec.md

@@ -0,0 +1,42 @@
+<!--
+  Delta spec template.
+  Only include the sections you need. A typical new-capability spec uses only ADDED.
+  A modification may use ADDED + MODIFIED. Removals need REMOVED with Reason+Migration.
+
+  CRITICAL format rules:
+  - Scenarios MUST use exactly 4 hashtags (####). Three hashtags will fail validation.
+  - Scenario steps MUST use bullet dash + bold: `- **WHEN** ...` and `- **THEN** ...`.
+  - Every requirement MUST have at least one scenario.
+-->
+
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text using SHALL/MUST -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->
+
+## MODIFIED Requirements
+
+<!-- Include the FULL updated requirement block (not just the diff).
+     The requirement name must match the existing spec exactly. -->
+
+### Requirement: <!-- existing requirement name -->
+<!-- full updated requirement text -->
+
+#### Scenario: <!-- updated or new scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- new expected outcome -->
+
+## REMOVED Requirements
+
+### Requirement: <!-- requirement name -->
+**Reason**: <!-- why being removed -->
+**Migration**: <!-- how users should adapt -->
+
+## RENAMED Requirements
+
+FROM: <!-- old requirement name -->
+TO: <!-- new requirement name -->

package/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->