From Epic to Merge: An End-to-End Workflow for Software Development with AI Agents

Coding agents are becoming increasingly capable of implementing individual software tasks. Give an agent a repository, a clear issue, and enough context, and it can often inspect the codebase, modify files, write tests, and produce a working implementation. The harder problem starts one level above that. What happens when we need to implement an entire feature consisting of ten related tasks? Some can run in parallel, some depend on others, some require architectural decisions, and some touch areas where autonomous changes should not be allowed. At that point, the challenge is no longer simply: Can an AI agent write the code? The more useful question becomes: How do we transform a software initiative into units of work that agents can execute, validate, review, and integrate safely? This article proposes an end-to-end workflow for implementing an Epic using AI agents while minimizing human intervention without removing the controls required by the risk of the changes.

Core architecture

The core architecture looks like this:

┌─────────────────────┐
│Epic                 │
│ intent + constraints│
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ Task dependency     │
│graph                │
└──────────┬──────────┘
           │
   ┌───────┴───────┐
   │               │
   ▼               ▼
┌──────────┐  ┌──────────┐
│Task A   │  │Task B   │
└──────┬───┘  └──────┬───┘
       │             │
       ▼             ▼
┌─────────┐   ┌─────────┐
│Planner │   │Planner │
└────┬────┘   └────┬────┘
     │             │
     ▼             ▼
┌─────────┐   ┌─────────┐
│Builder │   │Builder │
└────┬────┘   └────┬────┘
     │             │
     ▼             ▼
┌─────────┐   ┌─────────┐
│Reviewer │   │Reviewer │
└────┬────┘   └────┬────┘
     │             │
     └─────────────┬─────────────┘
                   ▼
┌─────────────────────┐
│Epic integration PR  │
│+ CI                 │
└──────────┬──────────┘
           │ human approval
           ▼
         main

The specific tools are interchangeable. The important part is the workflow.

The Epic as the source of intent

An Epic is useful because it gives the agents a shared description of what the system is supposed to accomplish. It should contain at least: the objective; the problem or product context; scope and explicit non-goals; requirements; tasks or user stories; acceptance criteria; dependencies and risks; success metrics. I would avoid treating the Epic as the absolute "source of truth." It is better understood as the central source of intent, requirements, and constraints for the initiative. The repository still contains the technical reality of the system. Existing APIs, schemas, architectural decisions, infrastructure, tests, and implementation constraints may reveal information that the Epic does not contain. This distinction becomes important once agents start making decisions. Imagine that a task only says: Add retry support to payment processing. An agent might reasonably ask: Which failures are retryable? How many retries are allowed? Should retries be synchronous or asynchronous? What happens to idempotency? Can the payment provider receive the same request twice? Is retrying outside the scope of a specific payment method? The task itself may not answer those questions. The Epic can provide the product and architectural boundaries required to answer them without duplicating the entire context in every issue. A practical implementation is to represent the Epic as a parent GitHub Issue and its tasks as sub-issues. This keeps the planning artifacts close to the code and allows issues, pull requests, commits, diagrams, files, and technical decisions to reference each other.

Task granularity matters more than prompt count

One of the easiest mistakes when building agentic development workflows is to hand a very large objective directly to a coding agent: Implement the entire billing Epic. A sufficiently capable model may still make progress, but the execution becomes difficult to reason about. The agent must simultaneously: discover the architecture; interpret requirements; make design decisions; modify multiple domains; keep dependencies consistent; validate behavior; understand what is in and out of scope. The problem is not simply context-window size. The problem is the number of decisions that must remain coherent throughout the execution. A better workflow reduces the complexity of each execution.

