Agent Flow Workflow

When an AI agent works on a flow in DevFlow, it follows a structured process from start to finish. This page describes each step of that process and what happens at every stage.

The Full Workflow

Step 1: Pick Up a Flow

The agent begins by selecting a flow to work on. It calls devflow_init with the flow ID, which locks the flow to this agent session. This prevents multiple agents from working on the same flow simultaneously.

You can assign a flow to the agent by moving it to planning, or the agent can pick up any flow that is in a ready state.

Step 2: Analyze Requirements

Before writing any plan, the agent reads the flow’s summary, description, and acceptance criteria. It also explores your codebase to understand:

• Existing code structure and patterns
• Related files and modules
• Testing conventions
• Dependencies that might be affected

This analysis phase ensures the agent understands the full context before proposing changes.

Step 3: Create an Implementation Plan

The agent creates a detailed plan that includes:

• Approach — How the task will be accomplished
• File changes — Which files will be created, modified, or deleted
• Architecture decisions — Any structural choices and their reasoning
• Tasks — A breakdown of individual steps, each with acceptance criteria
• Risks and considerations — Potential issues or edge cases

The plan is written in plain language so you can review it without reading code.

Step 4: Submit for Approval

The flow moves to the approval state. This is a gate — no code is written until you review and approve the plan.

You receive the plan in the flow detail view where you can:

• Read the full plan
• Review the proposed tasks
• Approve to proceed
• Reject with specific feedback

See Planning and Review for more details on this process.

Step 5: Start Implementing

After you approve the plan, the flow moves to ready and then to in_progress when the agent begins coding. The agent follows the approved plan, implementing each task in order.

Step 6: Track Progress Through Tasks

As the agent works, it marks tasks as complete one by one. You can watch this progress in real time on the flow detail view or the Kanban board. Each task has its own acceptance criteria, so you can see exactly what the agent considers “done” for each step.

Step 7: Create Commits and Track Git Changes

The agent creates Git commits as it works, following your project’s conventions:

• Branch naming — Uses the pattern configured in your project settings
• Commit messages — Follows your project’s commit message format
• Commit tracking — Every commit hash and message is recorded in the flow

All Git activity is linked to the flow, giving you a clear trail from requirement to code.

Step 8: Submit for Review

When implementation is complete, the agent moves the flow to review and provides:

• Agent summary — A description of what was implemented and any decisions made
• Testing instructions — Step-by-step guide for how to verify the changes
• PR link — A link to the pull request if one was created
• Commit list — All commits associated with this flow

Step 9: You Test and Decide

You review the implementation by:

1. Reading the agent’s summary
2. Following the testing instructions
3. Checking the PR and code changes
4. Running the application to verify behavior

Then you either:

• Approve — The flow moves to done. The work is complete.
• Reject with feedback — The flow returns to in_progress. The agent reads your feedback and makes the requested changes.

Git Settings Integration

The agent respects your project’s Git configuration throughout the workflow:

• Branch naming convention — The agent creates branches matching your pattern (e.g., feature/<display-id>-<slug>)
• Commit conventions — Commit messages follow your configured style
• PR target — Pull requests are created against the active release branch, or main if no release is active

You configure these settings once in your project’s Git settings. The agent follows them automatically for every flow.

What Happens If Something Goes Wrong

• Agent encounters an error — It logs the error in the session and may ask for clarification
• Plan is rejected — The agent revises based on your feedback and resubmits
• Review is rejected — The agent returns to implementation and addresses your comments
• Session disconnects — The flow remains in its current state. A new agent session can pick it up where it left off