EvolveSDLC
A software development method for teams where coding agents do most of the typing: two loops and a pulse, three change classes, a verifier that never built the change, and evidence bound to the commit it covers.
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 that does not come from the agent that did the work.
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. Every phase ends in an artefact a person can check, and the checking is done by an agent that did not do the building, with read-only tools and its own context.
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 agent roles are defined, three of which earn a definition file. 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
Read-only tools, a read-only token, a fresh context, and its own plan written before it reads anything the builder said.
Four completion decisions
Task complete, change ready, release verified, outcome realised. Declared by four different actors, kept apart on purpose.
Scroll the diagram sideways, or open it full size.
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. A person reads a diff only where data could be exposed.
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? | One evidence comment from the verifier, bound to the exact commit it verified | |
| 6 Deliver | Once per issue | Is it live, observed and reversible? | The production URL serves the merge, the identity chain is recorded, the rollback path is written | |
| 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.
Scroll the diagram sideways, or open it full size.
A change is declared done four times, by four different actors.
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
A verifier that did not build it has posted evidence bound to the head commit. Declared by the verifier.
Release verified
The production URL serves the merge commit, checked by its response rather than the platform's status. Declared by the deliver skill.
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.
Scroll the diagram sideways, or open it full size.
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; 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; then a person reads and merges. Never batched | The person merges | Whatever it takes |
| 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 | Automated gates only; class confirmed from the paths | As B | Zero |
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.
Scroll the diagram sideways, or open it full size.
The agents
Six roles, five separation rules, and a test for when a role earns a definition file of its own.
Six agent roles.
A role is a job with a tool boundary and a list of things it never does. Three of the six have a definition file in every repository; the others are prompts, built-in agents or scheduled routines.
| Role | Does | Tools | Never | Definition file |
|---|---|---|---|---|
| Planner | Decomposes the spec into issues sized so one session finishes one, draws the dependency graph, decides what can run in parallel | Read access to the spec and the repository; the tracker | Writes code | No: judgment shared with the person, in the coding agent's planning mode |
| Builder | Takes one issue: classes it, writes the plan as a ledger, builds on a branch in commits the guard accepts, self-checks, opens the pull request, hands off | Full coding tools in its own worktree | Merges. Verifies its own change. Touches another builder's branch | Yes, for fan-out builds: an isolated worktree per issue, the build skill preloaded, no tracker connector, a fixed four-item report |
| Verifier | Confirms or raises the class from the diff, writes its own checks from the acceptance criteria before reading the hand-off, executes them for the class, posts one evidence comment bound to the head commit | Read, search and shell only; a read-only token to the source host | Writes or edits any file. Reads the hand-off before writing its own plan. Says a thing works because the builder said so | Yes, in every repository. The tool restriction is enforced by the harness, not remembered |
| Security reviewer | For Class A only: reviews the diff against a fixed security checklist in its own context and returns findings the verifier merges into the evidence | Read, search and shell; no connectors | Edits. Reads the hand-off. Softens a finding because the diff explains why it is safe | Yes, launched by the verifier as a nested agent. Proven or dropped by its first run |
| Researcher | Landscape scans, evidence gathering, isolated critique panels at Discover and Distill | Web and read access | Asserts from memory what it could have fetched | No: the coding agent's built-in exploration agent and the research skills already restrict the tools |
| Distiller | Drafts the monthly pulse, consolidates memory, proposes edits to the method | Read access to the tracker, the source host and billing | Edits the method without a person accepting the edit | Later, as a scheduled routine |
Three things that look like agents and are not: the access-path tester is a script the verifier runs; delivery runs in the main session because it needs the merge connector and, for Class A, the person; and a session that launches the verifier on behalf of another is a relay, not a role.
Scroll the diagram sideways, or open it full size.
Five separation rules that do not bend.
The verifier is never the builder
Different definition, different session, no shared context. It has no write tools, so it cannot fix what it finds; findings go in the evidence comment.
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.
A person appears at four points
Classing disputes, Class A reads, Class A merges, and the escalation package when remediation does not converge. Everything else is an agent's job.
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.
Scroll the diagram sideways, or open it full size.
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
A verifier asked not to edit will edit under load. A verifier whose tool list has no edit tool cannot.
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 with worktree isolation is that.
How a definition is written
Name the inputs and refuse the rest: the verifier takes an issue identifier and a commit range, and a guard hook refuses a launch prompt that says anything about the change. Give the smallest tool list that does the job, and keep connectors out of any agent that has no business writing to a tracker. Switch memory off, because a fresh context is the reason the agent exists. Set a turn limit as the agent's own limits line. Fix the report: three items for the verifier, four for the builder; the launching session does the tracker work from the report, so the agent's output cannot be mistaken for evidence. Record the token count the launcher reports, because it is the only per-phase measurement the method has.
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: required checks green for C; 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.
Measured on the first runs: a verifier round costs 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, merged into one findings list. 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: Class A reads and merges are one at a time, so the method keeps Class A rare. 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 the missing ones inactive, proves them with one intentional failure blocked at the platform with the hook disabled, hands over a control-status table, a classes-accepted line and a foundations record | Activates what it installed; sets a class the evidence does not support; types a secret |
| 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, gets it agreed, 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 the read-only token and the verifier definition, 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 a file; moves an issue past review; substitutes a general-purpose agent |
| Deliver | Once per verified pull request | Proves with the repository's own check that the evidence names the head commit and passes, merges pinned to that commit, waits for the deployment, checks the production response against a baseline, records observability, writes the rollback path, posts the identity chain | Merges Class A (it stages the page and asks); rolls back; moves an issue to 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. Where a skill and the method disagree, the contract wins and the prose is corrected.
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 what moves the issue to blocked 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. 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 findings return to a builder, on the same branch. 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, and the human minutes spent. A required check on the pull request parses the latest such comment and passes only while the hash in it is the head commit; 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. Rolling back is the person's decision; the skill only writes the path.
Scroll the diagram sideways, or open it full size.
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; an issue moves to review, never to done, because done is the person's alone. 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; two tokens, one for building and a read-only one for verifying, the second proven unable to push.
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.
Scroll the diagram sideways, or open it full size.
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 verify worktree left dirty after the verifier stopped | The rule that the verifier writes nothing |
| 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).
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 agent is Claude Code; 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.
Scroll the diagram sideways, 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 the numbers it produced, and the claim it does not make.
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. A measurement baseline (cycle time, review time, defects on real work) is on the queue; until it exists the claim is not made.
What the method does not yet cover.
Mobile
The evidence is one preprint and practitioner reports. A verification pass has been researched and a toolchain proposed; adoption waits for one build run end to end.
The Class A leg
The first access-path test against a branch database has been recorded and the ceiling raised; a full Class A change through build, verify and deliver is the next run, and the security reviewer is proven or dropped by it.
The measurement baseline
Human minutes and verifier tokens are measured; builder tokens, cycle time and defect rates are not. Until they are, the method's own productivity is an open question.
The pulse
The monthly routine is specified and not yet built. The amendments the first runs produced sit in a notes file for the next revision rather than edited into the current one.
Adopting it, in order.
Foundations, once per repository
Run the setup skill: inventory what exists, install what is missing inactive, prove each control with one intentional failure and the hook disabled, and record which classes the repository may accept. Start with C and B; A unlocks when the access-path test has run once.
One issue through the loop
A Class C change first, then a Class B. Read what the verifier found. Record the human minutes and the friction. 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.6 with the amendments its first runs produced. It is the public description; the operating wiki, with its checklists, templates, scripts and evidence trails, is internal.
One outcome: software built by agents that a person can trust, because the proof never came from the builder.
Reference method v0.6. Use it, adapt it, or talk to us about running it on your own products.