When is a task granular enough? A useful rule is: A task is sufficiently granular when it represents one coherent delivery, can be implemented and validated independently, and can produce a pull request that can be understood, tested, and reverted without relying on undeclared changes. Task size should therefore not be measured primarily by lines of code or number of files. The more important property is cohesion. For example, adding a field to an API may require modifying: database schema ↓ domain entity ↓ service ↓ API endpoint ↓ tests. That can still be one coherent task. Several layers are affected, but they all implement the same vertical capability. By contrast, a change touching only three files may still be too broad if it combines: authentication + billing rules + event processing + infrastructure changes. The useful questions are therefore: Does the task have one observable result? Does it represent one coherent capability? Can it be validated independently? Are major architectural decisions already resolved? Can the diff be reviewed as one logical unit? Can the change be reverted independently? The last question is particularly useful: Can a reviewer understand and validate this diff as a single logical change? If the answer is no, the task probably needs further decomposition.

Separate investigation from implementation

Tasks become especially dangerous when uncertainty and implementation are mixed together. Consider: Choose an asynchronous processing architecture and implement it. This contains at least two fundamentally different types of work: deciding what architecture should exist; implementing that architecture. A better decomposition could be: Task 1 - Investigate asynchronous processing alternatives; Task 2 - Record the architectural decision; Task 3 - Implement the event producer; Task 4 - Implement the event consumer. The first tasks reduce uncertainty. The later tasks execute against a decision that already exists. This distinction also makes agent behavior easier to control. We can allow an agent to investigate broadly without implicitly granting it permission to modify the architecture.

A readiness check before implementation

Before a task reaches a Builder, the workflow should verify that it is actually ready to be implemented. A practical checklist is:

• [ ] There is one clearly defined outcome.
• [ ] Scope and non-goals are explicit.
• [ ] Acceptance criteria are verifiable.
• [ ] Dependencies are declared.
• [ ] No major architectural decision remains unresolved.
• [ ] The change represents a coherent capability.
• [ ] There is an objective validation strategy.
• [ ] The change can produce an independent pull request.
• [ ] The change can be reverted without removing unrelated work.
• [ ] The expected diff is reasonably bounded or its size is justified.

These do not need to become rigid numerical rules. A 2,000-line generated schema migration may be simpler than a 100-line authentication change. Cohesion, independence, and verifiability matter more than raw size.

One task, one isolated execution environment

Once tasks can run concurrently, filesystem isolation becomes necessary. A simple strategy is:

Epic
│
├── integration/epic-payments
│
├── task/payment-retry
│   └── worktree A
│
├── task/payment-webhook
│   └── worktree B
│
└── task/payment-events
    └── worktree C

Each Builder receives: its own Git branch; its own Git worktree or container; the context package for the current task; the relevant validation commands. This prevents two agents from directly modifying the same working directory. It does not, however, eliminate integration conflicts. Two isolated agents can still independently modify the same API, data model, or subsystem. Their worktrees are isolated operationally, but their changes may conflict semantically when integrated. The orchestrator must therefore understand task dependencies and integration order.

Model task dependencies explicitly

An Epic should not be treated as a flat task list. It is better represented as a dependency graph. For example:

┌───────────────┐
│ Add DB schema │
└───────┬───────┘
        │
┌───────┴───────┐
▼               ▼
┌────────────────┐ ┌────────────────┐
│ Write producer │ │ Create API     │
└───────┬────────┘ └───────┬────────┘
        ││                │
        ▼                ▼
┌────────────────┐
│ Write consumer │
└───────┬────────┘
        │
└──────────┬─────────┘
           ▼
┌────────────────┐
│ Integration    │
│ validation     │
└────────────────┘

A task can then have explicit metadata such as:

id : payment-consumer
blocked_by : - payment-schema
             - payment-producer

The orchestrator can execute independent nodes concurrently while waiting for their dependencies. This is significantly safer than telling several agents to work through the Epic and hoping they discover the correct order themselves.

Planner, Builder, and Reviewer

The workflow uses three main roles.

Planner

