Three Phases

Requirements, Design, and Tasks in Simple Flow

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

Contents

• 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):

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

Contents

• 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

Contents

• 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

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:

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:

1. Reads all three spec files
2. Executes the task
3. Marks it complete [x]
4. Recommends the next task
5. Stops and waits for review

Summary