Three Phases

Overview

Simple Flow guides you through three sequential phases, each producing a markdown document: Each phase requires explicit approval before proceeding to the next.

Phase 1: Requirements

Define what to build with user stories and acceptance criteria.

Output

specs/{feature}/requirements.md

Introduction - 2-3 sentence feature summary
Glossary - Domain terms used consistently throughout
Requirements - User stories with EARS acceptance criteria

EARS Format

Requirements use EARS (Easy Approach to Requirements Syntax):

Pattern	Format	Example
Event-driven	WHEN [trigger], THE [system] SHALL [response]	WHEN user submits login, THE Auth_System SHALL validate credentials
State-driven	WHILE [condition], THE [system] SHALL [response]	WHILE session active, THE Auth_System SHALL refresh tokens
Unwanted	IF [condition], THEN THE [system] SHALL [response]	IF password invalid, THEN THE Auth_System SHALL display error
Optional	WHERE [option], THE [system] SHALL [response]	WHERE MFA enabled, THE Auth_System SHALL require second factor

Example

## Requirements

### Requirement 1

**User Story:** As a user, I want to log in with my email and password,
so that I can access my account.

#### Acceptance Criteria

1. WHEN user submits valid credentials, THE Auth_System SHALL create a session
2. IF password is invalid, THEN THE Auth_System SHALL display error message
3. WHILE session is active, THE Auth_System SHALL maintain authentication state

Approval Prompt

“Do the requirements look good? If so, we can move on to the design.”

Phase 2: Design

Define how to build it with technical architecture.

Output

specs/{feature}/design.md

Overview - Solution approach and key decisions
Architecture - Mermaid diagrams showing system structure
Components - Interfaces and responsibilities
Data Models - TypeScript interfaces with validation rules
Error Handling - Error types and recovery strategies
Testing Strategy - Test categories and coverage

Mermaid Diagrams

All visual diagrams use Mermaid syntax:

Example Data Model

interface User {
  id: string;           // UUID, required
  email: string;        // Valid email format
  passwordHash: string; // Bcrypt hash
  createdAt: Date;
  lastLogin?: Date;
}

Approval Prompt

“Does the design look good? If so, we can move on to the implementation plan.”

Phase 3: Tasks

Generate a step-by-step implementation plan.

Output

specs/{feature}/tasks.md

Numbered checkbox list - Incremental coding steps
Requirement references - Traceability to requirements
Checkpoint tasks - Verification points (run tests)

Task Format

## Tasks

- [ ] 1. Set up authentication module structure
  _Requirements: 1.1_

- [ ] 2. Implement user data model
  - [ ] 2.1 Create User interface
  - [ ] 2.2 Add validation rules
  - [ ] 2.3 Write unit tests
  _Requirements: 1.2, 1.3_

- [ ] 3. Checkpoint - Verify all tests pass

- [ ] 4. Implement login endpoint
  _Requirements: 1.1, 1.4_

Task Rules

Rule	Description
Coding tasks only	No deployment, documentation, or manual testing
Incremental	Each task builds on previous
Checkpoints	Run tests every 2-3 tasks
Traceability	Reference requirements with `_Requirements: X.Y_`
Max 2 levels	Top-level (1, 2, 3) and sub-tasks (2.1, 2.2)

Approval Prompt

“Do the tasks look good?”

Phase Transitions

Forward Flow

Requirements ──approved──> Design ──approved──> Tasks ──approved──> Execute

Backward Flow (Phase Regression)

If gaps are found, the agent suggests returning to a previous phase:

Current	Trigger	Action
Design	Requirement ambiguous	”Should we update requirements?”
Tasks	Design gap found	”Should we update design?”
Execute	Task blocked	”Should we add a task?”

Execution

After all three documents are approved, execute tasks one at a time:

/specsmd-agent What's the next task?

Or specify a task:

/specsmd-agent Execute task 2.1

The agent:

Reads all three spec files
Executes the task
Marks it complete [x]
Recommends the next task
Stops and waits for review

Summary

Phase	Question	Output	Approval
Requirements	What to build?	`requirements.md`	”looks good”
Design	How to build?	`design.md`	”approved”
Tasks	Step by step?	`tasks.md`	”yes”
Execute	Build it	Code + `[x]` checkmarks	Per task

Getting Started

Framework

Ideation Flow

FIRE Flow

AI-DLC Flow

Simple Flow

Compare

Resources

Overview

Phase 1: Requirements

Output

Contents

EARS Format

Example

Approval Prompt

Phase 2: Design

Output

Contents

Mermaid Diagrams

Example Data Model

Approval Prompt

Phase 3: Tasks

Output

Contents

Task Format

Task Rules

Approval Prompt

Phase Transitions

Forward Flow

Backward Flow (Phase Regression)

Execution

Summary

​Overview

​Phase 1: Requirements

​Output

​Contents

​EARS Format

​Example

​Approval Prompt

​Phase 2: Design

​Output

​Contents

​Mermaid Diagrams

​Example Data Model

​Approval Prompt

​Phase 3: Tasks

​Output

​Contents

​Task Format

​Task Rules

​Approval Prompt

​Phase Transitions

​Forward Flow

​Backward Flow (Phase Regression)

​Execution

​Summary

Overview

Phase 1: Requirements

Output

Contents

EARS Format

Example

Approval Prompt

Phase 2: Design

Output

Contents

Mermaid Diagrams

Example Data Model

Approval Prompt

Phase 3: Tasks

Output

Contents

Task Format

Task Rules

Approval Prompt

Phase Transitions

Forward Flow

Backward Flow (Phase Regression)

Execution

Summary