SpecSafe

SpecSafe is a two-phase software engineering framework for AI-assisted development. It provides structured planning workflows to reduce ambiguity, then enforces test-driven implementation through small spec slices — regardless of which AI coding tool you use.

For the full canonical workflow, see docs/SPECSAFE-CANONICAL-WORKFLOW.md.

Two-Phase Workflow

PHASE 1: PLANNING
brainstorm → principles → brief → PRD → UX → architecture → readiness

PHASE 2: DEVELOPMENT
spec slice → tests → implementation → verify/QA → complete (or loop back)

Phase 1: Planning

Planning removes ambiguity before implementation begins. Each planning skill produces an artifact that informs the next stage.

| Step | Skill | Description | |------|-------|-------------| | 1 | specsafe-brainstorm | Divergent exploration of possibilities | | 2 | specsafe-principles | Product principles, non-goals, quality priorities | | 3 | specsafe-brief | Concise product/business framing document | | 4 | specsafe-prd | Testable requirements with user journeys and acceptance criteria | | 5 | specsafe-ux | UX design: tokens, components, flows, accessibility | | 6 | specsafe-architecture | System architecture with ADRs and technology decisions | | 7 | specsafe-readiness | Pre-development coherence check: GO / NEEDS REVISION / BLOCKED |

Phase 2: Development

Development begins only after the change is understood well enough to be implemented as a small spec slice.

| Stage | Skill | Persona | What happens | |-------|-------|---------|-------------| | SPEC | specsafe-new, specsafe-spec | Kai (Mason) | Create and refine a spec with requirements, acceptance criteria, scenarios | | TEST | specsafe-test | Reva (Forge) | Generate test files from spec scenarios — all tests start skipped | | CODE | specsafe-code | Zane (Bolt) | TDD red-green-refactor: unskip one test, write code to pass, repeat | | VERIFY | specsafe-verify | Lyra (Warden) | Run tests, validate against spec, loop back on failure | | QA | specsafe-qa, specsafe-complete | Lyra (Warden), Cass (Herald) | Full QA report with GO/NO-GO, then human approval gate |

Quick Start

# Install globally
npm install -g @specsafe/cli

# Initialize a project
specsafe init my-project

# Install skills for your AI tool
specsafe install claude-code    # Tier 1: full skills
specsafe install aider          # Tier 2: conventions
specsafe install continue       # Tier 3: prompts

# Check project health
specsafe doctor

Skills Reference

21 canonical skills:

Planning Skills

| Skill | Description | |-------|-------------| | specsafe-brainstorm | Divergent exploration before converging on a solution | | specsafe-principles | Product principles, non-goals, and quality priorities | | specsafe-brief | Create a concise product brief — problem, users, scope, success criteria | | specsafe-prd | Expand brief into full PRD with user journeys, FRs, NFRs | | specsafe-ux | UX design foundations — tokens, components, accessibility, flows | | specsafe-architecture | System architecture — components, data model, ADRs, technology stack | | specsafe-readiness | Pre-development coherence and readiness check |

Development Skills

| Skill | Description | |-------|-------------| | specsafe-new | Create a new spec with unique ID and initial requirements | | specsafe-spec | Refine spec with detailed requirements, criteria, scenarios | | specsafe-test | Generate test files from spec scenarios (all tests start skipped) | | specsafe-code | TDD implementation — unskip tests one at a time, write code to pass | | specsafe-verify | Run tests, validate against spec, loop on failure | | specsafe-qa | Full QA validation with report and GO/NO-GO recommendation | | specsafe-complete | Human approval gate — moves spec to COMPLETE |

Utility Skills

| Skill | Description | |-------|-------------| | specsafe-init | Initialize project — creates dirs, config, PROJECT_STATE.md | | specsafe-explore | Pre-spec exploration and research mode | | specsafe-context | Gather and present project context for AI agents | | specsafe-status | Project dashboard with spec counts by stage | | specsafe-archive | Archive obsolete or abandoned specs | | specsafe-doctor | Validate project health and configuration | | specsafe-skill-creator | Create new SpecSafe skills with proper structure and validation |

Agent Personas

| Persona | Role | Archetype | Stages | |---------|------|-----------|--------| | Elena | Exploration Lead | Scout | EXPLORE | | Kai | Spec Architect | Mason | SPEC, BRIEF, PRD | | Reva | Test Engineer | Forge | TEST | | Zane | Implementation Engineer | Bolt | CODE | | Lyra | QA Inspector | Warden | QA, VERIFY | | Cass | Release Manager | Herald | COMPLETE, STATUS, ARCHIVE, INIT, DOCTOR | | Aria | UX Designer | Prism | UX | | Nolan | System Architect | Sage | ARCHITECTURE |

Supported Tools

| Tool | Tier | Output | |------|------|--------| | claude-code | 1 — Full Skills | .claude/skills/*/SKILL.md + CLAUDE.md | | opencode | 1 — Full Skills | .opencode/skills/*/SKILL.md + .opencode/command/*.md | | cursor | 1 — Full Skills | .cursor/skills/*/SKILL.md + .cursorrules | | continue | 3 — Prompts | .continue/prompts/*.md + agent config | | aider | 2 — Conventions | .aider.conf.yml + CONVENTIONS.md | | zed | 2 — Conventions | .rules + .zed/settings.json | | gemini | 1 — Full Skills | .gemini/skills/*/SKILL.md + .gemini/commands/*.toml + GEMINI.md | | antigravity | 1 — Full Skills | .agent/skills/*/SKILL.md + .agent/rules/specsafe.md + AGENTS.md |

Configuration

specsafe.config.json

{
  "project": "my-project",
  "version": "1.0.0",
  "tools": ["claude-code"],
  "testFramework": "vitest",
  "testCommand": "pnpm test",
  "coverageCommand": "pnpm test --coverage",
  "language": "typescript",
  "specsafeVersion": "2.0.0"
}

PROJECT_STATE.md

Tracks the current state of all specs in the project:

# Project State — my-project

## Active Specs
| ID | Title | Stage | Owner |
|----|-------|-------|-------|

## Completed Specs
| ID | Title | Completed |
|----|-------|-----------|

## Metrics
- Total specs: 0
- Active: 0
- Completed: 0

Further Reading

• Canonical Workflow — source of truth for the two-phase model
• Tool Support Guide — per-tool setup details
• Persona Guide — how each persona works