Per-revolution PRD-to-SRS gates, maturity-aware agent execution, and why the production surface is off-limits to new code
Every engineering team I have spoken with in the past two years has the same problem. AI-assisted development is fast: faster than anyone predicted, faster than the process can absorb. Agents generate confidently. They decompose tasks, write services, wire contracts, and emit test scaffolding. What they do not know, because nobody told them, is which ring of the spiral they are operating in. That ignorance is not a minor configuration gap. It is a structural defect that produces outer-ring damage from inner-ring authorization.
§1 The Spiral Is a Commitment Accumulator
The Spiral model organizes development as an outward movement through successive revolutions, each traversing four quadrants: objective determination and alternative identification; risk identification and resolution; incremental build and verification; and customer review with next-phase planning. The quadrant sequence is not the key insight. The radius is. Cumulative cost and architectural commitment increase with every outward revolution. Inner-ring work operates at maximum uncertainty and minimum sunk cost, which means the price of rework is low and the tolerance for ambiguity is high. Outer-ring work sits at the opposite end: committed integration surfaces, production data contracts, and clinical workflow dependencies where a missed requirement costs a production incident, not a refactored prototype.
This gradient is the operating principle. The PRD-to-SRS translation recurs at every revolution boundary, each time with tighter fidelity requirements and a higher cost of getting it wrong. Agent harnesses that ignore ring position will apply inner-ring ambiguity tolerance to outer-ring generation tasks. The result is coherent code against the wrong specification, which is the most expensive class of defect because it often passes local verification.
§2 Revolution 1: Concept Ring — Prototype Mode
The concept ring is where behavioral intent is established. No architectural constraints are enforced here because the cost of enforcing them before the behaviour is confirmed is higher than the cost of violating them (as in tokens to construct / refactor e2e validation tests). The goal was iteration speed over a validated clinical workflow, not a production deployment topology. Prototype 1 was the artifact of this ring: a behavioural confirmation, not a system design.
The PRD at this ring is a behavioral contract. It encodes what the system must do for the clinical user, expressed in terms of observable outcomes: what data is read, what decision is surfaced, what workflow step is advanced. It does not encode service topology, API contract shape, or fault model. The SRS derived from it inherits that constraint: functional requirements only, no non-functional architecture requirements, no integration surface definitions. The capability-plan command operating at concept maturity produces a lightweight intent sketch. Agents are authorized to prototype in whatever topology is fastest. The revolution exits when the behavior is confirmed by the reviewing clinician or stakeholder, not before.
§3 Revolution 2: Design Ring — Decomposition Mode Entry
The design ring is where the architecture earns its right to exist. Behavior is confirmed. The question shifts from what does it do to how must it be structured to do it durably. This is the revolution boundary where prototype mode ends and decomposition mode begins. The transition is not automatic and not agent-driven; it is a human gate enforced by the spiral position parameter.
Decomposition at this ring uses several criteria but typically includes separation of concerns, which determines where the service boundary falls; performance contract, which encodes the latency and throughput obligation that the service must meet independently; and fault isolation classification, which asks whether the code is prone to failure in a way that, if co-located with other concerns, would produce cascading impact (e.g. blast radius). Code meeting that third criterion is isolated in its own microservice behind a NATS queue. When it fails, the queue holds state and the service recovers without blocking adjacent behavior. That is not defensive programming; it is a structural decision derived from the fault tolerance SRS that was informed by the prototypes.
The PRD at the design ring adds non-functional requirements that were deferred at concept: response time obligations, tenant isolation guarantees, and data residency constraints for in the SOLID data store. The SRS derived from it must encode service boundary definitions, API contract shape at the internal interface level, and a fault model per service with an explicit NATS queue dependency declaration where fault isolation applies. Prototype 2 validated this topology under a second clinical context. Agents at this ring operate against the decomposition SRS. The capability-plan command at validated maturity triggers the full PRD-to-SRS translation and requires fault tolerance classification before emitting any service boundary task.
§4 Revolution 3: Development Ring — Integration Surface Hardening
The development ring is where the validated service topology is built to its full specification and the integration surface is defined contractually. Prototype 3 — virtual, November — was the artifact of this revolution at EverBetter: a multi-tenant deployment with real clinical data structures, operating across the Maxwell Clinic and The Path client contexts, with FHIR-RDF graph queries running against Solid POD-resident data. The behavioral and structural questions were closed. The open question was whether the integration surface held under real tenant load and real data volume.
The PRD at this ring must close all deferral language from earlier revolutions. Every non-functional requirement marked “to be resolved at design ring” must be resolved. The SRS derived from it encodes the external API contract in full: endpoint shape, authentication model, error response contract, versioning policy, and rate model. It also encodes the validation and verification plan: which integration test suites cover which service boundaries, and what the pass criteria are before the ring closes. Unit tests must pass. Integration tests must pass. The capability-plan command at this ring requires a matching acceptance criterion traceable to the MRD for every agent task emitted. Agents are not permitted to generate new service boundaries at this ring; only to implement against the SRS-defined ones.
§5 Revolution 4: Production Ring — Agent Lockout
The production ring is where the operational prototype becomes a committed clinical system. It is also where the agent loop changes its fundamental operating mode. At every prior revolution, agents were authorised to generate against surfaces that were still evolving. At the production ring, that authorisation is revoked for any surface that has passed acceptance testing and moved to release. The agent loop carries one explicit instruction: do not let any new code engage the production surface.
Entry conditions for the production ring are the most demanding of any revolution. The PRD must have been reviewed and signed off by the clinical stakeholder. The SRS must encode complete end-to-end test coverage: every user-facing workflow from authentication through data query through clinical decision output must have a corresponding e2e test that passes. Every external API endpoint must have API-level contract tests that verify the response shape, error contract, and authentication behaviour independently of the internal service implementation. These are not aspirational targets. They are gate conditions. If they are not met, the revolution has not closed and the capability has not entered production maturity.
Once a surface enters production maturity, the agent harness enforces a hard gate. The copilot-instructions and the agents directory carry an explicit classification: any capability with production maturity is read-only to agent task generation. Agents may read the contract to inform work on adjacent concept or validated surfaces. They may not generate code that modifies, extends, or re-implements any part of the production surface. A change requires a new revolution: a PRD revision, a new SRS translation, a new e2e and API-level test pass, and a new acceptance sign-off before the surface is re-opened to agents. The spiral position parameter enforces this as a gate condition in the capability-plan command output, not as a documentation note.
The two-dimensional constraint applies here at its most consequential: capability maturity crossed with architectural surface area. A concept-maturity capability that touches a production integration surface inherits the outer-ring rules in full. The agent does not get to decide. The spiral position parameter, derived from the capability maturity field crossed with the surface area classification, determines which rules apply. This is the mechanism that prevents an inner-ring agent task from inadvertently modifying a production API contract because the task description was ambiguous about which service it was targeting.
§6 The product-capability Skill as the Spiral’s Operational Memory
The maturity field on each capability entry in the product-capability skill is what makes the spiral position parameter operational rather than theoretical. Four states cover the full revolution range. Concept: behavioural intent only; no architectural constraints enforced; agents in prototype mode; API-gateway monolith topology permitted; no decomposition SRS required. Validated: confirmed behaviour; decomposition SRS required; service boundary generation gated on fault tolerance classification; internal API contract shape required. Development: full SRS coverage; external API contract locked; unit and integration tests required to pass; acceptance criteria traceable to MRD required per agent task. Production: acceptance test passage confirmed; e2e and API-level tests passing; agent task generation blocked for this surface; change requires full revolution re-authorisation.
The capability-plan command reads this field at every invocation. It does not produce the same output class for a concept capability and a production capability. The output class, the verification burden, the human review requirement, and the agent authorisation boundary all derive from the maturity field crossed with the surface area classification. That is the spiral made executable: not a diagram on the wall, not a methodology chapter in a handbook, but a parameter in the harness configuration that gates what agents are permitted to do, per capability, per revolution.
Every revolution earns the right to proceed. The production ring earns the right to be left alone.
— ## FORMAT 2: LINKEDIN NATIVE POST — Most agent harnesses have a structural defect. They treat every sprint as a flat plane. Same context window. Same task decomposition. Same agent authorisation — regardless of whether the target surface is a throwaway prototype or a committed production API contract. The Spiral SDLC model names exactly why that’s wrong. And per revolution, tells you what to do about it. — The Spiral organises development as outward movement through successive revolutions. Each traverses four quadrants: objective setting, risk resolution, incremental build, review. The key feature is not the quadrants. It’s the radius. Cumulative cost and architectural commitment grow outward. The PRD-to-SRS gate is not a project-start event. It recurs at every revolution boundary — each time with tighter fidelity requirements. Here is what that looks like per ring. — Revolution 1: Concept Ring. PRD is a behavioural contract only. What the system must do for the clinical user, expressed as observable outcomes. No service topology. No API shape. SRS inherits that — functional requirements only. Agents are in prototype mode. Architectural violations are permitted. At EverBetter this meant all service logic in the API gateway. Deliberately wrong. The exit condition is stakeholder-confirmed behaviour, not a system design. — Revolution 2: Design Ring. Behaviour confirmed. Architecture earns its right to exist. PRD adds non-functionals deferred from concept: response time, tenant isolation, data residency. SRS must encode service boundary definitions, internal API contract shape, and a fault model per service. Decomposition applies three criteria: separation of concerns, performance contract, fault isolation classification. Code prone to failure is isolated behind a NATS queue. Recovery is asynchronous and non-cascading. Agents operate against the decomposition SRS. No freeform generation. — Revolution 3: Development Ring. All PRD deferral language closes here. SRS encodes the external API contract in full: endpoint shape, authentication model, error contract, versioning policy, rate model. Unit tests and integration tests must pass before the ring closes. Every agent task requires an acceptance criterion traceable to the MRD. No new service boundaries generated — only implementation against the SRS-defined ones. — Revolution 4: Production Ring. This is where the agent loop changes its operating mode entirely. A surface that has passed acceptance testing and moved to release is frozen to agents. The rule has no exceptions: no new code engages the production surface. Entry conditions: e2e tests passing for every user-facing workflow. API contract tests passing for every external endpoint — response shape, error contract, authentication behaviour — verified independently of internal service implementation. Clinical stakeholder sign-off on the PRD. Once a capability enters production maturity, the capability-plan command blocks agent task generation for that surface. Agents may read the contract. They may not modify, extend, or re-implement any part of it. A change requires a new revolution: PRD revision, SRS retranslation, full test pass, new sign-off. — The mechanism: a maturity field per capability in the product-capability skill. Concept, validated, development, production. The capability-plan command reads it at every invocation. A concept-maturity capability touching a production integration surface inherits the outer-ring rules in full. The agent doesn’t decide. The spiral position parameter does. Every revolution earns the right to proceed. The production ring earns the right to be left alone. — ## FORMAT 3: X/TWITTER THREAD — 1/ AI agent harnesses have a structural defect: they treat every sprint as a flat plane. Same authorisation, same decomposition, same verification burden for a throwaway prototype and a committed production API surface. The Spiral SDLC model names this — per revolution. 🌀 #SDLC #AgentDev #AIEngineering 2/ The Spiral is outward movement through successive revolutions: objective setting, risk resolution, incremental build, review. The key feature is the radius. Cumulative cost and architectural commitment grow outward. The PRD-to-SRS gate recurs at every revolution boundary — each time tighter. 3/ Revolution 1 — Concept Ring. PRD is a behavioural contract only: what the system must do, expressed as observable outcomes. No service topology, no API shape. SRS: functional requirements only. Agents in prototype mode. Architectural violations permitted. Exit condition: stakeholder-confirmed behaviour. 4/ At EverBetter Concept Ring meant all service logic in the API gateway. Deliberately wrong. Fastest topology for behavioural validation. Not a shortcut — prototype mode with an explicit exit condition. The ring doesn’t close until the clinical workflow is confirmed correct. 5/ Revolution 2 — Design Ring. Behaviour confirmed. Architecture now earns its right to exist. PRD adds deferred non-functionals: response time, tenant isolation, data residency. SRS must encode service boundaries, internal API contract shape, and a fault model per service. 6/ Decomposition uses three criteria: separation of concerns, performance contract, fault isolation classification. Code prone to failure goes into its own service behind a NATS queue. Recovery is asynchronous and non-cascading. Agents operate against the decomposition SRS. No freeform generation. 7/ Revolution 3 — Development Ring. All PRD deferral language closes here. SRS encodes the external API contract in full: endpoint shape, auth model, error contract, versioning policy, rate model. Unit and integration tests must pass before the ring closes. Every agent task needs an MRD-traceable acceptance criterion. 8/ Revolution 4 — Production Ring. The agent loop changes its operating mode entirely. A surface that has passed acceptance testing and moved to release is frozen to agents. One rule, no exceptions: no new code engages the production surface. 9/ Production ring entry conditions: e2e tests passing for every user-facing workflow. API contract tests passing for every external endpoint — response shape, error contract, auth behaviour — verified independently of internal implementation. Clinical stakeholder PRD sign-off. All required. Non-negotiable. 10/ Once a capability is in production maturity, the capability-plan command blocks agent task generation for that surface. Agents may read the contract. They may not modify, extend, or re-implement any part of it. A change requires a full new revolution: PRD revision, SRS retranslation, new test pass, new sign-off. 11/ The mechanism: maturity field per capability in the product-capability skill. Concept → validated → development → production. The capability-plan command reads it at every invocation. Agent authorisation boundary, verification burden, and human review gate all derive from it. 12/ A concept-maturity capability touching a production integration surface inherits the outer-ring rules in full. The agent doesn’t decide. The spiral position parameter does. Every revolution earns the right to proceed. The production ring earns the right to be left alone. /end