DEV Community: Rafael

How JavaScript Is Defined: From ECMAScript to Array.prototype.map

Rafael — Fri, 02 Oct 2026 21:18:51 +0000

We use JavaScript every day through syntax such as:

const numbers = [1, 2, 3];

const doubled = numbers.map(number => number * 2);

We know what map() does, but there is a more interesting question underneath:

Who decided that map() should behave this way?

Why does it skip empty array slots? Why does its callback receive the value, index, and array? Why can Array.prototype.map even be used with objects that are not arrays?

The answers are not specific to Chrome, Firefox, or Node.js. They come from the formal definition of the JavaScript language.

To understand that, we need to go back a little.

From JavaScript to ECMAScript

JavaScript was created by Brendan Eich at Netscape in the 1990s and first appeared in Netscape Navigator. Microsoft later introduced its own related implementation, called JScript.

This created an important problem. If different companies could independently decide how the language worked, code written for one browser could behave differently in another.

A common definition of the language was needed.

Standardization work started at Ecma International in November 1996, and the first edition of the ECMAScript standard was adopted in June 1997.

Ecma International is a standards organization. Inside it, different technical committees are responsible for different technologies. The committee responsible for JavaScript's standardized language is TC39, or Technical Committee 39.

So we can start building the relationship:

Ecma International → TC39 → ECMAScript specification

TC39 discusses and develops changes to the language. New features go through a proposal process before becoming part of the standard.

But where does ECMA-262 fit into this?

ECMA-262, ECMAScript, and JavaScript

ECMA-262 is the number of the Ecma standard that defines the ECMAScript language.

Its name is:

ECMAScript Language Specification

So these terms describe different things:

Term	What it is
Ecma International	Standards organization
TC39	Technical committee responsible for ECMAScript
ECMA-262	Standard document that defines ECMAScript
ECMAScript	Programming language specification defined by ECMA-262
JavaScript	Programming language based on and implementing the ECMAScript specification

ECMA-262 is periodically published in new editions.

For example, the current published standard is ECMA-262, 17th Edition, which defines ECMAScript 2026.

Term	Meaning
ECMA-262	The standard identifier
17th Edition	The edition of the ECMA-262 standard
ECMAScript 2026	The ECMAScript version defined by that edition

The 17th edition was published in June 2026 and defines ECMAScript 2026.

The number 262 is therefore not a JavaScript version.

Likewise ECMAScript 2026 does not mean "version 2026" in the traditional software-version sense. ECMAScript has followed an annual release model for several years.

There is also a living specification maintained by TC39. After the yearly snapshot is published, completed proposals and specification changes continue to be incorporated into the living document. As of October 2026, that document is already titled ECMAScript 2027.

This gives us the larger picture:

Now we can return to map().

Where does `map()` actually come from?

Consider:

const numbers = [10, 20, 30];

numbers.map(number => number * 2);

It may look as if numbers itself contains a map function.

It does not.

Object.hasOwn(numbers, "map");
// false

Arrays inherit that method through their prototype chain:

numbers → Array.prototype → Object.prototype → null

And:

numbers.map === Array.prototype.map;
// true

So when we write:

numbers.map(callback);

JavaScript finds map on Array.prototype and calls it with numbers as its this value.

Conceptually:

Array.prototype.map.call(numbers, callback);

This is where the ECMAScript definition of Array.prototype.map becomes relevant.

Reading the specification

The actual specification describes map() approximately like this:

1. Let O be ? ToObject(this value).
2. Let len be ? LengthOfArrayLike(O).
3. If IsCallable(callback) is false, throw a TypeError.
4. Let A be ? ArraySpeciesCreate(O, len).
5. Let k be 0.
6. Repeat while k < len:
   a. Let Pk be ! ToString(𝔽(k)).
   b. Let kPresent be ? HasProperty(O, Pk).
   c. If kPresent is true:
      i.   Let kValue be ? Get(O, Pk).
      ii.  Let mappedValue be ?
           Call(callback, thisArg, « kValue, 𝔽(k), O »).
      iii. Perform ?
           CreateDataPropertyOrThrow(A, Pk, mappedValue).
   d. Set k to k + 1.
7. Return A.

It's defined in ECMAScript® 2026 Language Specification.

This is not JavaScript source code.

Operations such as ToObject, HasProperty, Get, and Call are called abstract operations. They are tools the specification uses to formally describe how JavaScript must behave.

Let's translate this algorithm gradually.

First, identify what is being mapped

The algorithm starts with:

Let O be ? ToObject(this value).

For:

numbers.map(callback);

this is numbers.

So, for our example:

O = numbers

The specification deliberately calls it O, meaning an object, rather than something like array.

