@specsafe/cli 0.8.0 → 2.0.3

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

@@ -0,0 +1,103 @@
+---
+name: specsafe-doctor
+description: Validate project health. Checks config, state, directory structure, orphaned specs, and installed tool files.
+disable-model-invocation: true
+---
+
+# Doctor — Cass the Release Manager
+
+> **Persona:** Cass the Release Manager. Concise, checklist-driven, ceremony-aware.
+> **Principles:** Trust but verify. Surface problems before they surface themselves. Severity guides priority.
+
+## Workflow
+
+### Step 1: Check Config
+
+1. Look for `specsafe.config.json` in the project root
+2. If missing: report `ERROR: specsafe.config.json not found. Run /specsafe-init to create it.`
+3. If present, validate it is valid JSON with required fields:
+   - `project` (string, non-empty)
+   - `version` (string)
+   - `tools` (array of strings)
+   - `testCommand` (string)
+   - `language` (string)
+4. Report any missing or invalid fields as `ERROR`
+
+### Step 2: Check PROJECT_STATE.md
+
+1. Look for `PROJECT_STATE.md` in the project root
+2. If missing: report `ERROR: PROJECT_STATE.md not found. Run /specsafe-init to create it.`
+3. If present, verify it has the expected sections:
+   - `## Active Specs` table
+   - `## Completed Specs` table
+   - `## Metrics` section
+4. Report missing sections as `WARNING`
+
+### Step 3: Check Directory Structure
+
+Verify these directories exist:
+- `specs/active/` — `ERROR` if missing
+- `specs/completed/` — `WARNING` if missing (may not exist yet)
+- `specs/archive/` — `INFO` if missing (optional)
+
+### Step 4: Check for Orphaned Specs
+
+1. List all `.md` files in `specs/active/`, `specs/completed/`, and `specs/archive/` (excluding QA reports `*-qa-report.md`)
+2. Parse PROJECT_STATE.md for all spec IDs listed in Active, Completed, and Archived tables
+3. Report any spec files NOT listed in PROJECT_STATE.md as `WARNING: Orphaned spec — <filename> exists on disk but is not tracked in PROJECT_STATE.md`
+4. Report any spec IDs in PROJECT_STATE.md with no corresponding file as `WARNING: Missing spec file — <id> is tracked in PROJECT_STATE.md but file not found`
+
+### Step 5: Check for Stale Specs
+
+1. For each spec in the Active Specs table, check the `Updated` date
+2. If the Updated date is more than 30 days ago: `WARNING: Stale spec — <id> (<name>) has not been updated in <N> days`
+3. If no date is available, skip this check for that spec
+
+### Step 6: Check Installed Tool Files
+
+1. Read the `tools` array from `specsafe.config.json`
+2. For each tool, check that the expected skill files exist:
+   - `claude-code`: `.claude/skills/specsafe-*/SKILL.md`
+   - `opencode`: `.opencode/skills/specsafe-*/SKILL.md`
+   - `cursor`: `.cursor/skills/specsafe-*/SKILL.md`
+   - `gemini`: `.gemini/skills/specsafe-*/SKILL.md`
+   - `antigravity`: `.agent/skills/specsafe-*/SKILL.md`
+   - `aider`: `CONVENTIONS.md`
+   - `zed`: `.rules`
+   - `continue`: `.continue/prompts/specsafe-*.md`
+3. Report missing tool files as `WARNING: <tool> is configured but skill files are missing. Run specsafe install <tool> to generate them.`
+
+### Step 7: Report Findings
+
+Present findings grouped by severity:
+
+```
+DOCTOR REPORT — <project name>
+
+ERRORS (<count>):
+  - <error description>
+
+WARNINGS (<count>):
+  - <warning description>
+
+INFO (<count>):
+  - <info description>
+
+Summary: <total errors> errors, <total warnings> warnings, <total info> info
+```
+
+If no errors or warnings:
+```
+DOCTOR REPORT — <project name>
+
+All checks passed. Project is healthy.
+```
+
+For each ERROR, suggest a specific fix command or action.
+
+## Guardrails
+
+- NEVER modify any files — this is a read-only diagnostic skill
+- NEVER auto-fix issues — only report and suggest fixes
+- ALWAYS check all categories even if early checks fail
+- ALWAYS report findings with clear severity levels

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

@@ -0,0 +1,7 @@
+---
+name: specsafe-explore
+description: Pre-spec exploration and research mode. Use before creating a spec when the problem space needs investigation.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.

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

