| name | architect |
| compatibility | Built for Claude Code (subagents, model selection, interactive questions). Installs on any Agent Skills client. |
| allowed-tools | Bash, Read, Grep, Glob, Write, Edit, Task, AskUserQuestion |
| description | Make and document an architectural or technical decision before writing code. Run /architect for a meaningful choice between approaches, a feature or page designed from scratch, a stack decision, or when /develop says a decision is owed. Acts as a Staff/Principal engineer: challenges bad directions, asks deep feature-specific questions, recommends rather than lists, then writes a complete-build-spec ADR to docs/adr/ for confirmation. Owns all ADR files. |
Read ../conventions.md first (once per session). It carries the session start gate, model routing (this skill: strongest tier), panel rules, subagent rules, context economy, and output style. Apply the start gate before anything below.
What this skill does
Turns one open decision into a ratified ADR that is the complete build spec /develop implements from. One decision per run. It designs with the engineer (staged questions, suggested picks, they choose) and drafts via a subagent (the long ADR never sits in the main session).
Owns: every file under docs/adr/ ($ADR_DIR). Touches: the one linked roadmap feature's row (tick Design, link ADR, add the milestone rollup). Never: writes code, writes AGENTS.md (/audit and /sync own that), or creates files in docs/roadmap/.
Execution
Step 0 — Topic check
No topic given: ask "What design decision do you want to work through? One or two sentences." Wait, then proceed.
Pre-flight (main model, cheap)
- Freshness (teams):
git fetch; base = main else master; if git rev-list --count HEAD..origin/<base> > 0, warn "pull first."
- Resolve
$ADR_DIR (per conventions: per-workspace in a monorepo, _root/ for repo-wide). Create if missing. Note today's date.
- List existing ADRs in
$ADR_DIR (NNNN-*.md, index.md). Next number = highest + 1, zero-padded to 4 digits. Re-list right before the subagent writes (collision guard); never overwrite.
- Shape: simple decision →
NNNN-kebab-title.md (slug of 5 words max). Splits into 2+ sub-decisions → umbrella directory NNNN-title/ with index.md, child ADRs inside, research under NNNN-title/research/. A sub-decision of an existing umbrella (e.g. surfaced mid-build by /develop) lands inside that directory as the next child, added to its index.md.
- Overlap: read the first ~20 lines of each existing ADR. On clear overlap, panel: "Existing ADR may overlap:
<path>. Treat as?" New decision · Update in place · Supersede; pre-select by strength of overlap. Update/supersede: read the old ADR in full, set OPERATION, skip the staged conversation for in-place updates.
- Project context: root
AGENTS.md (fallback CLAUDE.md, else MISSING) plus the nested <area>/AGENTS.md for this feature's area. Count source files (tells the subagent how much code to read).
- Build approach for THIS feature: the feature's roadmap-row
Approach override, else the project default (root AGENTS.md, else the roadmap header). Carry it to the subagent; it shapes the ## Build plan slicing. None recorded: note the assumption, default to end-to-end slices.
- Linked roadmap feature: scan
docs/roadmap/ filenames and headings, open only the one file containing it, read its intent and acceptance-criteria seeds (these seed Stage a). No match: standalone-decision path, note it.
- Community/tool skills:
AGENTS.md (root + area) is the source of truth for what the project uses; identify only the skills relevant to this feature. Available is not relevant. A clearly relevant installed skill missing from AGENTS.md: use it and flag as an ADR follow-up. Whatever the project already runs is what your recommendation must build on or prefer.
Scope validation (in order)
Check B, already built: topic reads as an existing decision ("we chose", "already using", "just document") → panel: Document it (recommended) · Full design process. On Document: ask three free-text questions (alternatives considered, main reason, accepted tradeoffs), skip the stages, inject the answers as DOCUMENTATION_CONTEXT, and tell the subagent the ADR is born Accepted (already shipped).
Check A, product vs decision: a product-scoped topic ("a marketplace for freelancers") is not one decision. Say so, offer a panel of 4 foundational first decisions tailored to the product (typically stack/architecture, auth, core data model, the top product-specific concern), proceed with the pick.
Enhancement guard: inferred mode ENHANCEMENT with zero source files → stop and ask whether the code lives elsewhere (re-check that path) or does not exist (switch mode).
Framing — infer, don't interrogate
Infer from the topic + AGENTS.md + code, state it back in one line for cheap correction ("Reading this as a new FEATURE on your existing stack, web; correct me if not"): Mode (FEATURE · ARCHITECTURE · ENHANCEMENT · CROSS-CUTTING) · Platform (never assume web) · Workspace (monorepo: which app; read its nested AGENTS.md) · Stack and conventions (inferred, never asked) · Constraints (a compliance question only when this feature touches regulated data). Spend the whole question budget on the feature, none on the framing.
Staged design conversation (main model)
The core discipline: one dimension per question, real options with a suggested pick, the engineer chooses, and the spec is assembled from their answers. Never present a stage as a pre-filled bundle to accept or reject (a full AC list, a complete ERD, an entire stack in one box); that bundling is the known failure mode. Batch up to 4 closely related questions per panel round; run as few rounds as the stage allows. The assembled result is confirmed once, in the final ADR review (the data model also gets one light confirm at the end of its own walk, because a wrong model cascades).
Before the stages, enumerate every load-bearing dimension of this feature and sort each INFER / ASK / RECOMMEND. The checklist (apply what fits, add feature-specific ones): functional scope and boundaries · data model and persistence · lifecycle/state machine · API surface · authn/authz · validation and business rules · external integrations (webhooks, idempotency) · library/provider and build-vs-buy · failure and edge cases · performance and scale · security and compliance · observability · configuration and secrets · UX surface requirements (pixel detail stays with /develop) · SEO for public pages · and, when the topic IS a page: design source, design system, page composition, component inventory, asset strategy.
Leaving a gap is the failure mode: every blank dimension becomes a mid-build question or a wrong guess in /develop. Be exhaustive on load-bearing calls. Collect the RECOMMEND items as a list the subagent must decide (pick, one-line why, runner-up), never echo back as open questions.
- Stage (a) Requirements: ask one question at a time (core job, happy path, key rules and limits, important failure cases), seeded from the roadmap row. Derive the acceptance criteria (
AC-1…) from the answers; they are the contract the build satisfies and the spine every later stage hangs off.
- Stage (b) Data model (mandatory for data-backed features): elicit entities → fields (name, type, nullability) → relationships (cardinality) → rules (uniqueness, retention, invariants) in batched questions. Assemble, SHOW as an ERD-style table, confirm panel (
Matches (recommended) · Change a field or entity · A relationship is wrong), iterate to Accept. The migration becomes build task 1.
- Stage (c) Stack and tool walk: one layer per question in dependency order, layers derived from the platform and topic (not a fixed script), options generated fresh and current at runtime (never a canned list; be honest about staleness). Skip every layer the existing stack settles. For a greenfield ARCHITECTURE decision this walk IS the whole conversation; stages b/d/e/f collapse into "derived from the chosen stack," and the tool-skills offer below always runs after the walk.
- References consent (one panel, once): "Add a References section? The Rationale stays either way."
No references (recommended) → REFERENCES_LEVEL=none · Sources only → sources · Sources plus web-verified links → sources+links. For greenfield stack decisions recommend sources+links instead and run a current-landscape check (web subagent) before presenting stack options. Record the level; never re-ask.
- Tool skills and MCP offer (mandatory once tools are settled): for each newly chosen tool, detect fresh (
npx skills find <tool>, or a web search for " agent skill" / " MCP server"; never a hardcoded table), skip what AGENTS.md shows installed or declined, then one panel per tool: install skill and connect MCP · skill only · MCP only (no recommended pick; only options that exist). Act on the pick (npx skills add <owner>/<repo> -y; MCP connection is a user config step, point them there). Record installs for the ADR's Implementation skills field and declines for AGENTS.md so nothing re-offers. No search capability: fall back to an ADR follow-up naming the skill/MCP.
- Stage (d) API surface: one endpoint at a time (method, inputs, outputs, auth, key errors), a suggested shape per question.
- Stage (e) Security and authorization: rule by rule (ownership, roles, tenant scoping, compliance triggers).
- Stage (f) Edge cases and failure modes: one failure at a time (concurrency, retries, timeouts, partial failure, empty/error/loading states), a sensible default suggested per question.
- UI-page features: insert a page-design stage after (a): design source (ASK, never assume, even with a Figma MCP connected: From Figma · From a screenshot · From existing
design.md · No design yet, suggest a direction; record the source in the ADR) · design system · page composition · component inventory (existing vs net-new) · asset strategy when no assets exist.
Fallback only, when the topic is too vague to generate good questions: scaffold from questions/<mode>.md. Quality bar: every option maps to a real, feature-specific decision with a one-line tradeoff; no placeholder questions; no source citations in option labels (sources belong in the ADR).
After all stages: the confirmed ACs seed ## Requirements; the confirmed model, surface, and stack derive ## Build plan (each task tagged with the ACs it satisfies, migration first), sliced per the build approach. Decision-only ADRs (ARCHITECTURE, CROSS-CUTTING) get no Requirements or Build plan; the spec is ## Proposed stack / ## Standard definition, and /develop derives scaffold steps at build time (writing them in both places is the double-spec bug).
Subagent spawn (drafting leaves the main session)
Read agent-prompt.md and adr-template.md now (lazy). Fill the prompt and spawn a drafting subagent (mid-tier model; add WebSearch/WebFetch only when REFERENCES_LEVEL=sources+links):
- Inject only the resolved mode's block from the prompt's
## Instructions by mode (drop the other three).
- Inline the ADR skeleton between the template's START/END markers; omit the trailing filename/status/writing-rules meta sections (main-agent guidance, not subagent material).
- Inject: topic · inferred framing · build approach · all staged answers stage by stage (or "skipped, documenting a made decision") · RECOMMEND items (or "none") ·
REFERENCES_LEVEL · AGENTS.md contents · existing ADR list and related paths · $ADR_DIR, number, shape (umbrella: name the children; research goes under …/research/, never in docs/roadmap/) · source file count · operation (create / update / supersede; supersede also sets the old ADR to Superseded by [NNNN](…)) · date · documentation context if any · community skills as paths plus one-line relevance notes, not full content (the subagent reads on demand; inline full content only on clients whose subagents cannot read files).
After the subagent
ADR file missing or empty: report the failure, offer a re-run, never fabricate a summary. Otherwise:
- Self-check the file for the required sections per mode (Summary · Context · Requirements with IDed ACs · Options considered · Decision · Rationale · Consequences; Build plan with every AC traced to a task for data-backed modes; Feature design / Proposed stack / Migration plan / Standard definition per mode; decision-only ADRs must have no build plan, strip one if present). Flag any gap inline: "⚠️ Incomplete:
- Design-review gate (full-tier or foundational only): a fresh-model subagent critiques the draft (does it hold? is there a materially simpler option? which failure mode is missed?); surface the verdict, fix clear issues with targeted Edits. Skip for lean/medium and where subagents are unavailable (say so).
- Present: path, Decision line, Key tradeoff, Design review note. Then the confirmation panel:
Accept (recommended) · Change something · Rethink the approach. Apply feedback with targeted Edits (never a rewrite), re-present the same panel until Accept.
- On Accept, status by kind: a feature-linked ADR stays
Proposed (it moves to In Progress and Accepted via /develop as the feature builds and ships). A standalone decision ADR (no buildable feature) is set Accepted now (ratification is the deliverable). The documentation path was born Accepted.
- Link the roadmap (edit only this feature): buildable feature → tick
Design it (ADR), remove · needs a decision, link the ADR (relative path; an umbrella links its index.md), add - [ ] Build it: /develop <feature> with 2 to 5 milestone sub-items rolled up from the Build plan (atomic tasks stay in the ADR), add - [ ] Test it: /test <feature>, set status in-progress. Enroll genuine follow-up features as new rows tagged from ADR NNNN. Decision-only ADR → link the ADR cell, tick the Decision sub-task, leave execution sub-tasks untouched. No matching feature → panel: "Track this on the roadmap?" Yes: enroll it in the built-ready shape. No: note the ADR is off-roadmap.
Close (plain words)
Done. Here is the quick version.
What we decided: <one plain sentence>.
Why: <one plain sentence>.
Next: run /clear (the ADR lives on disk; this long design chat only costs tokens now), then /develop <feature>.
Reference files (lazy)
adr-template.md (ADR skeleton and writing rules) · agent-prompt.md (drafting-subagent prompt) · questions/*.md (generic per-mode scaffolds, fallback only).
