Quick Start

This guide walks you through the complete SpecSafe workflow -- from creating a spec to marking it complete. You will build a user authentication feature as an example.

1. Initialize your project

npm install -g @specsafe/cli
specsafe init

The interactive setup will ask for your project name, detect your AI tools, and install the appropriate skill files. See Installation for details.

2. Create a new spec

Open your AI tool in the project and run:

/specsafe-new "add user authentication"

SpecSafe creates a spec file in specs/active/ with a unique ID (e.g., SPEC-001) and populates it with an initial outline based on your description. The spec starts in the NEW stage.

3. Refine the spec

/specsafe-spec SPEC-001

This enters the SPEC stage. Your AI tool works with you to flesh out the spec -- defining acceptance criteria, edge cases, and technical approach. The spec becomes a clear contract for what "done" looks like.

4. Generate tests

/specsafe-test SPEC-001

SpecSafe moves to the TEST stage and generates test files based on the acceptance criteria in your spec. These tests define the target -- they should all fail initially because no implementation exists yet.

FAIL  src/auth/login.test.ts
  - should authenticate valid credentials
  - should reject invalid password
  - should handle missing email

This is the "red" in red-green-refactor.

5. Implement the code

/specsafe-code SPEC-001

Now in the CODE stage, the AI writes implementation code with a single goal: make the failing tests pass. It follows a strict TDD cycle:

1. Pick a failing test
2. Write the minimum code to make it pass
3. Refactor if needed
4. Repeat until all tests are green

PASS  src/auth/login.test.ts
  ✓ should authenticate valid credentials
  ✓ should reject invalid password
  ✓ should handle missing email

6. Validate with QA

/specsafe-qa SPEC-001

The QA stage runs a final validation pass. SpecSafe checks that:

• All tests pass
• The implementation matches the spec's acceptance criteria
• No obvious gaps or regressions exist

If QA finds issues, you go back to the CODE stage to fix them.

7. Complete the spec

/specsafe-complete SPEC-001

This moves the spec to the COMPLETE stage. The spec file is moved from specs/active/ to specs/completed/, and PROJECT_STATE.md is updated to reflect the finished work.

The full lifecycle at a glance

NEW → SPEC → TEST → CODE → QA → COMPLETE

Each transition is explicit. You always know where a feature stands, and the AI always knows what it should be doing at each stage.

What's next

• Project Structure -- Understand the files SpecSafe manages
• Workflow Overview -- Deep dive into each stage of the workflow
• Skills Reference -- All 22 skills and when to use them