methodology · version 1.2
building software with an agentic SDLC.
AI agents as first-class collaborators: interviewing, drafting, validating, testing, reviewing. humans set direction, make decisions, and own every merge.
/featurePhase 1Structured requirements interview, codebase scan, validated spec, Gherkin acceptance tests.
/tech-designPhase 2Difficulty-triaged architecture, ADRs, UX spec, and HTML mockups; only the artefacts the change warrants.
/implementPhases 3 – 5Plan decomposition, TDD subagent build loop, per-task review, feature-wide review report.
phases
slash commands
review rounds max
human-owned merges
one delivery model. consistent leverage across every phase.
The agentic SDLC compresses time-to-first-working-software, surfaces ambiguity earlier, and produces a stronger audit trail than traditional delivery. Every decision is written down, every change is reviewable, every test is named, and every claim is verified against the codebase before code is written.
AI agents do the volume work: interviewing for requirements, validating specs, drafting architecture documents, decomposing plans, writing failing tests then minimal code, and reviewing each task before it commits. Humans set direction, resolve trade-offs, sign off at every gate, and own merges and releases.
“We do not say ‘done’ without proof: the Gherkin scenario that defines the behaviour, the automated test that proves it, and the review report confirming zero blocking findings.”
what we changed, and why
agentic delivery doesn't fix traditional problems by accident.
Requirements arrive with gaps. Edge cases, non-functional needs, and integration constraints emerge during implementation, when they are most expensive to address.
Interview-first. An AI agent runs a structured, depth-first interview, scanning the codebase silently first so every question is grounded in what already exists. Gaps surface before any code is written.
Specs describe desired behaviour but make assumptions about the existing system that no one verifies. Code is written against assumptions that turn out to be wrong.
validate-spec reads the finished spec, extracts every claim it makes about the existing system, and checks each one against the real codebase. Discrepancies block the pipeline, not the review, not post-QA.
Plans are written at a level too coarse for engineers to follow without re-interpreting them. Interpretation drift is a silent source of scope creep.
Each task is sized so one implementer subagent can drive it RED to GREEN in a single pass, with explicit done-when criteria, real file paths, and coverage mapped back to acceptance scenarios.
Tests are added at the end, after the code is already written. A green suite at the end doesn't prove the tests would catch a regression; it just proves they pass today.
Tests are written before code at every task. A reviewer subagent treats a hollow or missing test as an automatic fail, even if the suite passes. Evidence over claims.
Acceptance criteria are written as prose and checked by eye, if at all, once the feature already feels finished.
Every Gherkin scenario is wired to a real Playwright-BDD test that drives the actual UI, not just prose. A genuine mismatch between a scenario and the built behaviour is escalated to a human, never forced green.
Decisions exist in memory, in Slack, in meeting notes. Six months later, nobody knows why something was built the way it was.
Every decision is in version control alongside the code: spec → acceptance tests → ADRs → plan → progress (with commit SHAs) → review report → merged PR. One git log from any answer.
core principles
five rules that govern every decision.
evidence over claims.
An agent saying "this works" is not evidence. A failing test that turns green is. A validate-spec report that confirms every claim against the actual codebase is. Every phase produces evidence; decisions reference that evidence by name.
human owns the decision, AI owns the draft.
AI agents produce extraordinary first drafts of anything: specs, architecture documents, ADRs, test scaffolds, code, review comments. Every phase ends with a named human signing off. No merges happen without human approval.
systematic over ad-hoc.
The same workflow runs for every feature. The difficulty triage that lets a small change skip ADRs is itself a system, not an escape hatch. When someone wants to bypass a gate, they propose changing the methodology, not silently shortcutting it.
complexity reduction.
Every artefact is the smallest thing that captures the decision. Plan tasks are sized so one implementer can drive them RED to GREEN in a single pass. ADRs are written only for decisions with real trade-offs.
learning compounds.
Every retrospective enriches the agentic harness: prompts, skills, commands, agents. The next feature starts with more leverage than the last. The methodology gets better automatically because the team feeds it.
the workflow
six phases. three pipelines. one audit trail.
discover
Interview + validate spec
produces
spec.md + acceptance/*.feature
PM/BA confirms the spec
design
Architecture, ADRs, UX
produces
system-design.md, ADRs, ux-spec.md
Senior Developer approves
plan
Task-level breakdown
produces
plan.md + progress.md, coverage map
Senior Developer signs the plan
build
Subagent-driven TDD + e2e wiring
produces
code + tests, 1 commit/task + e2e wiring
Orchestrator confirms suite green, no blocked tasks
review
Multi-layer verification
produces
review-report.md, approved PR
Senior Developer is final approver
ship
Deploy, observe, retro
produces
merged PR, harness edits
Product Owner accepts the outcome
discover
Interview + validate spec
produces
spec.md + acceptance/*.feature
PM/BA confirms the spec
design
Architecture, ADRs, UX
produces
system-design.md, ADRs, ux-spec.md
Senior Developer approves
plan
Task-level breakdown
produces
plan.md + progress.md, coverage map
Senior Developer signs the plan
build
Subagent-driven TDD + e2e wiring
produces
code + tests, 1 commit/task + e2e wiring
Orchestrator confirms suite green, no blocked tasks
review
Multi-layer verification
produces
review-report.md, approved PR
Senior Developer is final approver
ship
Deploy, observe, retro
produces
merged PR, harness edits
Product Owner accepts the outcome
Six phases, six gates. Each phase produces a tangible artefact. Each transition is a gate owned by a named human. AI drafts, humans decide.
phase details
what happens in each phase.
Goal
Convert customer notes into a validated spec, a set of Gherkin acceptance tests that hold as the definition of done, and a list of carried-forward open questions.
Activities
Silent codebase scan before any interview question is asked, surfacing what already exists per requirement area in plain language.
Depth-first interview: one requirement area at a time, one question at a time, no technical language.
Spec authoring covering: Problem Statement, Current vs New Behaviour, Impact on Existing System, Open Questions.
Spec validation loop: every existing-system claim marked Confirmed, Discrepancy, or Terminology gap. Discrepancies block the pipeline.
Gherkin generation: business-level language only, one file per area, one file per access control matrix.
Stress-test on demand: anyone can run a relentless interview (grill-me) against a draft spec to pressure-test it before it's treated as final.
Failsafe
The validate-and-fix loop runs at most three rounds. If discrepancies remain, the pipeline stops and the spec is sent back for manual review.
Artefacts
specs/spec.md
Problem statement, current vs new behaviour, open questions, adaptive sections.
specs/drafts/spec.draft.md
Only if paused: requirement areas covered, verbatim Q&A, where to resume.
acceptance/*.feature
One Gherkin file per requirement area + one for the access control matrix.
Gate
Owner: PM / BA
Zero discrepancies from validate-spec; every acceptance scenario corresponds to a section of the spec; unresolved open questions are recorded and owned.
Goal
Take the spec and acceptance tests from Phase 1 and produce a system design, Architecture Decision Records, and a UX spec with HTML mockups where warranted.
Activities
Difficulty triage (trivial / moderate / major): announces planned artefacts, allows engineer override.
System design: components, responsibilities, interfaces, data flow, impact on existing system with real file paths.
ADRs: one per genuine decision with real trade-offs. A change with no forks produces zero ADRs.
UX spec covering screens & flows, states, access-driven view variations derived from the permission matrix.
Design validation loop: checks coverage, implementability, and that every architectural open question is resolved or owned.
Failsafe
The validate-and-fix loop runs at most three rounds. If gaps remain after three rounds, the pipeline stops and the design is sent back for manual review.
Artefacts
design/system-design.md
Overview, components, data flow, cross-cutting concerns, links to ADRs.
design/decisions/ADR-NNN-<slug>.md
One per real decision. Zero if no real trade-offs.
design/ux-spec.md
Screens & flows, states, access-driven view variations, open UX questions.
design/mockups/
Static HTML mockups + PNG screenshots (rendered via the playwright-cli skill) for substantial UI changes.
Gate
Owner: Senior Developer / Tech Lead
Zero gaps from validate-design; every artefact the triage warranted is saved; every architectural open question is resolved or owned.
Goal
Decompose the work into ordered, test-drivable tasks. Each task is small enough that one implementer subagent can drive it RED to GREEN in a single pass.
Activities
Task decomposition: AI drafts an ordered list; each task records id, title, acceptance scenarios it satisfies, layer, real file paths, depends-on, done-when criteria, and design refs.
Sequencing rule: foundations first (schema/model), then API (endpoints, permissions), then client (screens from UX spec).
Coverage map: every acceptance scenario mapped to the task(s) covering it. A scenario with no covering task is a planning gap.
Orchestrator confirmation gate: plan presented as a numbered summary; human confirms or adjusts before build loop begins.
Schema mirror discipline: any task touching the production schema must also update the test schema; a CI check keeps them in sync.
Artefacts
implementation/plan.md
Ordered task list (immutable once accepted) with coverage map.
implementation/progress.md
Live state: phase, branch, base_ref, per-task status, commit SHA, review rounds.
Gate
Owner: Senior Developer (orchestrator confirms with user)
Every acceptance scenario maps to at least one task; coverage map is complete; progress.md is written with feature branch and base_ref recorded.
Goal
Execute the plan task-by-task with AI subagents, under strict TDD discipline, then turn the feature's own Gherkin scenarios into a real, passing end-to-end suite before the feature-wide review begins.
Activities
Implement (RED → GREEN): implementer subagent writes the failing test, confirms it fails for the right reason, writes minimal production code to make it pass, runs the full suite plus lint.
Review: a separate reviewer subagent re-runs the suite, checks the test is real (not a tautology), verifies design fidelity and schema mirroring.
Fix or accept: on pass, orchestrator commits and records the SHA in progress.md; on fail, implementer is spawned again in fix mode.
Acceptance wiring: once every task is committed, a dedicated subagent turns each Gherkin scenario into a real Playwright-BDD step against the live UI/API, reusing existing step phrases first.
Resume is built in: if interrupted, the next run reads plan.md + progress.md and continues from the first non-done task, including mid-way through acceptance wiring.
Failsafe
The per-task review loop runs at most five rounds. If a task hits five rounds without passing, it is marked BLOCKED and the entire pipeline stops. Acceptance wiring carries its own smaller failsafe: three attempts to fix a step-phrasing mismatch before escalating to the human; a genuine scenario/behaviour divergence escalates immediately.
Artefacts
Code + tests
Conformant to architecture and plan; committed in task-aligned increments.
progress.md (updated)
Commit SHA recorded for every done task.
e2e/steps/<feature>.steps.ts
Playwright-BDD step definitions wiring each Gherkin scenario to real UI/API behaviour, run via npm run e2e:bdd.
Commit history
One commit per accepted task: <type>(<feature>): <task title> [task <id>]; plus one commit wiring up acceptance steps.
Gate
Owner: Orchestrator
Every task in plan.md is marked done in progress.md with a corresponding commit SHA; every acceptance scenario is wired to a passing Playwright-BDD step or its divergence has been resolved with a human; test suite is green; no task is blocked.
Goal
Apply multiple review lenses to the finished feature, then arrive at a clear verdict: approved, or here is the list of blocking findings.
Activities
Feature-wide review (review-implementation): checks acceptance coverage against a live npm run e2e:bdd pass (or, at minimum, a jest/vitest test), design fidelity, UX fidelity, and correctness/security at a senior bar.
Visual evidence: per-scenario screenshots from the Playwright HTML report back the coverage table, so a passing scenario is backed by a picture of the actual end state, not just a green tick.
Architectural review (review-pr agent, optional): opus-tier subagent reviews the whole branch against main, covering cross-cutting concerns, architectural drift, naming.
External review handler: incoming audits or PR threads are verified against the codebase before any fix is agreed; one subagent per agreed item.
Human pre-deploy validation: senior developer runs the app, exercises the journeys, looks for what no agent thought to flag.
Failsafe
The final-review loop runs at most five rounds. If five rounds isn't enough, the pipeline stops with a do-not-declare-done verdict.
Artefacts
implementation/review-report.md
Suite status, blocking findings, advisory items, full acceptance-coverage table.
PR description
Phase checklist, Jira link, linked feature folder.
Gate
Owner: Senior Developer
Zero blocking findings in review-report.md; full suite green including npm run e2e:bdd; every acceptance scenario shows ✓ in the coverage table.
Goal
Merge, deploy, validate the outcome against the spec's success criteria, and feed learnings back into the agentic harness.
Activities
Merge: human-only, via PR with branch protection on main. Pre-commit hook as a hard backstop.
Deploy: existing helm/helmfile pipeline; progressive rollout patterns applied where the change warrants it.
Post-deploy validation: team runs the application against the same scenarios the acceptance tests encode, in production.
Retrospective: concrete output is a PR that edits the agentic harness: skills, commands, agents, project context. The methodology compounds.
Artefacts
Merged PR
Phase checklist, Jira link, feature folder link, review-report reference.
Harness edits
A PR that updates CLAUDE.md, .claude/skills/, .claude/commands/, or .claude/agents/.
Gate
Owner: Product Owner
Success criteria observed in production; retrospective has produced at least one concrete harness edit.
for clients
what's different from traditional delivery.
If you've worked with traditional delivery teams before, this is what you'll notice that's different, from the first requirements session to post-deploy validation.
more questions, earlier.
The requirements interview surfaces gaps in plain language, one question at a time. Every ambiguity left unanswered becomes a guess, and guesses are how teams ship the wrong thing.
claims about your system are verified, not assumed.
When the spec says "the system today does X", validate-spec checks that against the real code. If the spec is wrong about the current state, that surfaces before any new work is built on the wrong assumption.
design artefacts before any code.
Architecture and UX are produced and signed off before implementation begins. The exact set of artefacts is scaled to the size of the change: trivial changes get a short summary; major changes get the full treatment.
smaller, more frequent deliverables.
Because the build phase is decomposed into TDD-sized tasks and one commit ships per accepted task, the feature branch grows in small, verifiable increments. We don't wait until everything is finished to show you something working.
a live record of every decision.
Every ADR captures a decision the engineering team made: what the options were, what we chose, why. If you ever ask "why did we do it this way?" six months later, the answer is in the repo.
evidence, not just claims.
When we say "this feature works", we point to: the Gherkin scenario that defines the behaviour, the automated test that proves it — including, wherever practical, a browser-driven end-to-end run that exercises the real screen — the review report confirming zero blocking findings, and the success criterion from the spec.
FAQs
common questions.
The questions clients typically raise before and during onboarding.
They draft it. A human reviews every diff. A human merges every PR. Specialist subagents do the first-pass review (per-task and feature-wide), but the final approval is always human. The pre-commit hook physically blocks commits to main. We do not auto-merge.
The same thing that happens if a human makes a mistake: another reviewer catches it. The workflow has multiple lenses for exactly this reason: per-task review, the acceptance-wiring step (which surfaces a genuine mismatch between a scenario and the built behaviour rather than forcing it to pass), feature-wide review, optional architectural review, and the human reviewer. Where we have observed mistakes, they have been caught at one of these layers.
We use enterprise-grade agent platforms with contractual protections: no client data is used to train third-party models. Specifics depend on the engagement and your tooling preferences; we walk through this with you in onboarding.
It adapts. The agentic harness (CLAUDE.md, skills, commands, agents) is tuned per project. Skills name real file paths from the codebase scan, so they only work because they're configured to your stack. The difficulty triage is calibrated to the size of your team and the maturity of your codebase.
Yes. The workflow is itself a living artefact: this document, plus the skills and commands in .claude/. If a gate is the wrong gate, we change the gate together. The principles are what we won't trade away. The mechanics are open to refinement.
We map onto yours. /feature replaces or augments your discovery phase. /tech-design replaces or augments your design phase. /implement replaces or augments your build-and-review phase. Most clients find the overlap is large; the differences are in how each phase runs (AI-assisted), not what phases exist.
The audit trail this workflow produces is unusually strong: every decision is written down with rationale, every claim about the existing system is verified before code is written, every acceptance scenario is mapped to a passing test in the final review report, and every accepted task corresponds to a real git commit. For regulated industries, we add explicit compliance gates at Phase 2 and Phase 5.
let's build together
ready to ship with more evidence and less ambiguity?
Let's talk about how the agentic SDLC fits your codebase, your team, and your delivery cadence.