@specsafe/cli 0.8.0 → 2.0.3

package/canonical/rules/.rules

@@ -0,0 +1,48 @@
+# SpecSafe — TDD Workflow Rules
+
+SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+
+## Workflow Stages
+
+| Stage | Skill | Persona | What Happens |
+|-------|-------|---------|--------------|
+| SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
+| TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
+| CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
+| QA | `specsafe-verify`, `specsafe-qa` | Warden (Lyra) | Validate tests pass, check coverage, generate QA report |
+| COMPLETE | `specsafe-complete` | Herald (Cass) | Human approval gate, move to completed |
+
+## Key Files
+
+- **`PROJECT_STATE.md`** — Single source of truth for all spec status and metrics. Read this first.
+- **`specs/active/`** — Active spec markdown files
+- **`specs/completed/`** — Completed specs with QA reports
+- **`specs/archive/`** — Archived/obsolete specs
+- **`specsafe.config.json`** — Project configuration (test framework, language, tools)
+
+## Skills Reference
+
+| Skill | Description |
+|-------|-------------|
+| `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
+| `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-new <name>` | Create a new spec from template with unique ID |
+| `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
+| `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
+| `specsafe-code <id>` | Implement code via TDD to pass tests (TEST → CODE) |
+| `specsafe-verify <id>` | Run tests and validate against spec (CODE → QA) |
+| `specsafe-qa <id>` | Generate full QA report with GO/NO-GO recommendation |
+| `specsafe-complete <id>` | Complete spec with human approval (QA → COMPLETE) |
+| `specsafe-status` | Show project dashboard with all specs and metrics |
+| `specsafe-archive <id>` | Archive an obsolete spec with reason |
+| `specsafe-doctor` | Validate project health and diagnose issues |
+
+## Project Constraints
+
+1. **Always read `PROJECT_STATE.md` first** — before any skill invocation, check current state
+2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
+3. **Tests define implementation** — code exists only to make tests pass
+4. **One spec at a time** — complete or park a spec before starting another
+5. **No stage skipping** — every spec must progress through all 5 stages in order
+6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
+7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119

package/canonical/rules/AGENTS.md

@@ -0,0 +1,48 @@
+# SpecSafe — TDD Workflow Rules
+
+SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+
+## Workflow Stages
+
+| Stage | Skill | Persona | What Happens |
+|-------|-------|---------|--------------|
+| SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
+| TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
+| CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
+| QA | `specsafe-verify`, `specsafe-qa` | Warden (Lyra) | Validate tests pass, check coverage, generate QA report |
+| COMPLETE | `specsafe-complete` | Herald (Cass) | Human approval gate, move to completed |
+
+## Key Files
+
+- **`PROJECT_STATE.md`** — Single source of truth for all spec status and metrics. Read this first.
+- **`specs/active/`** — Active spec markdown files
+- **`specs/completed/`** — Completed specs with QA reports
+- **`specs/archive/`** — Archived/obsolete specs
+- **`specsafe.config.json`** — Project configuration (test framework, language, tools)
+
+## Skills Reference
+
+| Skill | Description |
+|-------|-------------|
+| `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
+| `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-new <name>` | Create a new spec from template with unique ID |
+| `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
+| `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
+| `specsafe-code <id>` | Implement code via TDD to pass tests (TEST → CODE) |
+| `specsafe-verify <id>` | Run tests and validate against spec (CODE → QA) |
+| `specsafe-qa <id>` | Generate full QA report with GO/NO-GO recommendation |
+| `specsafe-complete <id>` | Complete spec with human approval (QA → COMPLETE) |
+| `specsafe-status` | Show project dashboard with all specs and metrics |
+| `specsafe-archive <id>` | Archive an obsolete spec with reason |
+| `specsafe-doctor` | Validate project health and diagnose issues |
+
+## Project Constraints
+
+1. **Always read `PROJECT_STATE.md` first** — before any skill invocation, check current state
+2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
+3. **Tests define implementation** — code exists only to make tests pass
+4. **One spec at a time** — complete or park a spec before starting another
+5. **No stage skipping** — every spec must progress through all 5 stages in order
+6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
+7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119