That is because map() is more generic than it first appears. It can work with some non-array objects too.

Let len be ? LengthOfArrayLike(O).

For:

const numbers = [10, 20, 30];

we get:

len = 3

The algorithm now knows that it needs to consider positions 0, 1, and 2.

It then verifies that the callback is actually callable and creates the array that will contain the result.

We can approximate the beginning with:

const O = Object(this);
const len = O.length;

if (typeof callback !== "function") {
  throw new TypeError();
}

const A = new Array(len);

The real specification is more precise than this, but this is a useful mental model.

From an index to a property

Now the interesting part begins.

The algorithm initializes:

k = 0

and repeats until:

k < len

But it does not simply access:

O[k];

The specification first creates something called Pk:

Let Pk be ! ToString(𝔽(k)).

If:

k = 1

then conceptually:

k
↓
1

ToString(...)
↓
"1"

Pk = "1"

Why convert the index to a string?

Because an Array is also an Object.

Consider:

const arr = ["A", "B", "C"];

At the language level, we can think about its indexed properties like this:

"0" → "A"
"1" → "B"
"2" → "C"

This is why:

arr[1] === arr["1"];
// true

Normal JavaScript property keys are strings or symbols. The specification therefore turns the numeric position used by the algorithm into the property key that will be used to inspect the object.

This does not mean that a JavaScript engine must physically store "1" as a string somewhere in memory.

The specification defines behavior. The implementation is free to optimize that behavior internally.

Does that property actually exist?

After obtaining Pk, the algorithm asks:

Let kPresent be ? HasProperty(O, Pk).

A useful approximation is:

const kPresent = Pk in O;

This distinction is important because JavaScript arrays can contain holes.

Compare:

const a = [10, undefined, 30];

const b = [10, , 30];

Both produce:

a[1]; // undefined
b[1]; // undefined

But structurally they are different:

1 in a;
// true

1 in b;
// false

In a, the property exists and its value is undefined.

In b, the property does not exist.

This is why map() cannot simply retrieve the value and check whether it is undefined.

It first asks:

Does property "1" exist?

Only if the answer is true does it call the callback.

That explains this behavior:

[10, , 30].map(value => {
  console.log(value);
});

Output:

10
30

The callback is never executed for the missing property.

`HasProperty` and the prototype chain

There is another subtle detail.

HasProperty does not only inspect properties directly owned by the array.

It also considers the prototype chain.

That makes it closer to:

"1" in arr

than:

Object.hasOwn(arr, "1")

For example:

const arr = new Array(3);

Array.prototype[1] = 100;

The array itself still does not own "1":

Object.hasOwn(arr, "1");
// false

But:

"1" in arr;
// true

because JavaScript can find it here:

arr
 │
 │ "1"? no
 ▼
Array.prototype
 │
 │ "1"? yes
 └── 100

Therefore:

arr[1];
// 100

And because map() uses HasProperty, this also affects it:

arr.map(value => {
  console.log(value);
});

The callback receives 100.

This is an intentionally unusual example, and modifying native prototypes like this should generally be avoided. But it exposes how closely map() interacts with JavaScript's object model.

Reading and mapping the value

Once the property is known to exist, the specification performs:

Get(O, Pk)

For:

const numbers = [10, 20, 30];

when:

Pk = "1"

we get:

Get(numbers, "1")
→ 20

That becomes kValue.

The specification then calls:

Call(callback, thisArg, « kValue, 𝔽(k), O »)

Which can be understood approximately as:

callback.call(
  thisArg,
  kValue,
  k,
  O
);

This also explains where the familiar callback arguments come from:

numbers.map((value, index, array) => {
  // ...
});

They directly correspond to:

kValue → value
k      → index
O      → array

If our callback is:

value => value * 2

then:

kValue = 20

callback(20, 1, numbers)
↓
40

The specification calls that result:

mappedValue

Finally, it creates the corresponding property in the result array:

CreateDataPropertyOrThrow(A, Pk, mappedValue)

which we can roughly imagine as:

A[Pk] = mappedValue;

Then k is incremented, and the process repeats.

Putting the pieces together

A simplified version of everything we have just read would look like this:

function simplifiedMap(callback, thisArg) {
  const O = Object(this);
  const len = O.length;

  if (typeof callback !== "function") {
    throw new TypeError();
  }

  const A = new Array(len);

  for (let k = 0; k < len; k++) {
    const Pk = String(k);

    if (Pk in O) {
      const kValue = O[Pk];

      const mappedValue = callback.call(
        thisArg,
        kValue,
        k,
        O
      );

      A[Pk] = mappedValue;
    }
  }

  return A;
}

