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.
What is killing us is the translation from product intent to implementable software requirements.
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 artfact. Nothing is written down. Nothing is in context. The agent cannot know what was never recorded.
§3 — The Spiral Model Shows the Real Problem
The Spiral model is worth revisiting here, not as a return to sequential development, but as a commitment-aware iterative model that makes something visible that every other lifecycle diagram hides: specification rigor scales with the radius. Inner rings tolerate ambiguity. Outer rings require full traceability. The commitment partition is the boundary where ambiguity stops being acceptable and documented requirements become the prerequisite for execution.
Each revolution of the spiral demands a tighter SRS than the previous
one before agents execute the next ring. The PRD-to-SRS translation is
not a one-time gate at project start. It recurs at every revolution
boundary. An agent that ignores ring position generates into a
detailed-design problem with a concept-level SRS. That is precisely what
happens when you point Copilot at a mature microservices architecture
with nothing but copilot-instructions.md and a ticket
description.
The Spiral also makes explicit a constraint the other models obscure: new capabilities introduced to an established architecture inherit the surface area rules of what they touch, regardless of their own maturity. A brand-new capability that touches an Auth0 integration, a Solid POD binding, or a multi-tenant data layer is not operating at the inner ring of the spiral just because it is new. It is operating at the outer ring of every service it depends on. Capability maturity crossed with architectural surface area is the two-dimensional constraint that determines what level of specification is required before an agent generates a single line of code.
Agents do not know which ring they are on. Without a capability manifest, they assume the innermost one.
§4 — The Translation Layer Nobody Builds
Every agent harness in production today, GitHub Copilot with
copilot-instructions.md, Claude Code with
CLAUDE.md, Cursor with .cursorrules, Codex
with AGENTS.md, converges on the same structural approach:
a markdown file that tells the agent how to operate in your repository.
That file carries coding conventions, testing frameworks, and project
structure. It gives the agent everything it needs to execute correctly
within a known capability at a known ring position.
Not one of those files tells the agent which ring it is on. Not one of them records the product-architect conversation that determines which coordination pattern the current revolution requires, which prior integration commitments govern the implementation, or what the system must guarantee before the commitment partition can be crossed. That is the missing layer: the PRD-to-SRS translation, recurrent at every spiral boundary, absent from every harness configuration file format in the ecosystem.
§5 — Why This Is a Structural Problem, Not a Documentation Problem
The instinct, upon hearing this argument, is to paste a PRD into the repository and call it solved. That is not the solution. The problem is structural.
A PRD written for humans is organised around user stories and acceptance criteria. It does not encode ring position. It does not resolve product intent against existing architectural constraints. It does not tell the agent that a new capability, however simple in product terms, is touching a mature outer ring and must therefore satisfy full traceability before any code is generated. An agent that reads a PRD and proceeds directly to implementation is skipping the commitment partition. It is treating every feature as an inner-ring concept, regardless of where the architecture actually sits.
The required document is not a PRD. It is not a classical waterfall SRS. It is a capability manifest: a structured artfact that, for each capability, records the product requirement, the software requirement it generates, the services responsible, the coordination pattern required, the architectural constraints that govern the implementation, and the ring position that determines the verification gate the system must clear before agents proceed. It recurs with the spiral. It lives in the repository. It is the first document any agent reads before decomposing a multi-service feature.
§6 — What Good Looks Like
We have been here before. The artfact that captured this translation was the SRS: the outcome of conversations between product and architects. Product intent resolved against existing architectural constraints to produce implementable software requirements. The conversation was the thing. The SRS was just its artfact.
We stopped writing SRS documents because agile moved fast and the documents rotted. That was a reasonable trade when a senior engineer could reconstruct the intent from memory at each sprint. It is not a reasonable trade when the agent has no memory at all and no way to know which ring of the spiral it is executing against.
The corrected state adds two things to the repository. First, a
PRODUCT.md capability manifest referenced from
copilot-instructions.md, which maps each capability to its
product guarantee, participating services, coordination pattern,
architectural constraints, ring position, and end-to-end test. The agent
reads this before decomposing any multi-service feature. Second, a
/capability-plan command that facilitates the dialogue
between the PRD and the architect to arrive at the plan, encoding that
conversation as a PRODUCT.md entry rather than losing it in
a Slack thread or a whiteboard. The /capability-plan
command is the short-term forcing function. The real long-term value is
the manifest itself: a persistent, agent-readable artfact that encodes
the architectural bias every agent and every junior engineer currently
has to infer or miss.
This is not a new idea. It is the oldest idea in software engineering: specify before you implement. What is new is that specification must now be commitment-aware, ring-aware, and written for an audience that will not ask what it does not know.
Your agents are not failing because they lack intelligence. They are failing because you have not recorded the conversation that tells them which ring of the spiral they are on.
Build that document first.
Note: After publishing, I researched the most widely adopted third-party agent harness in the ecosystem, Everything Claude Code (ECC) by Affaan Mustafa, which works across GitHub Copilot, Codex, Claude Code, Cursor, and other AI agent harnesses and carries over 123k GitHub stars. ECC is a world-class harness: 25 specialized agents, 108 skills, 57 commands, a security layer, and 997 passing internal tests. It has no capability manifest. No PRD-to-SRS translation layer. No ring-position encoding. No mechanism for recording the product-architect conversation that determines what specification rigor the current revolution requires. This is not a gap in ECC specifically; it is a gap in the entire agent harness ecosystem. The missing layer is structural, not accidental.