This is the second part of the tunaFlow technology post series. In the first part, we talked about "give the process to the agent," and this time is about how we actually implemented that process. Currently, we're testing in multiple ways how to reduce the large amount of tokens generated by final testing and ContextPack 😁 If it's big, it's big, and if it's nothing, it might be that kind of problem, but due to our greed not to trade off either way, the release date is being delayed. Thank you for taking an interest in this humble project. We will repay you with an open source that is cool and excellent, not shabby. 🙏

---

When you tell an agent "make this"

If you tell Claude Code "refactor the authentication middleware," it immediately starts writing code. Without design. Without review. Sometimes it works well, but the more complex the task, the more problems arise.

- Starting implementation without understanding the scope of impact

- After fixing, saying "oh, this wasn't the right direction" and reverting

- Reviewing their own code saying "looks good ✅"

This is a problem that happens to people too. In a team, code review catches this, but when an agent does it alone, there's no safety mechanism.

tunaFlow's workflow pipeline was created to solve this problem. A structure that applies the human development process (design → approval → implementation → review) to agents.

> The inspiration for this workflow came from Stavros Korokithakis's blog. While proceeding with a project using Claude Code, the flow he naturally created — first making a Plan, implementing after approval, and reviewing the result — led to the thought, "shouldn't a tool support this?"

---

7-Step Workflow

tunaFlow's workflow has 7 steps.

1. Chat           — User explains requirements to Architect
2. Drafting       — Architect proposes Plan
3. Approval       — User approves/rejects/requests revision of Plan
4. Dev            — Developer implements code
5. Review         — Reviewer(s) review
6. Rework         — If review fails, fix → re-review
7. Done           — Complete

There are automatic transitions between each step, and the points where humans intervene are clear. We didn't implement everything at once, but created it step by step, sharing the problems and decisions we encountered in the process.

---

Marker-Based Detection: Extracting Structure from Agent Output

The first concern was "how do we detect that an agent has proposed a Plan?"

If you use an SDK, you can get structured output like submit_plan_proposal({ title, subtasks }) via function calling. But tunaFlow uses a CLI subprocess method, so agent output is free-form text.

So we use HTML comment markers.

## Authentication Middleware OAuth2 Migration
### subtasks
1. Replace JWT validation logic with OAuth2 PKCE
2. Modify Route guard adapter
3. Update tests
### description
Converting current JWT-based authentication to OAuth2 PKCE...

In the Architect's Persona (role prompt), there's a rule that says "when proposing a Plan, put it inside this marker," and the frontend parses this marker.

// planProposalParser.ts
const MARKER_OPEN = "";
const MARKER_CLOSE = "";
export function hasPlanProposal(content: string): boolean {
    return content.includes(MARKER_OPEN);
}

When the marker is detected, instead of plain text, it's rendered with the PlanProposalCard UI component. Users can approve/reject/request revision directly from the card.

Why HTML Comments

 is not rendered in markdown

Even if the agent puts the marker, it won't be visible in a normal markdown renderer, and only tunaFlow detects it. Even if the marker is accidentally output, it won't be exposed to users.

Limitations of Markers

Because it's marker-based, detection fails if the agent doesn't follow the format. This happened in actual use.

- Agent doesn't close the marker missing)

- No subtasks section inside the marker

- Marker is placed inside a code block making parsing impossible

There are two approaches. First, we detail the format rules in the Persona prompt. Second, we make the parser lenient — if closing marker is missing, treat to end of message as content, if subtasks are missing, display card with description only.

---

Approval Gate: The Point Where Humans Decide

When the Architect proposes a Plan, the user sees 3 options.

┌───────────────────────────────────┐
│ Plan: Auth Middleware OAuth2 Migration │
│                                   │
│ Subtasks:                         │
│  1. Replace JWT → OAuth2 PKCE    │
│  2. Modify Route guard             │
│  3. Update tests                   │
│                                   │
│  [Approve]  [Request Revision]  [Hold]  │
└───────────────────────────────────┘

- Approve: Implementation Branch is automatically created, and implementation instruction is sent to the Developer agent

- Request Revision: User enters feedback, and re-proposal request goes to Architect

- Hold: Decide later

Initially there were only 2 options (approve/reject), but in actual use, cases like "the direction is right but change the subtask a bit" were common, so we added request revision.

