FlowState Standard

The FlowState Standard is the comprehensive development framework for spec-driven software development. It defines the processes, standards, and requirements that ensure consistent quality, maintainability, and compliance across all development activities.

Table of Contents

1. Overview
2. Quick Reference
3. Core Documents
4. Process Documents
5. FlowState Integration
6. Document & Approval Workflow
7. Spec Workflow & UX Design
8. Technical Standards
9. Code Documentation
10. Compliance & Security
11. Getting Started
12. Document Status

Overview

What is the FlowState Standard?

The FlowState Standard is a holistic approach to software development that emphasizes:

• Quality First: High standards for code, testing, and documentation
• Process Driven: Consistent workflows from planning to deployment
• Compliance Ready: Built-in security and regulatory compliance
• Team Focused: Clear guidelines enabling team collaboration

Core Principles

Applicability

This standard applies to:

• All new feature development
• Bug fixes and enhancements
• Documentation updates
• Infrastructure changes
• Third-party integrations

Quick Reference

For New Team Members

For Daily Development

For Releases

Core Documents

Product & Architecture

When to Reference:

• Planning new features
• Understanding system interactions
• Making technology decisions
• Onboarding new team members

Quality Standards

When to Reference:

• Writing new code
• Reviewing pull requests
• Setting up tooling
• Defining coding standards

Process Documents

Development Process

When to Reference:

• Starting new features
• Creating specs and user stories
• Estimating work
• Planning sprints

User Documentation

When to Reference:

• Creating help articles
• Taking screenshots
• Writing user guides
• Updating documentation

FlowState Integration

FlowState is the single source of truth for all project, milestone, and task tracking. Local markdown documents serve as detailed specifications but must always be synchronized with FlowState.

Prerequisites (HARD REQUIREMENT)

Before starting ANY spec workflow, you MUST verify FlowState configuration exists.

Check for .flowstate/config.json:

# Check if FlowState is configured
cat .flowstate/config.json

Required Configuration:

{
  "projectId": "proj_xxxxx",
  "workspaceId": "work_xxxxx",
  "orgId": "org_xxxxx",
  "linkedAt": "2026-01-15T00:00:00.000Z",
  "packageName": "package-name"
}

If configuration is missing, STOP and initialize:

# Initialize FlowState for this project
flowstate init

# Or link to an existing project
flowstate project link proj_xxxxx

This is a hard requirement. The spec workflow CANNOT proceed without FlowState configuration.

Template-Based Workflow (MANDATORY)

All FlowState data MUST be created using the template file:

Template: .flowstate/templates/flowstate-milestone-template.json

+---------------------------------------------------------------------------+
|                    MANDATORY: Template-Based Creation Flow                 |
+---------------------------------------------------------------------------+
|                                                                            |
|   1. READ CONFIG                                                           |
|      - cat .flowstate/config.json                                          |
|        Extract: orgId, workspaceId, projectId                              |
|                                                                            |
|   2. LOAD TEMPLATE                                                         |
|      - .flowstate/templates/flowstate-milestone-template.json              |
|        Reference: milestone, specWorkflowTasks, mcpCreationExamples        |
|                                                                            |
|   3. CREATE MILESTONE (FlowState First)                                    |
|      - collection-create milestones {template.milestone.data}              |
|        Replace all {{placeholders}} with actual values                     |
|        Save returned milestoneId                                           |
|                                                                            |
|   4. CREATE PHASE TASKS (FlowState First)                                  |
|      - collection-create tasks {template.specWorkflowTasks.phase0...}      |
|        Create tasks for: phase0, phase1, phase2_design, phase2_wireframes, |
|        phase3_tasks, phase3_plan, phase4_implementation, phase4_verify     |
|                                                                            |
|   5. THEN CREATE SPEC DOCUMENTS                                            |
|      - Now create local markdown files                                     |
|        .flowstate/specs/{feature-name}/requirements.md                     |
|        .flowstate/specs/{feature-name}/design.md                           |
|        .flowstate/specs/{feature-name}/wireframes.html                     |
|        .flowstate/specs/{feature-name}/tasks.md                            |
|                                                                            |
|   6. UPDATE FLOWSTATE AS YOU WORK                                          |
|      - Mark tasks In Progress / Complete                                   |
|        Update milestone description with document links                    |
|        Create implementation tasks from tasks.md                           |
|                                                                            |
+---------------------------------------------------------------------------+

CRITICAL: FlowState entities MUST be created BEFORE local files.

Complete Workflow Steps

Step 1: Read Configuration

cat .flowstate/config.json

Extract these values for all subsequent operations:

• orgId: Organization ID
• workspaceId: Workspace ID
• projectId: Project ID

Step 2: Create Milestone in FlowState

Use MCP tool with template data:

// collection-create milestones
{
  "title": "Feature: {Feature Name}",
  "name": "Feature: {Feature Name}",
  "description": "## {Feature Name}\n\n{Description}\n\n**Status:** Planning\n\n## Spec Documents\n\n| Phase | Document | Status |\n|-------|----------|--------|\n| Requirements | Pending | Pending |\n| Design | Pending | Pending |\n| UX Wireframes | Pending | Pending |\n| Tasks | Pending | Pending |",
  "completed": false,
  "archived": false,
  "projectId": "{from config}",
  "orgId": "{from config}",
  "workspaceId": "{from config}",
  "userId": "{current user}",
  "timeBudgetHours": 0
}