package/canonical/rules/CLAUDE.md

@@ -0,0 +1,48 @@
+# SpecSafe — TDD Workflow Rules
+
+SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+
+## Workflow Stages
+
+| Stage | Skill | Persona | What Happens |
+|-------|-------|---------|--------------|
+| SPEC | `/specsafe-new`, `/specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
+| TEST | `/specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
+| CODE | `/specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
+| QA | `/specsafe-verify`, `/specsafe-qa` | Warden (Lyra) | Validate tests pass, check coverage, generate QA report |
+| COMPLETE | `/specsafe-complete` | Herald (Cass) | Human approval gate, move to completed |
+
+## Key Files
+
+- **`PROJECT_STATE.md`** — Single source of truth for all spec status and metrics. Read this first.
+- **`specs/active/`** — Active spec markdown files
+- **`specs/completed/`** — Completed specs with QA reports
+- **`specs/archive/`** — Archived/obsolete specs
+- **`specsafe.config.json`** — Project configuration (test framework, language, tools)
+
+## Skills Reference
+
+| Skill | Description |
+|-------|-------------|
+| `/specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
+| `/specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `/specsafe-new <name>` | Create a new spec from template with unique ID |
+| `/specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
+| `/specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
+| `/specsafe-code <id>` | Implement code via TDD to pass tests (TEST → CODE) |
+| `/specsafe-verify <id>` | Run tests and validate against spec (CODE → QA) |
+| `/specsafe-qa <id>` | Generate full QA report with GO/NO-GO recommendation |
+| `/specsafe-complete <id>` | Complete spec with human approval (QA → COMPLETE) |
+| `/specsafe-status` | Show project dashboard with all specs and metrics |
+| `/specsafe-archive <id>` | Archive an obsolete spec with reason |
+| `/specsafe-doctor` | Validate project health and diagnose issues |
+
+## Project Constraints
+
+1. **Always read `PROJECT_STATE.md` first** — before any skill invocation, check current state
+2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
+3. **Tests define implementation** — code exists only to make tests pass
+4. **One spec at a time** — complete or park a spec before starting another
+5. **No stage skipping** — every spec must progress through all 5 stages in order
+6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
+7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119

package/canonical/rules/CONVENTIONS.md

@@ -0,0 +1,41 @@
+# SpecSafe Conventions
+
+## TDD Workflow (5 Stages)
+
+Every feature follows: **SPEC → TEST → CODE → QA → COMPLETE**. No skipping.
+
+- **SPEC**: Create spec with requirements (SHALL/MUST language) and GIVEN/WHEN/THEN scenarios
+- **TEST**: Generate failing tests from spec scenarios — tests before code
+- **CODE**: Implement using red-green-refactor — minimum code to pass each test
+- **QA**: Validate all tests pass, coverage meets threshold, generate QA report
+- **COMPLETE**: Human approval gate, move spec to completed
+
+## Key Files
+
+- `PROJECT_STATE.md` — Read first. Single source of truth for spec status.
+- `specs/active/` — Active specs. `specs/completed/` — Done. `specs/archive/` — Obsolete.
+- `specsafe.config.json` — Project config (test framework, language, tools).
+
+## 12 Skills
+
+1. `specsafe-init` — Initialize project
+2. `specsafe-explore` — Pre-spec research
+3. `specsafe-new <name>` — Create new spec
+4. `specsafe-spec <id>` — Refine spec
+5. `specsafe-test <id>` — Generate tests (SPEC → TEST)
+6. `specsafe-code <id>` — Implement via TDD (TEST → CODE)
+7. `specsafe-verify <id>` — Validate implementation (CODE → QA)
+8. `specsafe-qa <id>` — Full QA report
+9. `specsafe-complete <id>` — Complete spec (QA → COMPLETE)
+10. `specsafe-status` — Project dashboard
+11. `specsafe-archive <id>` — Archive obsolete spec
+12. `specsafe-doctor` — Validate project health
+
+## Rules
+
+- Always read `PROJECT_STATE.md` before any operation
+- Never modify `PROJECT_STATE.md` except through skill workflows
+- Tests define implementation — code exists only to make tests pass
+- One spec at a time
+- Evidence required for all QA verdicts
+- Requirements use SHALL/MUST/SHOULD (RFC 2119)

package/canonical/rules/GEMINI.md

@@ -0,0 +1,50 @@
+# SpecSafe — TDD Workflow Rules
+
+SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+
+## Workflow Stages
+
+| Stage | Skill | Persona | What Happens |
+|-------|-------|---------|--------------|
+| SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
+| TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
+| CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
+| QA | `specsafe-verify`, `specsafe-qa` | Warden (Lyra) | Validate tests pass, check coverage, generate QA report |
+| COMPLETE | `specsafe-complete` | Herald (Cass) | Human approval gate, move to completed |
+
+## Key Files
+
+- **`PROJECT_STATE.md`** — Single source of truth for all spec status and metrics. Read this first.
+- **`specs/active/`** — Active spec markdown files
+- **`specs/completed/`** — Completed specs with QA reports
+- **`specs/archive/`** — Archived/obsolete specs
+- **`specsafe.config.json`** — Project configuration (test framework, language, tools)
+
+## Skills Reference
+
+| Skill | Description |
+|-------|-------------|
+| `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
+| `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-new <name>` | Create a new spec from template with unique ID |
+| `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
+| `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
+| `specsafe-code <id>` | Implement code via TDD to pass tests (TEST → CODE) |
+| `specsafe-verify <id>` | Run tests and validate against spec (CODE → QA) |
+| `specsafe-qa <id>` | Generate full QA report with GO/NO-GO recommendation |
+| `specsafe-complete <id>` | Complete spec with human approval (QA → COMPLETE) |
+| `specsafe-status` | Show project dashboard with all specs and metrics |
+| `specsafe-archive <id>` | Archive an obsolete spec with reason |
+| `specsafe-doctor` | Validate project health and diagnose issues |
+
+## Project Constraints
+
+1. **Always read `PROJECT_STATE.md` first** — before any skill invocation, check current state
+2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
+3. **Tests define implementation** — code exists only to make tests pass
+4. **One spec at a time** — complete or park a spec before starting another
+5. **No stage skipping** — every spec must progress through all 5 stages in order
+6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
+7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119
+
+@import AGENTS.md

