design

Architecture Designer — Main Design Workflow

This skill guides the user through a six-stage design process plus a sequence of post-design steps (architecture review, optional persona reviews, browser preview, optional visual verification, user confirmation, low-level design, test strategy, document save, document review, implementation offer), ending with browser-rendered Mermaid diagrams, low-level design artifacts, a test strategy, a reviewed and approved document, and an optional code skeleton.

Always use this skill for new architecture design, even if the user has already started describing their system in the conversation — do not skip straight to diagram generation or freeform advice.

Scripts directory: ../../scripts/ relative to this SKILL.md — referred to as <scripts_dir> throughout this file. Resolve it at runtime from this SKILL.md's absolute path.

---

How to run this workflow

Before starting — check for an existing session: look for docs/architecture-designer/session.json. If it exists, read it and ask the user:

"I found an existing design session for

[project name from the file, or 'a previous project' if unnamed] — [description from the file, or omit this clause if unset].

Would you like to continue where we left off, or start a new design from scratch?"

If continuing: first check progress.owner, if the key is present. If it reads "review" and progress.lastCompletedStep is before step11 (per references/session-schema.md section "Resuming Steps 6a–13 via progress" step 2 — step11 means that /architecture-designer:review pass already reached a document save and left a clean handoff), a /architecture-designer:review revision died mid-pipeline, not this skill's own design pipeline — this skill's resume logic below only covers the original design pass. Tell the user: "It looks like a previous /architecture-designer:review revision didn't finish. Run /architecture-designer:review to resume it instead." and stop here rather than proceeding into Stage resume. Otherwise (progress.owner is "design", the key is absent — legacy sessions predating this key, or one that never reached Stage 6a — or it reads "review" with lastCompletedStep at step11 or later, meaning that pass already completed cleanly): brief the user on where the previous session left off and resume from the first incomplete stage. Once stage1–5 are confirmed (the "Session completeness gate" precondition — stage6b/6c are not required, since Stage 6a can already have progressed before either is confirmed), also apply references/session-schema.md section "Resuming Steps 6a–13 via progress" — a session that died anywhere from Stage 6a through Step 13 should resume there, not restart the whole pipeline, and any pending key found means the previous session died mid-stage within 1–6c (same section covers this). If starting fresh: delete docs/architecture-designer/session.json (and docs/architecture-designer/diagrams.json and docs/architecture-designer/last-review.md if present) first.