This is not the actual implementation used by V8 or another JavaScript engine, nor is it a completely faithful reimplementation of every ECMAScript abstract operation.

But it exposes the logic behind the specification.

For:

const numbers = [10, 20];

numbers.map(value => value * 2);

we can now follow the first iteration:

k = 0
  ↓
Pk = "0"
  ↓
HasProperty(numbers, "0")
  ↓
 true
  ↓
Get(numbers, "0")
  ↓
 10
  ↓
callback(10, 0, numbers)
  ↓
 20
  ↓
result["0"] = 20

Then:

k = 1
  ↓
Pk = "1"
  ↓
HasProperty(numbers, "1")
  ↓
 true
  ↓
Get(numbers, "1")
  ↓
 20
  ↓
callback(20, 1, numbers)
  ↓
 40
  ↓
result["1"] = 40

And finally:

[20, 40]

What initially looked like a simple loop is actually built on top of several fundamental parts of JavaScript: objects, property keys, prototype lookup, property existence, function calls, and array creation.

That is the value of reading ECMA-262. It moves us from knowing how to use JavaScript to understanding why JavaScript behaves the way it does.

AWS Networking Fundamentals: VPCs, Subnets, Routing, IGWs, NACLs, and Security Groups

Rafael — Mon, 28 Sep 2026 13:44:58 +0000

In this post, we'll explore some of the fundamental concepts behind AWS networking and understand how they work together.

The goal is to build a clear mental model of how network communication works inside AWS. By the end of this post, you should be able to explain the role of components such as Regions, Availability Zones (AZs), VPCs, Subnets, Route Tables, Internet Gateways (IGWs), Network ACLs (NACLs), and Security Groups (SGs).

At its core, networking is about enabling devices and resources to communicate and exchange data. In AWS, the same principle applies, but the network is defined and managed through cloud infrastructure.

Consider a simple example: an EC2 instance hosting an application that needs to be accessible from the internet. For a user to reach that instance, AWS needs a valid network path and a set of rules controlling how traffic moves through the infrastructure.

Understanding these components and how they interact provides the foundation for designing and troubleshooting AWS networks.

Documentation often uses abbreviations instead of full names. To become more familiar with this terminology, we'll use the abbreviations introduced throughout this post, such as AZ, VPC, IGW, NACL, and SG.

Region and Availability Zone

An AWS Region is a geographic area where AWS operates its cloud infrastructure.

Each Region is independent from the others and contains multiple Availability Zones (AZs). When you create resources in AWS, one of the first decisions you make is which Region they should belong to. For example, us-east-1 represents the US East (N. Virginia) Region, while sa-east-1 represents South America (São Paulo).

A useful way to visualize the hierarchy is:
AWS Global Infrastructure → Region → Availability Zones

Choosing a Region can affect factors such as latency, cost, service availability, and data residency requirements.

Something to keep in mind is that the closest Region is not always the best choice. When selecting a Region, you should evaluate trade-offs such as latency, cost, service availability, capacity, and reliability requirements.

For example, even if your users are located in South America, you might choose a Region in North America if the additional latency is acceptable and that Region provides better pricing, service availability, or other advantages for your workload.

VPC

Amazon VPC allows you to create a logically isolated virtual network within an AWS Region, where you can launch and manage AWS resources.

Inside a VPC, you define how your network should behave, including its IP address range, subnets, routing rules, internet connectivity, and network security. Resources such as EC2 instances, databases, and load balancers can then be deployed inside this network according to the level of connectivity and isolation they require.

Amazon VPC allows you to create a logically isolated virtual network within an AWS Region, where you can launch and manage AWS resources. Also, a VPC can span multiple Availability Zones.

In practice, the VPC acts as the main network boundary for your AWS resources.

Subnets

Subnets are used to divide a VPC into smaller network segments and organize resources according to their networking requirements.

Each subnet belongs to a single AZ. This allows you to distribute resources across isolated locations for better availability and fault tolerance.

A subnet can be designed as public or private, depending on how its routing is configured.

A private subnet is commonly used for resources that should not be directly accessible from the internet, such as databases containing customer or transactional data.

A public subnet is commonly used for resources that need direct internet connectivity, such as public-facing web servers or load balancers.

What determines whether a subnet is public or private is mainly its routing configuration.

A public subnet has a route to an Internet Gateway (IGW), which provides a path between the subnet and the internet. However, this does not automatically make every resource inside the subnet publicly accessible. For example, an EC2 instance also needs a public IP address and appropriate security rules to communicate directly with the internet.

A private subnet does not have a direct route to an IGW. It can still access the internet for outbound traffic through a NAT Gateway.