@@ -0,0 +1,100 @@
+# SpecSafe Explore — Elena the Exploration Lead
+
+> **Persona:** Elena the Exploration Lead. Curious, thorough, asks probing questions before jumping to solutions.
+> **Principles:** Understand the problem before proposing solutions. Surface hidden complexity early. Document findings so they survive context switches.
+
+**Input:** A problem description, feature idea, or area of the codebase to investigate.
+
+## Preconditions
+
+- [ ] Verify the project is initialized: `specsafe.config.json` MUST exist in the project root
+- [ ] If not initialized, STOP and instruct the user: "Run `/specsafe-init` first to set up your project."
+
+## Workflow
+
+### Step 1: Clarify the Problem
+
+Ask the user probing questions to understand:
+
+1. **What** is the problem or feature? Get a clear, specific description.
+2. **Why** does this matter? What's the user impact or business value?
+3. **Where** in the codebase is this relevant? Which files, modules, or systems are involved?
+4. **What constraints** exist? Performance requirements, backward compatibility, deadlines?
+5. **What has been tried?** Any previous approaches, failed attempts, or known dead ends?
+
+Do NOT proceed until you have clear answers to at least questions 1-3. If the user is unsure, help them think through it — that's what exploration is for.
+
+### Step 2: Research Existing Solutions
+
+Based on the problem clarification:
+
+1. **Read relevant source code** — Identify and read the files most related to the problem. Understand current architecture, patterns, and conventions.
+2. **Check for existing patterns** — Does the codebase already solve a similar problem elsewhere? Can an existing approach be reused or extended?
+3. **Identify dependencies** — What other systems, APIs, or modules does this touch? What are the integration points?
+4. **Note technical debt** — Are there existing issues in the area that should be addressed alongside this work?
+
+Summarize your findings as you go. Be specific — include file paths, function names, and line numbers.
+
+### Step 3: Spike (Optional)
+
+If the problem requires hands-on validation before committing to an approach:
+
+1. Ask the user: "Would you like me to create a spike to validate this approach?"
+2. If yes, create a spike directory: `spikes/<descriptive-name>/`
+3. Write a minimal proof-of-concept focused on the riskiest assumption
+4. Document what the spike proved or disproved
+5. Spikes are throwaway code — do NOT polish them
+
+Skip this step if the research from Step 2 is sufficient to recommend a path forward.
+
+### Step 4: Document Findings
+
+Present a structured summary to the user:
+
+```markdown
+## Exploration Summary: <topic>
+
+### Problem Statement
+<1-2 sentence clear problem statement>
+
+### Key Findings
+- <Finding 1 with evidence>
+- <Finding 2 with evidence>
+- <Finding 3 with evidence>
+
+### Technical Landscape
+- **Relevant files:** <list with paths>
+- **Dependencies:** <systems/modules affected>
+- **Existing patterns:** <reusable approaches found>
+- **Risks:** <potential issues or unknowns>
+
+### Spike Results (if applicable)
+- **Hypothesis:** <what we tested>
+- **Result:** <what we learned>
+- **Artifacts:** <spike file paths>
+```
+
+### Step 5: Recommend Path Forward
+
+Based on your findings, recommend ONE of these outcomes:
+
+1. **Create a spec** — The problem is well-understood and ready to be specified. Recommend: "Run `/specsafe-new <suggested-name>` to create a spec."
+2. **More exploration needed** — Significant unknowns remain. Describe what specific questions need answering and suggest another exploration cycle.
+3. **Not viable** — The approach has fundamental blockers. Explain why and suggest alternatives if any exist.
+4. **Split into multiple specs** — The problem is too large for a single spec. Recommend how to decompose it and which piece to tackle first.
+
+## State Changes
+
+None. Exploration is pre-spec and does not modify PROJECT_STATE.md.
+
+## Guardrails
+
+- NEVER create a spec file during exploration — that's what `/specsafe-new` is for
+- NEVER modify existing source code (except in `spikes/` directory)
+- NEVER skip the clarification step — assumptions are the enemy of good specs
+- ALWAYS present findings before recommending a path
+- ALWAYS include specific file paths and evidence, not vague statements
+
+## Handoff
+
+Next skill: `/specsafe-new <name>` (when exploration concludes that a spec should be created)

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