Save the returned milestoneId - required for all tasks.

Step 3: Create Phase Tracking Tasks

Create a task for each spec workflow phase using template specWorkflowTasks:

// For each phase task from template:
// collection-create tasks
{
  "title": "Phase 0: Verify Prerequisites",
  "description": "{from template.specWorkflowTasks.phase0_prerequisites.description}",
  "status": "To Do",
  "milestoneId": "{from step 2}",
  "projectId": "{from config}",
  "orgId": "{from config}",
  "workspaceId": "{from config}",
  "userId": "{current user}",
  "timeBudgetHours": 0.5
}

Create these tasks in order:

1. phase0_prerequisites
2. phase1_requirements
3. phase2_design
4. phase2_wireframes
5. phase3_tasks
6. phase3_plan
7. phase4_implementation
8. phase4_verification

Step 4: Execute Spec Workflow

For each phase:

1. Mark phase task "In Progress" in FlowState
2. Create the spec document (requirements.md, design.md, wireframes.html, etc.)
3. Update milestone description with document link and status
4. Mark phase task "Complete" in FlowState
5. Proceed to next phase

Step 5: Create Implementation Tasks

After Phase 3 (tasks.md created), create a FlowState task for EACH implementation task:

// For each task in tasks.md:
// collection-create tasks
{
  "title": "Task {N}: {Task Name}",
  "description": "{from template.implementationTaskTemplate}",
  "status": "To Do",
  "milestoneId": "{milestone}",
  "projectId": "{from config}",
  "orgId": "{from config}",
  "workspaceId": "{from config}",
  "userId": "{current user}",
  "timeBudgetHours": {estimate}
}

Step 6: Execute Implementation

For each implementation task:

1. Query FlowState to get current task status
2. Mark task "In Progress": collection-update tasks {id} {"status": "In Progress", "startedAt": "{now}"}
3. Implement following TDD workflow
4. Mark task "Complete": collection-update tasks {id} {"status": "Complete", "completed": true, "completedAt": "{now}"}

Step 7: Complete Milestone

After all tasks complete:

// collection-update milestones {milestoneId}
{
  "completed": true,
  "completedAt": "{now}",
  "description": "{updated with completion summary}"
}

FlowState Entity Hierarchy

+---------------------------------------------------------------------------+
|                         FlowState Entity Structure                         |
+---------------------------------------------------------------------------+
|                                                                            |
|   ORGANIZATION (org_xxxxx)                                                 |
|       |                                                                    |
|       +-- WORKSPACE (work_xxxxx)                                           |
|               |                                                            |
|               +-- PROJECT (proj_xxxxx) <- Linked via .flowstate/config.json|
|                       |                                                    |
|                       +-- MILESTONE (mile_xxxxx)                           |
|                               |                                            |
|                               +-- TASK (task_xxxxx)                        |
|                                       |                                    |
|                                       +-- DISCUSSION (comment/status)      |
|                                                                            |
+---------------------------------------------------------------------------+

Source of Truth Principles

FlowState is the ONLY source of truth. All tracking MUST be stored in FlowState.

Enforcement Rules

MUST DO:

• Create milestone in FlowState BEFORE creating spec documents
• Create phase tasks in FlowState BEFORE executing phases
• Create implementation tasks in FlowState BEFORE writing code
• Update task status in FlowState when starting/completing work
• Update milestone description with document links after each phase
• Query FlowState to determine current state before resuming work

MUST NOT:

• Create local spec files without corresponding FlowState milestone
• Start implementation without FlowState tasks
• Track progress only in local TODO comments or markdown checkboxes
• Mark work complete without updating FlowState
• Proceed to next phase without updating FlowState

VERIFICATION:

// Before starting any work, verify FlowState state:
// 1. Query milestone
collection-get milestones {milestoneId}

// 2. Query tasks
collection-query tasks {"milestoneId": "{milestoneId}"}

// 3. Compare with local files
// 4. Reconcile any discrepancies (FlowState is authoritative)

Milestone Linking Workflow

Before creating spec documents, you must establish FlowState tracking:

+---------------------------------------------------------------------------+
|                         Milestone Linking Decision                         |
+---------------------------------------------------------------------------+
|                                                                            |
|   START: New Feature/Epic                                                  |
|       |                                                                    |
|       +-- Does a milestone already exist?                                  |
|               |                                                            |
|               +-- YES -> Link to existing milestone                        |
|               |          +-- Update milestone description with spec links  |
|               |                                                            |
|               +-- NO  -> Create new milestone                              |
|                          +-- Initialize with spec overview                 |
|                                                                            |
|       +-- Proceed to Spec Workflow (Phase 1)                               |
|                                                                            |
+---------------------------------------------------------------------------+

User Prompt Required:

Before beginning spec work, prompt the user:

Milestone Selection Required

Would you like to:

1. Link to an existing milestone
2. Create a new milestone

Please provide the milestone ID or name.

