Workflow State Mapping Guide

This guide explains how backlog.md task states map to /flowspec workflow commands in the Flowspec Spec-Driven Development (SDD) workflow.

Overview

Flowspec uses a state machine to coordinate task progression through the SDD lifecycle. Each task state corresponds to a workflow phase, and each phase is executed by running a /flowspec command.

Key Concept: Task states represent where you are in the development lifecycle, while /flowspec commands represent how to move forward.

State Mapping Table

Task State	Created By	Next Command	Agents Involved
To Do	Manual (task creation)	`/flow:assess`	workflow-assessor
Assessed	`/flow:assess`	`/flow:specify`	product-requirements-manager
Specified	`/flow:specify`	`/flow:research` or `/flow:plan`	researcher, business-validator (research) OR software-architect, platform-engineer (plan)
Researched	`/flow:research`	`/flow:plan`	software-architect, platform-engineer
Planned	`/flow:plan`	`/flow:implement`	frontend-engineer, backend-engineer, ai-ml-engineer, code-reviewers
In Implementation	`/flow:implement`	`/flow:validate`	quality-guardian, secure-by-design-engineer, tech-writer, release-manager
Validated	`/flow:validate`	`/flow:operate` or manual → Done	sre-agent (operate)
Deployed	`/flow:operate`	Manual → Done	—
Done	Manual	—	—

State Lifecycle Diagrams

Primary Forward Path (Full SDD Workflow)

To Do
  ↓ /flow:assess
Assessed
  ↓ /flow:specify
Specified
  ↓ /flow:research
Researched
  ↓ /flow:plan
Planned
  ↓ /flow:implement
In Implementation
  ↓ /flow:validate
Validated
  ↓ /flow:operate
Deployed
  ↓ manual
Done

Optional Research Path (Spec-Light Mode)

For simpler features that don't require research:

To Do
  ↓ /flow:assess
Assessed
  ↓ /flow:specify
Specified
  ↓ /flow:plan (skipping research)
Planned
  ↓ /flow:implement
In Implementation
  ↓ /flow:validate
Validated
  ↓ /flow:operate
Deployed
  ↓ manual
Done

Early Exit Paths

You can manually move to "Done" from several states:

Validated → Done (validation complete, deployment deferred)
In Implementation → Done (implementation complete, validation deferred)
Deployed → Done (production deployment confirmed)

Rework/Rollback Paths

When issues are found, you can move backward:

In Implementation → Planned (rework needed based on implementation findings)
Validated → In Implementation (rework needed based on validation findings)
Deployed → Validated (rollback from production)

How States Are Created

From flowspec_workflow.yml

States are defined in the flowspec_workflow.yml configuration file at the project root:

states:
  - "To Do"
  - "Assessed"
  - "Specified"
  - "Researched"
  - "Planned"
  - "In Implementation"
  - "Validated"
  - "Deployed"
  - "Done"

These states are automatically available in backlog.md for task management.

Built-in States

Two states are always present and cannot be removed:

To Do: Initial state for all new tasks
Done: Terminal state indicating work is complete

Custom States

You can add custom states by editing flowspec_workflow.yml:

states:
  - "To Do"
  - "Assessed"
  - "Specified"
  - "Security Audited"  # Custom state
  - "Researched"
  # ... rest of states

Important: When adding custom states, you must also define:

A workflow that outputs to this state
Transitions that connect it to the state graph

See Workflow Customization Guide for details.

State Transition Rules

Forward Transitions (Automatic)

When you run a /flowspec command, the task state automatically transitions to the workflow's output state:

# Task is in "Planned" state
/flow:implement

# After completion, task is now in "In Implementation" state

Valid Input States

Each /flowspec command can only run from specific states. These are defined in flowspec_workflow.yml:

workflows:
  implement:
    input_states: ["Planned"]
    output_state: "In Implementation"

If you try to run a command from an invalid state, you'll get an error:

# Task is in "To Do" state
/flow:implement

# Error: Cannot execute 'implement' from state 'To Do'.
# Valid input states: ['Planned']

Manual Transitions

Some transitions must be done manually using the backlog CLI:

# Mark task as Done
backlog task edit task-123 -s Done

# Rework: move back to Planned
backlog task edit task-123 -s Planned

Enforcement

The workflow configuration validates transitions to prevent invalid state changes:

transitions:
  - name: "implement"
    from: "Planned"
    to: "In Implementation"
    via: "implement"

If a transition is not defined in flowspec_workflow.yml, it will be rejected.

Examples

Example 1: Standard Feature Development

# 1. Create task (state: To Do)
backlog task create "Add user authentication"

# 2. Assess workflow suitability
/flow:assess
# → State: Assessed

# 3. Create specification
/flow:specify
# → State: Specified

# 4. Plan architecture (skipping research)
/flow:plan
# → State: Planned

