Project Structure

After running specsafe init, your project will have the following SpecSafe-specific files and directories.

Directory layout

my-project/
├── specs/
│   ├── active/          # Specs currently being worked on
│   ├── completed/       # Finished specs
│   └── archive/         # Archived specs
├── PROJECT_STATE.md     # Single source of truth for all spec status
├── specsafe.config.json  # Project configuration
└── <tool-specific files>

specs/

All spec files live here, organized by lifecycle stage.

specs/active/

Contains spec files that are in progress -- anything from NEW through QA. Each spec is a Markdown file named by its ID:

specs/active/SPEC-001.md
specs/active/SPEC-002.md

specs/completed/

When a spec reaches the COMPLETE stage, its file moves here. This gives you a historical record of delivered features.

specs/archive/

For specs that were abandoned or superseded. Moving a spec here keeps it available for reference without cluttering the active or completed directories.

Spec file format

Each spec file is Markdown with YAML frontmatter:

---
id: SPEC-001
name: User Authentication
stage: SPEC
created: 2025-01-15
updated: 2025-01-16
---

## Description

Add email/password authentication to the application.

## Acceptance Criteria

- Users can register with email and password
- Users can log in with valid credentials
- Invalid credentials return a clear error message
...

The frontmatter fields:

PROJECT_STATE.md

This file is the single source of truth for all specs in the project. It tracks every spec's current stage, making it easy for both humans and AI tools to understand project status at a glance.

SpecSafe updates this file automatically as specs move through stages. You should not need to edit it manually.

specsafe.config.json

Project-level configuration. Controls behavior like default test framework, project name, and tool-specific settings.

Tool-specific files

Each AI tool gets its own skill files in the location that tool expects. For example:

Claude Code

.claude/skills/specsafe-new/SKILL.md
.claude/skills/specsafe-spec/SKILL.md
.claude/skills/specsafe-test/SKILL.md
.claude/skills/specsafe-code/SKILL.md
.claude/skills/specsafe-qa/SKILL.md
.claude/skills/specsafe-complete/SKILL.md
...

Cursor

.cursor/rules/specsafe-*.mdc

Other tools

Each supported tool follows its own conventions for loading custom instructions. SpecSafe handles the placement automatically when you run specsafe install <tool>.