FlowState Checkpoints

FlowState must be updated at these mandatory checkpoints:

Milestone Description Format

Milestone descriptions should include links to all spec documents:

## {Feature Name}

{Brief description of the feature/epic}

**Estimated Hours:** {N}
**Priority:** {High/Medium/Low}
**Status:** {Ready for Implementation/In Progress/Complete}

---

## Spec Documents

| Phase | Document | Status |
|-------|----------|--------|
| Requirements | [requirements.md](.flowstate/specs/{feature-name}/requirements.md) | {Complete/Pending} |
| Design | [design.md](.flowstate/specs/{feature-name}/design.md) | {Complete/Pending} |
| UX Wireframes | [wireframes.html](.flowstate/specs/{feature-name}/wireframes.html) | {Complete/Pending} |
| Tasks | [tasks.md](.flowstate/specs/{feature-name}/tasks.md) | {Complete/Pending} |
| Implementation Plan | [YYYY-MM-DD-{feature-name}.md](docs/plans/YYYY-MM-DD-{feature-name}.md) | {Complete/Pending} |

---

## Summary

{Task summary with sections/phases}

---

## Success Criteria

- {Criterion 1}
- {Criterion 2}

Task Description Format

Each FlowState task should include:

## {Task Name}

**Estimate:** {hours}
**Dependencies:** {task IDs or "None"}

### Description
{What needs to be done}

### Files
- Create: `src/path/to/file.ts`
- Modify: `src/path/to/other.ts`

### Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] All unit tests pass

### TDD Steps
1. Write failing tests for {component}
2. Run tests to verify they fail
3. Implement {component}
4. Run tests to verify they pass
5. Commit

Discussion Tracking

Use FlowState discussions to track progress, decisions, and blockers:

When to Create Discussions:

Discussion Format:

**Type:** {Progress/Status/Blocker/Decision/Review}
**Timestamp:** {ISO 8601}

{Content of the update}

**Next Steps:**
- {Action item 1}
- {Action item 2}

Verification Before Acting (MANDATORY)

ALWAYS query FlowState before starting or resuming any work.

+---------------------------------------------------------------------------+
|                         MANDATORY: Verification Flow                       |
+---------------------------------------------------------------------------+
|                                                                            |
|   BEFORE ANY ACTION:                                                       |
|                                                                            |
|   1. QUERY FLOWSTATE                                                       |
|      - collection-get milestones {milestoneId}                             |
|      - collection-query tasks {"milestoneId": "{milestoneId}"}             |
|                                                                            |
|   2. DETERMINE CURRENT STATE                                               |
|      - Which tasks are Complete?                                           |
|      - Which task is In Progress?                                          |
|      - What is the next task to start?                                     |
|                                                                            |
|   3. COMPARE WITH LOCAL FILES (Optional)                                   |
|      - Do local files exist for completed phases?                          |
|      - Any discrepancy? FlowState is AUTHORITATIVE                         |
|                                                                            |
|   4. PROCEED WITH NEXT TASK                                                |
|      - Mark task In Progress in FlowState                                  |
|      - Do the work                                                         |
|      - Mark task Complete in FlowState                                     |
|                                                                            |
+---------------------------------------------------------------------------+

Verification Steps:

1. Query FlowState for milestone and task status
2. Determine which tasks are complete, in progress, and pending
3. Compare with local file state (FlowState is authoritative)
4. If discrepancy: Update FlowState to reflect reality OR redo work
5. Proceed only when FlowState reflects current reality

Query Commands:

// 1. Get milestone status
collection-get milestones {milestoneId}

// 2. Get all tasks for milestone
collection-query tasks {"milestoneId": "{milestoneId}"}

// 3. Get in-progress tasks (should be 0 or 1)
collection-query tasks {"milestoneId": "{milestoneId}", "status": "In Progress"}

// 4. Get pending tasks
collection-query tasks {"milestoneId": "{milestoneId}", "status": "To Do"}

If FlowState shows task Complete but local file missing:

• FlowState is authoritative - work was done
• Check git history for the file
• Recreate file if necessary

If local file exists but FlowState shows task To Do:

• FlowState is authoritative - task not officially complete
• Review the file, verify it meets acceptance criteria
• Update FlowState to Complete if file is valid

FlowState MCP Tools Reference

Common Queries:

// Get all tasks for a milestone
{"milestoneId": "mile_xxxxx"}

// Get in-progress tasks
{"status": "In Progress"}

// Get tasks by project
{"projectId": "proj_xxxxx"}

Milestone & Task Templates

Use the JSON template file for creating FlowState entities:

Template Location: .flowstate/templates/flowstate-milestone-template.json

The template includes:

Placeholder Substitution:

Replace these placeholders with values from .flowstate/config.json:

Quick Start:

# 1. Read config for IDs
cat .flowstate/config.json

# 2. Reference template
cat .flowstate/templates/flowstate-milestone-template.json

# 3. Create milestone using MCP
# collection-create milestones {data from template with placeholders replaced}

# 4. Create spec workflow tasks
# collection-create tasks {data for each phase task}

Skills Integration

The spec workflow integrates with the following skills:

Workflow with Skills:

1. /superpowers:brainstorming -> Clarify requirements
2. Create spec documents (requirements.md, design.md, wireframes.html, tasks.md)
3. /superpowers:writing-plans -> Expand tasks.md to implementation plan
4. Create FlowState milestone + tasks from plan
5. /superpowers:executing-plans (Subagent-Driven workflow)
6. Update FlowState task status as work progresses
7. /superpowers:requesting-code-review -> Final review
8. Mark milestone complete

Document & Approval Workflow

MANDATORY: All spec documents MUST be saved as Documents in FlowState with linked Approvals.

This section defines the mandatory workflow for persisting all planning artifacts (requirements, designs, tasks, implementation plans) in the FlowState system with proper approval tracking.

Core Requirements

Document & Approval Collections

FlowState uses two RxDB collections for document management:

Documents Collection

Document Types:

Approvals Collection

Approval Status Flow:

+---------------------------------------------------------------------------+
|                         Approval Status Workflow                           |
+---------------------------------------------------------------------------+
|                                                                            |
|   PENDING  -----> APPROVED (proceed to next phase)                         |
|      |                                                                     |
|      +------> NEEDS-REVISION (update document, create new approval)        |
|      |                                                                     |
|      +------> REJECTED (rethink approach, restart)                         |
|                                                                            |
+---------------------------------------------------------------------------+

FlowState First: Document Creation Order (CRITICAL)

MANDATORY: FlowState Documents MUST be created BEFORE filesystem files.

This is a strict ordering requirement. The FlowState Document is the source of truth, and the local markdown file is a synchronized copy.

+---------------------------------------------------------------------------+
|                    CRITICAL: FlowState First Workflow                      |
+---------------------------------------------------------------------------+
|                                                                            |
|   CORRECT ORDER:                                                           |
|   1. Create FlowState Document (with FULL content)                         |
|   2. Create FlowState Approval (linked to document)                        |
|   3. Write local file (content MUST MATCH FlowState Document exactly)      |
|                                                                            |
|   WRONG ORDER (PROHIBITED):                                                |
|   1. Write local file first                                                |
|   2. Then create FlowState Document with summary                           |
|   (This violates source of truth principle)                                |
|                                                                            |
+---------------------------------------------------------------------------+

Why FlowState First?

Content Requirements:

• FlowState Document content field MUST contain the FULL specification content
• The EXACT same content is written to the local markdown file
• NO summaries or abbreviated versions in FlowState Documents
• If the content is too long, it still goes in FlowState in full

Verification:

// After creating document and writing file, verify they match:
// 1. Read FlowState Document
collection-get documents {documentId}

// 2. Compare content field with local file
// They MUST be identical (character-for-character match)

Mandatory Document + Approval Workflow

EVERY spec document follows this workflow:

+---------------------------------------------------------------------------+
|            MANDATORY: Spec Document + Approval Workflow                    |
+---------------------------------------------------------------------------+
|                                                                            |
|   1. CREATE DOCUMENT IN FLOWSTATE FIRST (MANDATORY)                        |
|      - collection-create documents {with FULL content}                     |
|      - Link to projectId, milestoneId, taskId as appropriate               |
|      - Save returned documentId                                            |
|      - Content field contains COMPLETE specification                       |
|                                                                            |
|   2. CREATE APPROVAL IN FLOWSTATE (MANDATORY)                              |
|      - collection-create approvals {from approval-template.json}           |
|      - Link to documentId from step 1                                      |
|      - Set status: 'pending'                                               |
|                                                                            |
|   3. WRITE LOCAL FILE (matches FlowState Document content)                 |
|      - Write requirements.md / design.md / tasks.md locally                |
|      - Content MUST be identical to FlowState Document content field       |
|                                                                            |
|   4. WAIT FOR APPROVAL DECISION                                            |
|      - Query: collection-query approvals {"documentId": "..."}             |
|      - Check status: pending | approved | rejected | needs-revision        |
|                                                                            |
|   5. HANDLE DECISION                                                       |
|      - approved: Proceed to next phase                                     |
|      - needs-revision: Update FlowState doc first, then local file         |
|      - rejected: Rethink approach, restart from scratch                    |
|                                                                            |
+---------------------------------------------------------------------------+

Spec Phase Documents

Each spec workflow phase creates specific documents:

MCP Tool Examples

Create Document

// collection-create documents
{
  "orgId": "{{orgId}}",
  "workspaceId": "{{workspaceId}}",
  "projectId": "{{projectId}}",
  "milestoneId": "{{milestoneId}}",
  "documentType": "product",
  "title": "{{featureTitle}} - Requirements",
  "content": "{{requirementsContent}}",
  "documentVersion": 1,
  "approved": false,
  "userId": "{{userId}}",
  "metadata": {
    "templateVersion": "1.0.0",
    "scope": "milestone",
    "specPhase": "phase1",
    "localFilePath": ".flowstate/specs/{{featureName}}/requirements.md"
  }
}
// Save returned documentId for approval creation

Create Approval (immediately after Document)