Why 3-way

With 2-way (approve/reject), after rejection, you have to explain "why you rejected it" to the Architect again. With 3-way, you can immediately write feedback in the revision request and it's done in one go.

// Inside ApprovalGate
case "revise":
    // Enter feedback → Request Plan revision from Architect
    await requestPlanRevision(plan, feedback, architectEngine);
    break;

---

Implementation Branch: Implementation in an Isolated Space

When Plan is approved, a Branch is automatically created. Branch means "conversation branch" in tunaFlow (discussed in detail in part 3).

Click approve
  → Create new record in branches table (mode: "chat")
  → Create shadow conversation (branch:{branchId})
  → Create Plan document (docs/plans/{slug}.md)
  → Send implementation prompt to Developer

The Developer implements code within this Branch. Since it's isolated from the main conversation, even if implementation fails, the main conversation is unaffected.

The prompt sent to the Developer has this structure.

### 🔧 Start Implementation
Plan: "Authentication Middleware OAuth2 Migration"
Task Instructions:
- docs/plans/auth-oauth-migration.md
- docs/plans/auth-oauth-migration-task-01.md
- docs/plans/auth-oauth-migration-task-02.md

Rules:
1. Read each task file and implement in order
2. On each completion 
3. On complete 

Markers are used here too. When the Developer completes a subtask, they output marker, and tunaFlow detects this to update the Plan state.

---

Review RT: Review by a Different Agent

When implementation is complete, a Review Roundtable (RT) automatically starts. RT is a structure where multiple agents discuss (detailed in part 4).

Developer complete (impl-complete detected)
  → Automatically create Review Branch
  → Run tests (run_project_tests)
  → Send review prompt to 2 Reviewers
  → Each Reviewer independently reviews → outputs verdict

Reviewer prompt includes Plan document, implementation result summary, and test results. Reviewer outputs judgment with marker.

verdict: pass
findings:
- Implementation matches Plan
- Good test coverage
recommendations:
- Check authentication call method in ws_handler.rs
``

Reviewer Does Not Modify Code

This was an important design decision. The Reviewer's Persona has the rule "don't modify code. Just read and judge."

Do NOT modify any code, create commits, push changes.
MUST read files for review.
Submit review verdict only."

Reason: If the Reviewer fixes code, the roles with Developer get mixed. Reviewer only judges, and the Developer fixes. Like how code reviewers in a human team don't directly commit to PRs.

---

Rework: If It Fails, Do It Again

If the Review verdict is "fail", we transition to the Rework stage.

Reviewer verdict: fail
  → Plan phase: "rework"
  → Pass feedback to Developer
  → Developer fixes
  → Run Review RT again
  → Check verdict
  → If pass, Done; if fail, Rework again

A problem occurred here. Infinite loop.

Developer fixes → Reviewer fails → Developer fixes → Reviewer fails → ... This repetition 3 or more times often meant repeating the same problem the same way.

Doom Loop Detection

So we added Doom Loop detection. Count review_failed event occurrences in the plan_events table, and escalate if 3 or more.

// reviewWorkflow.ts
const freshEvents = await planApi.listPlanEvents(plan.id);
let lastEscalationIdx = freshEvents.length;
for (let i = freshEvents.length - 1; i >= 0; i--) {
    if (freshEvents[i].eventType === "doom_loop_escalated") {
        lastEscalationIdx = i;
        break;
    }
}

const failCount = eventsSinceReset
    .filter((e) => e.eventType === "review_failed").length;

Upon reaching 3 times:

"Review failed 3 times — Design review recommended. 
Choose between Architect redesign or Developer continues rework."

We tell the user "this might not be an implementation problem but a design problem." The decision of whether to continue Rework or modify the Plan itself is made by a human.

Rework Counter Reset

There's an important detail. When a Plan is revised, the failure counter resets. Even if it failed 3 times with the previous Plan, when starting again with the revised Plan, the counter starts from 0.

This was inspired by Optio, a GitHub CI automation tool. Optio counts "number of automatic retries after the last manual intervention," and tunaFlow follows the same pattern.

---

Points Where Humans Intervene

Throughout the entire flow, there are 3 mandatory points where humans must intervene.

1. Plan approval          — "Should we go this direction?"
2. After review judgment  — "Check review results and decide next action"
3. Doom Loop response     — "Failed 3 times. Change design or keep trying?"