# 5. Implement feature
/flow:implement
# → State: In Implementation

# 6. Validate quality, security, docs
/flow:validate
# → State: Validated

# 7. Deploy to production
/flow:operate
# → State: Deployed

# 8. Confirm deployment success
backlog task edit task-123 -s Done
# → State: Done

Example 2: Research-Heavy Feature

# 1-3: Same as above (To Do → Assessed → Specified)

# 4. Conduct research
/flow:research
# → State: Researched

# 5. Plan architecture
/flow:plan
# → State: Planned

# 6-8: Same as above (Planned → ... → Done)

Example 3: Validation Issues Found

# Task is in "Validated" state
# Validation found issues that need fixing

# Move back to Implementation
backlog task edit task-123 -s "In Implementation" \
  --notes "Fixing security issues found in validation"

# Re-implement fixes
/flow:implement

# Re-validate
/flow:validate
# → State: Validated

State Validation

Check Current State

# View task details
backlog task view task-123

# See current state in task metadata

Validate Workflow Configuration

Check that your state transitions are valid:

specify workflow validate

# Output:
# ✓ Configuration valid
# ✓ No cycles detected
# ✓ All states reachable from "To Do"
# ✓ Terminal states configured

Valid Workflows for Current State

To see which /flowspec commands can run from the current state:

# This information is available in the workflow config
from specify_cli.workflow.config import WorkflowConfig

config = WorkflowConfig.load()
workflows = config.get_valid_workflows("Planned")
# Returns: ['implement']

Troubleshooting

Error: "Cannot execute 'X' from state 'Y'"

Cause: You're trying to run a workflow from an invalid state.

Solution:

Check the current task state: backlog task view task-123
Check valid input states for the workflow in flowspec_workflow.yml
Run the correct workflow sequence, or manually change state if appropriate

Error: "State 'X' not found in configuration"

Cause: A state is referenced that doesn't exist in flowspec_workflow.yml.

Solution:

Check for typos in state name
Verify state is defined in flowspec_workflow.yml
Run specify workflow validate to check configuration

Warning: "State 'X' is not reachable"

Cause: A custom state has no transition path from "To Do".

Solution:

Add transitions to connect the state to the workflow graph
See Workflow Customization Guide

States Don't Match flowspec_workflow.yml

Cause: The workflow configuration may have been modified but not reloaded.

Solution:

Restart Claude Code or reload the configuration
Verify changes were saved to flowspec_workflow.yml
Run specify workflow validate to check for errors

Advanced Topics

Multiple Input States

Some workflows can accept multiple input states:

workflows:
  plan:
    input_states: ["Specified", "Researched"]
    output_state: "Planned"

This allows skipping optional phases (like research) while maintaining workflow integrity.

Optional vs Required Workflows

Workflows can be marked as optional:

workflows:
  research:
    optional: true

Optional workflows can be skipped, but their state transitions must still be defined.

Agent Loop Classification

States map to either "inner loop" (fast iteration) or "outer loop" (governance):

agent_loops:
  inner:
    agents:
      - "frontend-engineer"
      - "backend-engineer"
      # ... fast iteration agents

  outer:
    agents:
      - "workflow-assessor"
      - "quality-guardian"
      # ... governance agents

See Agent Loop Classification for details.

Workflow Architecture - Overall workflow design
Workflow Customization Guide - How to modify workflows
Workflow Troubleshooting - Common issues and fixes
Backlog User Guide - Task management with backlog.md
Agent Loop Classification - Inner vs outer loop

Summary

Task states represent progression through the SDD lifecycle
/flowspec commands transition tasks between states
States are defined in flowspec_workflow.yml
Transitions are validated to prevent invalid state changes
Built-in states ("To Do", "Done") are always present
Custom states can be added with proper workflow definitions
Some workflows are optional, some have multiple input states
Manual transitions are needed for completion and rework scenarios

Workflow State Mapping Guide

Overview

State Mapping Table

State Lifecycle Diagrams

Primary Forward Path (Full SDD Workflow)

Optional Research Path (Spec-Light Mode)

Early Exit Paths

Rework/Rollback Paths

How States Are Created

From flowspec_workflow.yml

Built-in States

Custom States

State Transition Rules

Forward Transitions (Automatic)

Valid Input States

Manual Transitions

Enforcement

Examples

Example 1: Standard Feature Development

Example 2: Research-Heavy Feature

Example 3: Validation Issues Found

State Validation

Check Current State

Validate Workflow Configuration

Valid Workflows for Current State

Troubleshooting

Error: "Cannot execute 'X' from state 'Y'"

Error: "State 'X' not found in configuration"

Warning: "State 'X' is not reachable"

States Don't Match flowspec_workflow.yml

Advanced Topics

Multiple Input States

Optional vs Required Workflows

Agent Loop Classification

Related Documentation

Summary