Building a new system

This is the forward path: a brief goes in at phase 1, and a composed, tested application comes out of phase 5. Every phase is one ccw_start; the children fan out on their own.

Pick the two roots first and use the same values everywhere — the documentation workspace and the development root, never nested.

Phase 1 — Requirements

ccw_start SDLC 1 Requirements

The run goes: intake analysis → system boundary → actors → domains → one child run per actor writing that actor's use cases → a coverage check that re-runs any actor whose fan-out produced nothing → consolidation → conceptual model (ENT-## entities with cardinality-labelled relationships) → business rules → functional requirements → NFRs → a consistency check → review → sign-off.

Two things are worth knowing before you start it:

• Clarification is bounded at two rounds. When the brief leaves something open, the workflow stops at a gate and asks. Answer in your agent's chat. Anything still unresolved becomes a logged open question, not a silent assumption.
• Business rules include the calculations. Every use-case step that computes or converts something, and every entity attribute that is not entered by a user, must end up as a business rule with its inputs and units, the algorithm or a named authoritative source, precision and rounding, edge cases and a worked example. A rule whose specification is a placeholder fails the consistency check. This is the difference between a system that documents "convert the local time to UTC" and one that names the IANA timezone of the place at that date.

Out: 01-requirements/ with actors.jsonl, domains.jsonl, use-cases/, use-cases.jsonl, business-rules.jsonl, requirements.jsonl, nfr.jsonl and a readable .md beside each, plus the documentation site.

Phase 2 — Solution Design

ccw_start SDLC 2 Solution Design

Takes projectName, the same workspaceDir, and an optional request to scope the pass ("design the payment subsystem"); leave it blank for a full pass over every layer.

It reads the requirements and any existing solution-architecture.md, works out which layers the system actually needs, and makes a numbered, justified choice per layer — frontend, backend, database, devops, security and whatever else applies. Each choice records what was rejected and why, so phase 6 can revisit it later without re-litigating from scratch.

The result is binding: phase 5 implements against these choices, phase 9 provisions them, and a workflow that finds the code contradicting the architecture reports it as a finding rather than adapting to it.

Phase 3 — Style Guide

ccw_start SDLC 3 Style Guide

Takes projectName and workspaceDir.

The workflow asks the style questions one at a time through your agent's own conversation — tone, brand personality, visual mood, accessibility ambition — then builds each item of the guide in its own step: tone of voice, colour palette, typography, layout and spacing, iconography and imagery, components.

Underneath the prose is 03-styleguide/design-tokens.json. A packaged Python helper validates it — WCAG contrast, type-scale and spacing-scale sanity — and renders the generated tables. The documentation site shows every token as a rendered example: the actual colour, the actual type scale, the actual spacing, worked examples of the voice. Phase 5 designs UX against these tokens, and UI Inspection later checks the built interface for colours, fonts, sizes and spacings that are not in this file.

Skip this phase only for a system with no user interface.

Phase 4 — System Decomposition

ccw_start SDLC 4 System Decomposition

Takes projectName, workspaceDir and an optional request ("align level 1 with the two product teams").

It divides the system completely into subsystems, hierarchically, with as many levels as the system needs — purpose, responsibilities, and the allocation of every domain, use case and requirement to a leaf. It deliberately stops there: no interfaces, no schemas, no per-subsystem technology choices. Those are phase 5's job, made against the binding architecture.

Out: 04-decomposition/subsystems.jsonl and system-decomposition.md. Give subsystems short, meaningful names — every later phase, report and directory uses them.

The consistency check will tell you if something in the requirements is allocated nowhere, and if the leaf subsystems form dependency cycles. Take a cycle report seriously: phase 5 builds in dependency order, and a cycle covering most of the leaves means the decomposition, not the build, is what needs fixing.

Phase 5 — Development and Test

ccw_start SDLC 5 Development and Test

The phase starts by checking its inputs exist, then builds a build map: the leaf subsystems from the decomposition, their dependencies from the architecture, and a build order. Cycles are condensed rather than silently broken, and reported.

Then, per leaf subsystem in that order (SDLC Build Subsystem):

1. UX design — screens, flows, states and accessibility for the subsystem's allocated use cases, strictly following the style guide. Skipped when the subsystem has no UI. This produces the UX specification; the interface itself is built in the next step.
2. Write code — modules planned against the binding solution architecture, implemented, dev-manifest.json written, the build verified, a bounded code review passed.
3. Unit tests — written and run behind a deterministic 95% branch coverage gate, measured from the project's own coverage report. A bounded improve-loop tries to close the gap; on exhaustion a human waiver gate decides.
4. Subsystem tests — a deterministic matrix check that every use case, requirement and NFR allocated to this subsystem is actually covered, then a bounded fix loop until green, then a unit-coverage recheck.
5. UI inspection, when the subsystem has an interface — the built UI checked against the design tokens and the UX spec.

When every leaf is built, SDLC Compose System writes the composition root: one runnable application under <devDir>/app wiring the subsystems together — entry point, dependency injection and configuration, UI shell — verified with a smoke run. This is the step that turns a set of green subsystems into a system that starts.

SDLC System Tests then derives and runs the system-level suite: every use case end-to-end plus the cross-cutting NFRs, checked as a matrix so a missing case is a failure rather than an omission. Failures are mapped to the subsystems that likely caused them, and each one goes through SDLC Fix Subsystem — a targeted change, a fresh 95% branch-coverage gate, the full subsystem suite, a diff-scoped review — instead of a full rebuild.

Fix rounds are bounded. When they run out with tests still red, the workflow stops at the System Fix Gate with what is failing and what was tried, and you decide: keep going, accept a waiver, or go back a phase.

Then what

The system runs and is proven. From here:

• Local Deployment to click through it yourself.
• Provision Infrastructure and Release and Deploy to ship it.
• SDLC 6 Change Request for everything that comes after — it is the entry point for changes, not a re-run of phase 1.