// collection-create approvals
{
  "projectId": "{{projectId}}",
  "milestoneId": "{{milestoneId}}",
  "documentId": "{{documentId}}",  // From document creation
  "title": "Approve: {{featureTitle}} - Requirements",
  "type": "document",
  "category": "spec",
  "categoryName": "requirements",
  "status": "pending",
  "documentType": "product",
  "documentContent": "{{requirementsContent}}",
  "orgId": "{{orgId}}",
  "workspaceId": "{{workspaceId}}",
  "userId": "{{userId}}"
}

Approve Document

// collection-update approvals {approvalId}
{
  "status": "approved",
  "response": "Requirements are complete and approved.",
  "approverId": "{{approverId}}",
  "respondedAt": "{{isoTimestamp}}"
}

// Also update the document
// collection-update documents {documentId}
{
  "approved": true,
  "approvedAt": "{{isoTimestamp}}",
  "approvedBy": "{{approverId}}"
}

Request Revision

// collection-update approvals {approvalId}
{
  "status": "needs-revision",
  "response": "Please address the following issues...",
  "comments": [
    {
      "text": "This requirement needs more detail",
      "selection": "The system shall validate input",
      "position": { "line": 45, "column": 1 }
    }
  ],
  "approverId": "{{approverId}}",
  "respondedAt": "{{isoTimestamp}}"
}

Query Pending Approvals

// collection-query approvals
{
  "milestoneId": "{{milestoneId}}",
  "status": "pending"
}

Revision Workflow

When an approval has status needs-revision:

1. Query approval to get feedback: collection-get approvals {approvalId}
2. Review the response and comments fields
3. Update local file with revisions
4. Create new Document version:

   // collection-create documents
   {
     // Same as original, but:
     "documentVersion": 2,  // Increment version
     "content": "{{revisedContent}}",
     "approved": false
   }
   

5. Create new Approval linked to new Document version
6. Wait for new approval decision

Document Templates

Three template files are provided in .flowstate/templates/:

Quick Reference:

# View document template
cat .flowstate/templates/document-template.json

# View approval template
cat .flowstate/templates/approval-template.json

# View combined workflow template
cat .flowstate/templates/spec-document-workflow-template.json

Enforcement Rules

MUST DO:

• Create Document in FlowState for EVERY spec file (requirements.md, design.md, wireframes.html, tasks.md, implementation-plan.md)
• Create Approval IMMEDIATELY after creating Document (do not skip)
• Link Document to appropriate projectId, milestoneId, taskId
• Wait for approval before proceeding to next phase
• Handle needs-revision by creating new Document version and new Approval
• Update Document approved field when Approval status changes to approved

MUST NOT:

• Create local spec files without corresponding FlowState Document
• Create Document without corresponding Approval
• Proceed to next phase while Approval status is pending or needs-revision
• Skip the approval workflow for any spec document
• Modify approved Documents without creating new version and new Approval

Verification Before Proceeding

Before proceeding to any new phase:

// 1. Query documents for milestone
collection-query documents {"milestoneId": "{{milestoneId}}"}

// 2. Query approvals for milestone
collection-query approvals {"milestoneId": "{{milestoneId}}"}

// 3. Verify all required documents exist
// 4. Verify all approvals have status "approved"
// 5. If any approval is "pending" or "needs-revision", STOP and handle

// Example: Check approval status for a specific document
collection-query approvals {
  "documentId": "{{documentId}}",
  "status": "approved"
}
// If empty result, document is NOT approved - cannot proceed

Spec Workflow & UX Design

Prerequisites

STOP: Before proceeding, verify FlowState Integration requirements are met:

• [ ] .flowstate/config.json exists with valid projectId
• [ ] Milestone created/linked for this feature
• [ ] User has confirmed milestone selection

See FlowState Integration for details.

Overview

The Spec Workflow is a structured approach to feature development that ensures alignment between requirements, design, and implementation. Every feature follows a sequential phase progression with approval gates.

+---------------------------------------------------------------------------+
|                         Spec Workflow Phases                               |
+---------------------------------------------------------------------------+
|                                                                            |
|   PHASE 1          PHASE 2          PHASE 3          PHASE 4              |
|  +---------+      +---------+      +---------+      +---------+           |
|  |REQUIRE- |  ->  | DESIGN  |  ->  |  TASKS  |  ->  |IMPLEMENT|           |
|  | MENTS   |      |  + UX   |      |         |      |         |           |
|  +----+----+      +----+----+      +----+----+      +----+----+           |
|       |                |                |                |                 |
|       v                v                v                v                 |
|   +-------+        +-------+        +-------+        +-------+            |
|   |APPROVE|        |APPROVE|        |APPROVE|        | VERIFY |            |
|   +-------+        +-------+        +-------+        +-------+            |
|                                                                            |
+---------------------------------------------------------------------------+

Phase 1: Requirements Document (WHAT)

Purpose: Define what the feature needs to accomplish from a user perspective.

Document Location: .flowstate/specs/{feature-name}/requirements.md

Required Sections:

# {Feature Name} - Requirements

## Overview
Brief description of the feature and its business value.

## User Stories
### US-{N}.{M}: {Story Title}
**As a** {user type}
**I want to** {action}
**So that** {benefit}

**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2

## Functional Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | ... | Must Have |