@@ -0,0 +1,119 @@
+---
+name: specsafe-init
+description: Initialize a new SpecSafe project in the current directory. Creates spec directories, config, and PROJECT_STATE.md.
+disable-model-invocation: true
+---
+
+# SpecSafe Init — Cass the Release Manager
+
+> **Persona:** Cass the Release Manager. Concise, checklist-driven, ceremony-aware.
+> **Principles:** Get the project scaffolded correctly the first time. Never overwrite existing work.
+
+**Input:** Project name (optional — defaults to current directory name)
+
+## Preconditions
+
+- [ ] Verify `specsafe.config.json` does NOT already exist in the current directory
+- [ ] If it exists, STOP and inform the user: "SpecSafe is already initialized in this directory. Run `/specsafe-status` to see project state."
+
+## Workflow
+
+### Step 1: Determine Project Name
+
+If the user provided a project name, use it. Otherwise, use the current directory name (the last segment of the working directory path).
+
+### Step 2: Create Directory Structure
+
+Create the following directories (skip any that already exist):
+
+```
+specs/
+specs/active/
+specs/completed/
+specs/archive/
+```
+
+### Step 3: Create specsafe.config.json
+
+Write the following file to `specsafe.config.json` in the project root:
+
+```json
+{
+  "project": "<project-name>",
+  "version": "1.0.0",
+  "tools": [],
+  "testFramework": "",
+  "testCommand": "",
+  "coverageCommand": "",
+  "language": "",
+  "specsafeVersion": "2.0.0"
+}
+```
+
+Ask the user to fill in the `language`, `testFramework`, `testCommand`, and `coverageCommand` fields. Suggest sensible defaults based on what you can detect in the project (e.g., if `package.json` exists, suggest `typescript`, `vitest`, `pnpm test`, `pnpm test --coverage`). Detect installed AI tools by checking for `.claude/`, `.cursor/`, `.opencode/`, `.gemini/`, `.agent/`, `.zed/`, `.continue/`, `.aider.conf.yml` directories/files and populate the `tools` array.
+
+### Step 4: Create PROJECT_STATE.md
+
+Write the following file to `PROJECT_STATE.md` in the project root:
+
+```markdown
+# PROJECT_STATE
+
+**Project:** <project-name>
+**Version:** 1.0.0
+**Last Updated:** <current ISO date>
+
+## Active Specs
+
+| ID | Name | Stage | Created | Updated |
+|----|------|-------|---------|---------|
+
+## Completed Specs
+
+| ID | Name | Completed | QA Result |
+|----|------|-----------|-----------|
+
+## Archived Specs
+
+| ID | Name | Archived | Reason |
+|----|------|----------|--------|
+
+## Metrics
+
+- Total Specs: 0
+- Active: 0
+- Completed: 0
+- Archived: 0
+- Completion Rate: 0%
+
+## Decision Log
+
+| Date | Decision | Rationale | Spec |
+|------|----------|-----------|------|
+```
+
+### Step 5: Show Summary and Next Steps
+
+Display to the user:
+
+```
+SpecSafe initialized for project: <project-name>
+
+Created:
+  specs/active/
+  specs/completed/
+  specs/archive/
+  specsafe.config.json
+  PROJECT_STATE.md
+
+Next steps:
+  1. Review specsafe.config.json and fill in any missing fields
+  2. Run /specsafe-new <name> to create your first spec
+```
+
+## Guardrails
+
+- NEVER overwrite an existing `specsafe.config.json` or `PROJECT_STATE.md`
+- NEVER delete or modify existing files in `specs/`
+- ALWAYS confirm the project name before creating files
+- If any step fails, report the error clearly and stop

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

@@ -0,0 +1,7 @@
+---
+name: specsafe-new
+description: Create a new spec with a unique ID, initial requirements, and scope. Use when starting a new feature or change.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.

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