The Planner investigates before implementation. Its responsibilities include: inspecting the relevant codebase; identifying affected components; checking dependencies; identifying risks; proposing an implementation approach; defining validation steps; detecting whether the task should be split. The Planner should not modify production files during this phase. Its output should be an execution plan, not an implementation. A typical result might look like:

Affected modules:
- payments/service.ts
- payments/repository.ts
- payments/service.test.ts

Implementation:
1. Add retry classification for transient provider errors.
2. Add bounded exponential retry behavior.
3. Preserve idempotency key across attempts.
4. Add tests for retryable and non-retryable failures.

Validation:
- unit test suite
- payment integration tests
- lint
- typecheck

Risk:
- ensure declined payments are never retried

That output becomes part of the Builder's context.

Builder

The Builder executes the approved task. Its responsibilities are intentionally narrower: implement the planned change; update or create tests; run the required validations; commit the changes; open or update the pull request. The Builder should not silently redefine acceptance criteria or expand scope because it discovered something interesting during implementation. If implementation reveals a significant architectural issue, the correct action is usually to escalate the finding back to the orchestrator.

Reviewer

The Reviewer evaluates the result independently. It should inspect: the actual diff; the acceptance criteria; tests; validation output; architectural constraints; possible regressions. The review should be based on the expected behavior, not merely on the Builder's explanation of what it implemented. That distinction matters because the Builder and Reviewer may otherwise share the same incorrect assumption. The Reviewer should return concrete findings such as:

BLOCKING Retry logic also retries PaymentDeclinedError.
Acceptance criterion: Only transient provider failures may be retried.
payments/service.ts:87

Instead of: The implementation doesn't look quite right. Objective findings make automated correction loops possible.

Internal and external orchestration

There are two broad ways to coordinate the agents.

Internal orchestration

A primary agent delegates work through a native multi-agent runtime. Conceptually:

main agent
├── planner agent
├── builder agent
└── reviewer agent

The runtime manages the child executions and returns their results to the parent. This is useful when delegation is closely tied to the reasoning process of the primary agent.

External orchestration

A separate process controls independent agent executions. For example:

orchestrator
├── agent process -- task A
├── agent process -- task B
└── agent process -- review A

The executions communicate through structured output, files, Git, APIs, or another durable mechanism. External orchestration is particularly useful when we need: deterministic workflows; separate worktrees or containers; explicit concurrency; retries; timeouts; task queues; persistent execution state; provider-independent agents. The architecture described in this article favors external orchestration for the main workflow while still allowing individual agents to use internal subagents when useful.

Give each task only the context it needs

The Epic contains global information. That does not mean every agent should receive the entire Epic, every previous conversation, and every implementation log. Instead, the orchestrator should build a task context package. For example:

epic:
  objective: Add asynchronous invoice processing
  constraints:
    - existing synchronous API must remain compatible
task:
  id: invoice-event-producer
  objective: Publish an event after invoice creation
  acceptance_criteria:
    - exactly one event is emitted after a successful transaction
    - failed transactions must not emit events
  dependencies:
    completed:
      - invoice-event-schema
  architecture:
    - ADR-014-event-bus.md
  relevant_files:
    - src/invoices/service.ts
    - src/events/publisher.ts
  validation:
    - npm test -- invoices
    - npm run typecheck
  instructions:
    - AGENTS.md

The pipeline becomes: Epic ↓ context selection ↓ task-specific context ↓ isolated execution ↓ validated result ↓ Epic integration. Long context windows are useful, but they should be treated as available capacity rather than a target to fill. More context is not automatically better context. Excessive context can introduce: obsolete information; conflicting instructions; irrelevant implementation details; old architectural assumptions; competing objectives. Context engineering is therefore part of orchestration. The question is not: How much information can the model receive? It is: What is the minimum sufficient context required to make this decision correctly?

Define autonomy as a risk policy

Reducing human intervention does not mean giving agents unrestricted permissions. The workflow should define which actions are safe to. (The original text ends here; preserve as given.)