The rest (Branch creation, Developer prompt sending, Review RT start, Rework transition) are automatic.

Initially, we thought "wouldn't it be better if everything was automatic?" Auto through review, auto-merge if pass. But the problems appeared immediately in actual use.

- Reviewer gave "pass" but actually missed edge cases

- Developer implemented differently from Plan's intent but Reviewer also missed it

- Everything ran automatically but the result was completely different from what was wanted

The cost of human verification (one click, 30 seconds of reading) is much less than the cost of fixing work that went wrong. So we maintained the principle of "automate but let humans judge the decision points."

---

Current Limitations

1. Workflow Overhead

Even for simple fixes (typo fix, one-line change), going through Plan → Approve → Dev → Review is excessive. Currently, users can skip the workflow and solve it directly through chat, but deciding "does this need a workflow?" is itself a cost.

2. Marker Format Deviation

There are still cases where agents don't follow the marker format. Especially with smaller models (Haiku, Gemini Flash), marker format compliance rates drop. We're responding with a lenient parser, but fundamentally SDK function calling is more stable. However, as long as we maintain the CLI subprocess method, markers are the practical choice.

3. Review Quality

Reviewer giving "pass" doesn't mean it's actually fine. Since Reviewer is also an agent, it misses things. In particular, it's difficult to structurally judge "does this change affect other files?" This is also why we integrated code-review-graph (covered in part 7).

4. Rework Convergence Problem

Even when the Rework loop runs, sometimes the same problem repeats. Developer receives Reviewer feedback and fixes, but only makes surface-level fixes without addressing root cause. This is partially addressed by a Failure Learning system that gives Developer information that "there was a similar failure before" (covered in part 9).

---

Real Usage Numbers

Results from testing 4 complete workflow cycles in the tunaInsight project.

- Average time Plan → Done: 3-5 minutes by agent execution time (excluding user approval wait)

- Rework occurrence rate: About 40% (1 or more Rework in 2 out of 4 times)

- Doom Loop occurrence: 0 times (no 3 consecutive failures)

- Bugs discovered in full cycle: 15 (result document marker remnants, Reviewer template contradictions, etc.)

15 bugs mainly came from "auto-generated document quality" and "marker parser edge cases." More problems were in surrounding infrastructure (document generation, marker parsing) than in the workflow logic itself.

---

Key Decisions Summary

Next Part Preview

Part 3: "Branching Conversations" — Branch Design and Usage

How Implementation Branch and Review Branch are created, why we chose drawer UX, and how adopt (result merge) works. The relationship between workflow and Branch is key.

---

Series List

1. [Give the Agent a Process](./01-Give-the-Agent-a-Process.md) — What We Learned Making AOC

2. Plan → Dev → Review — Workflow Pipeline Implementation Story (This article)

3. Branching Conversations — Branch Design and Usage

4. Making Agents Discuss — Roundtable Design and Limitations

5. When Conversations Get Long — Agent Long-term Memory Implementation

6. Running Workflow on Claude's $20 — Engine Architecture

7. Teaching Agents Code Structure — rawq + code-review-graph

8. Out of 246 Skills, Only What's Needed — Automatic Skill Application Implementation

9. When Agents Repeat Mistakes — Quality Assurance Design

10. Full Cycle with tunaFlow — Workflow Hands-on Test Review

- [Already Published] ContextPack — Context Design for Multi-Agent Orchestrator

---

References

- Stavros Korokithakis — Claude Code Workflow Pattern. Plan → Approval → Implementation → Review flow inspiration. https://www.stavros.io/posts/how-i-write-software-with-llms/

- Optio (github.com/jonwiggins/optio) — CI-based automatic PR management. Referenced "count since last manual intervention" pattern for Doom Loop.

- Addy Osmani — "Orchestrating Coding Agents": Plan Approval Gate, Dedicated Reviewer patterns. https://addyosmani.com/blog/code-agent-orchestra/

- tunaFlow internal documents

- Marker parser: src/lib/planProposalParser.ts

- Workflow: src/lib/workflow/ (7-file module)

- Plan state: src-tauri/src/commands/plans.rs

- Review: src/lib/workflow/reviewWorkflow.ts

- Doom Loop: src/lib/workflow/reviewWorkflow.ts:160