Full SDLC — overview

The SDLC package runs a whole software lifecycle as workflows — requirements, architecture, style guide, decomposition, build and test, change, deployment and release.

The Full SDLC package turns a software lifecycle into workflows your coding agent executes one step at a time. Twenty-nine published workflows live in the SDLC/ folder. Ten of them are numbered phases you start yourself, two more handle existing code, and the rest run as children — a use-case writer per actor, a build workflow per subsystem, a test workflow per level.

Each phase reads what the previous phase wrote, ends in a document that a human signs off, and pins a result the next phase can trust. Nothing in the chain is a summary of a summary: the artifacts are files on disk with stable ids, and every later phase reads the files.

The phases

#	Workflow	What it produces
0	SDLC 0 Reverse Engineer	The whole baseline below, recovered from an existing codebase with file/line evidence
1	SDLC 1 Requirements	Boundary, actors, domains, use cases, conceptual model, business rules, requirements, NFRs
2	SDLC 2 Solution Design	A numbered, justified technology choice per layer, plus the runtime topology: what deploys, what it exposes, what it needs
3	SDLC 3 Style Guide	Tone, colour, typography, layout, iconography, components — backed by `design-tokens.json`
3b	SDLC 3b Interaction Design	The screen inventory, the navigation graph, the shared shell, and wireframes of the primary flows
4	SDLC 4 System Decomposition	The subsystem hierarchy, with every domain, use case and requirement allocated to a leaf
5	SDLC 5 Development and Test	Every leaf subsystem built and tested, composed into one runnable app, proven by system tests
6	SDLC 6 Change Request	A change assessed through the traceability chain, then only the impacted phases re-run
7	SDLC 7 Local Deployment	The composed app running locally for human testing, stubbed or wired to live services
8	SDLC 8 Release and Deploy	A versioned artifact promoted staging → production, with verification and rollback
9	SDLC 9 Provision Infrastructure	The hosting environments as infrastructure-as-code, behind a plan and a cost gate

Alongside them, two workflows exist for code that already ships: SDLC Test Retrofit and SDLC Bug Fix.

Two roots, never nested

Every workflow after phase 4 takes two directories, and the distinction matters more than any other input:

workspaceDir — the documentation workspace. Phases 0–4 write it; phases 5–9 only read it.
devDir — the development root: source code, tests, manifests, the build map, reports. Usually the repository root.

devDir must never sit inside workspaceDir. Put source under the docs folder once and every later phase reads generated documentation as if it were code.

<workspaceDir>/            <devDir>/
  project.json               .tools/sdlc_devtools.py
  00-reverse/                build-map.jsonl
  01-requirements/           build-results.jsonl
    use-cases/               app/            ← composition root, the runnable system
  solution-architecture/     reports/
  03-styleguide/             deploy-local/
  interaction-design/        deploy-remote/{staging,production}/
  04-decomposition/          infra/
  06-changes/
  07-releases/
  08-bugs/
  site/                    ← the generated documentation site

What a phase run looks like

Phases 0–4 share one shape:

Init — the workspace directories are created; existing documents are read before anything is written.
Work, one step at a time — one actor's use cases, one technology layer, one style-guide item, one subsystem level. The engine hands over a single unit and will not move on until its result is reported.
Deterministic checks — shipped Python helpers compute what should not be judged: contrast ratios and scale sanity in the style guide, the dependency graph and coverage figures in development, hotspots in the retrofit. They emit evidence; the agent judges it.
A review node — an agent reviewer either approves or sends findings back, bounded by a maximum number of iterations so a run cannot loop forever.
A human gate — sign-off. The engine stops with status: "waiting" and your agent puts the question to you in your own session.
Pin the phase result — a structured result the next phase reads.

Phases 5–9 replace the sign-off with proof: coverage gates, a health check, a smoke run, a system-test matrix. Where a human decision is unavoidable — spending money, using production credentials, accepting a visual baseline — there is a gate for exactly that and nothing else.

Documentation and review comments

SDLC Document Requirements builds a static HTML site under <workspaceDir>/site from the requirements, the solution architecture, the style guide, the interaction design and the decomposition. It is deterministic (a packaged Python generator, sha256 change detection, so unchanged pages are skipped), cross-links every ACT/UC/ENT/REQ/NFR id to where it is defined, and renders mermaid diagrams, style-guide examples and the wireframes themselves.

The site has a comment toolbar. Comments export to review-comments.json, and SDLC Process Review Comments feeds them back: triage into content change, stakeholder question, docs-only note or declined; apply the content changes to the source .md + .jsonl pairs with their ids intact; regenerate the site. That is the loop for review by people who will never open the repository.

The trail

Every phase commits what it produced, at the point the workflow has already verified it — a signed-off baseline, a subsystem whose coverage gate passed, a green system suite. Commits carry trailers naming the phase, the stage, the subsystem, the ids and the run:

Implement SUB-03 Order management

SDLC-Phase: development
SDLC-Stage: code
SDLC-Subsystem: SUB-03
SDLC-Ids: UC-014, UC-015, REQ-021
SDLC-Evidence: build clean, code review approved
SDLC-Run: inst_9f2b41

That is what makes it a trail rather than a habit: sdlc_git.py trace reads the log back and shows, per use case, the commits that specified it, designed it, allocated it to a subsystem, implemented it, tested it and released it — and names the gaps. SDLC Trace Audit runs that check on demand, and phase 8 runs it before building a release: a version whose requirements cannot be traced to code stops at a gate.

A change or a bug gets its own branch (ch/CH-007-…, bug/BUG-003-…), merged when the record closes, so a change is reviewable as a unit. Nothing is ever pushed, force-pushed, rebased or reset — the only history written is new commits, one merge and one tag.

Three things the commit step refuses, on purpose:

Paths it does not own. Each step declares what it may commit; anything else staged aborts it. A requirements phase that touches source code is a bug in the phase, not a commit to make.
Credentials. The staged diff is scanned; a private key or a credential assigned to a literal stops the commit.
Nothing to say. Re-running a phase that changed nothing writes no commit, so the history has no noise.

Note that ccw_step_back cannot undo a commit — it reports one as a side effect it could not reverse. That is exactly why commits happen only at verified points.

Before you start

python3 3.8 or newer on the machine where the agent works. The deterministic helpers are shipped as instruction files, materialized into <devDir>/.tools/ and run through shell steps — nothing is installed from a package index.
git. The lifecycle commits into it: every phase records what it produced, with trailers that let the history be read back requirement by requirement. See the trail.
A browser tool for the agent if the system has a UI, so SDLC UI Inspection can capture screens.
The engine and an agent connected to it — see connect your agent.

Where to go next

Building a new system — phases 1 through 5, in order, with the inputs each one takes.
Working with existing code — reverse engineering, test retrofit, bug fixes, changes.
Deploying and releasing — local environments, infrastructure, releases and rollback.
Workflow reference — every workflow, its inputs, its outputs and its gates.