So, in practice, the distinction between public and private subnets comes primarily from how their route tables are configured.

It is very common to place compute resources, such as EC2 instances or load balancers, in a public subnet and databases in a private subnet.

In this architecture, users can reach the public-facing compute layer from the internet, while the database remains inaccessible directly from the internet. The database can still be reached by the application through the VPC's private network.

Internet Gateway

An Internet Gateway (IGW) is a VPC component that enables communication between resources inside the VPC and the internet.

An IGW is attached to a VPC and can be used as a target in a route table. For example:

0.0.0.0/0 → Internet Gateway

This route provides a path from the subnet to the internet. However, a resource such as an EC2 instance also needs a public IP address and appropriate security rules to communicate directly with the internet.

Route Table

A Route Table defines where network traffic from a subnet should be sent.

Each route contains two main pieces of information:

Field	Purpose
Destination	The IP range the traffic is trying to reach
Target	Where AWS should send that traffic

For example:

Destination	Target
`10.0.0.0/16`	`local`
`0.0.0.0/0`	Internet Gateway

The local route allows resources inside the VPC to communicate with each other. AWS automatically adds this route to every route table.

A route such as:

0.0.0.0/0 → Internet Gateway

means that traffic destined for addresses outside the VPC can be sent to the internet.

Each subnet must be associated with a route table. A route table can be associated with multiple subnets, but each subnet uses only one route table at a time. If no explicit association is defined, the subnet automatically uses the VPC's main route table.

Route tables are also what primarily distinguish public and private subnets:

A public subnet has a route to an Internet Gateway (IGW).
A private subnet does not have a direct route to an IGW. It may instead route outbound internet traffic through a NAT Gateway.

When multiple routes could match a destination, AWS uses the most specific matching route.

In short, a route table answers a simple question:

"Where should this packet go next?"

Network ACLs

A Network ACL (NACL) is a virtual firewall that controls inbound and outbound traffic at the subnet level.

You can think of it like passport control at an airport. Travelers represent network packets, while the passport control officer represents the NACL. Every time a traveler enters or leaves the country, their credentials are checked. Similarly, a NACL evaluates traffic whenever it enters or leaves a subnet.

NACLs are stateless, meaning inbound and outbound traffic are evaluated independently. If you allow traffic in one direction, you must also explicitly allow the corresponding traffic in the opposite direction.

The default behavior of a Network ACL (NACL) depends on whether it is the default NACL or a custom one.

NACL type	Default behavior
Default NACL	Allow all inbound and outbound traffic
Custom NACL	Deny all inbound and outbound traffic

Because NACLs are stateless, inbound and outbound traffic must be allowed independently.

NACL rules are evaluated in numerical order, starting with the lowest rule number. AWS stops evaluating rules as soon as it finds the first matching rule.

NACLs do not distinguish between requests and responses. They only evaluate whether a packet is entering or leaving the subnet. Because NACLs are stateless, both directions must be explicitly allowed. This applies both to response traffic and to new connections initiated by resources inside the subnet.

Security Groups

A Security Group (SG) is a virtual firewall attached to specific AWS resources, such as EC2 instances. While a NACL controls traffic at the subnet level, an SG controls traffic at the resource level.

Security Groups define which traffic is allowed to enter or leave a resource through inbound and outbound rules.

By default, a newly created SG:

denies all inbound traffic;
allows all outbound traffic.

SGs only support allow rules. Any traffic that does not match an allowed rule is implicitly denied.

One of the most important characteristics of Security Groups is that they are stateful. This means AWS keeps track of established connections.

For example, suppose an EC2 instance allows inbound HTTPS traffic on port 443:

Client → EC2
1.2.3.4:52000 → 10.0.1.10:443

If this connection is allowed by the SG, the response is automatically allowed:

EC2 → Client
10.0.1.10:443 → 1.2.3.4:52000

You do not need to create a separate outbound rule specifically for that response.

The same principle applies to connections initiated by the EC2 instance: if the outbound connection is allowed, the corresponding response traffic is automatically permitted.

By default, a new Security Group (SG) denies all inbound traffic and allows all outbound traffic.

Direction	Default behavior
Inbound	Deny all
Outbound	Allow all

If all outbound rules are removed, new outbound connections are denied. Because SGs are stateful, response traffic for an already allowed connection is still permitted automatically.

Differences between SGs and NACLs

