Agent Flow — Issue → Plan → Handoff

📥

User Input

User picks an issue from the table UI and selects a repository folder. The issue can be written in any language — vague, blunt, or broken English. That's fine.

REAL EXAMPLE ISSUE

"target is wrong, fix it" — repo: /projects/backend

↓

TRIGGERS PIPELINE

🧠

STAGE 01
UNDERSTAND

Issue Intake & Normalisation

Receive the raw issue text + selected repo path. Strip noise, detect language, normalise to English if needed. Tag it with a unique job ID.

What happens here

Raw issue text is cleaned and passed to the Understanding Agent with metadata: repo path, job ID, timestamp, and user-set priority.
LLM: Qwen 7B Local Python

Codebase 3-Layer Scan

The agent doesn't read the whole codebase. It queries a pre-built semantic index, follows import chains, and reads only relevant chunks. Like a senior dev who knows where to look.

The 3-layer funnel (see Codebase tab)

Layer 1: semantic search on index → candidate files
Layer 2: explore import/call relationships → trace the thread
Layer 3: read only the relevant 200–400 line chunks
ChromaDB Tree-sitter AST LLM: Qwen 7B Local

Web Context Fetch

If the issue references a library, error message, or concept the agent isn't sure about — it searches the web and reads the relevant docs or Stack Overflow thread before forming its understanding.

Triggers a web search when

— Issue mentions an external library or version
— Error message looks like a known bug
— Confidence in understanding is below threshold
Web Search Tool Official Docs Scraper

Issue Understanding Report

Agent produces a structured understanding of what the issue actually means — in precise technical language. "target is wrong" becomes a specific, actionable problem statement.

Output of this step

{ problem: "The render target in shader.go line 142 is using the wrong framebuffer ID causing visual corruption on resize", affected_files: [...], confidence: 87 }

Confidence
> 70%?

✓ YES → continue ✗ NO → ask user 1 question

↓

UNDERSTANDING CONFIRMED

📐

STAGE 02
PLAN

Solution Research (Web + Docs)

Before planning, the Planner agent searches for the best known solution approach — official docs, changelog notes, relevant GitHub issues in the library's own repo.

Why this matters

A 7B model doesn't know about APIs released last month. But if we fetch the docs and put them in context — it does. This is how a small model thinks like a pro.
Web Search Docs Fetcher LLM: 32B Server

Execution Plan Generation

Planner generates a precise, step-by-step execution plan. Not vague instructions — exact files, exact functions, exact changes required, in the order they need to happen.

Plan structure

Step 1: Edit shader.go line 142 — change framebuffer ID from X to Y
Step 2: Update renderer_test.go — add resize test case
Step 3: Check if resize handler in main.go needs update
Dependency ordered Atomic steps

Risk Assessment

Before handing off, the planner identifies what could go wrong. Which other parts of the codebase might be affected. What tests exist. What tests need to be written.

Risk flags example

⚠ framebuffer change may affect 3 other modules that reference it
⚠ No existing resize tests — Tester agent must write from scratch
✓ Change is isolated to rendering layer — low blast radius

↓

PLAN COMPLETE — HANDOFF

📦

STAGE 03
HANDOFF

AgentPayload Assembly

Everything from Stage 1 and Stage 2 is packaged into a single structured AgentPayload object. This is the complete context the Coder agent needs — and nothing more.

AgentPayload contains

— Original issue + normalised problem statement
— Affected files with relevant code chunks (not full files)
— Step-by-step execution plan (dependency ordered)
— Risk flags + test requirements
— Web context fetched (docs, Stack Overflow snippets)
— Job ID, repo path, priority, timestamp

Queue & Fire Coder Agent

AgentPayload is pushed to the task queue. Coder Agent picks it up immediately and begins execution. From this point the Understand/Plan pipeline is done — its job is complete.

Why we separate these concerns

