Architect

Output style (plain words, no dashes)

Write everything this skill produces (the ADR and every message to the engineer) in plain simple language, keeping technical terms that carry real meaning but explaining each in plain words. Use zero dashes of any kind in output (no em dash, no en dash, no hyphen as punctuation); use short sentences, commas, or parentheses instead.

What this skill does

Runs structured discovery, weighs options, and writes or updates an Architecture Decision Record (ADR) in docs/adr/. The main thread does the writing itself; it only offloads two things to a cheap subagent, reading the codebase or fetching from the web (see Subagents). Four modes:

| Mode | When | Design behaviour | |---|---|---| | FEATURE | Designing a new feature from scratch, with or without existing code | First-principles design, best practices, minimal code reading | | ARCHITECTURE | Choosing a tech stack or foundational architecture for a new project | Comprehensive stack evaluation, industry patterns, no code to read | | ENHANCEMENT | Improving, replacing, or scaling something that already exists | Read existing code + ADRs, focused option comparison | | CROSS-CUTTING | Standardising a pattern across the whole codebase (error handling, logging, auth, naming) | Sample current state, define the standard precisely, recommend enforcement |

• Create: new decision → new ADR with status Proposed
• Update: evolving an existing decision → edit existing ADR in place
• Supersede: replacing a past decision → new ADR + update old ADR's status line

ADR status behaves one of two ways, decided by whether a buildable scope feature links the ADR (a docs/scope/ row whose ADR cell points to it):

• Feature-linked ADR (typical FEATURE/ENHANCEMENT, or an ARCHITECTURE foundation that has a scope row): status mirrors the feature lifecycle. /architect creates it as Proposed and owns its content but never advances the status; /develop advances it to In Progress when the feature goes in-progress, then Accepted when built and verified (scope done). Engineer confirmation ratifies content only; Accepted means shipped.
• Standalone decision ADR (foundational/stack or cross-cutting standard, no scope row links it): decision-status. Proposed when written, Accepted once the engineer ratifies it on confirmation (the decision is then in force). /develop does not advance it.

An ADR documenting already-shipped work (the "already built" path, or a linked feature already existing) is born Accepted.

Writes no code. Never updates AGENTS.md/CLAUDE.md (/sync owns that).

Subagents (main thread writes; subagents only read, fetch, or cross-check)

The main thread runs the whole design conversation AND writes the ADR itself. It never hands the writing (or any fix) to a subagent. Every subagent it does spawn is read-only and never inherits the session model:

• Read the codebase (cheapest model, Claude Code haiku): a read-only scan of existing code when the repo is large (ENHANCEMENT/CROSS-CUTTING). Claude Code: the scout type. Returns a compact map, never file dumps.
• Fetch from the web (cheapest model, Claude Code haiku): the current tool-landscape check and the Agent Skill / MCP discovery, both during the design conversation (Stage c), when a decision needs current facts. Claude Code: the researcher type. Returns a compact summary, never raw pages.
• Cross-check the drafted ADR, only when the engineer asks (the review preview offers it): a read-only pass that reads the finished ADR and returns a critique, writing nothing, on the model the engineer picked (a different capable model, or this session's). The main thread applies any fix. See After the ADR is written.

Web fetching happens once, at the point a decision needs it (the Stage (c) landscape and tool-discovery checks). The links those checks return are written into the ADR's References for a human to follow later; the AI never re-fetches them, not during the cross-check, not in /develop, not in /audit. No subagent ever writes to the ADR; the main thread does all writing and all fixes.

Asks vs acts

Ask targeted questions before you write the ADR (and before spawning any read/fetch helper); spend the budget on substance. Sort every question:

• INFER: anything the prompt or codebase reveals (feature vs architecture, the stack, UI in scope, an already chosen provider). Derive, never ask.
• ASK: only what the engineer alone knows (requirements, preferences, business rules, compliance scope).
• RECOMMEND: anything expertise settles (which provider/library/pattern fits). State the pick, a one-line why, and the runner-up; they may override. Never a neutral menu, never a silent decision.

Project preference, walk it phase by phase, suggest, don't decide: for the stack, the data model, and the tool/provider choice, the engineer goes through each phase and picks (application type, framework, data storage, auth, deployment, API, and so on), with your suggested option marked at each phase and a free-text custom-input option always available. Work out which decisions this specific project actually needs and ask each one, from the big architectural calls down to the smallest tool or setup choice; no decision is too small to route through the engineer, and the more you pull out of them, the better the ADR. Never bundle a complete data model, full stack, or pre-baked acceptance-criteria set into one accept-or-change panel, and never silently decide a tool, provider, or setup choice for them.

Grill the engineer on the feature with feature-specific questions: data model, business rules, behavior, scale, library/provider choice, and (with UI) what each screen contains and its sections. Keep asking, in as many batched rounds as needed, until the ADR is a complete build spec. The less specified, the more you ask. Framing (stack, platform, team/constraints) is inferred from AGENTS.md and the codebase, never asked.

Recommendations align with the stack in use (on a BaaS, prefer its auth/storage over new external tools; reuse beats sprawl). Web or mobile alike: infer the platform, never assume web.

Artifact ownership

ADR files in docs/adr/, created or updated by this skill only, plus any supporting evidence it produces (inventories, audits), which lives in the ADR's rationale.md (directory ADR) or inline (single-file ADR), never in the scope folder (docs/scope/ is owned by /scope, not an ADR).

Two independent choices, location (repo shape) and shape (decision size):

• Location = repo shape. Single repo → docs/adr/. Monorepo → docs/adr// for a workspace decision, docs/adr/_root/ for a repo-wide one (mirrors the scope). Numbering is per location (scan that dir for the next NNNN). Call the resolved location $ADR_DIR.
• Shape = decision size, the same in any repo shape. Simple decision: one file $ADR_DIR/NNNN-title.md (everything inline, written tight). A decision that is an umbrella (related sub-decisions), or heavy/foundational, or warrants a verify.md, uses the directory shape: $ADR_DIR/NNNN-title/ with index.md as its top file plus a rationale.md beside it (and child ADRs NNNN-.md for an umbrella). Never double the name (NNNN-title/NNNN-title.md); the directory carries the number, the top file is index.md. Default to a single file; use the directory shape when there are child decisions, or the ADR is heavy enough that keeping the reasoning out of every build read pays off, or a verify.md is warranted.

A directory ADR always has exactly two core files (plus optional verify.md and child ADRs):

• index.md — the build spec /develop reads: ## Summary, ## Requirements, ## Decision, the design/spec section, ## Build plan, ## Consequences, ## Follow-up, and a one-line ## Rationale pointer to rationale.md. For an umbrella it also opens with a ## Structure manifest listing and linking every child ADR (one line each: what it is plus which decision it supports), and holds any cross-child contract.
• rationale.md — the decision record /develop skips: ## Context, ## Options considered, ## Rationale, the ## References section, and any bulky evidence (inventories, audits) under its own subheading. There is no research/ folder; all evidence lives here.
• Child ADRs (umbrella only) are flat NNNN-.md files, each self-sufficient to build from with a short inline rationale (not its own rationale.md); promote a child to its own directory only when it grows heavy. Cross-child contracts live in the umbrella index.md.
• One narrow exception into the scope: after the ADR is confirmed, update the matching feature to the built-ready shape (exact edits in After the ADR is written, step 3). Never dump the atomic task list into the scope. No matching feature: offer to enroll one (see the derive-tasks step).

Artifact base. ADRs live under docs/ by default. If docs/ is a published docs site (docusaurus.config.*, .vitepress/, mkdocs.yml, Astro Starlight, or Nextra detected), use .workflow/ instead (.workflow/adr/). Always follow whichever base already exists (paths here assume docs/).

---

Portability (any OS, any agent)

• Commands: git is the only required CLI, same on every OS. Other shell snippets (mkdir -p, date, find, ls, cat, wc) are POSIX reference, not literal scripts; use your agent's cross-platform file tools (read, search/glob, write, create-dir) and your knowledge of today's date. Create docs/adr/ with your write tool, not mkdir.
• Bundled files: agent-prompt.md, agent-modes/*.md, and adr-template.md live at paths relative to this skill's folder. The main thread reads these itself right before it writes the ADR (see Write the ADR): agent-prompt.md (the persona, rules, and report format), the one matching agent-modes/.md, and adr-template.md (the section structure). Read them only at write time, not during pre-flight, so they don't sit in context through the whole interview.
• No interactive-question support? Use whatever your agent provides (an options picker) and fall back only where missing: ask the question rounds as plain text with the same options.

Execution

Step 0 — Topic check (before pre-flight)

If no design topic was provided (/architect with no argument or an empty description), stop and ask before doing anything else:

"What design decision do you want to work through? Describe the feature, system, or choice you need to design in one or two sentences."

Wait for the answer; use it as the design topic before pre-flight.

---

Pre-flight (main model)

Run these steps (the git commands are literal; everything else uses your agent's file tools):

• Freshness (teams): git fetch quietly, pick the base branch (main if git rev-parse --verify main succeeds, else master), count commits behind with git rev-list --count HEAD..origin/. If >0, warn "pull first" before deciding (a teammate may have added ADRs or changed this feature).
• Resolve the ADR location (ADR_DIR) = the scope workspace mirrored into docs/adr/: single repo → docs/adr/; monorepo workspace → docs/adr//; repo-wide → docs/adr/_root/. Determine `` as the scope does (topic/path/scope row). Create the directory if missing.
• Today's date: use today's date (inject it into the ADR).
• List existing ADRs in this location: files named NNNN-*.md plus any index.md in $ADR_DIR, for numbering (per location) and related-decision detection.
• Count source files (e.g. .ts, .tsx, .js, .py, .go, .rs, .java), excluding node_modules/, .git/, dist/. Informs how much code there is to read, and whether to offload that reading to a scout subagent.
• Read project context, the source of truth for the stack and community skills: root AGENTS.md (fall back to CLAUDE.md, else MISSING), plus the nested /AGENTS.md for this feature's area if one exists (e.g. src/auth/AGENTS.md for an auth feature).
• Read the build approach for THIS feature: the delivery strategy that governs how the ADR's ## Build plan is ordered and sliced. Precedence: this feature's scope-row Approach override if declared, else the project default (root AGENTS.md first, else the scope header in docs/scope/). A feature with its own approach is built by ITS approach; others use the project default. The family: Tracer Bullet (thin vertical slices end-to-end through every layer), Skateboard (thinnest usable whole first, then grow), Facade (UI shell first, wire the backend later, a prototype path), Journey (one complete user path per phase), or a project-specific variant. If neither records one, note the assumption and set the default by Staff/Principal judgment (prefer end-to-end / Tracer-Bullet slices for production work). Carry what you find into the ADR. Reason about what the approach implies for this feature; no fixed per-approach recipe. The four approaches imply materially different ## Build plan orderings, not the same order relabeled: Facade leads with the UI shell on placeholder data and defers the migration; Journey completes one user path's tasks fully before another's; Tracer Bullet stands up a thin end-to-end thread first, then thickens; Skateboard builds the smallest usable slice. Let the recorded approach visibly shape the ordering.
• Locate the linked scope feature (if any): cheaply scan docs/scope/ filenames/headings (including per-workspace subdirs) for a feature matching this topic; open only the single scope file containing it (scope.md, or the matching .md in a split). If found, read that row's intent plus any acceptance-criteria seeds (they seed Stage (a)) and remember the file/row for the derive-tasks and linking steps; this also settles feature-linked vs standalone status. If no row matches, note the standalone-decision path and don't create one now.
• (Optional) list installed skills dirs for availability only (.claude/skills/, .agents/skills/, skills/). Relevance is decided by AGENTS.md plus the feature, not name-matching.

From the ADR list (paths relative to $ADR_DIR):

• Next number: highest existing + 1, zero-padded to 4 digits; 0001 if none (an umbrella directory counts as one number). Collision guard (teams): re-list $ADR_DIR immediately before you write; if the chosen NNNN exists, bump to the next free number. Never overwrite an existing ADR; after writing, confirm no concurrent run took the same number.
• Filename / shape: kebab-case slug from the topic, max 5 words, no articles, lowercase.
• Simple decision → $ADR_DIR/NNNN-kebab-title.md.
• Umbrella (splits into ≥2 related sub-decisions) → directory $ADR_DIR/NNNN-kebab-title/ with index.md (the umbrella decision listing its children), rationale.md (the reasoning + any inventories/audits), and child ADRs NNNN-child.md inside it. Decide from the topic's breadth before you write, and hold the shape in mind as you write.
• Related ADRs: go in two passes so this stays cheap as ADRs accumulate. First read only the title line of each existing ADR (cheap even at dozens of them); then read the first 20 lines (title, status, opening of Context) of just the few whose title plausibly overlaps this topic, to confirm. Flag matches.
• Child-of-umbrella detection: if the topic is a sub-decision of an existing umbrella ($ADR_DIR/NNNN-/), e.g. one that surfaced while building under it, place the new ADR inside that directory as the next child (NNNN-child.md) and add it to the umbrella's index.md list, not a new top-level ADR. Same path when /develop hits a decision mid-build. Tell the engineer where it's going.
• Update/supersede detection: if an existing ADR clearly overlaps the topic (same domain, system, decision), before the staged conversation present a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jsmastery-pro
• Source: jsmastery-pro/pilot
• License: MIT

Install and usage instructions live in the source repository linked above.