Feature	Security Group (SG)	Network ACL (NACL)
Scope	Resource level	Subnet level
Association	Attached to resources such as EC2 instances	Associated with subnets
State	Stateful	Stateless
Rules	Allow rules only	Allow and deny rules
Rule evaluation	All rules are evaluated together	Rules are evaluated in numerical order
Return traffic	Automatically allowed for an established connection	Must be explicitly allowed in the opposite direction
Inbound traffic	Controlled by inbound rules	Controlled by inbound rules
Outbound traffic	Controlled by outbound rules	Controlled by outbound rules
Default behavior	New SGs deny inbound and allow outbound traffic	Default NACL allows all traffic; custom NACLs deny all traffic until rules are added
Typical use	Fine-grained protection of individual resources	Broad traffic control across an entire subnet
Best suited for	Defining which resources or clients can communicate with a workload	Subnet-wide restrictions, explicit deny rules, and additional network filtering

In short: use Security Groups as the primary resource-level firewall, and use NACLs when you need subnet-level controls or explicit deny rules.

AI Subagents orchestration are now reliable

Rafael — Fri, 25 Sep 2026 14:26:13 +0000

Since the end of 2025, I've been thinking a lot about how to improve my development workflow with AI agents. Like many developers, I started using agents in their simplest form: manually. One agent, one task, a lot of supervision, and a lot of interaction to keep the work moving in the right direction. As I became more comfortable with these tools, understanding how to communicate with them, how much context to provide, and when to intervene, the main question started to change. It was no longer just about how AI could help me write code, but how much of my development workflow I could delegate to AI without losing control or quality.

My First Attempts at Agent Orchestration

I previously wrote about my first orchestration design using subagents. The design itself was reasonably solid, even though there was still a lot to improve, but getting consistent results from it was difficult. The parent agent was not always reliable when coordinating subagents. For example, after spawning a subagent, it would sometimes continue doing unrelated work instead of waiting for the delegated task. In other cases, it would repeatedly poll the subagent for results or start working on something that had already been delegated. That created duplicated work, unnecessary context usage, and unpredictable behavior.

This wasn't only a prompt-design problem. Part of the issue seemed to come from limitations in the agent harness or model behavior itself, and I even opened an issue in the openai/codex repository documenting one of these cases.

What Changed

Recently, however, this has started to change. For my workflow, Codex subagent orchestration has become reliable enough that I can actually design development processes around it. The parent agent can delegate a well-scoped task and wait when waiting makes sense, while I can continue interacting with the main thread, inspect what the subagents are doing, and redirect the work when necessary.

That may sound like a relatively small improvement, but I don't think it is. Once delegation itself becomes dependable, the problem changes. You can start thinking about which tasks should be delegated, which can run in parallel, which depend on previous results, what context each agent actually needs, and how the parent agent should integrate everything afterward. At that point, the workflow starts to look much closer to software engineering than simply asking a model to "implement this feature."

Planning Before Orchestration

This is also where planning becomes much more important. The fact that an agent can spawn several subagents does not mean that it should. Before delegating anything, I try to understand the feature and break it into tasks with clear boundaries, expected outputs, relevant constraints, and known dependencies. Some tasks should run sequentially, while others can happen in parallel.

One agent may investigate an unfamiliar part of the codebase, another may work on tests, another may review an implementation, and the parent agent can later combine those results into the next step. The important part is not the number of agents. It is whether the work has been decomposed correctly.

Repository-level context also becomes much more valuable in this model. Good AGENTS.md instructions, architecture documentation, project conventions, reusable skills, tests, strict type requirements, and other forms of persistent context give future agents a foundation they can reuse. Without that foundation, every new agent has to rediscover the project. With it, agents can enter the repository with a much better understanding of how the system works and how they are expected to behave. In practice, the quality of the orchestration depends not only on the model or the harness, but also on how well the project itself is prepared for agents.

AI Is Not Only About Building Faster

Another thing I've been thinking about is how we measure the value of AI in software development. Most discussions focus heavily on speed: how quickly a feature can be built, how much code an agent can generate, or how fast something can be shipped. I don't think that is the most interesting part.

Before working this way, I worked professionally at a software house where I shipped thousands of production commits. Like many teams working under real client deadlines, we constantly had to make trade-offs. A feature needed to go live, another task was already waiting, and the client needed the change. Because of that, work that we knew would improve the project could easily be postponed: more automated tests, broader integration coverage, additional edge-case validation, deeper refactoring, better documentation, or simply more polish. The problem was not that these things were unimportant. The problem was time.

AI Changes the Economics of Quality

This is where I think AI changes something important. It reduces the cost of doing some engineering work that was previously expensive in terms of developer time. An agent can investigate edge cases while another works on implementation. A subagent can expand tests without forcing the parent agent to carry every implementation detail in its context. Another agent can review a change against the original requirements or inspect an unfamiliar part of the codebase before any code is changed.

None of this removes the need for engineering judgment, and it does not guarantee quality, but it makes some work much cheaper to perform.

