The SDLC pipeline

SDS — design

Architecture, design components, decisions, APIs and data model, with the diagrams that explain them.

The SDS step designs the system from the approved requirements. The agent, working as an architect, breaks the system into design components, splits each one into ticket-sized implementation units, records the architecture decisions, and writes the Software Design Specification with the diagrams that explain it. Before anything is saved, the bridge proves that every requirement is actually implemented by the design.

What you get

A Markdown document titled Software Design Specification. The bridge adds the title block on top, and after the architect's text it adds two tables built from the checked design, then the version history:

Order	Section	Written by
1	Title block: project, client, version, date	Bridge
2	1. Architecture Overview — the style and why, with an architecture flowchart	Agent
3	2. Design Components — one sub-section per `DC-NNN`: responsibility, interfaces, data stores, requirements implemented, implementation units	Agent
4	3. Architecture Decisions — context, options considered, decision, consequences	Agent
5	4. Data Design — an entity-relationship diagram with attributes, the tables, and a data-flow diagram	Agent
6	5. Interface Design — the API endpoints table and key sequence diagrams	Agent
7	6. Deployment — environments, hosting and a deployment diagram	Agent
8	7. Security Design — authentication, authorization, data protection, audit logging	Agent
9	8. Open Questions	Agent
10	Design Component Catalogue — id, component, type, interfaces, requirements, number of units	Bridge
11	Requirements Traceability — each requirement, its priority, the components that implement it, and its coverage status	Bridge
12	Version History	Bridge

The bridge requires the headings Architecture Overview, Design Components, Architecture Decisions, Data Design, Interface, Deployment and Security; at least three Mermaid diagrams; and a mention of every design component id. A section that genuinely does not apply — no database in a client-only app, for example — says so in one sentence rather than inventing content.

The two bridge tables are the implementation-level truth: they come from the design that passed the coverage check, so the document can never claim a mapping no component implements.

Before you run it

The SRS must be approved. Until it is, /sds is locked with "Approve /srs to unlock this".
The project state must hold the SRS and a non-empty requirement list. Otherwise the run stops with "artifacts.srs missing — run /srs first." or "requirements[] is empty — run /srs first."

How it works

SDS makes one skill call, sdlc-architect, with up to three attempts. Every attempt goes through a stack of checks, and all the problems from one attempt are sent back together so a single retry can fix them.

Drawing diagram…

The architect receives every validated requirement (with priority and acceptance criteria), the SRS constraints and assumptions, the project and client names, and any notes. It is told outright that every requirement not marked "won't have" must be listed on a component and implemented by one of that component's units, and that mentioning a requirement only in the text does not count.

It returns design components, architecture decisions, API endpoints, database tables, the SDS Markdown and open questions. If a reply has no components or no document at all, the run stops immediately without a retry.

The checks on every attempt

Before checking, the bridge widens each component's requirement list to include every requirement its units carry, so a unit's requirement is never silently lost.

Check	What it enforces
Component shape	Every component matches the design-component schema: id pattern, type, complexity, interface kinds, risks as objects.
Implementation units	Every component has at least one unit; a unit's requirements are a subset of its component's, and together they equal them; unit ids are globally unique and prefixed by their component; every `dependsOn` resolves; the unit dependency graph has no cycle.
Component dependencies	Component-level dependencies are derived from the unit edges, then checked for cycles.
Assigned roles	Every component names a role from the project's team roles (architect, senior developer or junior developer).
Architecture decisions	Every decision cites only existing requirement ids and has exactly one selected option.
Coverage	Every requirement is covered: listed on a component and implemented by one of its units.
Markdown	Required headings, three diagrams, every component id cited.

The coverage check sorts each requirement into one of four states:

Status	Meaning
Covered	A component lists it and one of that component's units implements it.
Partial	A component claims it but no unit implements it, a unit implements it but its component does not list it, or the design only mentions it in prose.
Uncovered	Nothing in the design references it.
Excluded	Deliberately outside the design: priority "won't have", or status deferred or rejected. Shown with its reason; not counted against the design.

The design passes only when nothing is partial or uncovered and nothing references a requirement the SRS does not define. The one-line summary, "Requirements Coverage: X/Y Covered …", appears in the run's completion message.

After the document is written, the bridge saves the design into the project state, confirms every unit and dependency survived the save unchanged, and fills in each requirement's links to the components that implement it — failing the run if any "must" requirement ends up with none.

The run panel shows: Checking project state, Designing components, Validating the design, Checking requirements coverage, Writing the Markdown document, Persisting to project state.

Ids this step owns

Id	Meaning
`DC-NNN`	A design component — a service, module, API, database, job, integration, UI and so on. Becomes an epic in Tasks.
`DC-NNN-MM`	An implementation unit inside component `DC-NNN` — a table, endpoint, worker, event handler, UI component or module. Becomes one ticket.

Units carry a contract (the interface or schema they expose) and may depend on other units, in the same component or another.

Reviewing it

Check that:

the architecture fits the constraints the SRS recorded (hosting, mandated technology);
each component has a clear responsibility, and the units are genuinely buildable pieces with concrete contracts — they become tickets on the delivery board;
the Requirements Traceability table shows no surprises, and any excluded requirement is excluded for the reason you expect;
each architecture decision weighs at least three real options.

When you approve the SDS, every design component's status moves from draft to approved.

Request changes runs the architect again with your change list as additional notes; it does not see the previous draft. Name components and units — "Split DC-004 into a separate notification service", "Add an audit_log table to DC-002" — and remember the coverage check applies to the new design as well.

When it fails

What you see	Why	What to do
"architect returned no designComponents[] or no markdown document."	The reply had no design or no document. There is no retry for this.	Run it again; if it repeats, check the agent's `max_tokens` is high enough for a large design.
"The design does not implement every SRS requirement. Requirements Coverage: …"	After three attempts some requirements were still partial or uncovered.	Run it again. If one requirement keeps failing, check it is clear in the SRS, or request an SRS change.
"ECC script failed: scripts/validate-design-components.js" (or another validator)	A structural check kept failing — a bad enum, a unit outside its component, a dependency cycle, a missing role.	Run it again.
"The SDS document did not pass the Markdown checks."	Missing headings, fewer than three diagrams, or an uncited component id.	Run it again.

Nothing is written to the project state until the architect's reply has passed every check above, so a run that fails in the correction loop leaves the previous design untouched. Two guards run after the save and are rare: "ECC script failed: scripts/sdlc/verify-units-survived.js" (a unit changed on its way into the state) and "ECC script failed: scripts/traceability-update.js" (for example, a "must" requirement left with no component). Run the step again if you see one.

Under the hood

The driver is bridge/src/services/sdsPipeline.service.ts; the coverage matrix comes from bridge/sdlc-engine/scripts/sdlc/utils/requirements-coverage.js.
Written to the project state: designComponents (with units and derived dependencies), architectureDecisions, apiContracts, databaseSchema, each requirement's links to its components, and traceabilityMatrix. The phase moves to test planning.
The document is .sdlc/artifacts/sds-vN.md, registered as artifacts.sds together with the coverage matrix it passed. The draft is kept in .sdlc/tmp/sds-data.json while under review.