Flow States Reference

State Diagram

Every flow in DevFlow moves through seven states organized in three phases:

Preparation               Development                Complete
───────────────────────   ─────────────────────────   ────────
idea → planning → approval → ready → in_progress → review → done
         ↑          │                    ↑            │
         └──────────┘                    └────────────┘
        (reject with                    (reject with
         feedback)                       feedback)

The Three Phases

Preparation Phase

The preparation phase is about defining and approving the work before any code is written.

State	Included
idea	Yes
planning	Yes
approval	Yes

During this phase, the work is shaped from a rough idea into an approved implementation plan. No code changes happen yet.

Development Phase

The development phase is about building and reviewing the implementation.

State	Included
ready	Yes
in_progress	Yes
review	Yes

During this phase, code is written based on the approved plan, and the results are tested and reviewed.

Complete Phase

The complete phase contains a single state:

State	Included
done	Yes

The work is finished. Code is merged, time is tracked, and the full audit trail is recorded.

State Details

idea

The starting point for every flow.

What it means: A new idea has been captured. It may be a feature request, a bug report, or a task. No implementation details exist yet.
Who acts: Anyone can create a flow in the idea state. You, a team member, or an AI agent can initiate it.
What happens next: Move to planning when you are ready to have the AI agent analyze the idea and create an implementation plan.
Can go back to: Nothing — this is the first state.

planning

The AI agent creates a detailed implementation plan.

What it means: The AI agent is analyzing the idea, researching the codebase, and creating a step-by-step implementation plan with acceptance criteria and task breakdowns.
Who acts: The AI agent does the work. It reads project context, understands requirements, and produces a plan.
What happens next: The agent submits the plan and the flow moves to approval.
Can go back to: Nothing — but the flow can be sent back here from approval if the plan is rejected.

approval

You review the AI agent’s implementation plan.

What it means: The plan is ready for your review. You read through the proposed approach, acceptance criteria, and task list to decide if it is good enough to proceed.
Who acts: You (or any authorized team member). This is a human decision point.
What happens next:
- Approve — The flow moves to ready, and the plan is locked in.
- Reject — The flow goes back to planning with your feedback. The agent will revise the plan based on your comments.
Can go back to: Nothing — but rejecting sends the flow back to planning.

ready

The plan is approved and waiting for implementation to begin.

What it means: The implementation plan has been approved. The flow is queued and ready for the AI agent to start coding.
Who acts: No one acts in this state. It is a waiting state.
What happens next: The AI agent picks up the flow and moves it to in_progress when it starts working.
Can go back to: Nothing under normal circumstances.

in_progress

Implementation is actively happening.

What it means: The AI agent is writing code, creating commits, and working through the tasks defined in the approved plan.
Who acts: The AI agent does the implementation work. Progress is visible through task completion and git commits.
What happens next: When the agent finishes, it submits a summary and testing instructions, and the flow moves to review.
Can go back to: Nothing — but the flow can be sent back here from review if the implementation is rejected.

review

You test and review the implementation.

What it means: The AI agent has finished its work. You now test the changes using the provided testing instructions, review the code, and decide whether the implementation meets your standards.
Who acts: You (or any authorized team member). This is the final human quality gate.
What happens next:
- Approve — The flow moves to done. The work is complete.
- Reject — The flow goes back to in_progress with your feedback. The agent will address your concerns and resubmit.
Can go back to: Nothing — but rejecting sends the flow back to in_progress.

done

The flow is complete.

What it means: The implementation has been approved, the code is merged, and all work is finished. The flow’s completion time is recorded.
Who acts: No one. This is the final state.
What happens next: Nothing. The flow remains here as a permanent record.
Can go back to: Nothing — done is final.

Rejection Loops

Two states support rejection with feedback:

Approval rejection

planning → approval → (reject) → planning → approval → (approve) → ready

When you reject a plan in the approval state, you provide specific feedback explaining what needs to change. The flow returns to planning, where the AI agent revises the plan based on your feedback. The revised plan comes back to approval for another review. This loop can repeat as many times as needed until you are satisfied with the plan.

Review rejection

in_progress → review → (reject) → in_progress → review → (approve) → done

When you reject an implementation in the review state, you provide feedback describing what is wrong or what needs improvement. The flow returns to in_progress, where the AI agent addresses your concerns. The revised implementation comes back to review. Like approval, this loop continues until the implementation meets your standards.

Audit Trail

Every state transition is recorded with who performed the action and when it happened:

Event	What is recorded
Plan created	Who created the plan, timestamp
Plan approved	Who approved it, timestamp
Implementation started	Which agent started, timestamp
Code approved	Who approved the review, timestamp

This audit trail provides full traceability. Weeks or months later, you can look at any flow and understand exactly who made each decision and when. This is especially valuable for team environments where multiple people and AI agents are involved.