As engineering teams embrace agent harnesses, velocity is picking up, but only with the senior engineers. The junior engineers are struggling, and so are the agents. The reason is the same in both cases.
This matters because there are many possible feature workflows, but the architecture has a bias governed by product intent that exists as architectural constraints. Senior engineers carry that context. Junior engineers do not, and neither does the agent. We need an entity that represents it.
§1 — The Stack We Thought Was Enough
We built a proper agent ecosystem in our repository. We have a
copilot-instructions.md that loads architectural context
into every Copilot session. We have GitHub Actions workflows for build,
test, and deployment. We have an architecture agent and an orchestration
agent defined in .github/agents/. GitHub’s own analysis of
over 2,500 agent configuration files shows the most effective setups
cover six areas: commands, testing, project structure, coding style,
architecture, and workflow. We hit all six.
We also have Figma flows that document the UX. We have schemas. We have architecture decision records. By every published benchmark for agentic coding readiness, we were well-positioned.
And yet when a new feature required provisioning multiple resources across services, the agent produced perfectly valid, correctly layered code that had no idea how to participate in the capability it was supposed to enable.
§2 — What the Agent Could Not Tell Me
To illustrate: an API supporting a future mobile consumer needs two Auth0 flows, M2M and cookie-based. A PRD identifies the multiple consumers of the API. The architecture docs surface the prior integration commitments. Neither document alone produces the implementation decision. The agent builds correctly in isolation and misses the capability entirely. A senior engineer catches it. A junior engineer, or an unsupervised agent, does not.
The implementation decision, two Auth0 models motivated by prior integrations and a future consumer requirement, lives in neither the PRD nor the architecture docs. It lives in the conversation between the product owner and the architect. In human-paced development, a senior engineer sits in that conversation, carries the output in their head, and applies it at implementation time. In agentic development, that conversation has no artifact. Nothing is written down. Nothing is in context. The agent cannot know what was never recorded.
§3 — The Artifact We Were Missing
The fix is not a better agent. The fix is a missing artifact, written into the repository where the agent can reach it.
We call it the ./capacity-plan. It lives in the
repository alongside the code it governs. It is not a requirements
document and it is not architecture documentation; it is the synthesis of
both, written from the engineer’s point of view. When an engineer
produces a capacity plan, they are demonstrating in traceable prose that
they understand the product intent and the architectural constraints
which bound the implementation. That demonstration is the “conversation”
described in §2, made durable and placed in context.
A capacity plan entry for the Auth0 example is not long. It records the consumer surface (mobile app, future state), the prior M2M commitment, the session model the architecture requires, and the implementation decision which follows from those three facts together. Short. Durable. Versioned. In context for every agent session that touches that surface.
But a capacity plan alone solves only half the problem. The other half is the flow. Product intent does not originate at the PRD layer; it originates in market requirements which precede the PRD and constrain it. The full requirements chain is: market requirements document, which answers what the market needs and why; product requirements document, which answers what the product will do to satisfy that need; and system requirements specification, which answers how the system will implement those product behaviours. Each layer is a distinct artifact, each answers a distinct question, and each constrains the layer below it.
The capacity plan sits at the SRS layer. It is the engineer’s act of translating downward through that chain and recording the architectural reasoning at the point where product intent becomes code. Without the MRD-to-PRD-to-SRS chain made explicit, the capacity plan has no foundation. Without the capacity plan, the chain produces no implementation guidance the agent can consume.
With this structure in place, the agent has what a senior engineer had. The junior engineer has what they previously had to acquire through years of proximity to senior staff. The context that was formerly carried only in memory is now an artifact: reviewable, versioned, and transferable across every session, every engineer, and every agent that touches the codebase.