This is the full developer documentation for SDLC Studio # How it compares > How SDLC Studio differs from spec-driven and single-tool approaches like Spec Kit, Kiro and OpenSpec - a factual look at the category, not a scoreboard. A wave of good tools is bringing structure to AI coding. They are worth knowing, and they solve real problems. This page is about **where SDLC Studio sits in the category** - not a scoreboard, and not a claim that the others are wrong. ## Two axes that separate the field [Section titled “Two axes that separate the field”](#two-axes-that-separate-the-field) **Agent-agnostic vs single-tool.** Some tools are one editor or one model - the discipline lives inside that product. SDLC Studio is a standard Agent Skill that Claude Code, Cursor, Codex, Copilot, opencode and Gemini all read. If you change agents, or run several, the practice travels with you. **Planning vs proving.** Spec-driven approaches get the agent to write intent down first - a spec, a plan, tasks - and build to it. That is a real step up: the model has a target. SDLC Studio adds the half that comes *after* the plan: the acceptance criteria are executable and get run, status is recomputed from the files, and an independent reviewer signs off. It does not only *align* the agent on intent; it *argues back with facts*. ## Where SDLC Studio concentrates [Section titled “Where SDLC Studio concentrates”](#where-sdlc-studio-concentrates) * **Executable acceptance criteria.** “Done” is a test that runs, not a checkbox. See [executable acceptance criteria](/concepts/executable-acceptance-criteria/). * **Independent review as a gate.** The author can never sign off their own change. See [two-role review](/concepts/two-role-review/). * **Evidence as an artefact.** The verify report, the review record, the mutation ledger - the proof outlives the sprint. * **A source of truth the tools recompute.** Claim a count and [reconcile](/concepts/reconcile-drift/) recomputes it from the files; drift fails a gate. ## Picking the right tool [Section titled “Picking the right tool”](#picking-the-right-tool) If you want a lightweight way to make an agent plan before it codes, a planning-first tool may be all you need - and SDLC Studio’s own *lite* profile occupies that space. If you want the fuller engineering discipline - executable done, independent review, evidence that survives - and you want it to work across whichever agent you drive, that is the gap SDLC Studio is built for. Note The measured evidence - including where the discipline makes no measurable difference, and where frontier models no longer fall into the traps it guards - is published in the [white paper](https://github.com/DarrenBenson/sdlc-studio/blob/main/docs/whitepaper.md), whichever way it points. # The engagement floor > Delivery flows through stories and sprints. Work becomes a sized unit with acceptance criteria before it becomes a diff - the floor that catches ad-hoc coding. The engagement floor is one rule with teeth: **no ad-hoc coding.** Work becomes a story or a bug with acceptance criteria before it becomes a diff. ## What it enforces [Section titled “What it enforces”](#what-it-enforces) * A request (a CR or RFC) is **not work** until `refine` decomposes it into sized units - the [two-backlog rule](/concepts/two-backlog/). * A commit that touches delivery-relevant files is attributed to the unit it delivers, so an understated `Affects` - a change that quietly touches more than its story admits - is caught rather than shipped invisibly. * A subject naming more than one work item carries a `Refs:` trailer per owning id, so the floor can attribute the change per unit. ## Why a floor and not a guideline [Section titled “Why a floor and not a guideline”](#why-a-floor-and-not-a-guideline) Under time pressure, the tempting move is to “just make the change” and paper over the process afterwards. A guideline that relies on the agent remembering it fails exactly when it matters. The floor is mechanical: the commit gate refuses a change with no unit behind it and names the fix, so the discipline does not depend on good intentions at the moment of stress. ## It scales down [Section titled “It scales down”](#it-scales-down) The floor is not maximal ceremony for everything. A small repo can run a **lite profile** that collapses the pipeline to PRD → story → implement; a change flows at the weight it warrants. What the floor guarantees is not heaviness - it is that *something sized and reviewable* stands behind every diff. ## See also [Section titled “See also”](#see-also) * [Two-role review](/concepts/two-role-review/) - review is independent of the author at every tier. * [Sprint planning](/concepts/sprint-planning/) - the breakdown gate that refuses an un-ready batch. # Executable acceptance criteria > Acceptance criteria carry a Verify line the tooling actually runs. A story reaches Done only when they pass - so "done" is a machine-checkable fact, not a claim. An acceptance criterion in SDLC Studio is not just prose. It carries an executable `Verify:` line, and the Done gate runs it. ## The shape of a criterion [Section titled “The shape of a criterion”](#the-shape-of-a-criterion) ```markdown ### AC1: dropping a unit removes it from the open batch - **Given** an open run whose batch contains a unit - **When** `sprint batch drop --reason "..."` runs - **Then** the unit leaves the batch and the change is recorded - **Verify:** pytest tests/test_run_state.py::BatchMutationTests::test_drop_removes_unit - **Verified:** yes (2026-07-26) ``` The Given/When/Then states the behaviour a human reads and edits. The `Verify:` line is what the machine runs. ## The verifier DSL [Section titled “The verifier DSL”](#the-verifier-dsl) A `Verify:` line names a check the tooling executes - a `pytest`/`jest`/`vitest`/`go` test, a shell command, an HTTP probe, a `grep` for a required string, and more. `verify_ac run` executes them and writes a report: ```text /sdlc-studio verify_ac run --id US0433 [APL] US0433: ac=3 pass=3 fail=0 manual=0 unspecified=0 ``` A criterion can be `manual` when a human must observe the outcome - but the tooling names the manual ones honestly rather than counting them as proven. ## Why Done is gated on it [Section titled “Why Done is gated on it”](#why-done-is-gated-on-it) `transition -> Done` is not a free edit. It reads the verify report, and a story whose executable criteria have not passed is refused. That closes the gap between “someone wrote Status: Done” and “the deliverable actually meets its criteria” - a hand-edited status walks round the tool, and conformance re-checks it as a backstop. Tip Run the criteria at **delivery**, not only at close. A `Verify:` line that points at a renamed or deleted test verifies nothing while reading as green - so a test rename is a cross-unit coupling worth catching early. ## Coverage by construction [Section titled “Coverage by construction”](#coverage-by-construction) Because a test spec maps every criterion to a named test case, coverage is built in, not reverse-engineered at the end. The acceptance criteria are the oracle that closes the build loop: the agent builds until they pass, and the close proves they did. ## See also [Section titled “See also”](#see-also) * [Two-role review](/concepts/two-role-review/) - the other condition for Done. * [Mutation testing](/concepts/mutation-testing/) - proving the criteria’s tests can actually fail. * [Reconcile & drift](/concepts/reconcile-drift/) - keeping the verify stamps honest. # Mutation testing > A test that stays green over broken code proves nothing. The mutation gate injects declared faults into the changed surface and reports killed vs survived - so a green suite is earned. A passing test suite is only reassuring if the tests can actually fail. Mutation checking proves it: inject a fault, and confirm a test dies. ## How it works [Section titled “How it works”](#how-it-works) ```text /sdlc-studio mutation run --since ``` The gate mutates the changed surface - flips a comparison, drops a guard, changes a return - and re-runs the covering tests per mutation. Each mutant is reported **killed** (a test caught it) or **survived** (nothing did). A surviving mutant is a finding: the code path it changed is not really under test. ## Honest by construction [Section titled “Honest by construction”](#honest-by-construction) * An un-mutatable surface reads **un-checked**, never as a silent pass. * A stale report reads **STALE**. * A mutation run that was refused is **named**, not quietly skipped. * The bytecode cache is purged and the mutation applied to the call site, so a same-length mutant cannot reuse a cached `.pyc` and report SURVIVED without ever running. Tip The discipline in one line: **mutate the call site, purge the cache, and assert the patch changed the file.** A mutation harness that does not do all three can report a kill it never earned. ## Where it fits [Section titled “Where it fits”](#where-it-fits) Mutation checking is the backstop under [executable acceptance criteria](/concepts/executable-acceptance-criteria/). The criteria prove the behaviour is present; the mutation check proves the *test* would notice if it broke. A guard worth trusting is a guard whose mutant was killed. ## See also [Section titled “See also”](#see-also) * [Executable acceptance criteria](/concepts/executable-acceptance-criteria/) - the tests mutation checking hardens. * [Reconcile & drift](/concepts/reconcile-drift/) - keeping the evidence honest. # Personas - who the product is for > Alan Cooper-style personas model who the product serves, defined by goals not demographics - a full cast of primary, secondary, negative, customer and served users, plus stakeholder cards with veto lines. Model the people who use the product now and the ones who will. SDLC Studio has two distinct casts, and it is worth not confusing them. **Design personas** are *who the product is for* - the users and stakeholders it serves. The [Three Amigos](/concepts/three-amigos/) are *who builds and reviews it* - your team. This page is about the first. ## Cooper-style, goal-directed [Section titled “Cooper-style, goal-directed”](#cooper-style-goal-directed) A persona is a **specific, goal-directed person the product serves - defined by its goals, not its demographics** (Alan Cooper’s model). “A 34-year-old urban professional” is a market segment; “someone who needs to reschedule three overlapping meetings from a phone on a train” is a persona. The second one tells you what to build. Every user story names the persona it serves, so the work always answers *for whom*. ## The full cast [Section titled “The full cast”](#the-full-cast) Personas are not just the one obvious user. SDLC Studio models a cast, because a real product serves and affects more people than the person clicking the button: | Role | Who they are | | ---------------- | ------------------------------------------------------------------------------------------------------- | | **Primary** | The single precise individual the interface is designed for. One Primary per interface (Cooper’s rule). | | **Secondary** | Served by the Primary’s interface, but with one extra need. | | **Supplemental** | Uses the product, but their needs are already met by serving the others. | | **Negative** | The anti-persona - explicitly *not* who you are designing for. Naming them stops scope creep. | | **Customer** | Buys or authorises the product but does not use it. | | **Served** | Affected by the product without using it at all. | Only Primary and Negative are mandatory; the rest are there when the product warrants them. This is how you model both the people using the product **now** and the ones who **will** - an aspirational Primary for where the product is going is a first-class persona, not an afterthought. ## Stakeholders and their veto lines [Section titled “Stakeholders and their veto lines”](#stakeholders-and-their-veto-lines) Beyond users, a distinct **stakeholder** card models the people who can block a release without ever opening the app - the economic buyer, a compliance or regulatory authority, ops and support, groups served but not using. Each stakeholder card carries: * **Veto lines** - what makes them block a release outright. * **The evidence they read** - what actually moves them. * A built-in arbitration rule: **a stakeholder’s goals never override the Primary persona’s interface.** The person the product is *for* wins the design argument; the stakeholder wins the release argument. ## Generating the cast [Section titled “Generating the cast”](#generating-the-cast) ```text /sdlc-studio persona create # interactive, or --from-archetype /sdlc-studio persona generate --from-prd # a cast from the PRD /sdlc-studio persona generate --stakeholders # the stakeholder panel ``` Note Archetypes are **seeds** - a role plus a one-line disposition - not fifteen ready-made characters. `persona create` grows the full, project-specific persona from a seed on demand, so your cast is about your product, not a stock library. A well-formed persona has a fixed shape - Quick Reference, Who They Are, ordered End Goals, Experience Goals, Behaviours & Context, Frustrations and a Scenario (its context and the key path the persona takes; validation scenarios live in the test specs, not the card). “Well-formed” is **structural, not evidential**: SDLC Studio checks the persona is complete, not that you did field research - that part is still your job. ## Where to next [Section titled “Where to next”](#where-to-next) * [The Three Amigos](/concepts/three-amigos/) - the team that builds and reviews the work these personas define. * [PRD](/specs/prd/) - the requirements the personas’ goals justify. * [The two-backlog model](/concepts/two-backlog/) - how a persona’s goal becomes a sized story. # Reconcile & drift > Status is recomputed from a census of the files, not asserted. Reconcile detects and fixes index, status and count drift - so what the project claims matches what exists. The status a project claims is only worth trusting if something checks it against reality. `reconcile` is that something: it recomputes state from a **census of the files** and reports where the claim and the files disagree. ## What drifts [Section titled “What drifts”](#what-drifts) * **Index rows** - an artefact with no index row, or a row pointing at a file that no longer exists. * **Status mismatches** - an index row that says Open while the file says Fixed. * **Counts** - an epic’s “3/5 stories done” checkbox that no longer matches its children. ```text /sdlc-studio reconcile # detect: read-only, reports drift /sdlc-studio reconcile apply # fix the mechanical drift /sdlc-studio reconcile --verify # also run the executable Verify: lines ``` `detect` writes nothing; `apply` fixes the mechanical drift; the index is *derived*, never hand-authored. ## Why derived beats asserted [Section titled “Why derived beats asserted”](#why-derived-beats-asserted) A spec-driven tool writes the status down and trusts the agent to keep it current. A week and ten changes later, the documents and the code have quietly diverged and nothing noticed. Reconciliation removes the trust: the count is recomputed from the files every time, and a pre-commit gate refuses a commit whose counts, index or status do not match - naming the exact drift and the fix. Note This is the difference between *aligning* the agent on intent and *arguing back with facts*. Claim a count and reconcile recomputes it. Let a document drift from the code and the gate stops you. ## See also [Section titled “See also”](#see-also) * [Executable acceptance criteria](/concepts/executable-acceptance-criteria/) - `reconcile --verify` runs them. * [Mutation testing](/concepts/mutation-testing/) - proving those tests can fail. # RFC vs CR > A change request is a request to change behaviour. An RFC is a design exploration that weighs options before committing. Both live in the discovery backlog; refine turns either into work. Both a change request and an RFC live in the [discovery backlog](/concepts/two-backlog/). The difference is what they are *for*. ## Change request (CR) [Section titled “Change request (CR)”](#change-request-cr) A **CR** is a request to change behaviour. “Add data export.” “The sprint close cannot converge.” It states what should be different and why, carries a priority and a T-shirt size, and is ready to be refined into delivery work as soon as it is accepted. Reach for a CR when the *what* is clear and the question is scheduling and sizing. ```text /sdlc-studio cr create ``` ## RFC [Section titled “RFC”](#rfc) An **RFC** is a design exploration. It weighs options against each other before anything is committed - the problem, the alternatives with their trade-offs, and a recommendation. It is the place to think, so that the decision is recorded with the reasoning that produced it, not just the outcome. Reach for an RFC when the *how* is genuinely open, or the decision is expensive to reverse. ```text /sdlc-studio rfc create ``` ## Both cross the same bridge [Section titled “Both cross the same bridge”](#both-cross-the-same-bridge) Whichever you file, it becomes delivery work the same way: `refine` decomposes it into sized epics and stories, and it reaches its terminal status only when those children are Done. A CR goes **Complete**; an RFC reaches its own terminal. Neither is closed by hand - both are derived from what shipped. ## See also [Section titled “See also”](#see-also) * [The two-backlog model](/concepts/two-backlog/) - the discovery/delivery split both live in. # Sprint planning & autosprint > How a delivery batch becomes a sprint - the breakdown gate, capacity and appetite, the test strategy, and the goal-driven autosprint loop that closes with reconcile and review. A sprint in SDLC Studio is a **batch of delivery work driven to a goal**, opened deliberately and closed with ceremony. Planning is where the batch is chosen, sized against reality, and gated before any code is written. ## The breakdown gate [Section titled “The breakdown gate”](#the-breakdown-gate) `sprint plan` refuses a batch that is not ready: an un-refined request, an un-sized unit, a story whose acceptance criteria are still placeholders. The refusal is the point - it stops a plan filling with work nobody scoped. ```text /sdlc-studio sprint plan --stories Ready --epic EP0001 --goal done --write ``` `--write` opens the run: it stamps a run id, the start time, the approved batch and a token baseline, and it archives any previous run. Before that, `plan` runs a `git fetch` and an origin-drift pre-flight, so you never plan against a stale checkout. ## Goal ladder [Section titled “Goal ladder”](#goal-ladder) A plan targets a rung: `triage -> plan -> design -> done`. Run a single rung for a checkpoint (groom the batch, produce a design), or `--goal done` to take it all the way. The rung is recorded on the run, so the close can say what the sprint was actually for. ## Capacity and appetite [Section titled “Capacity and appetite”](#capacity-and-appetite) The plan measures the batch against a **standing appetite** (the sprint’s capacity in units and minutes) and records the **accepted** appetite it was planned at. If a batch exceeds the standing appetite, the overage is flagged and the run is reported against the standing figure - so a decision to take on more than fits is written down, never hidden by quietly raising the ceiling. ## The test strategy [Section titled “The test strategy”](#the-test-strategy) The plan derives, from your TSD, which risk areas the batch touches and which coverage the TSD demands that the batch would not deliver - so gaps are named at plan time, not discovered at review. ## Autosprint - the goal-driven loop [Section titled “Autosprint - the goal-driven loop”](#autosprint---the-goal-driven-loop) An agent runs in a loop that cannot judge its own exit condition. The lifecycle has always been that loop: specify, build, validate against the specification, reconcile, repeat - with acceptance criteria as the test that closes it. `sprint --goal done` (autosprint) runs it: a prioritised batch, built and verified rung by rung, stopping when its acceptance criteria are met, closing with a reconcile and review. Note This is the lineage Test-Driven -> Behaviour-Driven -> Eval-Driven -> **Goal-Driven** Development. You set the goal and the criteria; the agent drives the proven lifecycle to it, and the close proves it got there. ## The close [Section titled “The close”](#the-close) `sprint close` is one deterministic chain: goal verdict, retro validate and extract, lessons summary, the close gate (reconcile, review currency, the retro), a handoff if the run stopped short, and the review anchor. Past the two-role threshold, `--apply-signoff` fans an operator’s sign-off into per-unit Done transitions. See [two-role review](/concepts/two-role-review/). ## See also [Section titled “See also”](#see-also) * [The two-backlog model](/concepts/two-backlog/) - where a sprint’s batch comes from. * [The engagement floor](/concepts/engagement-floor/) - why ad-hoc coding is refused. # The Three Amigos > Your own engineering team - Product, Engineering and QA - who specify together, build apart and review independently. Each owns one spec document, each does the work and reviews it, and no seat ever signs off its own work. The “Three Amigos” is a long-standing software practice: before work starts, three viewpoints look at it together - **Product** (what and why), **Engineering** (how), and **QA** (what if it goes wrong). SDLC Studio ships that team as real, named people and wires them into the lifecycle, so the practice happens by default instead of when someone remembers to book the meeting. ## Meet the team [Section titled “Meet the team”](#meet-the-team) | Amigo | Viewpoint | Owns the | | ---------------------- | ------------ | ------------------ | | **Lena** - Product | *What & why* | [PRD](/specs/prd/) | | **Dani** - Engineering | *How* | [TRD](/specs/trd/) | | **Sam** - QA | *What if* | [TSD](/specs/tsd/) | Each amigo owns one of the three specification documents and reviews every change from that angle - Product for user value and scope, Engineering for feasibility and TRD alignment, QA for testability and TSD alignment. ## Do the work, then review the work - never the same instance [Section titled “Do the work, then review the work - never the same instance”](#do-the-work-then-review-the-work---never-the-same-instance) Each amigo has a **dual render**. It *does* the work (writes the story, plans the code) and it *reviews* the work - but **never as the same instance on the same unit**. A seat never signs off its own homework. Each is consulted as an independent subagent, and their views are synthesised, so a blind spot in one is caught by another. Tip This is the whole idea in one line: **specify together, build apart, review independently.** The people who agreed what to build are not the single point of failure who also decides it is done. ## Grown from your project, not shipped identically [Section titled “Grown from your project, not shipped identically”](#grown-from-your-project-not-shipped-identically) Ask for your team and it is generated from *your* project: ```text /sdlc-studio persona generate --team ``` It reads the PRD, the stack and the risk signals, asks the few questions it cannot infer (risk class, compliance regime), and writes named seats whose non-negotiables come from your domain - a payments QA paranoid about idempotency, a games QA about frame budgets, a security seat that vetoes card data outside the vault. The seat that argued for a requirement is the one who refuses to sign off work that misses it. Edit a card and generation treats it as authored - it is never overwritten. It does not make the model smarter, and SDLC Studio does not claim it does. It makes the review **cover the risks this project actually has**, instead of a generic role-prompt walking past them. ## When they are consulted [Section titled “When they are consulted”](#when-they-are-consulted) The Amigos are consulted **automatically** at the ceremonies where a decision is expensive to get wrong - creating an epic, creating a story, planning the code for a story, and fixing a bug. The decomposition commands bake the consult in: `refine` is engineering-led, `triage` is QA-led. You can also call them by hand: ```text /sdlc-studio consult team ``` Controls: `--with-personas` / `--skip-personas`, `--persona ` for one voice, and `--quick` / `--thorough` for depth. ## How this becomes a hard gate [Section titled “How this becomes a hard gate”](#how-this-becomes-a-hard-gate) The Amigos’ review feeds the [two-role review gate](/concepts/two-role-review/), which separates two jobs that must never be the same actor: * The **adversarial reviewer** - an amigo’s review render - always runs, and its pass is recorded as **evidence**. It is input to the sign-off, never the sign-off itself: the author’s own automation approving its own work is not a review. * The **reviewer of record** - an independent principal (the operator, or a named delegate in a separate trust boundary) - records the sign-off. A delegate drawn from the author’s own session is refused, loudly. Past a configured point in a project’s life, a unit needs **both** records - the adversarial evidence and an independent sign-off - before it can reach Done. Done means signed off, by someone who did not write it. ## Where to next [Section titled “Where to next”](#where-to-next) * [Two-role review & sign-off](/concepts/two-role-review/) - the independence gate the Amigos run under. * [Personas](/concepts/personas/) - the other cast: who the product is *for*. * [The specification layer](/specs/overview/) - the three documents the Amigos each own. # The two-backlog model > A request is not work. In SDLC Studio a discovery backlog of change requests and RFCs becomes delivery work - sized epics, stories and bugs - only via refine. This is the biggest shift in v5. The single biggest change to how SDLC Studio is used: **there are two backlogs, and a request only becomes work by crossing between them.** ## The two backlogs [Section titled “The two backlogs”](#the-two-backlogs) * **Discovery backlog** - *what someone wants.* Change requests (**CRs**) and RFCs. An idea, a bug report, a design question. Cheap to file, unsized, not yet committed. * **Delivery backlog** - *what the team will build.* Epics, stories and bugs, each carrying acceptance criteria and a size. This is the sprint’s raw material. A request in the discovery backlog is **not work**. It becomes delivery work only when [`refine`](#refine) decomposes it into sized units. That crossing is the whole point. ```plaintext Discovery backlog Delivery backlog ───────────────── ──────────────── CR: "export my data" ─refine─▶ EP: Data export RFC: "should we cache?" ├─ US: request + queue (3 pts, ACs) └─ US: deliver the file (2 pts, ACs) ``` ## Why the split exists [Section titled “Why the split exists”](#why-the-split-exists) Merge the two and every idea looks like committed work. A one-line “wouldn’t it be nice” sits in the same list as a sized, accepted story, and planning quietly treats them alike - so the plan fills with things nobody scoped, estimates collapse to a floor, and “the backlog” stops meaning anything. Keeping them separate makes one rule enforceable: **you cannot plan a sprint over an un-refined request.** The breakdown gate refuses it. A change that arrives without a sized unit behind it is caught, not shipped. ## `refine` - the crossing [Section titled “refine - the crossing”](#refine---the-crossing) []() `refine` reads a CR or RFC and produces the delivery units that satisfy it: an epic and its stories (or bugs), each with Given/When/Then acceptance criteria and a point size relative to work you have already delivered. ```text /sdlc-studio refine --id CR0421 ``` Grooming is real work, and it sits on top of the points. A freshly refined story is a scaffold: its acceptance criteria are placeholders until you author them against the specific slice. Refine first, then groom the criteria, then plan. Note A request reaches its terminal status (a CR is **Complete**, an RFC has its own terminal) only when the delivery units it decomposed into are all Done. You do not close a CR by hand - it is **derived** from its children. Delivery drives discovery, never the other way round. ## Bugs and issues [Section titled “Bugs and issues”](#bugs-and-issues) * A **bug** is delivery work: a defect with a severity and a size, filed straight into the delivery backlog. It is fixed through a story-like path and its Done gate. * An **issue** is a discovery-tier report you have not yet triaged. `triage` turns an issue into bugs (or closes it). Like a CR, an issue is not work until it is decomposed. ## Sizing is compulsory [Section titled “Sizing is compulsory”](#sizing-is-compulsory) Every delivery unit carries a size - modified Fibonacci story points on a story or bug, a T-shirt size on a CR/RFC/epic. Sizing is what makes the estimate a number rather than a guess, and it is what lets the planner see that two units touch the same file and cannot run in parallel. The tooling **refuses** an un-sized unit into a plan; a bug’s severity is its urgency, a different axis from its size. ## What this means day to day [Section titled “What this means day to day”](#what-this-means-day-to-day) 1. Someone has an idea → file a **CR** (or an **RFC** for a design question). Cheap, unsized. 2. You accept it → **`refine`** it into an epic + sized stories, then **groom** their acceptance criteria. 3. Now it is delivery work → **`sprint plan`** a batch of it, build, verify, review, close. 4. The CR goes **Complete** automatically when its stories are Done. ## See also [Section titled “See also”](#see-also) * [RFC vs CR](/concepts/rfc-vs-cr/) - which kind of request to file. * [Sprint planning](/concepts/sprint-planning/) - how a delivery batch becomes a sprint. * [Executable acceptance criteria](/concepts/executable-acceptance-criteria/) - what grooming produces. # Two-role review & sign-off > The author of a change can never record its sign-off. An adversarial reviewer files findings as evidence; a reviewer of record ratifies. The separation is mechanical, not a convention. Review in SDLC Studio is **independent of the author, by construction**. This is a gate, not a guideline. ## Two roles, never merged [Section titled “Two roles, never merged”](#two-roles-never-merged) * **The adversarial reviewer** - a fresh context that did not write the code. It runs an adversarial pass, tries to break the change, and files findings as *evidence*. It does not approve. * **The reviewer of record** - the operator, or a named delegate in a separate trust boundary. It ratifies the evidence and records the sign-off. The author is neither. A self-review never clears the Done gate: the check compares the reviewer id against the author id, and a unit whose reviewer equals its author - or that has no recorded author - fails. ## Why mechanical [Section titled “Why mechanical”](#why-mechanical) Volume is the problem. When an agent authors most of the change, “please have someone review it” collapses under load, and the tempting shortcut is to let the author bless their own work. Making the separation mechanical removes the shortcut: the tooling refuses to record a sign-off the author controls, so the human ratifies *evidence someone else produced* rather than re-reading every line. ## The forward-only threshold [Section titled “The forward-only threshold”](#the-forward-only-threshold) A project sets `review.two_role_after` in its config. A delivery unit numbered past that threshold reaches Done only with an independent reviewer-of-record sign-off; earlier units keep the project’s prior behaviour. The discipline applies forward, so turning it on does not retroactively block delivered work. ## How a close uses it [Section titled “How a close uses it”](#how-a-close-uses-it) ```text /sdlc-studio sprint close --apply-signoff --principal "you" ``` `--apply-signoff` fans the reviewer-of-record’s approval into a per-unit sign-off for each story in the batch, transitions each to Done, and records the evidence. The adversarial pass is recorded separately (a sprint-level review can cover a batch as its evidence). Caution Be honest about what is mechanical and what is discipline. The tool enforces the mechanical case: a sign-off whose reviewer id equals the author id never clears the gate. Whether a *delegate* is genuinely independent - in a separate trust boundary, not one the author controls - is a judgement the record makes **auditable**, not an unforgeable lock. The value is that self-review becomes a deliberate, logged exception instead of the silent default. ## See also [Section titled “See also”](#see-also) * [Executable acceptance criteria](/concepts/executable-acceptance-criteria/) - the other half of Done: the criteria must pass *and* the sign-off must land. * [The engagement floor](/concepts/engagement-floor/) - why review is independent of the author at every tier. # FAQ > Plain-language answers to the common questions - what PRD, epic, story and acceptance criteria mean, the two-backlog model, refine vs triage, and how Done is decided. ## Do I need to know the commands? [Section titled “Do I need to know the commands?”](#do-i-need-to-know-the-commands) No. Say what you want in plain language - “plan the next sprint”, “extract the spec from this code”. The commands shown throughout the docs are the explicit form for people who prefer them. ## What do PRD, epic, story and acceptance criteria mean? [Section titled “What do PRD, epic, story and acceptance criteria mean?”](#what-do-prd-epic-story-and-acceptance-criteria-mean) A **PRD** is the product requirements - what to build and why. **Epics** are the big chunks of that work; **stories** are the small, testable pieces. **Acceptance criteria** are the checkable conditions that say a story is done. SDLC Studio writes them all as plain files you can read and edit. ## What is the two-backlog model? [Section titled “What is the two-backlog model?”](#what-is-the-two-backlog-model) A **discovery** backlog holds requests (change requests and RFCs) - ideas, not committed work. A **delivery** backlog holds sized epics, stories and bugs. A request becomes delivery work only when `refine` decomposes and sizes it. See [the two-backlog model](/concepts/two-backlog/). ## Refine or triage - what is the difference? [Section titled “Refine or triage - what is the difference?”](#refine-or-triage---what-is-the-difference) `refine` turns an accepted **CR or RFC** into sized delivery work (epics + stories). `triage` turns an untriaged **issue** into bugs (or closes it). Both cross a request from discovery into delivery. ## Issue or bug - which do I file? [Section titled “Issue or bug - which do I file?”](#issue-or-bug---which-do-i-file) A **bug** is delivery work: a defect with a severity and a size, fixed through its Done gate. An **issue** is a discovery-tier report you have not yet triaged into bugs. ## How is “Done” decided? [Section titled “How is “Done” decided?”](#how-is-done-decided) Two conditions. The story’s executable acceptance criteria must **pass** (`verify_ac` runs them), and - past the two-role threshold - an **independent reviewer** who is not the author must sign it off. You cannot simply write `Status: Done`; conformance re-checks it. See [executable acceptance criteria](/concepts/executable-acceptance-criteria/) and [two-role review](/concepts/two-role-review/). ## Greenfield or brownfield - which path? [Section titled “Greenfield or brownfield - which path?”](#greenfield-or-brownfield---which-path) Greenfield is a new project: `/sdlc-studio init` then `prd create`. Brownfield is existing code: `/sdlc-studio prd generate`, which extracts a spec and validates it by running tests against your real implementation. ## Where does it put files? [Section titled “Where does it put files?”](#where-does-it-put-files) Plain markdown under `sdlc-studio/` in your project, so everything is reviewable and version-controlled - `prd.md`, `epics/`, `stories/`, `bugs/`, `reviews/`, and more. Generated test code goes under `tests/`. ## Which agents does it work in? [Section titled “Which agents does it work in?”](#which-agents-does-it-work-in) Claude Code, Cursor, OpenAI Codex, GitHub Copilot, opencode and Gemini CLI - one install covers them. It is a standard Agent Skill. See [Works with your agent](/integrations/). ## Is it an npm package or an SDK? [Section titled “Is it an npm package or an SDK?”](#is-it-an-npm-package-or-an-sdk) No. It is a curl-installed Agent Skill - a folder of instructions, templates and scripts. There is nothing to import into your code, no account, and no server. ## What is the sprint loop? [Section titled “What is the sprint loop?”](#what-is-the-sprint-loop) `sprint` drives a prioritised batch of work along a goal ladder (`triage → plan → design → done`), stops when its acceptance criteria are met, and closes with a reconcile and review. Run a single rung for a checkpoint, or `--goal done` to take it all the way. See [sprint planning](/concepts/sprint-planning/). ## How do I upgrade an existing project? [Section titled “How do I upgrade an existing project?”](#how-do-i-upgrade-an-existing-project) Re-run the installer, or `/sdlc-studio skill-update`. It is a drop-in - existing projects keep working, and the v5 workflow gates are off until you turn them on. See [upgrading](/upgrading/). # For AI agents > The exact steps an AI agent follows to install SDLC Studio into a project and adopt the discipline. Machine-readable llms.txt and per-page markdown are provided. If you are an AI coding agent evaluating or installing SDLC Studio, this page is for you. A machine-readable index of the whole site is at **[/llms.txt](/llms.txt)**, with the full text at **[/llms-full.txt](/llms-full.txt)**. Every page is available as markdown by appending nothing special - request the page and read its content. ## What SDLC Studio is [Section titled “What SDLC Studio is”](#what-sdlc-studio-is) An open Agent Skill (the `SKILL.md` format) that runs the full software development lifecycle: a discovery backlog of requests (CRs/RFCs) becomes sized delivery work (epics, stories, bugs with acceptance criteria) via `refine`; a sprint plans, builds under TDD, verifies against executable acceptance criteria, and closes with an independent two-role review. It is agent-agnostic and runs entirely in the user’s repository. ## Install it into a project [Section titled “Install it into a project”](#install-it-into-a-project) Caution Confirm with the human operator before installing - this writes to their machine. 1. **Install the skill.** ```bash curl -fsSL https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.sh | bash -s -- --target auto ``` Or `--local` for the current project only. The entry point is `.claude/skills/sdlc-studio/SKILL.md` (name, description with use-when triggers, `allowed-tools`). Requires Python 3.10+. 2. **Orient before acting.** Read `sdlc-studio/reviews/LATEST.md` if it exists, then run `/sdlc-studio status` and `/sdlc-studio hint`. Fetch before trusting local state: a clone can be behind its remote. 3. **Adopt the discipline.** Do not hand-author `_index.md` files or hand-allocate ids. Create artefacts with `scripts/artifact.py new` (collision-free id + index row). A story reaches Done only when its executable acceptance criteria pass and an independent reviewer - not you, the author - signs it off. ## The rules you must not walk round [Section titled “The rules you must not walk round”](#the-rules-you-must-not-walk-round) * **Two backlogs.** A request is not work until `refine` decomposes it into sized units. * **Executable done.** `transition -> Done` is gated on the verify report. A hand-edited `Status: Done` is caught by conformance. * **Independent review.** A self-review never clears the Done gate. The reviewer id must differ from the author id. * **Reconcile, do not assert.** The index is derived from the files; `reconcile` syncs it. ## Zero-setup evaluation [Section titled “Zero-setup evaluation”](#zero-setup-evaluation) To evaluate the tool on a repository without changing it: ```text /sdlc-studio audit --profile repo ``` A read-only, refute-panel-verified audit of the host repo; findings are filed as Bug/CR artefacts, with remediation-only handling for secrets. ## See also [Section titled “See also”](#see-also) * [Getting started](/getting-started/) - the human-facing version of this. * [The two-backlog model](/concepts/two-backlog/) and [executable acceptance criteria](/concepts/executable-acceptance-criteria/) - the two rules most agents get wrong first. # Getting started > Install SDLC Studio in one line, learn the v5 mental model, and start your first project - new idea or existing code. SDLC Studio installs as an [Agent Skill](https://agentskills.io) - a folder of instructions, templates and deterministic scripts that your AI coding agent reads. There is nothing to import into your code, no account, and no server. It runs entirely in your own repository. ## The mental model (read this first) [Section titled “The mental model (read this first)”](#the-mental-model-read-this-first) If you last used SDLC Studio when it was mostly human-driven, or you have only ever vibe-coded, three ideas are worth thirty seconds before you install. 1. **Two backlogs, not one.** A **discovery** backlog holds requests - change requests (CRs) and RFCs. A request is not work yet. It becomes **delivery** work - epics, stories and bugs, each with acceptance criteria - only when `refine` decomposes and sizes it. This one rule keeps “ideas” and “committed, sized work” from ever being the same list. 2. **Done is proven, not declared.** A story reaches Done only when its executable acceptance criteria pass **and** an independent reviewer - never the author - signs it off. The tools recompute status from the files, so you cannot simply write `Status: Done` and have it stick. 3. **You are in the lead; the tooling holds the discipline.** You set the goal and approve each step. The agent carries the cost of the ceremony - authoring the spec, keeping it current, running the checks - so the discipline stays affordable. ## Install [Section titled “Install”](#install) []() * macOS / Linux ```bash curl -fsSL https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.sh | bash ``` * Windows ```powershell irm https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.ps1 | iex ``` * Every agent you have ```bash curl -fsSL https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.sh | bash -s -- --target auto ``` You do this once. It installs into your agent’s skills directory; `--list-targets` shows the map, `--local` installs into just the current project. See [Works with your agent](/integrations/) for the per-agent detail, and [For AI agents](/for-ai-agents/) if an agent is doing the install. Tip Installing in a sensitive environment? Pin a tagged release and make the checksum mandatory: `... | SDLC_STUDIO_REQUIRE_CHECKSUM=1 bash -s -- --version `. **Requirements:** Python 3.10+ for the bundled scripts (standard library only; PyYAML is the one optional dependency, needed only if you set a project `.config.yaml`). The `gh` CLI only for GitHub sync. Whatever test runners your acceptance criteria invoke. ## Your first project: one command [Section titled “Your first project: one command”](#your-first-project-one-command) You do not need to know the pipeline order. **`init guided`** walks you from an empty (or existing) repo all the way to a ready first sprint plan, one stage at a time: ```text /sdlc-studio init guided ``` It works out for itself whether you are **greenfield** (nothing yet) or **brownfield** (existing code) from the files in your repo, and forks each stage accordingly - you never have to choose `create` versus `generate`. It walks these seven stages: 1. **agents** - seeds `AGENTS.md` and `CLAUDE.md` so every AI agent you use reads the same discipline. 2. **prd** - the [PRD](/specs/prd/): interviewed from scratch on greenfield, reverse-engineered from your code on brownfield. 3. **trd** - the [TRD](/specs/trd/), generated from the PRD. 4. **tsd** - the [TSD](/specs/tsd/), the test strategy the sprint plan will later read. 5. **personas** - your project’s [team](/concepts/three-amigos/), grown from the PRD and its risk signals for you to accept or edit. 6. **decompose** - the PRD broken into epics and sized stories. 7. **plan** - your first sprint plan. Onboarding ends exactly where delivery begins. Each stage **drafts** its document for you to review, then advances only when you confirm: ```text /sdlc-studio init guided --confirm # accept the drafted stage and move on /sdlc-studio init guided --skip # skip this stage (a recorded decision) /sdlc-studio init guided --reset # start the walk again ``` Tip It is **resumable**. Progress is checkpointed, so you can stop after any stage and pick up later - `status` and `hint` keep pointing you back at `init guided` and naming the next stage until you reach that first plan. Prefer to try before you commit to anything? On existing code, `/sdlc-studio audit --profile repo` runs a read-only, refute-panel-verified audit of the repo and files what it finds - zero setup. ## Never lose your place [Section titled “Never lose your place”](#never-lose-your-place) ```text /sdlc-studio status # the at-a-glance dashboard: what is specified, built, proven, checked /sdlc-studio hint # the single next thing to do ``` While guided onboarding is under way, `hint` points you straight back at the next stage; once you are past the first plan it becomes the ordinary next-step ladder. Either way you do not need to memorise commands - say what you want in plain language (“plan the next sprint”, “extract the spec from this code”) and the agent maps it. ## Where to next [Section titled “Where to next”](#where-to-next) * **[Greenfield walkthrough](/walkthrough/greenfield/)** - build a task-management app end to end. * **[Brownfield walkthrough](/walkthrough/brownfield/)** - adopt an existing app the same way. * **[The two-backlog model](/concepts/two-backlog/)** - the single biggest shift, explained properly. * **[FAQ](/faq/)** - PRD, epic, story, acceptance criteria, and the rest, in plain language. # Works with your agent > One install, six agents. Per-harness install locations and how to invoke SDLC Studio in Claude Code, Cursor, OpenAI Codex, GitHub Copilot, opencode and Gemini CLI. SDLC Studio is a standard [Agent Skill](https://agentskills.io) - a `SKILL.md` and a folder of deterministic scripts. Any agent that reads the skill format runs the same discipline. That is the whole point of *agent-agnostic*: switch agents, keep the practice. ## One install [Section titled “One install”](#one-install) ```bash curl -fsSL https://raw.githubusercontent.com/DarrenBenson/sdlc-studio/main/install.sh | bash -s -- --target auto ``` `--target auto` installs into every agent it finds. `--list-targets` shows the map; `--local` installs into just the current project; the installer refreshes other copies it finds (opt out with `--no-sweep`). ## Where it installs, and how to invoke it [Section titled “Where it installs, and how to invoke it”](#where-it-installs-and-how-to-invoke-it) | Agent | Global | Project-local | Invoke | | ---------------- | --------------------------- | ------------------ | ------------------------------------------ | | Claude Code | `~/.claude/skills` | `.claude/skills` | `/sdlc-studio` or model-invoked | | OpenAI Codex | `~/.agents/skills` | `.agents/skills` | `$sdlc-studio`, `/skills` | | Gemini CLI | `~/.gemini/skills` | `.gemini/skills` | auto via description; `/skills` to confirm | | opencode | `~/.config/opencode/skills` | `.opencode/skills` | auto via skill tool | | GitHub Copilot | (repo-scoped) | `.github/skills` | from chat | | Cursor / generic | `~/.agents/skills` | `.agents/skills` | via `AGENTS.md` | The generic `agents` location (`~/.agents/skills` / `.agents/skills`) is read by Codex, Gemini, Copilot and Cursor - so a single install covers the tools that share it. ## Requirements [Section titled “Requirements”](#requirements) * **Python 3.10+** for the bundled scripts (standard library only). PyYAML is the one optional dependency, needed only if you set a project `.config.yaml`; without it the scripts degrade to built-in defaults with a one-line warning, never a crash. * **`gh` CLI** only for the GitHub sync commands. * Whatever **test runners** your acceptance criteria invoke (pytest, vitest, go, …). ## Multi-agent, together [Section titled “Multi-agent, together”](#multi-agent-together) Because every project mints collision-free artifact ids, several people and agents on different machines can file bugs, stories and change requests concurrently and never clash. No coordination, no renumber-on-merge. See [the two-backlog model](/concepts/two-backlog/) for how that work is organised. # The specification layer > PRD, TRD and TSD are the three documents that turn an idea into buildable, testable work - one owned by each of the Three Amigos. The PVD sits above them to coordinate a product built from many repos. Before a single story is planned, SDLC Studio writes down **what** to build, **how** to build it, and **how you will know it works**. Three documents, one owned by each member of your team: | Document | Answers | Owned by (Three Amigos) | | ----------------------------------------------- | --------------------------- | -------------------------- | | **[PRD](/specs/prd/)** - Product Requirements | *What & why* | Lena, the Product seat | | **[TRD](/specs/trd/)** - Technical Requirements | *How* | Dani, the Engineering seat | | **[TSD](/specs/tsd/)** - Test Strategy | *What if - how we prove it* | Sam, the QA seat | These are the biggest levers you can pull. Every epic, story and acceptance criterion downstream is only as good as the three documents it descends from, and each one is a real artefact you can read, edit and version - plain Markdown under `sdlc-studio/`, not a hidden prompt. ## How they stack [Section titled “How they stack”](#how-they-stack) ```text PRD (what & why) sdlc-studio/prd.md │ ▼ TRD (how) sdlc-studio/trd.md │ ▼ TSD (how we prove it) sdlc-studio/tsd.md │ ▼ Personas → Epics → Stories → Code ``` The TRD is gated on the PRD (you cannot design a solution to a problem you have not stated), and the TSD sets the coverage targets the whole pipeline is later measured against. The PRD is the richest input `persona generate --team` reads to grow your project’s team (the generator can also run standalone from a bare repo), and all three feed the `epic` and `story` decomposition into sized, testable work. ## Create, generate, review [Section titled “Create, generate, review”](#create-generate-review) Every spec document supports the same modes, and which of the first two you use is decided by whether the code already exists: * **`create`** - **greenfield.** An interactive conversation builds the document from scratch. Best when you are starting something new. * **`generate`** - **brownfield.** SDLC Studio reads your existing codebase and reverse-engineers the document, marking every inferred claim with a confidence marker - `[HIGH]` / `[MEDIUM]` / `[LOW]` on the PRD, and `[INFERRED]` on the TRD and TSD. * **`review`** - re-check a document against the current code and update it, so a spec cannot silently drift from reality. Caution A **generated** spec is a hypothesis, not the truth. It is worthless until its tests pass against the existing code - SDLC Studio marks the confidence of every inferred line so you can see what still needs proving. This is the difference between a migration blueprint and documentation. ## One product, many repos: the PVD [Section titled “One product, many repos: the PVD”](#one-product-many-repos-the-pvd) A single repository never needs more than a PRD - its PRD is the top of the tree. When several repos form **one product** (shared features, an inter-repo API, coordinated releases), the coordination itself needs an owner. That is the [**Product Vision Document**](/specs/pvd/): the product layer above the PRD that maps each product feature to the repo that owns it, kept honest by a read-only projection into every child repo. ## Where to next [Section titled “Where to next”](#where-to-next) * [PRD - Product Requirements](/specs/prd/) - what to build and why. * [TRD - Technical Requirements](/specs/trd/) - how it is built. * [TSD - Test Strategy](/specs/tsd/) - how you prove it works. * [PVD - Product Vision](/specs/pvd/) - coordinating a multi-repo product. * [The Three Amigos](/concepts/three-amigos/) - the team that owns and reviews each document. # PRD - Product Requirements Document > The PRD captures what to build and why. Author it interactively for a new project, or reverse-engineer it from an existing codebase with confidence markers. Owned by the Product seat of the Three Amigos. The **Product Requirements Document** is the top of the tree for a single repo: *what* the product does and *why*. It is owned by **Lena, the Product seat** of the [Three Amigos](/concepts/three-amigos/), and it is the richest input every later step reads - personas, epics, stories and the closing review all trace back to it. It lives as plain Markdown at `sdlc-studio/prd.md`. ## Three modes [Section titled “Three modes”](#three-modes) * create (greenfield) An interactive conversation builds the PRD from scratch: ```text /sdlc-studio prd create ``` 1. You are asked about the project name, purpose and target users. 2. You describe features one by one, with acceptance criteria. 3. You are asked about non-functional requirements - performance, security, scale. 4. The PRD is written to `sdlc-studio/prd.md`. Best for new projects. * generate (brownfield) SDLC Studio reads your existing code and reverse-engineers the requirements: ```text /sdlc-studio prd generate ``` 1. An explore pass reads your routes, components, tests and config. 2. Features are extracted and their acceptance criteria inferred. 3. The PRD is written with **confidence markers** - `[HIGH]`, `[MEDIUM]`, `[LOW]` - so you can see what is certain and what is a guess. Best for documenting a codebase that already exists. `generate --force` replaces an existing PRD. * review Re-check the PRD against the current codebase and update each feature’s status: ```text /sdlc-studio prd review ``` Every feature is marked **Complete**, **Partial**, **Stubbed**, **Broken** or **Not Started**, and features found in the code but missing from the PRD are surfaced. This is how the document stays honest after a few sprints. Caution A generated PRD is an extraction, not a specification, until its acceptance criteria pass against the code. Treat `[LOW]`-confidence lines as questions to answer, not facts to trust. ## What it captures [Section titled “What it captures”](#what-it-captures) The PRD is a structured document, not a free-form brief. Its sections: 1. Project Overview 2. Problem Statement 3. Feature Inventory 4. Functional Requirements 5. Non-Functional Requirements 6. AI/ML Specifications (when applicable) 7. Data Architecture 8. Integration Map 9. Configuration Reference 10. Test Coverage Analysis 11. Technical Debt Register 12. Documentation Gaps 13. Recommendations 14. Open Questions You do not have to fill every section for a small project - the point is that the shape is there, so nothing important is silently missing. ## What you can do with it [Section titled “What you can do with it”](#what-you-can-do-with-it) * **Grow your team from it.** The PRD is the strongest input `persona generate --team` will ever have - it reads the PRD to propose a project-specific engineering team and a stakeholder panel. * **Decompose it into work.** `epic` and `story` read the PRD to produce the delivery backlog, each story naming the persona it serves. * **Keep it true.** `prd review` re-checks feature status against the code every few sprints, so the document tracks reality instead of drifting into fiction. ## Where to next [Section titled “Where to next”](#where-to-next) * [TRD - Technical Requirements](/specs/trd/) - how the PRD’s *what* becomes a *how* (the TRD is gated on the PRD). * [Personas](/concepts/personas/) - the users the PRD’s features serve. * [The Three Amigos](/concepts/three-amigos/) - how Lena, Dani and Sam each review the spec from their angle. * [The two-backlog model](/concepts/two-backlog/) - how requirements become sized, planned work. # PVD - Product Vision Document (larger projects) > When several repos form one product, the Product Vision Document is the layer above the PRD - a single writable master that maps every product feature to its owning repo and coordinates a centralised vision, projected read-only into each child repo. Most vibe-coding and spec-driven tools assume one repo, one product. Real products are rarely that tidy - a web app, an API, a mobile backend and a shared library can be one product to a customer and four repositories to the team. The **Product Vision Document** is the layer above the PRD that holds that product together with a **centralised vision**. Note A single repo never needs a PVD - its PRD is the top of the tree. Reach for a PVD when several repos form one product: shared features, an inter-repo API, coordinated releases - and the coordination is currently living as stale prose in review notes and handovers. ## What it is [Section titled “What it is”](#what-it-is) The PVD **coordinates and traces - it never re-specifies.** It does not restate any feature; it points at the per-repo PRD that owns the spec. There is one writable master, read-only everywhere else, kept honest by a projection that fails loud if it drifts. * **One writable master:** `sdlc-studio/product/pvd.md`, in a product (anchor) repo, owned by the **Product Manager** persona - distinct from the Product Owner who owns each repo’s PRD. * **The manifest:** `sdlc-studio/product/manifest.yaml` lists each child repo by short id, local path and git URL. It is a coordination manifest, not a hard dependency: a repo that is not on disk yields an *unresolved* marker rather than a silent pass. * **The feature map:** in the master, each product feature `PF####` maps to its owning repo and the CR / RFC / PRD artefact that lands it. ## The workflow [Section titled “The workflow”](#the-workflow) ```text /sdlc-studio pvd create # render the tiered master into the product repo /sdlc-studio pvd sync # project the master read-only into each child repo /sdlc-studio pvd drift # fail loud if a child projection has gone stale ``` 1. **`pvd create`** renders the master into `sdlc-studio/product/pvd.md`. 2. List each repo in `manifest.yaml`. 3. Map each `PF####` to its owning repo and the artefact that delivers it. 4. **`pvd sync`** projects the master read-only into every child repo (a symlink in production, a synced copy in development); **`pvd drift`** is the standing seam-check that fails if a projection goes stale. ## Proportionality: two tiers [Section titled “Proportionality: two tiers”](#proportionality-two-tiers) * **Lean (always):** vision & scope, strategic goals, the master feature inventory, cross-repo dependencies, API contract commitments, a risk & conflict register, and a decisions log. * **Opt-in (large multi-team products only):** the master / domain / team PVD topology tree, G1–G5 governance stage-gates, and formal release coordination. Delete what you do not use - the tool does not want you carrying empty ceremony. Caution The feature map is reviewed by humans in the normal review cadence, **not machine-checked** - an automated cross-repo traceability check was tried and deliberately retired. The PVD makes the coordination visible and owned; it does not pretend to prove it. ## PVD vs the `project` command [Section titled “PVD vs the project command”](#pvd-vs-the-project-command) Do not confuse the two. The `project` command is **single-repo** orchestration - it builds a dependency graph of one repo’s epics and drives them to done in order. The **PVD is the multi-repo layer** - coordinating the separate products that together form one. Different scope, different jobs. ## Where to next [Section titled “Where to next”](#where-to-next) * [PRD](/specs/prd/) - the per-repo document the PVD coordinates but never restates. * [The specification layer](/specs/overview/) - how the PVD sits above PRD / TRD / TSD. * [Sprint planning](/concepts/sprint-planning/) - how each repo’s own backlog becomes sprints. # TRD - Technical Requirements Document > The TRD bridges what (PRD) and how (code) - architecture, technology choices with real rationale, API and data design, ADRs. Generate mode adds an architecture assessment. Owned by the Engineering seat. The **Technical Requirements Document** bridges the gap between *what* (the [PRD](/specs/prd/)) and *how* (the code). It captures the architecture, the technology choices and their rationale, the API and data design, and the decisions worth recording. It is owned by **Dani, the Engineering seat** of the [Three Amigos](/concepts/three-amigos/). It lives at `sdlc-studio/trd.md`, and it is **gated on the PRD** - you cannot design a solution to a problem you have not written down. ## Three modes (plus visualise) [Section titled “Three modes (plus visualise)”](#three-modes-plus-visualise) * create (greenfield) An interactive conversation builds the TRD, starting from the project type: ```text /sdlc-studio trd create ``` 1. **Project type classification** - Web App, API Backend, Mobile Backend, CLI, SDK. 2. Architecture recommendations for that type, which you accept or customise. 3. Technology-stack decisions - each one needs a **real justification**, not “we know it”; deviations from the recommended default are captured as ADRs. 4. API design, data architecture, infrastructure and security. Requires a PRD at `sdlc-studio/prd.md`. Best for greenfield or a major re-architecture. * generate (brownfield) Reverse-engineer the TRD from an existing codebase: ```text /sdlc-studio trd generate ``` It detects the project type and architecture pattern, extracts the stack from configs, maps API contracts from routes, documents data models from schemas, and reads deployment config for the infrastructure picture - all with `[INFERRED]` confidence markers. It then runs an **architecture assessment** (see below). Best for brownfield. * review Compare the TRD against the implementation and sync it: ```text /sdlc-studio trd review ``` New components and changes are folded in, significant decisions become new ADRs, and answered questions are resolved. Step four of review explicitly checks the TRD still aligns with the PRD - that the architecture supports every product feature. ## The architecture assessment (generate mode) [Section titled “The architecture assessment (generate mode)”](#the-architecture-assessment-generate-mode) On a brownfield project, `trd generate` does not just describe the architecture - it **judges** it against best practice for the project type, and reports findings with severity markers `[CRITICAL]` / `[REVIEW]` / `[INFO]`. It looks for: * pattern alignment with the project type, * architecture smells - Big Ball of Mud, Distributed Monolith, God Objects, * whether the technology selection is appropriate, * standards compliance for APIs and error handling. This turns “document the code” into “document the code and tell me where it hurts.” ## Visualise the architecture [Section titled “Visualise the architecture”](#visualise-the-architecture) ```text /sdlc-studio trd visualise ``` Parses the TRD’s Technology Stack, Architecture Decisions and Integrations, extracts the system boundaries, containers and components, and regenerates **C4-model diagrams as Mermaid** into the TRD’s Architecture Diagrams section - so the picture is generated from the document, never hand-drawn and left to rot. ## What it captures [Section titled “What it captures”](#what-it-captures) Project type classification and architecture implications · architecture decisions with rationale · technology stack with strong justifications · API contracts and data schemas · integration patterns · infrastructure approach · security considerations · ADRs · open technical questions · (brownfield) the architecture assessment. Tip The rule that a technology choice needs a real reason - not familiarity - is the TRD earning its keep. A stack chosen by habit is the most expensive kind of decision to unwind later. ## Where to next [Section titled “Where to next”](#where-to-next) * [TSD - Test Strategy](/specs/tsd/) - how the design is proven to work. * [PRD - Product Requirements](/specs/prd/) - the *what* the TRD answers *how* to. * [The Three Amigos](/concepts/three-amigos/) - Dani owns the TRD; the whole team reviews it. # TSD - Test Strategy Document > The Test Strategy Document defines what to test, how, when and by whom - coverage targets, test levels, quality gates. It sets the targets the status dashboard measures and is a leg of the closing review. Owned by the QA seat. The **Test Strategy Document** is the project-level answer to *how do we know it works?* It defines what to test, how, when, and who is responsible - one strategy per project, which the individual test specs then apply to specific stories. It is owned by **Sam, the QA seat** of the [Three Amigos](/concepts/three-amigos/). It lives at `sdlc-studio/tsd.md`. ## What a Test Strategy Document defines [Section titled “What a Test Strategy Document defines”](#what-a-test-strategy-document-defines) * **What** to test - scope, levels and types (unit, integration, E2E, performance, security). * **How** to test - frameworks and the automation approach. * **When** to test - CI/CD integration and the quality gates that block a build. * **Who** tests - roles and responsibilities. Its sections: Overview & Objectives · Test Scope (in / out) · Test Levels · Test Environments · Test Data Strategy · Automation Strategy · CI/CD Integration & Quality Gates · Defect Management · Roles & Responsibilities · Tools & Infrastructure. ## Three modes [Section titled “Three modes”](#three-modes) * **`tsd`** (create) - a guided conversation about objectives, test levels, framework preferences, the automation approach and the quality gates. A PRD should exist first, for context. * **`tsd generate`** - reads your test files and CI config, identifies the frameworks in use (Jest, Playwright, pytest, …), documents current coverage and gaps, and writes the strategy with `[INFERRED]` markers. * **`tsd review`** - re-checks the strategy against the codebase and updates tool versions, gates and levels. ## Quality gates [Section titled “Quality gates”](#quality-gates) The TSD is where you decide what blocks a build. A typical set: | Gate | Criteria | Blocking | | ----------------- | ----------- | -------- | | Unit coverage | ≥ 90% | Yes | | Integration tests | 100% pass | Yes | | E2E critical path | 100% pass | Yes | | Performance | p95 < 500ms | Yes | ## How the rest of the pipeline uses it [Section titled “How the rest of the pipeline uses it”](#how-the-rest-of-the-pipeline-uses-it) This is worth stating precisely, because it is easy to assume the TSD is checked line by line - it is not: * The **status dashboard** measures real coverage against the **targets the TSD sets** - that is how a project knows it is below its own bar. * At sprint close, the TSD is one leg of the **unified review** (PRD / TRD / TSD / personas, plus the code), so the strategy is re-examined against what actually shipped. Note `verify_ac` verifies each **story’s acceptance criteria** against the live code (`ac=N pass=N fail=0`) - it does not read the TSD directly. The TSD sets the project-wide targets and gates; the per-story `Verify:` lines are what prove an individual acceptance criterion. Two different instruments, both needed. ## Where to next [Section titled “Where to next”](#where-to-next) * [Executable acceptance criteria](/concepts/executable-acceptance-criteria/) - the per-story oracle the TSD’s targets sit above. * [PRD](/specs/prd/) and [TRD](/specs/trd/) - the other two documents in the specification layer. * [The Three Amigos](/concepts/three-amigos/) - Sam owns the TSD and reviews for testability. # Upgrading from v1 / v4 > What changed since the human-driven era - the two-backlog workflow, sizing, the two-role gate - and how an existing project upgrades without disruption. If you have used SDLC Studio since the early, mostly human-driven days, the tool has grown a lot of discipline. The good news: **nothing changes in an existing project until you say so.** ## The upgrade is opt-in [Section titled “The upgrade is opt-in”](#the-upgrade-is-opt-in) Re-run the installer (or `/sdlc-studio skill-update`). It is a drop-in: no project migration, and existing `sdlc-studio/` directories keep working exactly as they did. The v5 workflow changes - the two-backlog gates, sizing demands, terminal-status derivation - are **off by default**. An existing project upgrades with zero disruption and keeps its old flow until you turn enforcement on. ## What is new to learn [Section titled “What is new to learn”](#what-is-new-to-learn) * **[The two-backlog model](/concepts/two-backlog/).** The single biggest shift: a request (CR/RFC) is not work until `refine` sizes it into delivery units. This is new if you last drove the pipeline by hand. * **Sizing is compulsory.** Delivery units carry points (stories/bugs) or a T-shirt size (CRs/RFCs/epics). The planner refuses an un-sized unit. * **[Two-role review](/concepts/two-role-review/).** Past a configurable threshold, Done needs an independent, non-author sign-off. * **[Sprint planning](/concepts/sprint-planning/) and autosprint.** A deliberate batch driven to a goal, closed with reconcile and review. ## Turning enforcement on [Section titled “Turning enforcement on”](#turning-enforcement-on) Three deliberate steps, documented in the repo’s upgrade guide: 1. `migrate_v3 sizing` - convert existing requests and containers to a T-shirt size deterministically, and report the delivery units that need re-sizing. 2. `refine` the accepted requests into sized delivery work. 3. Set `two_backlog.enforce: true` in `.config.yaml`. The sizing migration only *adds* a `Size:` line and the workflow is one config line, so the upgrade is reversible. ## The numbering question [Section titled “The numbering question”](#the-numbering-question) New projects mint collision-free ULIDs (`US-01JQK3F8`) so parallel agents never fight over sequential ids. An existing project is asked the numbering question explicitly on upgrade, with three supported answers - it is never auto-flipped. Note The full, in-repo detail - what changed, the numbering question and its answers, and the honest breaking-change notes - lives in `docs/existing-users.md` in the repository. # A first change (quick taster) > One feature, start to finish - what you say in plain language, and what your team does. From a raw idea to a closed, independently reviewed sprint. The two-minute version. You drive the whole lifecycle in **plain language** - you say what you want, the agent works out what you mean, and the discipline holds underneath. Here is one feature - *adding the ability to delete a task* - from a raw idea to a closed, reviewed sprint, told the way you would actually experience it: what you say, and what your team does. Note This is the two-minute version, and it assumes a project already exists. For the full journey from nothing, see the [greenfield walkthrough](/walkthrough/greenfield/) (build a task-management app from an empty repo); to adopt code you already have, see the [brownfield walkthrough](/walkthrough/brownfield/). Tip You never have to memorise commands. Everything below also has an explicit command (shown as *the explicit form*) for when you prefer it - but the point is that you don’t need it. 1. **You say:** *“Add a delete function to the task list.”* The request is filed in the **discovery backlog** - an idea, not committed work yet. It is cheap and unsized. (For a bigger design question - *“should deletes be soft or permanent?”* - you’d say *“open an RFC”* to weigh the options first.) > *The explicit form:* `cr create` 2. **You say:** *“Refine that into work.”* `refine` breaks the request into an **epic and sized stories**, each with plain, checkable acceptance criteria - for example: ```text US: A user can delete their own task AC1 Given a signed-in user with a task, When they delete it, Then it is removed from their list AC2 Given a task they do not own, When they try to delete it, Then it is refused ``` Now it is delivery work. If the criteria are still rough, you say *“tidy up the acceptance criteria”* and the team makes each one concrete. > *The explicit form:* `refine --id CR0007` 3. **You say:** *“Plan a sprint over it.”* The **breakdown gate** checks the batch is ready - refined, sized, criteria written - and refuses if it isn’t. Then it opens the sprint and shows you the plan. > *The explicit form:* `sprint plan --goal done --write` 4. **You say:** *“Build the first story.”* **Dani** (your Engineering seat) writes the failing test first, implements the delete, and runs the story’s acceptance criteria. The story reaches Done only when they pass - so “done” is a fact the tool checked, not a claim. ```text verify_ac run --id US0012 -> ac=2 pass=2 fail=0 ``` > *The explicit form:* `verify_ac run --id US0012` 5. **You say:** *“Review it.”* A **fresh reviewer that did not write the code** runs an adversarial pass - does it really refuse deleting someone else’s task? - and files what it finds as evidence. You, or someone other than the author, ratify it. The author can never sign off their own work, so your AI isn’t marking its own homework. > *The explicit form:* `critic sprint-review` then your sign-off 6. **You say:** *“Close the sprint.”* The close records your sign-off, transitions the stories to **Done**, marks the epic and the request **Complete**, validates the **retro** and extracts its lessons, and runs the gate. One command, the whole ceremony. > *The explicit form:* `sprint close --apply-signoff --principal "you"` Note Want it hands-off? You say *“take this to done”* and the **goal-driven autosprint** runs the batch to its goal - build, verify, review - and closes with a reconcile and review. You set the goal and the acceptance criteria; the team drives the proven lifecycle to it. ## What you are left with [Section titled “What you are left with”](#what-you-are-left-with) The delete feature, shipped: every story Done against passing criteria, a review record naming a reviewer who wasn’t the author, a retro with its lessons, and the request marked Complete - all as plain files under `sdlc-studio/`, true to the code that was actually built. You got there by talking. Next: the concepts behind each step - [the two-backlog model](/concepts/two-backlog/), [sprint planning](/concepts/sprint-planning/), [two-role review](/concepts/two-role-review/), [executable acceptance criteria](/concepts/executable-acceptance-criteria/). # Brownfield walkthrough - adopt an existing app > A worked example of bringing a codebase you already have under the discipline. Guided init detects the stack and reverse-engineers the specs; the generated spec is a hypothesis until its tests pass against the real code. Most tools assume you are starting fresh. Real work usually is not - you inherit a codebase and have to make it safe to change. Here we adopt an existing **TaskFlow** app (say, an Express + React task manager with some tests and a CI file) and bring it under the full discipline, without rewriting a line to begin with. Tip **Try before you commit.** Before adopting anything, `/sdlc-studio audit --profile repo` runs a read-only, refute-panel-verified audit of the repo and files what it finds - zero setup, nothing written to your code. A good way to see what SDLC Studio notices about a codebase it has never seen. ## One command, forked for existing code [Section titled “One command, forked for existing code”](#one-command-forked-for-existing-code) In the existing `taskflow/` repo: ```text /sdlc-studio init guided ``` Guided init finds `package.json` (and friends), classifies the project **brownfield**, and forks every stage from *author* to *reverse-engineer* - you never choose `create` versus `generate`, it chooses for you. 1. **agents** - seeds `AGENTS.md` / `CLAUDE.md` (leaving anything you already have untouched). 2. **prd** - instead of interviewing you, it reads your routes, components, tests and config and **reverse-engineers** [`sdlc-studio/prd.md`](/specs/prd/), marking every inferred claim `[HIGH]`, `[MEDIUM]` or `[LOW]`. You see TaskFlow’s real feature inventory extracted from the code, with the guesses flagged as guesses. > *The explicit form:* `prd generate` 3. **trd** - it reverse-engineers [`sdlc-studio/trd.md`](/specs/trd/) from the code and runs an **architecture assessment**: pattern alignment, smells (Big Ball of Mud, Distributed Monolith), technology fit - reported with `[CRITICAL]` / `[REVIEW]` / `[INFO]`. This is the “document the code and tell me where it hurts” step. > *The explicit form:* `trd generate` 4. **tsd** - it reads your existing tests and CI, identifies the frameworks (Jest, Playwright, pytest…), and infers the [test strategy](/specs/tsd/) with `[INFERRED]` markers - what you cover today and where the gaps are. > *The explicit form:* `tsd generate` 5. **personas** - it grows the [team](/concepts/three-amigos/) and the design personas from the extracted PRD, so review has domain teeth from day one. 6. **decompose** and **7. plan** - the extracted spec becomes epics and stories, and you get a first sprint plan over the parts you want to change. ## The one rule that makes brownfield safe [Section titled “The one rule that makes brownfield safe”](#the-one-rule-that-makes-brownfield-safe) Caution A generated spec is a **migration blueprint, not documentation** - and it is worthless until proven. **Do not trust a generated specification until its tests pass against the existing code.** An unvalidated extraction is a guess dressed as a fact. So the brownfield loop has an extra beat the greenfield one does not. For the slice you are adopting, SDLC Studio writes tests from the extracted spec and runs them **against your real implementation**: ```text /sdlc-studio story generate --epic EP0001 # extract implementation-ready stories from the code /sdlc-studio code verify --story US0003 # do the extracted ACs actually hold against the code? ``` Acceptance criteria that pass are trusted; ones that fail are where your spec and your code disagree - which is exactly the list of things to fix or re-specify. Only once the extracted spec is green do you plan real change over it, from there following the same build → verify → review → close path as the [greenfield walkthrough](/walkthrough/greenfield/). ## What you have [Section titled “What you have”](#what-you-have) A codebase you inherited, now with a spec that is **proven against the code** rather than assumed, an architecture assessment that names the risks, a test strategy that reflects reality, and a team that reviews with your domain’s non-negotiables. From here, every change goes through the discipline - but the adoption cost was reading, not rewriting. ## Where to next [Section titled “Where to next”](#where-to-next) * [Greenfield walkthrough](/walkthrough/greenfield/) - the same lifecycle from an empty repo. * [The specification layer](/specs/overview/) - create vs generate, and the confidence markers, in detail. * [The two-backlog model](/concepts/two-backlog/) - how the extracted work becomes planned sprints. # Greenfield walkthrough - build a task-management app > A worked example from an empty repo to a shipped, reviewed increment. Guided init writes the specs, grows the team and plans the first sprint; then you build one increment under the full discipline. Let us build a real thing from nothing: **TaskFlow**, a small task-management web app where a signed-in user can create, list, complete and delete their own tasks. This page follows it from an empty repository to a first increment that is built, proven and independently reviewed. You will spend most of it in plain language. Every step has an explicit command shown as *the explicit form*, but you do not need to type them. ## Part 1 - from empty repo to a first plan, in one command [Section titled “Part 1 - from empty repo to a first plan, in one command”](#part-1---from-empty-repo-to-a-first-plan-in-one-command) In your empty `taskflow/` repo: ```text /sdlc-studio init guided ``` Guided init sees no code and classifies the project **greenfield**, then walks the seven stages. Review each draft, then say *“looks good, continue”* (the explicit form is `init guided --confirm`). 1. **agents** - it writes `AGENTS.md` and `CLAUDE.md` so every AI tool you point at TaskFlow follows the same rules. 2. **prd** - an interview: *what is TaskFlow, who is it for, what must it do?* You describe the features; it writes [`sdlc-studio/prd.md`](/specs/prd/) - a Feature Inventory (create / list / complete / delete a task, sign-in), functional and non-functional requirements (a task list loads in under 300ms), and the open questions. 3. **trd** - from that PRD it drafts [`sdlc-studio/trd.md`](/specs/trd/): project type *Web App*, a recommended stack with real rationale, the task and user data models, the REST endpoints, and any decision worth an ADR. 4. **tsd** - it drafts [`sdlc-studio/tsd.md`](/specs/tsd/): the [test strategy](/specs/tsd/) - unit ≥ 90%, the delete-a-task path 100% covered end to end, and the quality gates that will block a build. 5. **personas** - it grows your [team](/concepts/three-amigos/) and the people TaskFlow is *for*: ```text /sdlc-studio persona generate --team # Lena (Product), Dani (Eng), Sam (QA), grown from TaskFlow /sdlc-studio persona generate --from-prd # Priya, the busy team lead who lives in her task list ``` 6. **decompose** - the PRD becomes epics and sized stories, each naming the persona it serves: ```text /sdlc-studio epic /sdlc-studio story --epic EP0001 ``` 7. **plan** - it grooms the backlog and plans your first sprint. This is where guided init ends - you are standing exactly where delivery begins. ```text /sdlc-studio reconcile && /sdlc-studio validate # a clean, drift-free backlog /sdlc-studio sprint plan # a sized, sequenced first sprint ``` Everything so far is plain Markdown under `sdlc-studio/` that you read and edit - `prd.md`, `trd.md`, `tsd.md`, `epics/`, `stories/`, `personas/`. Caution **Cold-start reality.** A sprint’s Done gate runs your tests, and an empty repo has none yet. So you build the **foundation** epic (the app skeleton, the test harness, sign-in) by hand up to a green gate first. Only then do you hand the following epics to the sprint loop. The tool will not pretend an empty repo has a runnable gate. ## Part 2 - build one increment under the discipline [Section titled “Part 2 - build one increment under the discipline”](#part-2---build-one-increment-under-the-discipline) Now the foundation is green and *“a user can delete their own task”* is a Ready story (`US0007`). 1. **You say:** *“Build the delete-a-task story.”* **Dani**, your Engineering seat, writes the failing test first, implements the endpoint and the UI action, and runs the story’s acceptance criteria. The story reaches Done only when they pass. ```text verify_ac run --id US0007 -> ac=2 pass=2 fail=0 manual=0 ``` > *The explicit form:* `story implement --story US0007`, then `reconcile --verify --story US0007` 2. **You say:** *“Review it.”* A **fresh reviewer that did not write the code** - Sam’s review render - runs an adversarial pass: does it truly refuse deleting *someone else’s* task? It files what it finds as evidence. Then you, or a delegate who is not the author, sign it off. > *The explicit form:* `critic evidence …` then `critic signoff --principal "you"` 3. **You say:** *“Close the sprint.”* The close records the sign-off, transitions the stories to **Done**, derives the epic and any parent request to **Complete**, validates the **retro** and lifts its lessons, and runs the gate. > *The explicit form:* `sprint close --retro RETRO0001 --apply-signoff --principal "you"` Note Want it hands-off for the rest? You say *“take this epic to done”* and the goal-driven autosprint drives the whole batch - build, verify, review - and closes with a reconcile and review. You set the goal and the acceptance criteria; the team drives the proven lifecycle to it. ## What you have [Section titled “What you have”](#what-you-have) TaskFlow’s delete feature, shipped: every story Done against **passing** criteria, a review record naming a reviewer who was not the author, a retro with its lessons, and the request marked Complete - all as plain files under `sdlc-studio/`, true to the code that actually exists. You got here by describing what you wanted; the discipline held underneath. ## Where to next [Section titled “Where to next”](#where-to-next) * [Brownfield walkthrough](/walkthrough/brownfield/) - the same journey starting from code you already have. * [The specification layer](/specs/overview/) - the PRD, TRD and TSD you just wrote, in detail. * [Sprint planning & autosprint](/concepts/sprint-planning/) - how the plan and the hands-off loop work.