## Non-Functional Requirements
| ID | Requirement | Target |
|----|-------------|--------|
| NFR-1 | Performance | < 200ms response |

## Constraints & Assumptions
- Constraint 1
- Assumption 1

## Out of Scope
- Item 1

Approval Criteria:

• All user types identified
• User stories cover all scenarios
• Acceptance criteria are testable
• Requirements are complete and unambiguous
• Stakeholder sign-off received

Phase 2: Design Document + UX Wireframes (HOW)

Purpose: Define the technical architecture and user experience design.

Document Locations:

• Technical: .flowstate/specs/{feature-name}/design.md
• UX Wireframes: .flowstate/specs/{feature-name}/wireframes.html

Technical Design Document

Required Sections:

# {Feature Name} - Technical Design

## Architecture Overview
High-level system design and component interactions.

## Component Design
### {Component Name}
- Purpose
- Props/API
- State management
- Dependencies

## Data Models
### {Model Name}
| Field | Type | Description |
|-------|------|-------------|
| id | string | Unique identifier |

## API Specifications
### {Endpoint}
- Method: GET/POST/PUT/DELETE
- Path: /api/v1/...
- Request/Response schemas

## Integration Points
- Backend services
- Third-party APIs
- Existing components

## Security Considerations
- Authentication requirements
- Authorization rules
- Data handling

## Performance Considerations
- Caching strategy
- Optimization approach

UX Wireframes Document

Purpose: Visualize the user interface before implementation.

Format: HTML wireframes with annotations

Template: .flowstate/templates/wireframe-template.html

Required Elements:

<!-- Wireframe Document Structure -->
<!DOCTYPE html>
<html>
<head>
  <title>{Feature Name} - UX Wireframes</title>
</head>
<body>
  <!-- Document Metadata -->
  <div class="meta">
    <p><strong>Document Version:</strong> 1.0</p>
    <p><strong>Date:</strong> {Date}</p>
    <p><strong>Purpose:</strong> Visual wireframes for {feature}</p>
    <p><strong>Related Document:</strong> {requirements-doc}</p>
  </div>

  <!-- Epic/Feature Section -->
  <h2>Epic {N}: {Epic Name}</h2>

  <!-- User Story Reference -->
  <div class="wireframe-desc">
    <strong>US-{N}.{M}:</strong> {User story summary and context}
  </div>

  <!-- Wireframe Container -->
  <div class="wireframe-container">
    <div class="wireframe-title">{Screen/Component Name}</div>
    <!-- Browser mockup with URL -->
    <!-- Interactive elements -->
    <!-- State variations -->
  </div>

  <!-- Key UI Elements Annotation -->
  <h3>Key UI Elements</h3>
  <ul>
    <li><strong>{Element}:</strong> {Purpose and behavior}</li>
  </ul>

  <!-- Summary Table -->
  <h2>Summary of Wireframes</h2>
  <table>
    <tr><th>Epic</th><th>Wireframes</th><th>Key Elements</th></tr>
  </table>
</body>
</html>

Wireframe Standards:

Annotation Requirements:

Each wireframe must include:

1. Screen title - Clear identification
2. User story reference - Links to requirements
3. Key UI elements list - Annotated descriptions
4. Interaction notes - Click behaviors, hover states
5. Data displayed - What information appears where
6. Error states - How errors are communicated

Approval Criteria:

• All user stories have corresponding wireframes
• Technical design aligns with architecture standards
• Data models are complete
• API contracts are defined
• UX wireframes cover all screens/states
• Wireframes annotated with key UI elements
• Design review completed

Phase 3: Tasks Document (STEPS)

Purpose: Break down implementation into discrete, estimable tasks.

Document Location: .flowstate/specs/{feature-name}/tasks.md

Required Structure:

# {Feature Name} - Implementation Tasks

## Overview
Total Estimated Hours: {N}
Priority: {High/Medium/Low}
Target Milestone: {Milestone Name}

## Task Breakdown

### 1.0 {Major Section} ({N} hours)

#### 1.1 {Task Name}
- **Estimate:** {hours}
- **Dependencies:** {task IDs or "None"}
- **Description:** {What needs to be done}
- **Acceptance:** {How to verify completion}
- **Files:** {Expected files to create/modify}

#### 1.2 {Task Name}
...

### 2.0 {Major Section} ({N} hours)
...

## Implementation Order
1. Tasks 1.1-1.3 (can be parallelized)
2. Task 2.1 (depends on 1.x)
3. Tasks 2.2-2.4 (can be parallelized)
...

## Testing Requirements
- Unit tests for: {components}
- Integration tests for: {flows}
- E2E tests for: {user journeys}

## Documentation Requirements
- [ ] TSDoc comments
- [ ] Component Storybook stories
- [ ] User documentation updates

Task Granularity Guidelines:

Approval Criteria:

• Tasks are appropriately sized (<= 8 hours each)
• Dependencies are identified
• Estimates are realistic
• Testing requirements defined
• Implementation order is logical

Phase 4: Implementation & Verification

Purpose: Execute tasks following TDD methodology with continuous verification.

Execution Strategies:

Implementation Checklist:

For each task:

• [ ] Write failing tests first (TDD)
• [ ] Implement to pass tests
• [ ] Refactor for quality
• [ ] Update TSDoc comments
• [ ] Verify against acceptance criteria
• [ ] Mark task complete in FlowState

Verification Requirements:

Approval Gates

Each phase requires explicit approval before proceeding:

+----------------+     +----------------+     +----------------+
|   GENERATED    | ->  |    REVIEW      | ->  |    DECISION    |
|   (AI/Human)   |     |  (Stakeholder) |     |                |
+----------------+     +----------------+     +-------+--------+
                                                      |
                              +-----------------------+-----------------------+
                              v                       v                       v
                       +----------+            +----------+            +----------+
                       | APPROVE  |            |  REVISE  |            |  REJECT  |
                       |          |            |          |            |          |
                       | -> Lock  |            | -> Update|            | -> Rethink|
                       | -> Next  |            | -> Review|            | -> Restart|
                       +----------+            +----------+            +----------+

Decision Criteria:

Effective Feedback:

• Specific: "Use JWT tokens instead of sessions"
• Actionable: "Add rate limiting to API endpoints"
• Not vague: "Fix it" or "Make it better"

File Structure

All spec documents are stored in a standard structure:

.flowstate/
+-- config.json                    # FlowState configuration
+-- templates/
|   +-- flowstate-milestone-template.json  # Milestone & task templates
|   +-- wireframe-template.html            # UX wireframe template
+-- docs/
|   +-- FLOWSTATE.md              # This document (process overview)
+-- steering/                      # Project steering documents
|   +-- PRODUCT.md                # Product vision and requirements
|   +-- TECHNICAL.md              # Architecture decisions
|   +-- STRUCTURE.md              # Code organization
|   +-- QUALITY.md                # Code quality standards
|   +-- SECURITY.md               # Security standards
|   +-- TDD.md                    # Test-driven development
|   +-- TSDOC.md                  # Code documentation (TSDoc)
|   +-- DOCUMENTATION.md          # User documentation standards
|   +-- COMPLIANCE.md             # Compliance requirements
+-- specs/
    +-- {feature-name}/
        +-- requirements.md        # Phase 1
        +-- design.md             # Phase 2 - Technical
        +-- wireframes.html       # Phase 2 - UX
        +-- tasks.md              # Phase 3
        +-- assets/               # Images, mockups
            +-- wireframe-001.png
            +-- flow-diagram.svg

Naming Conventions:

• Feature folders: kebab-case (e.g., user-authentication)
• Documents: Standard names (requirements.md, design.md, tasks.md, wireframes.html)
• Assets: Numbered with description (e.g., 001-card-view.png)

UX Wireframe Generation

When to Create Wireframes:

• New user-facing features
• Significant UI changes
• Complex interaction flows
• Multi-screen workflows

Wireframe Tooling:

HTML Wireframe Template:

See .flowstate/templates/wireframe-template.html for a complete example including:

• Responsive CSS components
• Interactive elements
• State variations
• Annotation patterns
• Summary tables

Wireframe Review Checklist:

• [ ] All user stories have visual representation
• [ ] Navigation flow is clear
• [ ] Error states are shown
• [ ] Loading states are shown
• [ ] Empty states are shown
• [ ] Key UI elements are annotated
• [ ] Interactions are described
• [ ] Color coding is consistent with legends
• [ ] Responsive considerations addressed
• [ ] Accessibility notes included

Quick Reference Commands

# Create new spec structure
mkdir -p .flowstate/specs/{feature-name}/assets
touch .flowstate/specs/{feature-name}/{requirements,design,tasks}.md
cp .flowstate/templates/wireframe-template.html .flowstate/specs/{feature-name}/wireframes.html

# Generate wireframe template
cp .flowstate/templates/wireframe-template.html .flowstate/specs/{feature-name}/wireframes.html

FlowState Sync Points

At the end of each phase, sync with FlowState:

See FlowState Integration for complete integration requirements.

Quick Commands:

# Verify FlowState config exists
cat .flowstate/config.json

# Query milestone status
flowstate milestone get mile_xxxxx

# Query tasks for milestone
flowstate tasks list --milestone mile_xxxxx

Technical Standards

Test-Driven Development

When to Reference:

• Writing unit tests
• Learning TDD workflow
• Testing React components
• Testing hooks and services

Coverage Requirements:

• Statements: >= 80%
• Branches: >= 75%
• Functions: >= 80%
• Lines: >= 80%

Security Standards

When to Reference:

• Handling user data
• Implementing authentication
• Writing secure code
• Conducting security reviews

Code Documentation

TSDoc/JSDoc Standards

When to Reference:

• Writing new functions, classes, or modules
• Documenting component props and APIs
• Generating API documentation
• Code review for documentation completeness

Documentation Coverage Requirements

TSDoc Syntax Standards

All code documentation must follow TSDoc syntax for TypeScript compatibility:

