When people think of an AI agent workflow, most picture one agent, one long task and a wait for the result. That works for small jobs. On something big, like “move payments to a new provider”, one agent researches, plans and implements all at once: context bloats, you never see a plan, and mistakes surface only after the code is written.
This post describes a pipeline that splits the work into three stages: research, plan, build. A separate agent runs each stage, stages hand off through files, and the plan goes through your approval before anyone writes code.
Why a staged AI agent workflow?
The problems with a single-agent session:
- Context grows. Every file read during research stays in context during implementation.
- The plan is invisible. The agent decides what to do and goes straight to coding.
- Mistakes show up late. A wrong assumption only appears when the tests fail.
A staged pipeline splits these across agents. The researcher doesn’t write code, the planner only writes the plan, the builder implements it. Each works with its own small context.
Three stages and their handoff files
| Stage | Agent | Output | Rule |
|---|---|---|---|
| Research | Researcher | 01-arastirma.md | No code; report the current state and the options |
| Plan | Planner | 02-plan.md | Goal, out of scope, files, steps, test strategy, acceptance criteria |
| Build | Builder | Code and tests | Implement the plan, run the tests |
Why do handoff files matter? Because the next agent reads only the previous agent’s result, not its whole conversation. The plan file is also a document for you: you read what will happen before building starts.
AgentVera writes these files under .agentvera/handoff/<date>-<topic>-<id>/. The folder is kept out of git through the local exclude file, so it never shows up as a change in your repository.
When does a stage advance?
The most important part of the pipeline is the transition rule. An agent might ask midway, “Which database should we use?” That question must not trigger the next stage.
So a stage advances only when the agent’s reply ends with the [[TESLİM]] marker, checked by a regex condition node. Questions the agent asks before finishing don’t move the flow; you answer, and the agent continues.
The approval step
Reading the plan before it reaches the builder is the most valuable moment in the pipeline. A wrong plan takes five minutes to fix here and hours once code exists.
In AgentVera, the option to get your approval before the plan goes to the builder is on by default. It inserts a human approval node into the flow. The waiting step is listed in the status bar, and with Telegram notifications on you can approve from your phone.
Setting up the pipeline step by step
AgentVera’s Research → Plan → Build pipeline sets this up in one window:
- Open the pipeline from the ⌘K command palette, or use the button in Details → Flows.
- Write the job in the Topic / goal field. The clearer it is, the more focused the researcher.
- Pick a tool for each stage: Claude Code, Codex or another supported CLI.
- Leave the approval option on.
- Press Create and start. Three agents are created, placed in panes and the flow starts.
A notify node tells you when the flow is done. You can edit the pipeline later in Details → Flows, for example to add a review step after the builder.
How to write a good goal
The researcher’s first input is the goal you write. A good goal:
- Describes the outcome: “Move the payment provider from X to Y without changing the current API contract.”
- States the limits: “Don’t touch the invoicing module.”
- Defines success: “Existing payment tests must pass, and add an integration test for the new provider.”
A goal like “improve payments” pushes the researcher to read the whole codebase.
Extending the pipeline with your own flow
The three-stage pipeline is a starting point. You can extend the same structure in flows:
- Condition node: take a different path when the reply contains a certain phrase.
- Transform node: send the next agent only the last code block or the first N lines.
- Wait: leave time between two steps.
- Notify: get told about important steps.
- Turn limit: automatically stop connections that loop.
Example: moving to a new payment provider
Let’s follow the pipeline through a real job. The goal: “Move the payment provider from X to Y; don’t change the current API contract, don’t touch the invoicing module.”
Research stage
The researcher writes no code. It reads the current payments module, lists where provider X is used, maps Y’s matching concepts and notes the risks. Its output is 01-arastirma.md: which files are affected, which behaviors must be kept, which questions are open.
If the researcher hits an open question, such as “does the refund flow move too?”, it asks. Because the reply doesn’t end with [[TESLİM]], the flow doesn’t advance; you answer and the researcher finishes its report.
Plan stage
The planner reads only the research file. It doesn’t carry the whole conversation, so its context stays small. It writes the goal, out of scope, the files to change, the steps, the test strategy and the acceptance criteria to 02-plan.md.
Approval
The plan comes to you. The issues most often caught here:
- A module that should stay out of scope sneaking into the plan.
- Existing tests missing from the test strategy.
- Step order, such as interface first, then implementation.
Write your correction and approve, or reject. Rejecting stops the flow; ask the planner for a fix and start again.
Build stage
The builder implements the approved plan and runs the tests. Because the plan is clear, it stays in scope. You get a notification when it’s done, and if automatic code review is on, the findings are ready too.
When is a pipeline overkill?
Not every job needs three stages. Setting up a pipeline for a one-file fix, a typo or a small style change takes longer than the work. A rough rule: if the change touches several modules, there’s uncertainty, or a wrong assumption is expensive, use a pipeline; otherwise go with one agent.
Scheduling and running pipelines remotely
You don’t have to sit at the computer while a long pipeline runs. A few helpers:
- Telegram notifications: approve the plan from your phone, and reply to a notification to send text to that agent.
- Scheduled tasks: send an agent a message on a cron schedule, for example to start dependency research every morning.
- Prevent sleep: the setting that keeps the computer awake while agents work stops overnight jobs from stalling.
Checklist
- Does the goal describe the outcome and limits in one paragraph?
- Was the researcher told not to write code?
- Is plan approval on?
- Will the builder run the tests?
- Will you be notified when the flow ends?
Wrapping up
A staged AI agent workflow makes agents more predictable on big jobs. Research and plan live in separate files, building starts only after you’ve read the plan, and context stays small at every stage.
AgentVera sets up this pipeline in one click and lets you extend it however you like. Start on the free plan, and see notifications and approvals to handle steps like plan approval remotely.