Sdlc Design Arch
Published by ntanh1402 in sdlc-skills
What this skill does
Design and approve the target architecture of a Feature or ChangeRequest in the project wiki, while its requirements are a draft or once they are agreed - the services, frontends, endpoints, events, data and externals it needs, their contracts, Mermaid diagrams, traceability and architecture decisions - and mark what is not built yet. Use when requirements need technical design, impact mapping, interface contracts or ADRs, when a spec changed after its design, or to approve a ChangeRequest whose
Add Sdlc Design Arch to your agent
Review the source and files first. When you are ready, copy the prompt instruction or use the CLI command supported by your environment.
Install with a prompt
Paste this into a compatible coding agent:
add this skill "sdlc-design-arch" from https://github.com/ntanh1402/sdlc-skillsInstall with the CLI
Run this command in a controlled environment after reviewing the repository:
npx skills add https://github.com/ntanh1402/sdlc-skills --skill sdlc-design-archSkill instructions
Design the architecture
This skill is the second lifecycle step. It takes a Feature or
ChangeRequest whose Requirements are a draft (Draft, Proposed) or agreed
(ReqApproved), and writes its approved target design:
- Feature:
# Architecturefilled anddesignBasedOnset to the Feature's version. When the Feature isReqApproved(and no existing Task is outdated or uncovered), its status becomesApproved, orInDevwhen a Task is alreadyDone(removing the pending entries of concepts whose Tasks are allDone). ADraftFeature staysDraft. - ChangeRequest:
# Deltafilled anddesignBasedOnset. When the ChangeRequest isReqApproved(and no existing Task is outdated or uncovered), in the same change: statusApproved(orImplementedwhen every Task isDone), the target Feature's Requirements and Architecture updated to the new target, and pending entries removed for concepts whose Tasks are allDone. While it isProposed, the Feature is not touched: it shows only agreed changes. - In both: every new or changed Design concept file written as its target,
with a pending entry; decisions in
wiki/<app>/decisions/ADR-<name>.md.
A target designed before its Requirements were agreed may be designed again
after the spec changes: the design is revised in place. A ReqApproved
target whose design is already current needs no design at all: a short run
approves it (section 1, APPROVE).
Its draft prefix is arch-: the draft for CR-sms-alerts is
wiki/arch-CR-sms-alerts.
Before you start
Read, in this skill's folder, references/read-protocol.md; each section names
the other references/ files to read when it starts.
Find the wiki as the read protocol says, and check that it matches this
skill. RELEASE, next to this file, holds one line such as 1.0.0:
cd "$WIKI" && $T copy check --release "<the line in RELEASE>"
status | Do |
|---|---|
current | Go on |
older | Stop: "The wiki's tool is older than this skill. Run sdlc-setup-wiki to upgrade the wiki." |
newer | Stop: "The wiki was set up by a newer release. Update your installed sdlc-skills." |
edited | Stop: "The wiki's tool copy was edited by hand. Run sdlc-setup-wiki to restore it." |
Then read the schema pages schema.md, feature.md, change-request.md,
architecture-decision.md and the page of every Design type you may touch, in
the wiki's .wiki-llm/schema/. When a Requirement is removed, also
user-story.md and test-case.md.
| Request | Skill |
|---|---|
| Show or explain an existing architecture | sdlc-ask-wiki |
| Requirements are missing, unclear or not approved | sdlc-write-spec |
| User stories | sdlc-write-stories; it runs at the same time as this skill |
| Build tasks, or test design, from an approved design | sdlc-plan-tasks, sdlc-design-story-tests, sdlc-design-feature-tests |
When "design this" could mean several of these, ask one routing question.
The gates
A gate is a stop for the person's explicit approval. There are three, so the person decides what is being done (Intent), how (Design), and exactly what is saved (Change-set), each before the next cost is paid.
- Approval is an explicit yes to the gate's question. "Sounds good", silence or "whatever you think" is not approval.
- An edit at a gate reopens that gate and every later one.
- When you cannot ask the person (a run with no one to answer), or the person asks you to skip questions or approvals ("don't ask me, just write it"), stop before the first gate and start no draft. Return the open decisions and the gates the work still needs. Never assume approval.
- When the person rejects the design, stop. A draft worktree this run started is discarded; a worktree an earlier run started is left as it is.
- Being asked to run this skill does not approve anything it writes.
- A refusal this file states is a refusal. Do not turn it into a question.
1. Look up: readiness and what exists
Accept one FEAT-* or CR-* key; if the user named none, find the
candidates: Features Draft or ReqApproved, ChangeRequests Proposed or
ReqApproved, that are not designed or whose design is outdated. Read it on
the default branch and classify:
| State | When | Do |
|---|---|---|
READY | A Feature Draft or ReqApproved, or a ChangeRequest Proposed or ReqApproved, whose Architecture (Feature) or Delta (ChangeRequest) is None | Go on |
REDESIGN | The same statuses, already designed, and designBasedOn names an older version than version, or the person asks to change the design | Go on, revising the design in place (section 5, "A design written again") |
APPROVE | ReqApproved, designed, and designBasedOn names the current version | The short run of section 7: no new design |
NOT_MERGED | Not on the default branch, but a wiki/*-<Key> draft exists | Stop and name the draft (git branch -a --list 'wiki/*-<Key>') |
ALREADY_DESIGNED | Approved or later | Stop: a change to the design is a new ChangeRequest, written with sdlc-write-spec |
AMBIGUOUS | Several candidates | One question that names them; write nothing until it is answered |
CONFLICT | The requirements contradict an accepted decision or a live contract | Show both, with paths, in the first round and ask how to proceed |
NOT_MERGED and ALREADY_DESIGNED are refusals, not questions.
A draft spec is designed like an agreed one. Say in the first round that the
Requirements are still a draft, so the design may have to be done again when
they change, and that the target becomes Approved only once they are
agreed.
Then read the PRD and every Reference the Feature or ChangeRequest links,
every Requirement, the target Feature's current Architecture (for a
ChangeRequest), the accepted decisions in decisions/, every Design concept
the requirements touch, and the References in references/index.md about
the subject (an architecture document, a domain page, a code example): search
the Application's indexes and grep -rl for the domain words. For existing components, read
their linked repository, OpenAPI or AsyncAPI contracts when they are
available, read-only.
The wiki is the record. When code and wiki disagree, read
references/architecture-checklist.md now and classify the difference with
its "Drift". Material Drift stops the run before the Intent gate: show both
sides, ask which is true, and name the skill that settles it. It is a change
another skill owns (section 2).
Also read the Tasks and TestSuites that already exist for the Feature: the
design may make them out of date. For REDESIGN, read what changed in the
spec since the version the design was made from (git log -p on the
overview.md and the PRD's content file), and run
$T outdated --feature <Key> (or --change <Key>): it lists the stories,
Tasks and TestSuites also written from an older version.
An unfinished run. Last, ls "$WIKI"/.worktrees/*/plan.md 2>/dev/null
lists the runs that stopped part-way. When one is for this request (its
folder is arch-<Key>, or its plan's title names this request), read
references/write-protocol.md now and go on as its section 2 says, without
asking the rounds again.
2. Questions and the Intent gate
Read references/architecture-checklist.md, references/contract-rules.md
and references/adr-format.md now: the choices of section 3
use them.
Ask in rounds. A round is a numbered list of every question that can be answered now, each with your recommended answer. The person confirms or corrects, which is faster than composing an answer, and sees your reasoning before any work is done.
Q1 - Where are coupons validated? SVC-orders already owns order totals
(services/SVC-orders/overview.md).
➡️ In SVC-orders, with no new service.
Q2 - What else in the wiki must change because of this?
➡️ EP-create-order gains a couponCode field; DB-shop gains TBL-coupons.
Which questions to ask, and how many, is your judgement. Three things are fixed:
- The format. Numbered questions, each with a recommendation. A recommendation that rests on the wiki cites the path. A question whose answer depends on another question in the same round waits for the next round.
- At least one round, even when a brief seems complete. Its questions are then the assumptions you would otherwise make without saying so.
- The wiki question. Ask what else in the wiki must change because of this request, with your own answer as the recommendation. A request usually touches more files than it names; asking finds them before the plan is approved, not after.
Wait for the answers. Ask another round when the answers open new questions. Search the wiki again whenever an answer brings a system, a term or a claim about current behaviour you have not read. When nothing that changes the output is left undecided, go to the Intent gate: one approval, after the rounds.
A change another skill owns. When an answer needs a wiki change this skill does not own, do not make it. List it under "For other skills" in the Run plan and in the summary. When your work depends on it (such as material Drift), stop before the Intent gate and name the skill to run first.
The first round names the target and its state, and puts to the person the choices of section 3 that are theirs to make, each with your recommendation and the wiki paths it rests on: what is reused and what is new, how the parts talk to each other, who owns new data, and each choice that will become a decision. It also holds:
- any drift or conflict the lookup found;
- the wiki question, answered with the concepts you expect to add, change or remove;
- downstream freshness. The wiki does not know whether a
TodoTask has started. List the existing Tasks and TestSuites the design will make out of date, and ask which of theTodoTasks have started. Each started Task needs a separate, explicit acknowledgement.
Do not ask what the Requirements, an accepted decision or a live contract already settle.
Intent gate. Restate the target, its Requirements, the systems you will
reuse or add, the decisions you expect, drift found, and the Tasks or
TestSuites that go out of date. Ask for approval (DESIGN BASIS CONFIRMED).
3. What goes into the design
Go Requirement by Requirement and flow step by flow step, and decide with
references/architecture-checklist.md:
- Existing or new. Reuse an existing Service, frontend, table or channel unless a different ownership or lifecycle boundary is proven. Never copy a concept to avoid changing it.
- Interaction: a synchronous Endpoint, an asynchronous Channel and
Subscription, or an External Operation; request, response, payload,
validation, errors, compatibility and version
(
references/contract-rules.md). - User interface: only when a Requirement has one; which WebFrontend or MobileFrontend owns each surface. Never invent a frontend.
- Data: owner, read and write paths, schema, migration, retention, PII.
- Security: authentication, authorization, secrets, audit, abuse.
- Failure: idempotency, timeout, retry, ordering, dead letters, fallback, recovery.
- Operation: capacity, latency, availability, observability, rollout, rollback.
- Decisions. Every material, hard-to-reverse choice with a credible
alternative becomes a decision (
references/adr-format.md). Reuse an accepted decision that already covers it; supersede one only with a new decision.
Do not pick a technology before a constraint requires it.
Descriptive fields. A field whose schema page lists values as "common"
(serviceType, deployTarget, platform, authType and the like) is the
person's to choose. Suggest the values the Application already uses for it,
then the common ones, and ask in a question round when the evidence does not
settle it.
References. Link the References a later step will need from the Design
files and the Feature or ChangeRequest you write, under # References, with
a note on what to take from each: a code example of a pattern the design
reuses, a vendor document behind an Operation. Do not create a Reference;
when the design needs one the wiki lacks, say so at the Intent gate and name
sdlc-edit-wiki or sdlc-import.
4. Run plan and the Design gate
Read references/write-protocol.md now.
Start or resume the draft arch-<Key> as write-protocol.md section 2 and
section 3, "At section 4", say. The input paths are the Feature's or
ChangeRequest's overview.md and its PRD, and for a ChangeRequest also the
target Feature's overview.md, which another ChangeRequest may change
meanwhile.
Prepare the design packet:
- Context and constraints.
- The concept ledger: every concept new, modified, removed or reused, with the reason.
- The high-level Mermaid
flowchart, and onesequenceDiagramper main flow with its failure branches. - The contract of every new or changed concept, as its schema page requires.
- The decisions, with alternatives.
- Traceability: each Requirement to the concepts that satisfy it.
- Drift, risks, rollout and rollback.
- Downstream freshness: each existing Task or TestSuite this design makes out
of date, and which
TodoTasks the person said have started.
Write the Run plan (write-protocol.md section 4). Its ## Files are the
Feature's or ChangeRequest's overview.md first, then for a ChangeRequest the
target Feature's overview.md, each Design concept file of the ledger that is
not reused, each decision file, and the log.md of every concept folder they
are in. The out-of-date Tasks and TestGroups go under ## For other skills
(sdlc-plan-tasks, sdlc-design-story-tests, sdlc-design-feature-tests);
never edit them.
Design gate. Show the full packet, never only a summary, then the Run
plan. Ask for approval (TARGET DESIGN APPROVED). Any edit needs the gate
again.
5. Write
In the draft worktree, under wiki/<app>/. Write the Feature's or
ChangeRequest's overview.md first: it holds the diagrams, the decisions and
the traceability, so a run that stops after it can be resumed from the file.
-
Feature: fill
# Architecturewith its nested sections in the schema's order (## Context and constraints,## High-level architecture,## Services,## Frontendsonly with a user interface,## Runtime sequences,## Decisions,## Traceability). SetdesignBasedOn: { version: <its version>, at: <its versionDate> }. Setstatus: Approvedonly when it isReqApproved. -
ChangeRequest: fill
# Delta(## Target deltawith every concept qualifiednew,modifiedorremoved,## Runtime sequences,## Decisions,## Traceability) and setdesignBasedOnthe same way. When it isReqApproved, also apply it (section 7, "Applying a ChangeRequest"). While it isProposed, leave its status and the target Feature as they are. -
Design concepts: write each new one as the full target with
status: Planned; rewrite each changed one to the target withstatus: Modifying; set each removed one tostatus: Removingand keep its file. Give each a last section:# Pending changes * [CR-sms-alerts](../../change-requests/CR-sms-alerts/overview.md) — modified — the SMS send path is not live yet.A concept that already has a
# Pending changessection gets one more entry. -
Calls go under the caller's
# Calls. Never write a reverse section (# Used by,# Publishers,# Subscribers,# Superseded by) or anindex.md; the tool writes them. -
Decisions:
decisions/ADR-<name>.mdwithstatus: Accepted, linked from## Decisions. -
Logs: an entry in the
log.mdof every concept folder you change, for example* **Target design**: Designed the SMS channel for CR-sms-alerts from version 2. Written by an AI model with sdlc-design-arch.
A design written again (REDESIGN). Rewrite # Architecture or
# Delta to the new target and set designBasedOn to the current version.
For each Design concept:
- still in the design: rewrite it to the new target; its pending entry stays;
- new to the design: write it as above, with its pending entry;
- dropped from the design: when a
DoneTask of this target already built the concept, its code is merged in the repository, so set the concept tostatus: Removingwith a# Pending changesentry (removed) sosdlc-plan-tasksplans a new Task to remove the code. Otherwise remove this target's pending entry: aPlannedfile with no entry left is deleted (it was never built), and aModifyingorRemovingfile with no entry left gets back the text it had before this target's first design (git logon the file) and its live status; - a
TodoTask of the target that has not started and plans a dropped unbuilt concept loses that link from its# Planned scope. It is the only edit this skill makes to a Task; list each one under## For other skills(sdlc-plan-tasksreplans it).
Show the dropped and restored files at the Design gate.
6. Self review, finish and commit
Follow write-protocol.md section 3, "At section 6". In the self review (its
section 5), have the review sub-agent also check by reading that:
- every Requirement appears in
## Traceability; - the diagrams match the prose and the contracts;
- every concept in
## Target delta(or in## Servicesand## Frontendsfor a new Feature) exists and has its pending entry (unless all its Tasks of an approved target are alreadyDone); - no Task, TestSuite or TestCase was edited beyond what
plan.mdlists (dropping links to a concept a redesign deleted, or unlinking a Requirement that approving a ChangeRequest removed); designBasedOnnames the target's current version andversionDate;- the status is
Approved(orInDev/ImplementedwhenDoneTasks exist) only when the target wasReqApprovedand none of its Tasks is outdated (basedOnolder than the target'sversion), and the target Feature of a ChangeRequest was changed only when the ChangeRequest was approved.
Commit message: arch(<Key>): <title>. In the summary, "For other skills"
lists the Tasks, stories and TestGroups reported out of date, and "Next" is
"sdlc-plan-tasks, sdlc-design-story-tests and sdlc-design-feature-tests after the merge". When the target
is still a draft, add: "the Tasks can be built and closed while the spec is a
draft; the Design files' pending entries stay until the target is approved".
7. Approving a design that is current
When Tasks already exist. An approved target never has an outdated Task
(basis.approved-task): the Requirements cannot change after approval, so
every Task must catch up with the current version before it. Before setting a
ReqApproved target to Approved, InDev or Implemented, run
$T outdated and $T coverage tasks for the target. If any Task, Todo or
Done, is outdated (basedOn older than the target's version), or any
Design concept is uncovered while Tasks exist, approve nothing: keep the
status ReqApproved, list each outdated Task and uncovered concept in the
summary, and name sdlc-plan-tasks under "For other skills" (it plans a Task
for each difference and updates the basedOn of each Done Task it checked).
Then run this skill again to approve.
When the Tasks are current and at least one is Done, remove this target's
# Pending changes entry from each Design concept whose covering Tasks of
this target are all Done; when a concept has no pending entry left, remove
# Pending changes and set its status to Active (or Deprecated when it
was Removing). Set a Feature with any Done Task to InDev (otherwise
Approved), and a ChangeRequest whose Tasks are all Done to Implemented
(otherwise Approved).
Applying a ChangeRequest. When a ChangeRequest is approved, in the same
draft: set its status (Approved or Implemented), remove the pending
entries of concepts whose Tasks of this ChangeRequest are all Done, and
update the target Feature's Requirements (the Feature's copy becomes the
current text) and its # Architecture to the new target. The Feature's
version does not change: the ChangeRequest has its own. When that removes a
Requirement a Feature user story lists, fix those stories in the same draft as
the last rule of user-story.md says, unlink that Requirement's anchor to
plain text in any Task's # Acceptance, list them in the Run plan and show
the edits at the Design gate. When it removes a Requirement that TestCases
cover, fix those cases the same way, as the last rule of test-case.md says.
A changed Requirement keeps its key: its stories stay as they are.
The short run (APPROVE): a ReqApproved target whose design was made from
its current version. First do the check of "When Tasks already exist": when it
fails, stop before any draft and give the summary it names. Otherwise read
references/write-protocol.md and use the short run in the draft
arch-<Key>:
- Look up.
- Ask only when the lookup leaves something undecided.
- One stop that is the Intent and the Design gate together: the exact changes, file by file.
- Write.
- The Change-set gate.
- Commit, then the summary with "Done" and "Next" only.
There is no Run plan and no self review beyond the tool's own checks. The one stop shows, file by file:
- a Feature:
status: Approved(orInDevwhen a Task isDone, plus the Design files whose pending entries for the Feature are removed); - a ChangeRequest:
status: Approved(orImplementedwhen every Task isDone), the Feature update above, and any Design files whose pending entries for the ChangeRequest are removed.
Then the Change-set gate and the commit, arch(<Key>): approve. A
ChangeRequest whose Delta no longer fits the target Feature (another
ChangeRequest changed it meanwhile) is a REDESIGN, not an approval: say so
and go back to section 2.
The summary
End the run with at most four lines:
Done: wiki/arch-FEAT-coupons, 4 files, pushed. Open the pull request.
Not done: services/SVC-orders/overview.md (the contract for refunds is undecided)
For other skills: REQ-coupons-expiry is ambiguous (sdlc-write-spec)
Next: sdlc-plan-tasks, sdlc-design-story-tests and sdlc-design-feature-tests after the merge.
Leave out "Not done" and "For other skills" when they have nothing to say. Do not list what the self review fixed, and do not repeat the design: the person approved the content at the gates, so the last message only says where it is and what comes next.
Done when
- The target and the design choices were confirmed in the rounds, and the design basis was approved at the Intent gate.
- Every Requirement maps to concrete target concepts.
- Existing systems were searched and reused where they fit.
- Interfaces, data, security, failure paths, quality targets and rollout are explicit.
- Every material one-way choice has an accepted decision.
- Every changed concept has its target status and pending entry.
designBasedOnnames the version designed from, and the status isApprovedonly for a target whose Requirements are agreed.- Downstream Tasks and TestSuites were confirmed current or reported out of date.
- The self review found nothing it could not fix, or the person accepted what was left at the Change-set gate.
draft finishwasok, the change set was approved, anddraft commitreported the branch.
Files included
- agents/openai.yaml
- references/adr-format.md
- references/architecture-checklist.md
- references/contract-rules.md
- references/read-protocol.md
- references/write-protocol.md
- RELEASE
- SKILL.md

