Software built by agents, proven by evidence.
EvolveSDLC is a software development method for teams where coding agents do most of the typing. It keeps the parts of a lifecycle that still matter when an agent builds, drops the parts that existed only because people were slow, and adds the one thing agentic development needs most: proof matched to risk, including independent verification where the class requires it.
The method rests on a finding that reorganises everything else. Developers cannot tell whether AI is making them faster: a randomised study measured experienced developers as slower with AI assistance while they believed themselves faster. So nothing in this method is justified by how it feels. Each phase leaves evidence a person can check. Class A and B changes require an independent verifier; Class C uses a distinct builder attestation and required checks. Those are different forms of assurance.
It is written as a method that runs, not a method that is read. The change loop executes through four skills and one scheduled routine, each a numbered procedure with fixed inputs, fixed outputs, a limit and a stop condition. Six roles describe the work. Runtime restrictions must be tested; a role definition is not proof of isolation. Controls live on the platform, and the hooks inside the coding agent are feedback only.
Two loops and a pulse
Three phases once per product, three per change, one on a calendar. Seven phases, each ending at a gate that is passed by an artefact existing.
Proof proportionate to risk
Three change classes, set by the paths a change touches. A comment may raise the class and never lower it.
A verifier that never built it
For Class A and B: a fresh context, scoped credentials, tested source-write restrictions and an independent plan before the builder's account is read.
Four completion decisions
Task complete, change ready, release verified, outcome realised. Four distinct evidence and decision points, kept apart on purpose.
The method
Eight principles, seven phases, three classes and four completion decisions. Everything else follows from these.
Eight rules that decide every other rule.
When a method is short, the principles are what a session falls back on under load. These eight are the ones that held when the method met real work.
Evidence beats impression
A phase is complete when its exit condition is demonstrated, not when it feels done. The research says the feeling is unreliable, so it is not admissible.
Proof is proportionate to risk
Risk is set by what a change touches. A path-based floor decides the minimum class; a comment may raise it, never lower it.
The reviewer is never the builder
Code review is an agent's job as far as it can be, and the reviewing agent runs in a different context with read-only tools. Human review follows the selected involvement level and the nonreversible-change floor.
Work runs in parallel where it is independent
Builders work on independent issues at once in separate worktrees. Reviews and research fan out. The person's attention is the only serialised resource.
The reviewable diff is the unit of work
A commit over a fixed size is refused at commit time and flagged again on the pull request. Small diffs are what keep agent review honest at volume.
Hooks are feedback; the platform is the control
A hook inside the coding agent sees only what passes through it. Branch protection and required checks are the control, and every control is proven with the hook switched off.
Decisions are written where the next session will find them
In a decision record, a repo instruction file or a memory file. A decision made in chat will be made again, differently, by the next session.
Methodology as code
Every rule a script can check is a check, a hook or a verifier action; every phase a session runs is a skill with numbered steps. A rule an agent has to remember will be skipped under load.
Two loops and a pulse.
Seven phases, each starting with D. They do not run as one line: three run once per product, three run once per change and repeat dozens of times, and one runs on a calendar.
| Loop | Phase | Runs | Question it answers | Gate artefact |
|---|---|---|---|---|
| Product loop | 1 Discover | Once per product | Is there a problem worth solving, and for whom? | A discovery record: problem, a real user conversation, the landscape, the golden path, a build-or-skip decision |
| 2 Define | Once per product | What exactly are we building, and how will we know it works? | The spec: acceptance criteria an agent can test, scope boundary, vocabulary, risk surface, an outcome contract with a baseline | |
| 3 Design | Once per product | How will it be built, and what must not be decided silently? | Data model, stack decisions as records, authorisation design, the experience, the work decomposed into issues with a dependency graph | |
| Change loop | 4 Develop | Once per issue | Is the change built, on a branch, with its own self-check? | Foundations proven once per repo; then an unmerged pull request with a plan ledger and a hand-off comment |
| 5 Demonstrate | Once per issue | Has an agent that did not build it shown it works and is safe? | Independent verifier evidence for A/B, or an all-Class-C builder attestation, bound to the exact head commit | |
| 6 Deliver | Once per issue | Is it live, observed and reversible? | The applicable hosted or install release is proven, its identity chain recorded and its recovery evidence complete | |
| Pulse | 7 Distill | Monthly | What did the last month teach, and what changes because of it? | Edits to the method and the queue, from a pre-filled draft with the month's numbers |
A gate is passed by an artefact existing, not by a box being ticked. Each phase has numbered sub-components with a checklist; the change loop's sub-components are the steps of the skills in Part 3.
Four completion decisions, each with its own evidence.
Most methods have one definition of done and let the builder declare it. This one keeps four apart, because the first three say the work was done well and only the fourth says it was worth doing.
Task complete
The builder has a pull request open with a self-check. Declared by the builder, and worth exactly that much.
Change ready
For A/B, an independent verifier has posted evidence at the head commit. For an all-Class-C diff, the distinct attestation and required checks pass. A current verifier record takes precedence.
Release verified
The hosted response or applicable install-release evidence proves the merge revision. The delivery record includes the observation and recovery evidence required by the product.
Outcome realised
The metric the change was meant to move, set at Define with a baseline, read after its observation window. Declared by the person.
Three classes, set by paths, and a ceiling per repository.
The amount of proof a change needs is decided by what it touches, before anyone argues about how small it is.
| Class | What sets it | Demonstrate | Deliver | Human minutes across the loop |
|---|---|---|---|---|
| A | Schema migrations and access policies; the data-access adapter's choice of client, filter or bucket; middleware and runtime configuration; authentication and payments; the involvement setting; secrets and public environment variables; prompts that hold tools, read user data or have their output rendered; on mobile, any permission or entitlement | The verifier reads every line, runs an access-path test against a branch database, and performs a security pass; human read and authorized approval at sign-off and above; two independent review lenses and reversibility at agents. Never batched | Pinned merge according to involvement; a manual merge at every-gate | No cap at sign-off and above; zero routine target at agents, with escalations recorded |
| B | Features and interface; adapter code that changes none of the above; on mobile, anything changing the native binary | Automated gates, the plan ledger re-verified at the head commit, the golden path exercised once, the diff read, evidence posted | Merged once every required check is green, pinned to the verified commit | Fifteen |
| C | Copy, styling, documentation, and files on the repository's Class C list | Required checks and a distinct builder attestation, accepted only for an all-Class-C diff | As B | Zero routine target; escalations recorded |
A repository accepts only the classes its controls can gate. A line in its instruction file says which, and its exceptions register names the control that unlocks the next one. Each class carries packet defaults: attempts per finding, remediation rounds, sessions, and the human-minute budget; an issue brief may tighten them and never loosen them.
At Standard involvement, routine B/C work targets zero human acts and A targets one sign-off including the human read. These are targets, not guarantees. Agents and sign-off levels use a criterion-mapping check for plans; higher levels require human agreement. B/C merge and completion remain automatic when the full chain permits them at every level. A at agents requires two independent exact-head review records and reversibility; sign-off and plan-and-sign-off require authorized approval, and every-gate stages a manual merge. Class A completion above agents remains a human decision. Nonreversible changes escalate at every level.
The agents
Six roles, explicit separation rules, and a test for when a role earns a definition file of its own.
Six agent roles.
Roles describe responsibilities. A definition file is useful when a tool, credential or context boundary must be enforced, or repeated independent work justifies one. Definitions and installation records do not prove runtime isolation.
Planner
Decomposes the specification into issues and a dependency graph. Reads the source material and records decisions; does not build the change.
Builder
Works on one issue in its own branch or worktree, runs self-checks, opens a pull request and hands off. Does not independently verify or merge its own work in the builder role.
Verifier
Starts in a fresh context at the exact head. Plans from acceptance criteria before reading the builder account, runs applicable checks and publishes evidence with scoped credentials. Product-source writes, pushes and merges are prohibited; bounded test scratch and evidence outputs are permitted.
Security reviewer
Provides a separate Class A security lens, launched by the loop session rather than nested inside the verifier. At agents involvement, its exact-head record remains distinct from the verifier evidence.
Researcher
Collects sources and compares alternatives during discovery and the monthly pulse. Separates observed facts, vendor statements and inference.
Distiller
Drafts the monthly pulse from delivery, measurement and spend records. Proposes method changes for the owner to judge; the routine does not silently adopt policy.
Separation rules and human involvement.
The verifier is never the builder
Different definition, different session, no shared context. It cannot change product source, push or merge. Bounded scratch outputs and scoped evidence publication are permitted. Credential and filesystem boundaries must be tested in the actual runtime.
The verifier writes before it reads
Its plan comes from the acceptance criteria. It reads the builder's hand-off only afterwards, may add checks from it, and never removes any.
The builder cannot deploy
Branch protection means the only way to the main branch is a merged pull request, and the builder does not merge.
Human involvement is explicit
The repository records agents, sign-off, plan-and-sign-off or every-gate for each class. Blocking escalations and nonreversible changes still require a person. Higher-risk work cannot be more autonomous than lower-risk work; outcome review remains human-owned.
Authority comes from the token and the harness, never from the model
Switching a session to a more capable model does not widen what it may do. The deny list, the connector allow-list and the token are the same for every model.
Coordination goes through the record
Agents coordinate through the tracker and the source host, not through each other. An issue's state says who holds it; a pull request says a build is done; an evidence comment says a verification is done.
When a role earns a definition file.
Roles are not files. A file is another thing to keep true, so it earns its place only when one of three conditions holds.
The tool restriction must be enforced, not remembered
An instruction alone does not prevent edits. Test product-source writes and credential authority in the actual runtime, including shell and connector routes.
The contract requires a fresh context
The second-context rule is a property of the launch, not of the prompt. A file is what makes a fresh context repeatable.
The work runs as parallel copies
N independent issues need N contexts in N worktrees. A definition can request this; the launch and filesystem evidence must show that the worktrees are separate.
How a definition is written
Keep launch inputs bounded, form the verification plan before the builder account is read, and use the least authority the role needs. The launcher supplies repository-scoped, short-lived App installation credentials; the verifier receives no minting authority. Publish head-bound evidence on the source host and mirror it through the authorized loop session. Report unavailable measurements as unknown.
The verifier, as it runs
Launched in a fresh context from a session opened in the repository, in a detached worktree checked out at the exact commit under review. It classes the change from the diff first, writes its plan from the acceptance criteria, reads the hand-off only then, and executes for the class: a distinct builder attestation and required checks normally suffice for an all-Class-C diff; the test, build and typecheck commands, every ledger check re-run at the head, the golden path once and the diff read in full for B; every line read, the access-path report, the advisor count and the security review for A. It composes one comment in a fixed shape that a required check parses, posts it on the pull request, and stops. A push after the evidence turns that check red, and that is correct.
Historical first-run observation: a verifier round cost sixty to a hundred thousand tokens and six to eleven minutes for a Class B change, by the launcher's own count.
Parallelism is designed at Design and executed at Develop.
The unit of parallelism is the issue. Two issues can run at once when they touch disjoint files, do not both change the schema, and do not both depend on a third unfinished issue.
Patterns that work
Fan-out builders: N independent issues, N builder agents, N worktrees, N pull requests, each verified separately. Fan-out review: a Class A change gets a security lens in its own context, with a distinct head-bound record when required by the involvement level. Fan-out research: discovery and pulse questions run as parallel isolated agents whose findings are compared. Pipeline: the verifier starts on one issue while the builder starts the next.
Where parallelism stops
Schema changes serialise: one Class A schema change at a time, merged before dependent work starts. Shared files serialise: two issues touching the instruction file, the adapter or a shared component are dependent, and the graph says so. The person serialises: Human decisions serialize where the involvement level or nonreversible floor requires them; plan independent work around those decisions. Never batch Class A.
The skills
Four phase skills and a scheduled routine run the change loop, so that its steps are actions that leave artefacts rather than rules a session has to remember.
Four phase skills and a routine.
A skill is a packaged procedure a session invokes: numbered steps, fixed inputs, fixed outputs, a limit and a stop condition. The discovery, definition and design phases are judgment work covered by interview, research and design skills that already exist; they stay as gate checklists.
| Skill | Runs | Does | Never |
|---|---|---|---|
| Setup | Once per repository; inventory monthly | Inventories the controls a repository already has, installs missing controls through authorized setup, proves an intentional prohibited action and staged fake-secret rejection at the platform with local hooks disabled, and records the supported classes. A rollback rehearsal is required before agents involvement | Raises the class ceiling from configuration alone; exposes credential values; claims an untested runtime boundary is accepted |
| Build | Once per issue | Refuses an issue above the repository's ceiling, claims it, adds limit and stop lines from the class defaults, classes the change from the paths, writes the plan as a ledger of checkable gates, checks criterion mapping, obtains human plan agreement where the level requires it, builds on a branch in commits the guard accepts, self-checks, opens the pull request, hands off | Merges; verifies its own change; lowers a class; continues past the limits line |
| Verify | Once per pull request, up to three rounds | Preflights scoped credentials and the supported runtime, launches the verifier in a fresh context at the head commit, mirrors the evidence on the tracker, decides with a script (pass, hand back, ask, blocked), runs the bounded remediation loop | Merges; edits product source; widens credentials; treats a failed runtime preflight as passed |
| Deliver | Once per verified pull request | Reconciles declared evidence authority and exact-head checks, merges where class and involvement permit, proves the hosted or install release, observes it, follows the rehearsed rollback policy and records the complete identity chain | Bypasses protections; treats any different-account review as human approval; marks incomplete delivery done |
| Distill routine | Monthly, scheduled | Numbers per class, exceptions past expiry, outcome contracts past their window, a repository inventory, the pre-filled draft of the pulse | Edits the method; closes an exception |
Every skill has the same eight parts.
What it covers, when it activates, what it reads, its procedure, what it produces, its limits, when it stops, and what it never does. The method is the policy; phase contracts describe its execution. Record discrepancies and resolve them before the affected action. Implementation does not silently amend approved policy.
The packet
Two lines in every issue brief exist for the agent rather than the person. Limits says how much a session may spend before it stops: attempts, rounds, sessions, human minutes, diff size. Stop or escalate says when to record a blocker and required decision instead of trying something else. A brief without them gets the class defaults before work starts.
The ledger
For Class A and B the plan is a ledger on the branch: one observable outcome per acceptance criterion, a command and an expected result wherever a command can decide it, a manual gate only where none can, with a named future replacement check or a reason none exists. A linter refuses a gate that cannot fail. The verifier re-runs every gate at the head commit and treats the ledger as untrusted input.
The remediation loop
On a fail verdict the verifier classifies every finding: valid, needs a decision, already addressed, false positive, duplicate, out of scope, ambiguous. Only valid defects return to the builder. Nonblocking decisions outside the Class A floor become linked backlog issues; blocking findings, changed criteria, unknown floor applicability and nonreversible changes go to the person. Three rounds at most, two attempts per finding, and the loop ends early when the same test fails after different fixes, the same files churn without the count falling, or a fix reopens an earlier finding. Then a blocked package: blocker, state, attempts, evidence, recommendation, decision required.
Evidence is bound to a commit, and delivery is a chain.
The evidence comment is the method's central artefact. It has a fixed shape because a self-signed gate cannot produce it truthfully, and a required check reads it.
The comment carries the verifier's session and timestamp, the full commit hash it verified, the class it confirmed or raised, a statement that the session has no earlier comments on the issue, machine-generated artefacts, findings with file and line, a verdict with its single most important reason, human minutes and acts, and the product-AI evaluation evidence where applicable. The declared evidence-authority mode selects the required checker and permitted publisher. Missing authority stops delivery. The required check validates the applicable evidence and passes only while its commit is the head; a push afterwards turns it red until a fresh round verifies the new head.
Delivery records an identity chain in the tracker so any production deployment traces to its evidence and any evidence to the code it covered: pull request, reviewed commit, merge commit, deployment, and the production URL as observed. The merge is pinned to the reviewed commit, so a push between the check and the merge fails the merge instead of landing an unverified head. The rollback path names the deployment that served production before, the promotion path back to it, the revert path, and the data step. A failed release watch follows the rehearsed rollback automatically except at every-gate, where a person performs it. An irreversible data step escalates. On the second rollback for a class in a calendar month, autonomy drops one level and higher-risk classes remain no more autonomous.
A non-hosted release uses its declared artifact or install contract. Install proof authenticates the merge commit's default-branch push runs and the installed revision; later comment-triggered runs are not release proof. A no-release change uses its declared contract rather than an invented deployment. Missing observations remain missing. Product-AI evaluation follows its own versioned contract; development-agent evaluations are separate.
Platform and controls
Four systems, one rule about hooks, and a stack with one pick per category.
Four systems, one line each.
The tracker holds intent and evidence
Briefs in a packet format with limits and stop lines; the class in the first comment; hand-off, evidence, blocked-package and delivery comments in fixed shapes; comments append-only; delivery sets done for B/C at every involvement level and A at agents only when the complete evidence chain permits it. Other Class A deliveries remain in review for the person. The tracker's own automation must not set done on merge.
The source host holds code and its protection
A branch per issue; a pull request the builder cannot merge; a protected main branch that deploys; required checks including the evidence check; the plan ledger in the repository; separate builder and verifier authority; the verifier uses scoped App installation credentials and must be proven unable to push or change product source.
Memory holds context
An instruction file that prescribes and is pruned monthly; a memory file that records facts; decision records; a foundations record of what the setup skill installed; a secrets register that holds every key and every place it is installed; an exceptions register with an owner and an expiry on every waiver, under a baseline nothing waives.
The harness decides what a session may attempt
A deny list and a connector allow-list per repository; authority that never widens with a model switch; a context budget with a checkpoint at sixty percent of the window and a hand-off at seventy-five; cost counted per accepted change, never per token.
A hook is feedback. The platform is the control.
A hook is a command the coding agent runs at a lifecycle event. It can refuse an action, add text to the session's context, or record something. It sees only the calls routed through the coding agent, so every control is proven with the hook switched off.
| Hook | When | Refuses or records | The control it serves |
|---|---|---|---|
| Harness guard | Before a shell command or a file write | A push to the main branch under any spelling, a force flag, a recursive delete outside the worktree, a network call to an unlisted host, a write outside the worktree | Branch protection; the deny list |
| Commit guard | Before a commit | A diff over the size limit, a data-access import outside the adapter, a secret pattern, a staged environment file | The diff-size, lint and secret-scan checks on the pull request |
| Agent-launch guard | Before an agent is launched | A verify launch on any agent but the verifier; a verifier launch with more than its two inputs; a launch prompt that says anything about the change | The separation rules |
| Verifier integrity | When a sub-agent stops | A product-source change after verification; permitted scratch and evidence outputs are classified separately | Product-source integrity and bounded output paths |
| Session context | When a session starts or resumes | Records nothing; prints the classes accepted, the branch and head, the open pull request | The rule that a session starts from the record |
| Checkpoint | Before the context is compacted | Writes a checkpoint file and asks for the issue's checkpoint comment | The context budget |
| Audit log | After a state-changing call | One line per call, token-shaped values redacted | The measurement baseline |
Rejected, with reasons: a typecheck after every edit (minutes per edit on a typed stack, and the pull request runs it anyway); a model-judged hook as a gate (a model judging a model is feedback, never a control); auto-approved permission prompts (widens authority without a person); a stop hook that loops the session against the ledger (the ledger and its checker give the same evidence without holding a session hostage); any hook with write authority to the record (an agent nobody launched).
This is a reference hook catalog, not an installation inventory. Record which hooks and platform controls a repository actually has and what each observed run proves. Completion is decided from the delivery evidence, not from a retired local done-state hook.
One pick per category; deviate only by a decision record.
The method is stack-agnostic in its rules and opinionated in its defaults. The web default is a React meta-framework on a git-connected hosting platform, a managed Postgres with row-level security behind a single data-access adapter, the platform's own authentication (a dedicated identity service only when there are organisations), object storage, a payments provider, transactional email, a durable job runner, a large language model behind a provider adapter, error tracking and product analytics. The coding runtime needs its own tested isolation contract; the tracker and the source host are Linear and GitHub. A product that deviates records why in an architecture decision record in its own repository. Mobile is proposed, not adopted: a managed React Native toolchain with cloud builds and a flow-based end-to-end runner, pending one build run end to end.
View the diagram here, or open it full size.
Evidence and limits
What the first runs measured, what the method does not yet cover, and how to adopt it.
What the first runs measured.
The method was run on a production web product before any of its guidance was written up. These are historical pilot observations, not current portfolio averages or a forecast. The claim they do not support remains explicit.
Human minutes for a Class C change
A documentation change went from claim to production with no person touching it: the builder classed it, the verifier confirmed the class and the required checks, the deliver skill merged, watched the deployment and checked the response.
Human minute for a Class B change
A bug fix in a pure module: one question to agree the plan, then a ledger of five gates, a fresh-context verification that found two real edge cases the builder had missed, a pinned merge and a production check. The budget is fifteen.
Minutes per verifier round
Sixty to a hundred thousand tokens of a fresh context per round, by the launcher's count. The builder's and the deliver skill's token costs are not yet measurable from inside a session, and the method says so rather than estimating.
The method makes no claim that AI-assisted development is faster in the teams that use it. No source measures that for them, and the strongest finding in the literature is that the people doing the work cannot tell. Measurement and operations guidance now exists, but its acceptance and adequate longitudinal data are separate. Unknown minutes or spend are not zero. Compare cycle time, human acts, defects and cost per accepted change before claiming productivity gains.
What remains unproven.
Human approval and runtime isolation
A review at the exact head from a different account does not by itself prove independently controlled, authorized-human approval. That enforcement and live acceptance remain open. Native Codex credential and filesystem isolation also needs acceptance evidence; a fresh context or role file is insufficient.
Measurement and operations
The monthly routine and guidance exist. A written incident or recovery procedure is not an observed operational run. Historical pilot numbers do not establish productivity across products.
Mobile, desktop and shared infrastructure
Mobile adoption still needs device and store evidence. Desktop signing, updates and recovery need product-specific acceptance. Shared infrastructure needs explicit evidence about which products a change can affect.
Evaluation and factory practices
Product AI has a versioned evaluation contract; each product must supply its cases, baseline and observed outcomes. Evaluation of development agents is a separate pilot. The next factory experiment is a bounded shared-configuration and runtime-conformance pilot using existing records and skills; a desktop orchestrator is not adopted.
Adopting it, in order.
Foundations, once per repository
Inventory actual controls and evidence authority, install what is missing with scoped permission, and prove platform refusal with local hooks disabled. Set the class ceiling from evidence, not a file. Accept a complete slice from its evidence; rehearse rollback before granting agents involvement.
One issue through the loop
Run one permitted change through its class-specific proof and delivery chain. Read verifier findings where required. Record human acts, minutes and friction, with unknown measurements labeled. Do not patch a skill while it is running; fix it after, from the record.
The pulse
After a month, read the numbers per class, the exceptions past expiry and the outcome contracts past their window, and change the method where the record says to. The method is a state to maintain, not a date to hit.
This page describes the method at version 0.7, separating approved policy, implemented behavior and outstanding acceptance. It is the public description; the operating wiki, with its checklists, templates, scripts and evidence trails, is internal.