That is also why I don't care if I sometimes spend hours or even days working with AI on the same feature. If the result has better architecture, stronger tests, fewer edge cases, better documentation, and a more polished implementation, then the value is not that AI helped me finish the feature in twenty minutes. The value is that AI allowed me to spend engineering effort differently. For me, AI is becoming less about building faster and more about making it practical to build with more quality.

Anyone who has spent enough time developing with AI agents also knows that generating something that works is becoming relatively easy. Generating something that is consistent with the existing architecture, maintainable, properly tested, understandable by another developer, aligned with the product requirements, and free from generic AI defaults is a different problem.

This is especially visible in frontend work, where agents can easily converge toward similar layouts and visual patterns without strong direction, but the same problem exists in backend development. Agents can introduce unnecessary abstractions, inconsistent naming, duplicated logic, weak boundaries, or solutions that technically work but do not really fit the architecture of the system. Better models help, but the workflow around them still matters just as much. Planning matters, context matters, task boundaries matter, and review still matters.

What This Looks Like in Practice

I've been applying these ideas while building my public project TowelBooks and while contributing to different projects through my GitHub. A large amount of that work has been done with relatively low-cost models such as GPT-5.6 Luna, which is another part of this shift that I find interesting.

Agentic workflows do not necessarily require using the most expensive model for every step. A stronger model can be useful for architecture, planning, difficult reasoning, or ambiguous problems, while smaller implementation, investigation, testing, and review tasks can often be delegated to cheaper models once the work has been decomposed properly. Good task decomposition can therefore improve reliability and cost efficiency at the same time.

Final Thoughts

What interests me most about this direction is not the idea of an agent generating an entire application from one prompt. It is the possibility of building a development workflow where we can decompose engineering problems, delegate focused pieces of work, execute independent tasks in parallel, preserve context boundaries, review intermediate results, and coordinate everything through a parent agent.

The developer still owns the architecture, defines the constraints, decides which trade-offs are acceptable, and remains responsible for the final result. But the amount of engineering work that can happen around those decisions is increasing quickly.

You may have noticed that I've mentioned Codex a lot throughout this article. That's simply because it has become my primary AI development tool. I've been particularly impressed by how quickly the agent experience has evolved. For my workflow, combining stronger models for planning and reasoning with lower-cost models for implementation and delegated tasks has made multi-agent development much more practical.

The most interesting part, though, is not any single model. It is that the surrounding tooling is finally becoming reliable enough for these workflows to move from experiments into actual software development processes.

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

Rafael — Mon, 21 Sep 2026 21:55:40 +0000

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.

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 perform automatically and which require approval.

A possible policy is:

Autonomous

Agents may perform these operations inside their isolated task environment:

edit application code;
add or update tests;
run tests, linters, and static analysis;
create commits;
open pull requests;
apply Reviewer-requested fixes that remain within the approved scope.

Autonomous with additional validation

Changes in this category may proceed automatically only when specific validation rules succeed:

dependency updates;
non-destructive database migrations;
API contract changes;
shared configuration changes;
changes affecting multiple domains or services.

Human approval required

Examples include:

production deployments;
destructive migrations;
secret access or modification;
infrastructure mutations;
authentication or authorization changes;
billing operations;
irreversible data transformations;
final integration into the main branch.

These categories should not be universal constants.

A migration adding a nullable column may be routine in one system and dangerous in another with billions of rows.

The correct abstraction is therefore not a hardcoded list of actions.

It is a risk policy.

The complete implementation cycle

We can now put the pieces together.

1. Create the Epic

The human or product process defines:

objective
problem
scope
non-goals
requirements
acceptance criteria
risks
success metrics

At this stage, the emphasis is on what needs to be achieved, not exactly how every part will be implemented.

2. Decompose the Epic

A planning process converts the Epic into tasks.

Each task is checked for:

cohesion
independence
testability
reversibility
architectural uncertainty

If major design uncertainty exists, investigation tasks are created before implementation tasks.

3. Build the dependency graph

Dependencies between tasks are declared explicitly.

For example:

A ──► C ──► E
│
└──► D ──► E

B ───────► E

Tasks A and B can begin immediately.

C and D wait for A.

E waits for all upstream work.

The orchestrator now has enough information to determine safe parallelism.

4. Create the Epic integration branch

A branch is created from the current target branch:

main
  │
  └── epic/invoice-processing

Individual task branches are based on an appropriate integration state.

Long-running Epics should periodically synchronize with the target branch to avoid allowing the integration branch to drift too far from main.

5. Build a context package for the next task

The orchestrator selects only the information required for the task:

Epic summary
+ task description
+ acceptance criteria
+ architecture decisions
+ completed dependencies
+ relevant files
+ repository instructions
+ validation commands
+ risk constraints

This becomes the Planner's initial input.

6. Run the Planner

The Planner inspects the repository and produces a plan.

Possible outcomes are:

READY

NEEDS_SPLIT

BLOCKED_BY_ARCHITECTURE

BLOCKED_BY_DEPENDENCY

Only READY tasks proceed automatically.

This step acts as an important boundary between project planning and code generation.

7. Create an isolated Builder environment

The orchestrator creates:

task branch
+
Git worktree or container
+
task-specific context

For example:

worktrees/
├── payment-retry/
├── payment-webhook/
└── invoice-events/

Independent Builders can now execute concurrently without sharing the same filesystem.

8. Execute the Builder

The Builder receives:

task context
+
Planner result
+
repository instructions

It implements the change and runs the required validations.

The result should include structured information such as:

status: completed

commit: a814ed3

validation:
  unit_tests: passed
  integration_tests: passed
  lint: passed
  typecheck: passed

files_changed:
  - src/payments/service.ts
  - src/payments/service.test.ts

notes:
  - preserved existing idempotency behavior

The exact schema is not important.

Structured output is.

An orchestrator should not need to parse an essay to determine whether tests passed.

9. Open the task pull request

Each task produces a pull request targeting the Epic integration branch:

task/payment-retry
        │
        ▼
epic/payment-improvements
        │
        ▼
main

The task PR should remain independently reviewable.

CI runs again outside the Builder's local environment.

This gives us two independent validation layers:

Builder validation
        +
CI validation

10. Run the Reviewer

The Reviewer receives:

task requirements
+
acceptance criteria
+
diff
+
test results
+
relevant architecture constraints

It returns structured findings.

For example:

status: changes_requested

findings:
  - severity: blocking
    file: src/payments/service.ts
    line: 87
    reason: declined payments are being retried
    criterion: only transient failures may be retried

Or:

status: approved
findings: []

11. Run the correction loop

If the Reviewer finds a blocking problem:

Reviewer
   ↓
Builder
   ↓
validation
   ↓
Reviewer

The loop continues within predefined limits.

An important operational detail is that retries should not be infinite.

After a certain number of unsuccessful correction cycles, the task should be escalated.

For example:

attempt 1 → failed review
attempt 2 → failed review
attempt 3 → failed review
               ↓
        human escalation

Repeated failure is itself useful information. It may indicate that the task is poorly specified, incorrectly decomposed, or hiding an unresolved architectural problem.

12. Merge into the Epic integration branch

Once:

Builder validation = passed
CI = passed
Reviewer = approved

the task can be merged into the Epic branch according to the project's autonomy policy.

This may unblock downstream tasks in the dependency graph.

The orchestrator then schedules the newly available work.

13. Run Epic-level validation

Passing every task independently does not prove that the Epic works as a whole.

Once all required tasks are integrated, the workflow runs broader validation:

full test suite
integration tests
end-to-end tests
contract tests
migration checks
security checks
performance checks

The exact set depends on the project.

This stage catches problems that task-level validation cannot detect.

For example, two individually correct tasks may still implement incompatible assumptions.

14. Validate the Epic acceptance criteria

The final Reviewer evaluates the integrated result against the original Epic rather than individual tasks.

The question changes from:

Did we implement Task 7 correctly?

to:

Does the system now satisfy the outcome defined by the Epic?

This distinction is important.

A workflow can successfully complete every task and still fail to achieve the intended product behavior if the decomposition itself was incomplete.

15. Human approval and final merge

If the final integration satisfies the Epic criteria, the workflow produces an Epic pull request:

epic/payment-improvements
        │
        ▼
       main

This is an appropriate place for a human approval gate.

The human is no longer expected to manually implement or review every small code change.

Instead, human attention is concentrated where it has the highest value:

requirements
architecture
risk
exceptions
final integration

That is a more realistic interpretation of "human-in-the-loop" development than requiring a person to supervise every tool call made by an agent.

Choosing models by role

There is no requirement that every stage use the same model.

Different roles have different computational requirements.

The Planner may benefit from stronger reasoning because it needs to understand architecture and dependencies.

The Reviewer may need similar capability because it must identify subtle inconsistencies.

A Builder executing a very constrained change may not require the same model.

Conceptually:

Orchestrator ── high reasoning capability

Planner      ── high reasoning capability

Reviewer     ── high reasoning capability

Builder      ── selected according to task complexity

This also creates room for provider-independent workflows.

An orchestration layer could use OpenCode, Codex, Claude, or other coding-agent runtimes without fundamentally changing the architecture described here.