The Understand + Plan pipeline is expensive (web search, indexing, 32B model). It runs once. The Coder is fast and focused — it only needs the payload, not the history of how it was built. SQLite queue Async handoff

↓

📦 AgentPayload — handed to Coder Agent

PROBLEM

Precise technical description of the actual issue

FILES + CHUNKS

Only the relevant 200-400 lines, not whole files

PLAN

Atomic steps in dependency order

WEB CONTEXT

Docs + Stack Overflow fetched and summarised

RISK FLAGS

What might break, what tests are needed

JOB META

Job ID, repo, priority, timestamp

The single hardest problem in this system. You can't dump an entire codebase into a 7B model's context. The answer is a 3-layer funnel — each layer narrows the search until only the relevant 200–400 lines remain.

Semantic Index Search

Fast, broad — finds candidate files

Before the agent reads anything, the entire codebase is pre-indexed into ChromaDB using nomic-embed-text embeddings. Each chunk is ~40 lines of code with file path + function name metadata.

When an issue comes in, the agent converts the issue text into an embedding and does a similarity search. Returns the top 10–15 most semantically relevant chunks in milliseconds.

Input: "target is wrong" → Embedding search → Returns: shader.go, renderer.go, framebuffer.go

↓ narrows from whole repo to ~15 candidate files

AST Relationship Traversal

Smart, structural — traces the thread

Tree-sitter parses the candidate files and builds a lightweight call graph. The agent can now traverse relationships: "what calls this function?", "what does this function import?", "where is this variable defined?"

This is how a senior developer reads code — they don't read files top to bottom, they follow the thread of execution. The agent does exactly the same.

shader.go → calls setFramebuffer() → defined in renderer.go line 89 → that's where the bug is

↓ narrows from 15 files to 2–4 specific functions

Targeted Chunk Extraction

Precise, minimal — only what the LLM needs

Only the identified functions and their immediate context (±20 lines) are extracted and passed to the LLM. Never a whole file. Never more than ~400 lines total in context.

This keeps the LLM's context window clean, focused, and under budget — even on a 7B model with a 8K context window. The LLM gets exactly what it needs to understand and fix the problem.

Final context sent to LLM: renderer.go lines 80–130 + shader.go lines 138–155 = 67 lines total

↓

One-time Index Build

Happens before any job runs — not during

The ChromaDB index is built once when you first point the system at a repo. After that it's updated incrementally — only re-embeds files that changed since the last git commit. A watchdog monitors file changes and triggers a re-index automatically.

1000-file repo → ~2 min initial index → then instant incremental updates on change

Key Design Decisions

Why not just dump the whole codebase into context?

A 7B model has an 8K–32K token context window. A real codebase is millions of tokens. You'd hit the limit on the first file. The 3-layer funnel gets the agent to the right code in under 400 tokens of code context — leaving room for the plan, web docs, and output.

Why web search during the Understand stage, not just the Plan stage?

Because sometimes the agent can't even form a correct understanding without knowing what a library does. If the issue says "the gRPC deadline is wrong" and the model doesn't know gRPC's deadline API, understanding fails. Web search in Stage 1 fixes this.

Why the 70% confidence threshold before planning?

If the agent doesn't understand the issue well enough, any plan it makes will be wrong — and the Coder will implement the wrong fix. One question to the user at this point is far cheaper than a failed build cycle.

Why separate Understand and Plan into two distinct stages?

They have different jobs. Understanding is about reading and comprehending. Planning is about deciding and structuring. Mixing them causes the agent to plan before it fully understands — which is how humans write bad code too.

Why does the Planner use the 32B server model?

Planning requires multi-step reasoning, dependency ordering, and risk assessment. This is where model size matters most. The 7B handles code editing well — but architectural decisions need the bigger brain.

Why chunk by function, not by line count?

A function is a unit of logic. Splitting mid-function destroys meaning. Tree-sitter extracts whole functions as chunks — so the LLM always gets complete, coherent logic, not half a loop or a function missing its return statement.