/**
 * Brief description of the function.
 *
 * @remarks
 * Additional details about implementation or usage notes.
 *
 * @example
 * ```typescript
 * const result = calculateTotal(items, { includeTax: true });
 * console.log(result); // { subtotal: 100, tax: 8, total: 108 }
 * ```
 *
 * @param items - Array of line items to calculate
 * @param options - Calculation options
 * @param options.includeTax - Whether to include tax in total
 * @returns Calculated totals object
 * @throws {@link ValidationError} When items array is empty
 *
 * @see {@link LineItem} for item structure
 * @public
 */
export function calculateTotal(
  items: LineItem[],
  options: CalculateOptions
): TotalResult {
  // implementation
}

Required TSDoc Tags

Compliance & Security

Security Standards

When to Reference:

• Handling user data
• Implementing authentication
• Writing secure code
• Conducting security reviews

Key Requirements:

• All user input must be validated
• All outputs must be encoded
• Authentication required for protected routes
• Secrets never in code

Compliance Requirements

When to Reference:

• Before code reviews
• Before releases
• During audits
• Planning compliance work

Compliance Targets:

• Test Coverage: >= 80%
• Accessibility: WCAG 2.1 AA
• Security: No critical vulnerabilities
• Documentation: 100% feature coverage

Getting Started

New Developer Checklist

1. Environment Setup

   • [ ] Clone repository
   • [ ] Install dependencies (npm install)
   • [ ] Set up environment variables
   • [ ] Verify build (npm run build)
   • [ ] Run tests (npm test)

2. Read Core Documents

   • [ ] TECHNICAL.md - Understand the system
   • [ ] QUALITY.md - Learn coding standards
   • [ ] FLOWSTATE.md - Know the workflow

3. First Contribution

   • [ ] Pick a starter issue
   • [ ] Follow TDD.md for testing
   • [ ] Submit PR following this workflow

Development Workflow Summary

+---------------------------------------------------------------------------+
|                        FlowState Development Workflow                      |
+---------------------------------------------------------------------------+
|                                                                            |
|  1. REQUIREMENTS (Spec Phase 1)                                            |
|     +-- Define user stories -> Acceptance criteria -> Approval gate        |
|         FLOWSTATE.md (Spec Workflow)                                       |
|                                                                            |
|  2. DESIGN + UX (Spec Phase 2)                                             |
|     +-- Technical design -> UX wireframes -> Annotations -> Approval gate  |
|         FLOWSTATE.md (Spec Workflow), wireframes.html                      |
|                                                                            |
|  3. TASKS (Spec Phase 3)                                                   |
|     +-- Task breakdown -> Estimates -> Dependencies -> Approval gate       |
|         FLOWSTATE.md (Spec Workflow)                                       |
|                                                                            |
|  4. DEVELOP (Spec Phase 4)                                                 |
|     +-- Write tests -> Implement -> Refactor -> TSDoc                      |
|         TDD.md, QUALITY.md, TSDOC.md                                       |
|                                                                            |
|  5. TEST                                                                   |
|     +-- Unit tests -> Integration -> E2E -> UX review against wireframes   |
|         TDD.md                                                             |
|                                                                            |
|  6. REVIEW                                                                 |
|     +-- Code review -> Security review -> Compliance check                 |
|         QUALITY.md, SECURITY.md, COMPLIANCE.md                             |
|                                                                            |
|  7. DOCUMENT                                                               |
|     +-- Generate API docs -> Write user docs                               |
|         TSDOC.md, DOCUMENTATION.md                                         |
|                                                                            |
|  8. RELEASE                                                                |
|     +-- Deploy -> Verify -> Monitor                                        |
|         TECHNICAL.md                                                       |
|                                                                            |
+---------------------------------------------------------------------------+

Document Status

Current Document Inventory

Template Inventory

Document Dependencies

FLOWSTATE.md (This Index)
    |
    +-- PRODUCT.md --------------------+
    |       ^                          |
    |       | references               |
    |       |                          v
    +-- TECHNICAL.md <--------------- SECURITY.md
    |       ^                          |
    |       |                          |
    |       +--------------------------+
    |
    +-- STRUCTURE.md
    |
    +-- QUALITY.md ------------------->
    |       ^                          |
    |       |                          |
    |       +<-------------------------+
    |
    +-- TDD.md
    |
    +-- TSDOC.md <--------------- QUALITY.md
    |       |                          ^
    |       | references               |
    |       +--------------------------+
    |
    +-- COMPLIANCE.md
    |       ^
    |       | references
    |       |
    +-- SECURITY.md
    |
    +-- DOCUMENTATION.md

Contributing to Documentation

Adding New Documents

1. Create document following naming convention (UPPERCASE.md)
2. Include standard sections (Overview, Table of Contents)
3. Add to FLOWSTATE.md index
4. Link from related documents
5. Submit PR for review

Updating Existing Documents

1. Make changes following existing format
2. Update "Last Updated" date
3. Update FLOWSTATE.md if structure changes
4. Submit PR for review

Documentation Standards

• Use Markdown format
• Include table of contents for long documents
• Add code examples where applicable
• Cross-reference related documents
• Keep content current with codebase

Feedback & Questions

For questions about the FlowState Standard:

1. Check the relevant document first
2. Search existing issues
3. Ask in team channel
4. Create a documentation issue if needed

The FlowState Standard is a living document. Updates are made regularly to reflect current best practices and project requirements.