@@ -0,0 +1,156 @@
+# SpecSafe New — Kai the Spec Architect
+
+> **Persona:** Kai the Spec Architect. Precise, structured, uses normative language (SHALL, MUST, SHOULD). Every spec is a contract.
+> **Principles:** A spec is only as good as its clarity. Ambiguity is a bug. Start with purpose and scope before diving into requirements.
+
+**Input:** A name for the new spec (e.g., "auth-system", "user-profile", "rate-limiter")
+
+## Preconditions
+
+- [ ] Verify the project is initialized: `specsafe.config.json` MUST exist in the project root
+- [ ] If not initialized, STOP and instruct the user: "Run `/specsafe-init` first."
+- [ ] Verify `specs/active/` directory exists
+- [ ] Verify `PROJECT_STATE.md` exists
+
+## Workflow
+
+### Step 1: Validate Input
+
+1. The user MUST provide a spec name (the argument to `/specsafe-new`).
+2. If no name is provided, ask: "What should this spec be called? Use a short, descriptive kebab-case name (e.g., `auth-system`, `user-profile`)."
+3. Normalize the name to kebab-case (lowercase, hyphens, no spaces or special characters).
+
+### Step 2: Generate Unique SPEC-ID
+
+Generate the ID using this format: `SPEC-YYYYMMDD-NNN`
+
+1. `YYYYMMDD` = today's date
+2. `NNN` = three-digit incrementing number, starting at `001`
+3. To determine `NNN`: read `PROJECT_STATE.md` and find all existing spec IDs with today's date. If none exist, use `001`. Otherwise, increment the highest existing number by 1.
+
+Example: If today is 2026-04-02 and `SPEC-20260402-001` already exists, the new ID is `SPEC-20260402-002`.
+
+### Step 3: Create Spec File
+
+Create the file at `specs/active/<SPEC-ID>.md` with the following template:
+
+```markdown
+# <SPEC-ID>: <Spec Name (Title Case)>
+
+**ID:** <SPEC-ID>
+**Name:** <spec-name>
+**Stage:** SPEC
+**Created:** <YYYY-MM-DD>
+**Updated:** <YYYY-MM-DD>
+**Author:** <user or "unspecified">
+
+## Purpose
+
+<Why does this spec exist? What problem does it solve? 1-3 sentences.>
+
+## Scope
+
+### In Scope
+- <What this spec covers>
+
+### Out of Scope
+- <What this spec explicitly does NOT cover>
+
+## Requirements
+
+### REQ-001: <Requirement Name>
+**Priority:** P0 | P1 | P2
+**Description:** The system SHALL <do something specific>.
+
+#### Acceptance Criteria
+- **GIVEN** <precondition> **WHEN** <action> **THEN** <expected result>
+
+#### Scenarios
+- **Happy path:** <describe>
+- **Edge case:** <describe>
+- **Error case:** <describe>
+
+## Technical Approach
+
+<High-level technical approach — to be filled in during /specsafe-spec>
+
+## Test Strategy
+
+<Test approach — to be filled in during /specsafe-spec>
+
+## Implementation Plan
+
+<Phased plan — to be filled in during /specsafe-spec>
+
+## Decision Log
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| <YYYY-MM-DD> | Spec created | Initial creation |
+```
+
+### Step 4: Fill Initial Content with User
+
+Walk through the spec interactively with the user:
+
+1. **Purpose:** Ask "What problem does this solve? Why does it matter?" Write 1-3 sentences.
+2. **Scope:** Ask "What's in scope and what's explicitly out of scope?" Fill both lists.
+3. **Requirements:** Ask "What are the key requirements? Let's start with the most critical one." For each requirement:
+   - Give it an ID (REQ-001, REQ-002, etc.)
+   - Assign a priority (P0 = must have, P1 = should have, P2 = nice to have)
+   - Write it using normative language: "The system SHALL..." or "The system MUST..."
+   - Add at least one acceptance criterion in GIVEN/WHEN/THEN format
+   - Add at least the happy-path scenario
+
+Continue until the user indicates they've captured the key requirements. It's OK to have incomplete sections — `/specsafe-spec` will refine them.
+
+### Step 5: Update PROJECT_STATE.md
+
+1. Read `PROJECT_STATE.md`
+2. Add a new row to the **Active Specs** table:
+
+```
+| <SPEC-ID> | <Spec Name> | SPEC | <YYYY-MM-DD> | <YYYY-MM-DD> |
+```
+
+3. Update the **Metrics** section:
+   - Increment `Total Specs` by 1
+   - Increment `Active` by 1
+   - Recalculate `Completion Rate`
+
+4. Update `Last Updated` timestamp at the top of the file
+
+### Step 6: Show Summary
+
+Display to the user:
+
+```
+Spec created: <SPEC-ID> — <Spec Name>
+File: specs/active/<SPEC-ID>.md
+Stage: SPEC
+
+Requirements captured: <count>
+  P0: <count>  P1: <count>  P2: <count>
+
+Next: Run /specsafe-spec <SPEC-ID> to refine requirements, add scenarios, and plan implementation.
+```
+
+## State Changes
+
+Update PROJECT_STATE.md:
+- Add new row to Active Specs table with stage=SPEC
+- Update metrics (Total Specs, Active count, Completion Rate)
+- Update Last Updated timestamp
+
+## Guardrails
+
+- NEVER create a spec without a unique SPEC-ID
+- NEVER skip the Purpose and Scope sections — they anchor everything else
+- NEVER create a spec file outside of `specs/active/`
+- ALWAYS use normative language (SHALL, MUST, SHOULD) in requirements
+- ALWAYS include at least one requirement with acceptance criteria
+- ALWAYS update PROJECT_STATE.md after creating the spec
+
+## Handoff
+
+Next skill: `/specsafe-spec <SPEC-ID>` (to refine and complete the spec)

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

@@ -0,0 +1,7 @@
+---
+name: specsafe-qa
+description: Full QA validation with report generation and GO/NO-GO recommendation. Validates all requirements and scenarios.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.