ntanh1402/sdlc-skills

sdlc-design-arch

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 diag…

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/ntanh1402/sdlc-skills --skill sdlc-design-arch

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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: # Architecture filled and designBasedOn set to the

Feature's version. When the Feature is ReqApproved (and no existing Task is outdated or uncovered), its status becomes Approved, or InDev when a Task is already Done (removing the pending entries of concepts whose Tasks are all Done). A Draft Feature stays Draft.

  • ChangeRequest: # Delta filled and designBasedOn set. When the

ChangeRequest is ReqApproved (and no existing Task is outdated or uncovered), in the same change: status Approved (or Implemented when every Task is Done), the target Feature's Requirements and Architecture updated to the new target, and pending entries removed for concepts whose Tasks are all Done. While it is Proposed, 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:

bash
cd "$WIKI" && $T copy check --release "<the line in RELEASE>"
statusDo
currentGo on
olderStop: "The wiki's tool is older than this skill. Run sdlc-setup-wiki to upgrade the wiki."
newerStop: "The wiki was set up by a newer release. Update your installed sdlc-skills."
editedStop: "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.

RequestSkill
Show or explain an existing architecturesdlc-ask-wiki
Requirements are missing, unclear or not approvedsdlc-write-spec
User storiessdlc-write-stories; it runs at the same time as this skill
Build tasks, or test design, from an approved designsdlc-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:

StateWhenDo
READYA Feature Draft or ReqApproved, or a ChangeRequest Proposed or ReqApproved, whose Architecture (Feature) or Delta (ChangeRequest) is NoneGo on
REDESIGNThe same statuses, already designed, and designBasedOn names an older version than version, or the person asks to change the designGo on, revising the design in place (section 5, "A design written again")
APPROVEReqApproved, designed, and designBasedOn names the current versionThe short run of section 7: no new design
NOT_MERGEDNot on the default branch, but a wiki/*-<Key> draft existsStop and name the draft (git branch -a --list 'wiki/*-<Key>')
ALREADY_DESIGNEDApproved or laterStop: a change to the design is a new ChangeRequest, written with sdlc-write-spec
AMBIGUOUSSeveral candidatesOne question that names them; write nothing until it is answered
CONFLICTThe requirements contradict an accepted decision or a live contractShow 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.

text
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 Todo Task has

started. List the existing Tasks and TestSuites the design will make out of date, and ask which of the Todo Tasks 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:

  1. Context and constraints.
  2. The concept ledger: every concept new, modified, removed or reused, with the

reason.

  1. The high-level Mermaid flowchart, and one sequenceDiagram per main flow

with its failure branches.

  1. The contract of every new or changed concept, as its schema page requires.
  2. The decisions, with alternatives.
  3. Traceability: each Requirement to the concepts that satisfy it.
  4. Drift, risks, rollout and rollback.
  5. Downstream freshness: each existing Task or TestSuite this design makes out

of date, and which Todo Tasks 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 # Architecture with its nested sections in the schema's

order (## Context and constraints, ## High-level architecture, ## Services, ## Frontends only with a user interface, ## Runtime sequences, ## Decisions, ## Traceability). Set designBasedOn: { version: <its version>, at: <its versionDate> }. Set status: Approved only when it is ReqApproved.

  • ChangeRequest: fill # Delta (## Target delta with every concept

qualified new, modified or removed, ## Runtime sequences, ## Decisions, ## Traceability) and set designBasedOn the same way. When it is ReqApproved, also apply it (section 7, "Applying a ChangeRequest"). While it is Proposed, 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 with status: Modifying; set each removed one to status: Removing and keep its file. Give each a last section:

markdown
  # 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 changes section gets one more entry.

  • Calls go under the caller's # Calls. Never write a reverse section

(# Used by, # Publishers, # Subscribers, # Superseded by) or an index.md; the tool writes them.

  • Decisions: decisions/ADR-<name>.md with status: Accepted, linked

from ## Decisions.

  • Logs: an entry in the log.md of 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 Done Task of this target already built the

concept, its code is merged in the repository, so set the concept to status: Removing with a # Pending changes entry (removed) so sdlc-plan-tasks plans a new Task to remove the code. Otherwise remove this target's pending entry: a Planned file with no entry left is deleted (it was never built), and a Modifying or Removing file with no entry left gets back the text it had before this target's first design (git log on the file) and its live status;

  • a Todo Task 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-tasks replans 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 ## Services and ## Frontends

for a new Feature) exists and has its pending entry (unless all its Tasks of an approved target are already Done);

  • no Task, TestSuite or TestCase was edited beyond what plan.md lists

(dropping links to a concept a redesign deleted, or unlinking a Requirement that approving a ChangeRequest removed);

  • designBasedOn names the target's current version and versionDate;
  • the status is Approved (or InDev / Implemented when Done Tasks

exist) only when the target was ReqApproved and none of its Tasks is outdated (basedOn older than the target's version), 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>:

  1. Look up.
  2. Ask only when the lookup leaves something undecided.
  3. One stop that is the Intent and the Design gate together: the exact

changes, file by file.

  1. Write.
  2. The Change-set gate.
  3. 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 (or InDev when a Task is Done, plus the

Design files whose pending entries for the Feature are removed);

  • a ChangeRequest: status: Approved (or Implemented when every Task is

Done), 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:

text
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.
  • designBasedOn names the version designed from, and the status is

Approved only 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 finish was ok, the change set was approved, and draft commit

reported the branch.

from this repository

More skills

All skills
ntanh1402
Community

sdlc-ask-wiki

Answer questions from the project wiki without changing it - list an application's Features with status, spec version, owner, priority, design readiness and open ChangeRequests; list what was written from an older version of a spec; show one Feature's approved architecture with its diagrams, services, frontends, contracts, decisions, traceability and what is not built yet; show one Endpoint or consumer with its input, output, validations and diagrams; show a user story or print its paste-ready c

1h installs
2
GitHub stars
1
Updated
Nov 13
ntanh1402
Community

sdlc-build-task

Write the code and unit tests of one wiki Task in one code repository, against the project wiki - read the Task's acceptance and planned scope, the contracts of the Design files it covers and the Application's conventions, plan the files, write them in a git worktree on a branch of their own, check them against the wiki and commit with a Task trailer, without pushing. Use when a developer asks to build, implement or code a Task of the project wiki. Not for coding without a wiki Task, for changin

1h installs
2
GitHub stars
1
Updated
Nov 13
ntanh1402
Community

sdlc-close-task

Record in the project wiki that the code of one wiki Task is merged - set the Task Done with its merge commit, remove the pending entries of the Design files it covered and mark them live, and move its Feature to InDev or its ChangeRequest to Implemented. Use after a Task's pull request is merged, when a developer asks to close, finish or complete a Task in the wiki. Not for closing a ticket in a tracker, for merging or reviewing code, for marking a Feature released, or for any other change of s

1h installs
2
GitHub stars
1
Updated
Nov 13
ntanh1402
Community

sdlc-convert-doc

Convert local documents into Markdown by routing text-bearing files through Microsoft MarkItDown and OCR-heavy inputs through Datalab Marker. Use when asked to convert PDFs, scanned PDFs, images, Word, PowerPoint, Excel, HTML, EPUB, email, archives, or other document files to Markdown, especially when OCR, tables, equations, layout preservation, or extraction-quality fallback is needed.

1h installs
2
GitHub stars
1
Updated
Nov 13