The model becomes an execution component rather than the workflow itself.

Measure the workflow

Once the process is structured, it can be measured.

Useful metrics include:

tokens consumed per task;
tokens consumed per agent role;
execution time per task;
total Epic execution time;
number of retries;
number of failed Builder attempts;
Reviewer findings;
CI failures;
tasks completed without human intervention;
human escalations;
cost per pull request;
cost per Epic.

These metrics should not be used only to minimize token usage.

They can help answer more useful questions.

For example:

Does adding a Planner reduce failed implementations?

Does a stronger Reviewer reduce integration defects?

Are certain task types consistently escalated?

At what task size does autonomous completion become unreliable?

Is parallel execution actually reducing lead time?

At that point, decisions about agents and models can be based on workflow performance rather than intuition.

The workflow as a state machine

Once everything above is explicit, the orchestration problem becomes surprisingly mechanical.

A task can move through states such as:

PENDING
   ↓
READY
   ↓
PLANNING
   ↓
BUILDING
   ↓
VALIDATING
   ↓
REVIEWING
   │
   ├── changes requested ──► BUILDING
   │
   ├── blocked ────────────► ESCALATED
   │
   └── approved
           ↓
        MERGED

The Epic has its own lifecycle:

PLANNING
   ↓
EXECUTING
   ↓
INTEGRATING
   ↓
VALIDATING
   ↓
AWAITING_APPROVAL
   ↓
COMPLETED

This is the point where AI-assisted software development starts looking less like a chat interface and more like a distributed software-delivery system.

And that is probably the more useful abstraction.

Final thoughts

The most interesting problem in AI-assisted software development is increasingly not code generation itself.

It is orchestration.

An autonomous development workflow needs to answer questions such as:

What should the agent work on?
What context should it receive?
Which work can happen in parallel?
Which decisions have already been made?
How should the implementation be validated?
Who reviews the result?
What happens when the Reviewer disagrees?
Which actions can happen automatically?
Where is human approval required?
How do independent changes become one coherent feature?

Better models will make individual executions more capable.

They will not eliminate the need to answer those questions.

A robust agentic development workflow therefore should not be designed around the assumption that a sufficiently powerful model can receive an entire project and simply "figure it out."

Instead, the system should reduce ambiguity before execution.

That means:

clear intent
+ coherent tasks
+ explicit dependencies
+ minimal relevant context
+ isolated execution
+ objective validation
+ independent review
+ risk-based autonomy
+ controlled integration

The objective is not to remove humans from software engineering.

It is to move human attention away from supervising routine implementation and toward the decisions where judgment, product context, architecture, and risk actually matter.

Once those boundaries are explicit, AI agents stop being isolated coding assistants and become components of a software delivery pipeline.

DEV Community: Rafael

How JavaScript Is Defined: From ECMAScript to Array.prototype.map

From JavaScript to ECMAScript

ECMA-262, ECMAScript, and JavaScript

Where does map() actually come from?

Reading the specification

First, identify what is being mapped

From an index to a property

Does that property actually exist?

HasProperty and the prototype chain

Reading and mapping the value

Putting the pieces together

AWS Networking Fundamentals: VPCs, Subnets, Routing, IGWs, NACLs, and Security Groups

Region and Availability Zone

VPC

Subnets

Internet Gateway

Route Table

Network ACLs

Security Groups

Differences between SGs and NACLs

AI Subagents orchestration are now reliable

My First Attempts at Agent Orchestration

What Changed

Planning Before Orchestration

AI Is Not Only About Building Faster

AI Changes the Economics of Quality

What This Looks Like in Practice

Final Thoughts

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

The Epic as the source of intent

Task granularity matters more than prompt count

When is a task granular enough?

Separate investigation from implementation

A readiness check before implementation

One task, one isolated execution environment

Model task dependencies explicitly

Planner, Builder, and Reviewer

Planner

Builder

Reviewer

Internal and external orchestration

Internal orchestration

External orchestration

Give each task only the context it needs

Define autonomy as a risk policy

Autonomous

Autonomous with additional validation

Human approval required

The complete implementation cycle

1. Create the Epic

2. Decompose the Epic

3. Build the dependency graph

4. Create the Epic integration branch

5. Build a context package for the next task

6. Run the Planner

7. Create an isolated Builder environment

8. Execute the Builder

9. Open the task pull request

10. Run the Reviewer

11. Run the correction loop

12. Merge into the Epic integration branch

13. Run Epic-level validation

14. Validate the Epic acceptance criteria

15. Human approval and final merge

Choosing models by role

Measure the workflow

The workflow as a state machine

Final thoughts

Where does `map()` actually come from?

`HasProperty` and the prototype chain