flowchart TD
task(["new task"]) --> captain["captain - classify the work"]
%% small-feature - straight to code, no investigator, no plan
captain -->|small-feature| sf["code - implement + mandatory unit tests<br/>(agents: code)"]
sf --> sf2["nested verify<br/>(agents: verifier)"]
sf2 --> sf3["nested review-code when the change is risky<br/>(agents: code-reviewer)"]
%% bugfix - reproduction test first, then the smallest fix
captain -->|bugfix| bf["code - write the failing reproduction test<br/>(agents: code)"]
bf --> bf2["minimal fix<br/>(agents: code)"]
bf2 --> bf3["nested verify<br/>(agents: verifier)"]
bf3 --> bf4["final end-to-end verify<br/>(agents: verifier)"]
%% documentation - investigate first, plan only when needed
captain -->|documentation| dc["investigator<br/>(agents: investigator)"]
dc --> dcq{"plan<br/>needed?"}
dcq -->|yes| dc2["plan<br/>(agents: planner)"]
dcq -->|no| dc3["code - nested verify<br/>(agents: code · verifier)"]
dc2 --> dc3
dc3 --> dc4["final verify<br/>(agents: verifier)"]
%% architecture - plan only, approved milestones are the completion
captain -->|architecture| ar["investigator<br/>(agents: investigator)"]
ar --> ar2["plan - nested review-plan + grilling<br/>(agents: planner · plan-reviewer · developer)"]
ar2 --> ar3["milestone files under plans/ - no implementation dispatch<br/>(approved milestones are the completion)"]
%% implementation-from-milestone - plan only if the milestone is not yet reviewed
captain -->|implementation-from-milestone| im{"milestone<br/>already reviewed?"}
im -->|no| im2["plan<br/>(agents: planner)"]
im -->|yes| im3["code per task<br/>(agents: code)"]
im2 --> im3
im3 --> im4["final end-to-end verify<br/>(agents: verifier)"]
%% full-feature - the biggest one, shown in detail in the sequence diagram below
captain -->|full-feature| ff["full-feature - the whole machinery<br/>(detailed sequence diagram below)"]
My agentic workflow
ai
development
🤔 Why ?
As i mentioned in my earlier posts, i am using an agentic workflow for coding. The challenge was to create a setup that is both reliable (within reason) and cheap (within reason) - at least cheap enough for a private person to afford.
I think with less than 50$ / month i have a rather good setup currently - especially for the amount of coding that i do. Or rather, let them do.
What i want to write about today is how my workflow / loop currently works, what the components are and the ideas behind it.
👨🏭 How ?
I am the type of person who always wants to know how things work. That means - i don’t like blackboxes and if any type of machinery works, i want to see how it works and why.
That means - i prefer open source, i prefer self-hosted solutions, i prefer to see the thoughts that the AI has. Which, by the way, already proved its worth a few times when the AI went into either a completely wrong direction (because of poor wording on my side - it’s always the user’s fault) or was caught in some type of undetected loop and burned tokens like a madman.
For these reasons i am mainly using Zoo Code as a vscode extension. Sadly it has a nasty bug that lets the subagents break their connection to their parents if another vscode session is open. That bug was claimed to be resolved in the latest version, but it wasn’t. That means i can’t really work on 3 projects in parallel, which i often do. It is just more efficient to do something else when the agents work in the background.
As an alternative i am currently testing OpenCode in serve mode. That has the secondary benefit that i - one day in the future - can work with deployments on demand and hosted agentic coding. That’s important to me, because sometimes i just want to start a command and leave the agent running, while turning off my main computer. If the agent runs on a server, perhaps even containerized, that would help a lot. OpenHands goes in that direction, but i could not figure out how to get multi-stage-agents to work.
🚧 Execution
Different agent-types
The basic idea of this approach is to have different agent types have different roles. You have the heavy models for planning and strategy, you have cheap models for actual coding work - and you have separate models from different model families to verify and review the actual work.
Captain
The entry point for every request: classifies the incoming work into exactly one workflow and hands it to the Lieutenant as a subtask, then supervises the result against the completion criteria. The Captain’s own hands stay off the repository - classification and supervision only.
Lieutenant
Receives work that is already classified, loads the matching skill and drives it to completion by delegating every concrete step - investigation, planning, implementation, verification - to specialist sub-tasks. Its specialty is keeping context lean between those sub-tasks, treating their summaries as the authoritative state.
Investigator
Turns an unclear task into a short, cited evidence report (path:line) containing only facts that could change the implementation. It answers the questions a planner cannot proceed without - no solutions, no writing to the repository.
Planner
Turns the task and the investigation evidence into the smallest correct, implementation-ready plan, making each design decision explicit and reusing what the repository already has. The only files it ever writes are milestone files under plans/.
Code
Executes exactly one scoped task: the smallest correct change, following the repository’s conventions, plus the tests for the changed behavior. It also owns the nested quality gates end to end - dispatching the Verifier and the Code-reviewer until both come back clean.
Verifier
Proves that a change actually works by building focused tests, running the relevant verification and - when something fails - diagnosing it to root cause with evidence. It never grades on vibes; weak tests get strengthened before anything is declared working.
Plan-reviewer
Adversarially stress-tests a plan before anyone builds it: completeness, correctness, feasibility, dependency order, scope and whether verification can objectively pass. Findings are reported by severity - the plan itself is never edited.
Code-reviewer
Advisory review of a change and its direct blast radius for correctness, security, reliability, compatibility and maintainability problems, reported by severity with concrete fixes. It only reviews what the change touches and never modifies files.
Security-review
Looks at a change purely from an attacker’s perspective - injection, credential exposure, access control, data leakage, suspicious dependencies - and reports what is exploitable or risky, ranked by security topic. Like the other reviewers, its output is advisory only.
It is not really in the loop yet, as i think it should best be called manually on demand.
Different workflows
Different workloads need different workflows. While it is possible to run everything with the full feature workflow, it just does not make much sense.
This is 1:1 the exact table i am injecting into the Captain skill.
| Symptoms | Type | Skill |
|---|---|---|
| Multi-part, design-heavy work; multiple files/components; architecture decisions needed; complex scope | Full feature | full-feature |
| Single, contained, obvious change; one file or a few files; no design ambiguity | Small feature | small-feature |
| Plan-only output; no implementation requested; architecture design, feasibility study, or research | Architecture | architecture |
| Defect or broken behavior; a test or reproduction case is needed; regression fix | Bugfix | bugfix |
Primary deliverable is a document — create, update, or correct existing prose docs under README.md and docs/ |
Documentation | documentation |
An approved milestone file exists under plans/ and the task maps directly to it |
Implementation from milestone | implementation-from-milestone |
Example: workflow map
The table above is what the captain uses to pick a workflow - here is that same decision as a diagram, one branch per workflow. The agents are just annotations on the steps - the branching and the decision logic are the subject. full-feature is collapsed to a single node and gets its own detailed diagram below.
Example: Full Feature
I have drawn a diagram of the full feature workflow - unlike the map above, which only shows the shape of the branching, this one is that workflow in full detail. This is the biggest and most complete workflow. Others are usually smaller, skip some steps or are not as thorough with their testing/verifications.
sequenceDiagram
autonumber
actor d as Developer
participant p as Planner
participant pr as Plan-reviewer
participant l as Lieutenant
participant c as Captain
participant i as Investigator
participant co as Coder
participant cor as Code-reviewer
participant v as Verifier
d->>c: Prompt with task
c->>i: Investigate context
i-->>i: Investigator collects data from codebase and user
i->>c: Report context
c->>c: Decide exact workflow
c-->>l: Dispatch workflow
alt full-feature
l-->>p: Plan the tasks
p-->>i: Investigate only if needed
i-->>p: Report investigations
p-->>d: grill the user
d-->>p: answer questions
loop planning stage
p-->>p: Create/Update plan
p-->>pr: Review draft
pr-->>p: Report review
end
p-->>p: Write Milestone-files
p-->>l: Report the plan
loop for each milestone: development stage
l-->>co: Dispatch development
loop implement-review-loop
loop implement-verify-loop
co-->>co: Implement assigned task
co-->>co: Implement tests
co-->>v: Dispatch verifier
v-->>v: Check/Update UnitTest
v-->>v: Execute verification
v-->>v: Diagnose cause for failure
v-->>co: Report for re-implementation
end
co-->>cor: Dispatch for review
cor-->>cor: Review code
cor-->>co: Report findings
end
co-->>l: Report implementation results
end
l-->>v: Final end-to-end verify
v-->>l: Report result
end
l-->>c: Report result
c-->>d: Report result
Steps and some comments as a table:
| No | Description | Agent | Comment |
|---|---|---|---|
| 1 | Developer sends prompt with task | Captain | This needs to be precise, as it sets the base for everything else. |
| 2 | Captain asks Investigator to gather context | Captain | Gather information to use for decisions. |
| 3 | Investigator collects data from codebase and user | Investigator | Read the code, grill the user. |
| 4 | Investigator reports context back to Captain | Investigator | Raw facts only - no decisions yet. |
| 5 | Captain decides the exact workflow | Captain | Not every task needs the full machinery. Small fixes skip most of what follows. |
| 6 | Captain dispatches the workflow to Lieutenant | Captain | The Captain decides strategy - the Lieutenant is the Executing Officer. |
| 7 | Lieutenant asks Planner to plan the tasks | Lieutenant | Planning is a separate role so implementation details don’t creep in too early. |
| 8 | Planner asks Investigator for details - only if needed | Planner | Collect detailed information necessary for detailed planning. |
| 9 | Investigator reports findings to Planner | Investigator | Grounds the plan in reality instead of assumptions. |
| 10 | Planner grills the developer with questions | Planner | User interaction - if anything is unclear, the user gets asked questions. |
| 11 | Developer answers the questions | Developer | |
| 12 | Planner creates/updates the plan | Planner | Start of the planning loop - the plan is a draft until it survives review. |
| 13 | Planner sends draft to Plan-reviewer | Planner | Same idea as code review, but for the plan - mistakes are far more expensive later. |
| 14 | Plan-reviewer reports findings back to Planner | Plan-reviewer | Loop continues until the review comes back clean. |
| 15 | Planner writes milestone files | Planner | The plan becomes durable state - later stages (and re-sessions) can pick it up. |
| 16 | Planner reports the finished plan to Lieutenant | Planner | Planning stage is done, execution can start. |
| 17 | Lieutenant dispatches development for each milestone | Lieutenant | Milestones are the unit of dispatch - small enough to verify, big enough to matter. |
| 18 | Coder implements the assigned task | Coder | One task at a time, in line with the plan. |
| 19 | Coder implements tests | Coder | Tests are part of the task, not an afterthought. |
| 20 | Coder dispatches the Verifier | Coder | The coder never grades its own work. Verifier also has to be from another model family. |
| 21 | Verifier checks/updates the unit tests | Verifier | Weak tests get strengthened before anything is declared working. |
| 22 | Verifier executes the verification | Verifier | Actual runs, not vibes. |
| 23 | Verifier diagnoses the cause of failure | Verifier | Root cause first - otherwise the coder just patches the symptom. |
| 24 | Verifier reports back to Coder for re-implementation | Verifier | Closes the implement-verify loop until verification passes. |
| 25 | Coder dispatches Code-reviewer | Coder | Same distrust, different axis: now the design and quality get checked. |
| 26 | Code-reviewer reviews the code | Code-reviewer | Looks for things tests can’t catch - structure, naming, needless complexity. |
| 27 | Code-reviewer reports findings to Coder | Code-reviewer | Feeds the implement-review loop. |
| 28 | Coder reports implementation results to Lieutenant | Coder | Milestone complete - Lieutenant tracks overall progress. |
| 29 | Lieutenant dispatches final end-to-end verify | Lieutenant | Individual milestones passing doesn’t mean the feature works as a whole. |
| 30 | Verifier reports final result to Lieutenant | Verifier | The last gate before anything is reported as done. |
| 31 | Lieutenant reports result to Captain | Lieutenant | Captain checks the result against the completion criteria. |
| 32 | Captain reports result to Developer | Captain | Captain closes the loop with the developer. |
This works quite well and is as close to hands-free development as i am currently comfortable with.
Important considerations
Distributing the models between those agents is not easy, depends on which models you have available and probably changes within a few months as new models arrive. Just as a general rule: any reviewer-agent MUST be of a different model family (!) than the agent it reviews. This should minimize blind spots for both.
| agent | model-classification |
|---|---|
| Captain | Heavy - classification and supervision only, so the token volume stays negligible and the budget can go into judgment |
| Lieutenant | Mid - orchestration and condensing summaries; reliable tool-use beats raw reasoning here |
| Investigator | Cheap / fast - read-only evidence gathering, runs often and in parallel |
| Planner | Heavy - planning and strategy is what the heavy models are for; design mistakes are the expensive ones |
| Code | Cheap / fast - highest token volume of the whole loop, the plan already carries the thinking |
| Verifier | Cheap / fast - root-cause diagnosis needs teeth; must be a different model family than Code |
| Plan-reviewer | Heavy - must be a different model family than Planner |
| Code-reviewer | Cheap / fast - must be a different model family than Code |
| Security-review | Mid - must be a different model family than Code |
Additional backing skills
Some skills do not belong to a single workflow - they back the whole process:
grilling
The interview technique behind the Planner’s grilling in step 10. The skill makes the agent ask exactly one question at a time - the most upstream decision that is still open - together with its own recommended answer, and sweep the codebase for facts first, so the user only gets asked what the code cannot answer. Each answer settles one decision and reshapes the next questions; the interview ends when nothing is left silently assumed.
release
Drives a full release end-to-end: version bump, changelog, release PR into testing, promotion PR into main and the GitHub release tagged on main, all run through a helper script with a manual fallback. It stops at three pause gates - confirm the version, release PR, promotion PR - because merging those PRs is always the human’s job.
writing-for-humans
The standard every prose artifact has to pass - documentation, READMEs, release notes, even commit messages. It grades each unit of text on four criteria (message first, calibrated to the reader, one message per unit, every unit earns its place) and a review pass sorts failures into buckets like buried or deadweight with a proposed rewrite for each.
🌩️ Problems
This workflow relies heavily on subtask-creation. Currently not a lot of harnesses support it this way. Also, every harness works slightly differently - some, like OpenCode and ZooCode - define agents by having a different prompt - some only have different skills they can use. So the actual definition and setup of that flow depends on the target harness. I managed to get OpenCode and ZooCode to work, and i use both nearly daily.
But - because for example zed, which i like as an editor as well as a harness (despite it missing a few features), does not support agents (named in zed: profiles) as “having their own prompts”, i rewrote my setup to work with skills only.
Another problem was that ZooCode already brings some predefined agent-types with it. And those are not fully customizable, so i ditched/overwrote the “orchestrator”, “architect” and “debug” agents and replaced them with my own. Because the new “top-tier” agent does strategic decisions about the route, i called it “Captain” - and the Lieutenant is his executing officer.
👎 Downsides
Cost
Not having everything in one single session reduces the overall token cost, heavily reducing cached tokens, but it also slightly increases the non-cached tokens, as it potentially uses different providers and different sessions where the tokens are not cached. The overall token consumption is still less, and the quality of the results improves a lot - but you COULD have scenarios where this approach costs more. Or the captain chooses a too-heavy workflow.
???
You tell me? To be honest, i would not go back to working without that workflow - for me there are no noteworthy downsides.
📋 Where
You can find the latest state of my current workflow on my GitHub: https://github.com/gelse/AI-snippets. If you happen to have ZooCode or OpenCode, there is also a nice little autoinstaller for you. But I think it only works on Linux. And you have to have python installed (i just got rid of the node installation, as i realized i do not use it and do not have time or mood to maintain it).