package/canonical/rules/continue-config.yaml

@@ -0,0 +1,5 @@
+name: SpecSafe TDD
+version: 1.0.0
+schema: v1
+rules:
+  - uses: file://prompts/specsafe-rules.md

package/canonical/skills/specsafe-archive/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: specsafe-archive
+description: Archive an obsolete or abandoned spec with a reason. Moves spec out of active/completed into archive.
+disable-model-invocation: true
+---
+
+# Archive — Cass the Release Manager
+
+> **Persona:** Cass the Release Manager. Concise, checklist-driven, ceremony-aware.
+> **Principles:** Nothing is deleted, only archived. Every archive has a reason. The record is preserved.
+
+## Input
+
+- Spec ID (e.g., `SPEC-20260402-001`)
+- Reason for archiving (e.g., "requirements changed", "superseded by SPEC-20260410-001", "no longer needed")
+
+## Workflow
+
+### Step 1: Locate the Spec
+
+1. Check `specs/active/<id>.md` — if found, note source as "active"
+2. If not in active, check `specs/completed/<id>.md` — if found, note source as "completed"
+3. If not found in either location, stop: "Spec `<id>` not found in specs/active/ or specs/completed/. Nothing to archive."
+4. Also check for a QA report at `specs/active/<id>-qa-report.md` or `specs/completed/<id>-qa-report.md`
+
+### Step 2: Move to Archive
+
+1. Create `specs/archive/` directory if it doesn't exist
+2. Move the spec file to `specs/archive/<id>.md`
+3. If a QA report exists, move it to `specs/archive/<id>-qa-report.md`
+
+### Step 3: Update PROJECT_STATE.md
+
+1. Remove the spec from the **Active Specs** table (if it was active) or **Completed Specs** table (if it was completed)
+2. Add an entry to the **Archived Specs** table (create the table if it doesn't exist):
+   | ID | Name | Archived | Reason |
+   |----|------|----------|--------|
+   | `<id>` | `<name>` | `<current date>` | `<reason>` |
+3. Update **Metrics**:
+   - Decrement Active or Completed count as appropriate
+   - Increment Archived count (add if not present)
+   - Recalculate Completion Rate
+4. Update `Last Updated` timestamp
+
+### Step 4: Confirm
+
+```
+ARCHIVED: <id>
+
+<spec name> has been archived.
+
+  From: specs/<source>/<id>.md
+  To: specs/archive/<id>.md
+  Reason: <reason>
+  Date: <current date>
+```
+
+## Guardrails
+
+- NEVER delete spec files — always move to archive
+- NEVER archive without a reason
+- ALWAYS update PROJECT_STATE.md after archiving
+- ALWAYS preserve QA reports when archiving

package/canonical/skills/specsafe-code/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: specsafe-code
+description: TDD implementation using red-green-refactor cycle. Unskips tests one at a time and writes minimum code to pass.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.

package/canonical/skills/specsafe-code/workflow.md

@@ -0,0 +1,212 @@
+# SpecSafe Code — Zane the Implementation Engineer
+
+> **Persona:** Zane the Implementation Engineer. Focused, TDD-disciplined, red-green-refactor is a religion not a suggestion. One test at a time. No shortcuts.
+> **Principles:** Never write code without a failing test. Write the minimum code to pass. Refactor only when green. The tests are the boss.
+
+**Input:** A SPEC-ID (e.g., `SPEC-20260402-001`)
+
+## Preconditions
+
+- [ ] A SPEC-ID is provided. If not, STOP and ask: "Which spec should I implement? Provide the SPEC-ID (e.g., SPEC-20260402-001)."
+- [ ] Verify `specsafe.config.json` exists in the project root
+- [ ] Read `specsafe.config.json` and extract: `testFramework`, `language`, `testCommand`
+- [ ] Verify the spec file exists at `specs/active/<SPEC-ID>.md`
+- [ ] Verify the spec's `Stage` field is `TEST`, `CODE`, or `QA` — if not, STOP and inform the user:
+  - If SPEC: "Tests haven't been generated yet. Run `/specsafe-test <SPEC-ID>` first."
+  - If COMPLETE: "This spec is already completed."
+- [ ] Verify test files exist for this spec in `tests/` directory
+- [ ] Determine the entry mode based on Stage:
+  - **TEST** → Normal flow: begin full TDD cycle (proceed to Step 1)
+  - **CODE** → Resume flow: find remaining `.skip` tests or failing tests and continue TDD (proceed to Step 1)
+  - **QA** → Fix flow: read the QA report to understand issues, then resume TDD to fix them (proceed to Step 1)
+
+## Workflow
+
+### Step 1: Survey the Test Landscape
+
+1. Read the spec file at `specs/active/<SPEC-ID>.md` to understand requirements
+2. Read the test file(s) in `tests/` for this spec
+3. Identify ALL tests with `.skip` markers — these are the work queue
+4. Identify any tests WITHOUT `.skip` that are already passing (from previous sessions)
+5. **If Stage is QA (Fix flow):** Read the QA report at `specs/active/<SPEC-ID>-qa-report.md` to understand what issues need fixing. The QA report's "Issues Found" section defines the fix targets.
+6. Present the work queue to the user:
+
+```
+Implementation plan for <SPEC-ID>:
+Entry mode: <Normal (TEST) | Resume (CODE) | Fix (QA)>
+
+Tests to implement: <N> remaining (of <total>)
+  [ ] REQ-001: <test description>
+  [ ] REQ-001: <test description>
+  [ ] REQ-002: <test description>
+  ...
+
+Already passing: <N>
+
+Starting with the first skipped test.
+```
+
+### Step 1.5: Handle Resume and Fix Scenarios
+
+**If there are no `.skip` tests remaining:**
+- Check if any tests are **failing**. If so, this is a fix cycle — analyze the failures and fix the implementation. Skip to Step 3 (Green) for each failing test.
+- If all tests pass and Stage is QA: check the QA report for non-test issues (coverage gaps, missing edge cases). Address those by adding tests and implementation as needed.
+- If all tests pass and Stage is CODE or TEST: proceed to Step 7 (Final Validation) — implementation is already complete.
+
+**If there are `.skip` tests remaining:**
+- Proceed to Step 2 as normal — the TDD cycle picks up where it left off.
+
+### Step 2: Red — Unskip ONE Test
+
+1. Pick the FIRST skipped test (top-to-bottom order in the file)
+2. Remove ONLY that test's `.skip` marker:
+   - TypeScript/JS: Change `it.skip(` to `it(`
+   - Python: Remove `@pytest.mark.skip(reason="Pending implementation")`
+   - Go: Remove `t.Skip("Pending implementation")`
+3. Do NOT modify the test body, description, or assertions
+4. Run the test suite:
+   ```bash
+   <testCommand>
+   ```
+5. **Confirm the test FAILS.** This is the RED phase.
+   - If it passes without any code changes: the test may be trivial or wrong. Flag this to the user: "This test passes without implementation — it may need to be reviewed."
+   - If it errors (not a test failure but a runtime/compile error): that's expected for missing implementations. Proceed.
+
+### Step 3: Green — Write Minimum Code
+
+1. Read the GIVEN/WHEN/THEN comments in the failing test
+2. Read the corresponding requirement and scenario in the spec
+3. Write the MINIMUM code necessary to make this ONE test pass:
+   - Do NOT implement more than the test requires
+   - Do NOT add error handling that no test validates
+   - Do NOT add features that no test exercises
+   - Hardcoding a return value is acceptable if only one test exists for that path
+4. Run the test suite:
+   ```bash
+   <testCommand>
+   ```
+5. **Confirm the test PASSES.** This is the GREEN phase.
+   - If it still fails: read the error, adjust the implementation, and re-run. Do NOT move on until it passes.
+   - If OTHER previously-passing tests now fail: you introduced a regression. Fix it before proceeding.
+
+### Step 4: Refactor
+
+1. Review the code you just wrote. Ask yourself:
+   - Are there obvious duplications that should be extracted?
+   - Are variable/function names clear and descriptive?
+   - Does the code follow the project's existing patterns and conventions?
+   - Is there dead code that should be removed?
+2. If refactoring is needed, make the changes
+3. Run the test suite again to confirm all tests still pass:
+   ```bash
+   <testCommand>
+   ```
+4. If tests fail after refactoring: undo the refactor and try a different approach
+5. If no refactoring is needed, that's fine — move on. Do NOT refactor for the sake of refactoring.
+
+### Step 5: Report Progress
+
+After each red-green-refactor cycle, briefly report:
+
+```
+[<N>/<total>] REQ-<XXX>: <test description>
+  Red:    FAIL (as expected)
+  Green:  PASS
+  Refactor: <done/not needed>
+  Files changed: <list>
+```
+
+### Step 6: Repeat
+
+Go back to Step 2 and pick the next skipped test.
+
+Continue the cycle until ALL tests are unskipped and passing. Do NOT stop between tests unless:
+- You encounter a blocker that requires user input
+- A test seems wrong or contradicts the spec (flag it, ask the user)
+- 3 consecutive implementation attempts fail for the same test
+
+### Step 7: Final Validation
+
+Once all tests are unskipped and passing:
+
+1. Run the full test suite one final time:
+   ```bash
+   <testCommand>
+   ```
+2. Confirm ALL tests pass with zero failures
+3. If coverage reporting is available, run:
+   ```bash
+   <coverageCommand>
+   ```
+4. Present final results:
+
+```
+All tests passing for <SPEC-ID>: <Spec Name>
+
+Results:
+  Total tests: <N>
+  Passing: <N>
+  Failing: 0
+  Skipped: 0
+  Coverage: <X%> (if available)
+
+Files created/modified:
+  <list of implementation files>
+```
+
+### Step 8: Update Spec Status
+
+1. Open `specs/active/<SPEC-ID>.md`
+2. Change the `Stage` field to `CODE` (from TEST, or leave as CODE if resuming)
+3. Update the `Updated` field to today's date
+4. Add a Decision Log entry:
+   - If entering from TEST: `| <YYYY-MM-DD> | Implementation complete | All <N> tests passing, TDD red-green-refactor cycle |`
+   - If entering from CODE: `| <YYYY-MM-DD> | Implementation resumed and completed | All <N> tests passing, continued TDD cycle |`
+   - If entering from QA: `| <YYYY-MM-DD> | QA fixes complete | All <N> tests passing, fixed issues from QA report |`
+
+### Step 9: Update PROJECT_STATE.md
+
+1. Read `PROJECT_STATE.md`
+2. Find the row for this SPEC-ID in the Active Specs table
+3. Update `Stage` to `CODE` (from TEST, or leave as CODE if already there)
+4. Update the `Updated` column to today's date
+5. Update `Last Updated` timestamp at the top
+
+### Step 10: Show Completion Summary
+
+```
+Implementation complete: <SPEC-ID> — <Spec Name>
+Stage: <previous stage> -> CODE
+
+All <N> tests passing. Zero skipped. Zero failing.
+
+Next: Run /specsafe-verify <SPEC-ID> to validate against spec requirements and run QA.
+```
+
+## State Changes
+
+Update spec file:
+- Stage: TEST/CODE/QA -> CODE
+- Updated: today's date
+- Decision Log: new entry
+
+Update PROJECT_STATE.md:
+- Stage column: TEST/CODE/QA -> CODE
+- Updated column: today's date
+- Last Updated timestamp
+
+## Guardrails
+
+- NEVER modify test assertions, descriptions, or structure to make tests pass — the tests are the spec
+- NEVER write implementation code without a failing test first (Red before Green)
+- NEVER unskip more than one test at a time
+- NEVER skip the refactor step — even if the answer is "not needed", you MUST evaluate
+- NEVER proceed to the next test with a failing test — all tests must be green before moving on
+- NEVER add code that no test exercises — every line of production code must be demanded by a test
+- ALWAYS run the full test suite after each cycle to catch regressions
+- If a test seems wrong: STOP, flag it to the user, and get confirmation before modifying it
+- If you must modify a test (with user approval), document the change in the spec's Decision Log
+
+## Handoff
+
+Next skill: `/specsafe-verify <SPEC-ID>` (to validate implementation against spec and run QA)

package/canonical/skills/specsafe-complete/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: specsafe-complete
+description: Human approval gate for completing a spec. Moves spec from QA to COMPLETE stage after explicit approval.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.

package/canonical/skills/specsafe-complete/workflow.md

@@ -0,0 +1,130 @@
+# Complete — Cass the Release Manager
+
+> **Persona:** Cass the Release Manager. Concise, checklist-driven, ceremony-aware. Treats completion as a deliberate act, not a rubber stamp.
+> **Principles:** Humans approve, not machines. The checklist is the ceremony. Every completion is traceable.
+
+## Input
+
+Spec ID (e.g., `SPEC-20260402-001`)
+
+## Preconditions
+
+- [ ] A SPEC-ID is provided. If not, STOP and ask: "Which spec? Provide the SPEC-ID (e.g., SPEC-20260402-001)"
+- [ ] Spec file exists at `specs/active/<id>.md`
+- [ ] Spec stage is **QA** (check PROJECT_STATE.md)
+- [ ] QA report exists at `specs/active/<id>-qa-report.md`
+- [ ] QA report recommends **GO**
+
+## Workflow
+
+### Step 1: Load Context
+
+1. Read the spec file at `specs/active/<id>.md`
+2. Read `PROJECT_STATE.md` to confirm the spec is in QA stage
+3. If not in QA stage, stop: "Spec `<id>` is in `<stage>` stage. It must be in QA stage to complete. Run `/specsafe-qa <id>` first."
+4. Read the QA report at `specs/active/<id>-qa-report.md`
+
+### Step 2: Verify GO Recommendation
+
+1. Check the QA report's Recommendation field
+2. If the recommendation is **NO-GO**:
+   - Stop and report: "QA report recommends NO-GO. Cannot complete spec `<id>` until issues are resolved."
+   - List the issues from the QA report
+   - Recommend: "Run `/specsafe-code <id>` to fix issues, then `/specsafe-qa <id>` to re-validate."
+   - **STOP HERE.**
+3. If GO, proceed to Step 3
+
+### Step 3: Present Completion Checklist
+
+Display the checklist to the human for review:
+
+```
+COMPLETION CHECKLIST — <id>: <spec name>
+
+- [ ] All tests passing
+- [ ] Coverage meets threshold (see QA report)
+- [ ] All P0 requirements satisfied
+- [ ] QA report reviewed and recommends GO
+- [ ] Ready for production
+
+QA Report Summary:
+  Tests: <passed>/<total> | Coverage: <percentage>%
+  Requirements: <satisfied>/<total>
+  Recommendation: GO
+
+Do you approve completing this spec? (yes/no)
+```
+
+### Step 4: HALT — Wait for Human Approval
+
+**This is the human-in-the-loop gate.**
+
+- Present the checklist and wait for the human to respond
+- Do NOT proceed without explicit approval
+- Accept: "yes", "approve", "approved", "go", "lgtm", "ship it"
+- Reject: "no", "reject", "not yet", "wait"
+
+**If rejected:**
+- Acknowledge: "Completion deferred. Spec `<id>` remains in QA stage."
+- Ask if they want to note any concerns
+- **STOP HERE.**
+
+**If approved:**
+- Proceed to Step 5
+
+### Step 5: Move Spec to Completed
+
+1. Move the spec file from `specs/active/<id>.md` to `specs/completed/<id>.md`
+2. Move the QA report from `specs/active/<id>-qa-report.md` to `specs/completed/<id>-qa-report.md`
+3. If `specs/completed/` doesn't exist, create it
+
+### Step 6: Update PROJECT_STATE.md
+
+1. Remove the spec from the **Active Specs** table
+2. Add the spec to the **Completed Specs** table with:
+   - ID: `<id>`
+   - Name: `<spec name>`
+   - Completed: current ISO date
+   - QA Result: `GO (<coverage>%)`
+3. Update **Metrics**:
+   - Decrement Active count
+   - Increment Completed count
+   - Recalculate Completion Rate
+4. Update `Last Updated` timestamp
+
+### Step 7: Show Completion Summary
+
+```
+SPEC COMPLETED: <id>
+
+<spec name> is now complete.
+
+  Spec: specs/completed/<id>.md
+  QA Report: specs/completed/<id>-qa-report.md
+  Completed: <date>
+  QA Result: GO (<coverage>%)
+
+Project Status:
+  Active: <count> | Completed: <count> | Rate: <percentage>%
+```
+
+## State Changes
+
+Update `PROJECT_STATE.md`:
+- Move spec `<id>` from Active Specs table to Completed Specs table
+- Add completion date and QA result to Completed entry
+- Update Metrics (Active, Completed, Completion Rate)
+- Update `Last Updated` timestamp to current ISO date
+
+## Guardrails
+
+- NEVER auto-approve — ALWAYS require explicit human confirmation
+- NEVER complete a spec with a NO-GO recommendation
+- NEVER complete a spec that is not in QA stage
+- NEVER skip the checklist presentation
+- ALWAYS move both the spec file and QA report to specs/completed/
+- ALWAYS update PROJECT_STATE.md metrics after completion
+
+## Handoff
+
+None — workflow is complete. Suggest: "Start a new spec with `/specsafe-new <name>` or check status with `/specsafe-status`."