# Architect > Architecture and implementation planning gate for complex or high-blast-radius work. Produces evidence-backed decisions, reviewable slices, acceptance evidence, and conditional human review ownership without editing code. - Skill: `flurdy/architect` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add flurdy/architect` - Raw SKILL.md: https://api.skillmd.com/api/skills/flurdy/architect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: flurdy (https://skillmd.com/u/flurdy) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/flurdy/architect --- # Architect Architecture and implementation planning before coding. Use this skill to spend deliberate reasoning budget on the plan, while leaving the implementation itself free to use a cheaper/faster model when the plan is clear. ## When to Use Use `/architect` for tasks with architectural uncertainty, high blast radius, or expensive mistakes: - Cross-module, cross-service, or multi-repo changes - New abstractions, boundaries, workflows, or domain model changes - Database/schema migrations or data backfills - Public APIs, event schemas, contracts, SDKs, or integrations - Auth, permissions, privacy, compliance, or security-sensitive work - Performance, scalability, resiliency, or concurrency-sensitive changes - Hard-to-reverse decisions - Ambiguous requirements or multiple plausible approaches - Work likely to split into several commits, beads, tickets, or PRs - Any task where the user explicitly asks for architecture, design, planning, or approach Usually skip it for: - Small bug fixes with obvious locality - Copy/text tweaks - Simple CSS/layout adjustments - Mechanical dependency bumps - Straightforward test additions - Refactors whose pattern and scope are already obvious ## Usage ```text /architect /architect ABC-123 /architect bd-456 /architect --tier premium /architect --tier second-opinion /architect --tier all-in /architect --no-prompt ``` ## Planning Tiers Do not expose model churn as the primary interface. Ask for a planning **tier** when the user has not specified one and the choice matters. | Tier | Meaning | Use when | |------|---------|----------| | `standard` | Standard coding tier | Moderate planning, low ambiguity | | `premium` | Premium reasoning tier, preferring subscription/OAuth routes | Architectural uncertainty or costly mistakes | | `second-opinion` | In-session draft + one vendor-independent `/second-opinion validate-plan` review | Need an independent validation pass | | `all-in` | Premium draft + one bounded `/second-opinion validate-plan --agent quorum --panel focused` review batch | High-risk, cross-service, security, data migrations | This skill declares `model-tier: premium`, but that is semantic routing metadata, not a mandate to use a particular provider or model. Prefer the best configured premium route; concrete route mappings, authentication, and metered classification live in the runtime rather than this skill. Treat external API-backed panels as separately consented, bounded routes. If the user names a specific model/provider, preserve that preference in the plan metadata and, where possible, recommend how to run the planning session with that route. If unavailable, fall back to the best configured reasoning tier and say so. ## Instructions ### Tier guard This skill is `model-tier: premium`. Before starting, check which model you are running as. If it is below the premium tier for this runtime (e.g. Sonnet or Haiku in Claude Code), say so and ask via `AskUserQuestion` whether to: - **Continue here** — accept reduced depth on this run - **Stop** — switch model (`/model` in Claude Code) or rerun in a premium session Skip the prompt when the user explicitly chose the current model or passed `--no-prompt`. On a premium model, stay silent and proceed. This guard checks the *engine*; the planning tier prompt below (step 2) chooses how much reasoning to *spend* — they compose. ### 1. Parse the Request Identify: - The task/request/question - Any Jira key (`[A-Z][A-Z0-9]+-\d+`) - Any bead id (`bd-...` or project-specific bead id) - Any explicit planning tier (`--tier standard|premium|second-opinion|all-in`) - Any explicit model preference (`--model ` or a natural-language model mention) - Whether the user asked not to be prompted (`--no-prompt`) If the request is missing or too vague, ask one clarifying question before investigating. ### 2. Decide Whether to Prompt for Tier If no tier/model was specified: - For clearly high-risk work, default to `premium` and state why; prefer the configured subscription/OAuth reasoning route first. - For very high-risk work (security/data/cross-service), ask whether to use `premium` or `all-in` before adding a bounded multi-model review. Explain that `all-in` queries the available subscription/OAuth-first CLIs and still requires explicit consent for any route that `/second-opinion` classifies as metered or unknown. - For moderate work, ask with `AskUserQuestion`: - `standard` — good enough, stay in-session - `premium` — spend stronger reasoning budget - `second-opinion` — draft, then request one independent validation - `all-in` — premium draft, then request one bounded multi-model validation batch - If `--no-prompt` was supplied, choose the lowest tier that is responsible and continue. Never block on model selection if the user has already made the intent clear. ### 3. Gather Context Read-Only Stay read-only while gathering context. Do **not** edit code, create branches, create beads, transition tickets, or commit changes. Architect never creates or updates tracker records, even after a user confirms a proposed plan or owner. Step 4 renders an explicitly owned handoff; only a separate invocation of the receiving workflow can propose and apply tracker changes. Gather only the context needed to plan: 1. **Tracker context** - Jira key: fetch the ticket, acceptance criteria, linked Confluence/design links, and related issues using Jira tools or `/jira-ticket` when available. - Bead id: resolve through `~/.agents/skills/next/scripts/next-select resolve ` before reading. Use only the returned store via `bd -C show `; inspect relevant dependencies/children there. Ambiguous or unavailable ownership means no guessed-store reads. - For new work, use `next-select stores` and choose by outcome, not cwd. In the proven store, use `bd -C list --status=open` and targeted `bd -C search "" --status all` for duplicates and related work. Inspect only high-signal matches; this is a relevance check, not a backlog audit. - When Beads is unavailable, use the established Jira/Trello/other tracker when its context is accessible. Otherwise retain a tracker-neutral view of independently valuable durable work; do not introduce a tracker merely to satisfy the template. 2. **Repository shape** - `pwd` - `git status --short` - `git branch --show-current` - `git ls-files | head -200` or targeted `find`/`rg` for the relevant area - When repository context establishes a validated `workspace.json` project-context index, consume its topology, repository paths, and context links when useful. Treat it as optional and do not require, create, repair, regenerate, or audit it. If missing or suspect context blocks responsible planning, state the limitation and recommend `project-workspace doctor`; do not turn Architect into the workspace diagnostic or repair owner. 3. **Existing patterns** - Search for similar features, APIs, migrations, tests, contracts, or components. - Read representative files. Prefer a few high-signal files over broad scanning. 4. **Conditional prior-art research** - Trigger this pass when the plan selects or replaces a dependency, introduces a third-party integration, proposes a reusable component or abstraction, or addresses a problem likely to have an established solution. Also trigger it when the user explicitly asks for buy-vs-build, ecosystem options, or prior art. - Skip it entirely for routine local changes whose repository pattern and implementation path are already clear. Do not render a skipped-research placeholder, require a web search, or turn this into a planning gate. - When triggered, search in this order and stop as soon as the evidence is sufficient: 1. Repository code, history, dependency manifests, and nearby docs. 2. Capabilities, dependencies, and specialist skills already available in the current runtime. 3. Authoritative external sources only when the local pass leaves a material fit, support, compatibility, licensing, or maintenance question unresolved. - Reuse `/librarian` when it is available for open-source library internals, implementation details, history, and source-backed comparisons. For package availability or public API facts, use the runtime's existing search/fetch tools against official registries, vendor docs, specs, or upstream source. Do not create a parallel research workflow or rely on unsourced summaries. - Keep the lookup bounded to plausible candidates. For each serious candidate, record the source evidence, fit, and material gaps, then recommend exactly one classification: - **Adopt** — use an existing capability as-is. - **Extend** — make a bounded change to the closest-fit capability. - **Compose** — combine existing capabilities without introducing a new foundational solution. - **Build** — add the minimum new implementation because evidenced gaps rule out the others. - A **Build** recommendation must say why the inspected candidates are insufficient. Absence of a search result is not evidence; narrow the claim or name the unresolved question instead. 5. **Docs/designs** - If Jira or the user links to Confluence, fetch the page. - If Figma/design details are required, mention the needed design context and use the available Figma/context tooling if present in the runtime. Keep the context summary concise and cite file paths, official URLs, or upstream source clearly. ### 4. Produce an Architecture Plan Output a plan that is implementation-ready but does not perform implementation. Detailed plans are working input, not current architecture documentation. Do not create Markdown solely to preserve planning reasoning. Render the plan inline. Reuse an existing stable source when supplied; label it as planning input and state its outcome-based disposition. A request to persist new planning input or its review owner produces the explicit handoff below, not a file or tracker write from Architect. The final user-facing plan starts with the decision summary, before investigation detail: ```markdown ## Architect Plan: ### Decision brief - Recommendation: - Decision needed: - Choices: - Detailed input: - Documentation disposition: ### Planning tier - Tier: - Model preference: - Why this tier: ### Goal ### Context gathered - Tracker/docs: ... - Relevant code paths: ... - Existing patterns: ... ### Assumptions - ... ### Prior-art decision | Candidate | Source evidence | Fit / material gaps | |---|---|---| | ... | | ... | - Recommendation: — - New implementation justification: ### Recommended approach ### Alternatives considered 1. — rejected/accepted because ... 2. ... ### Implementation slices | # | Slice / deliverable | Observable outcome | Acceptance evidence | |---|---|---|---| | 1 | | | | | 2 | ... | ... | ... | ### Tracking recommendation ### Test strategy - Happy path: - Sad path: - Edge cases: - Regression/contract/migration checks: ### Risks and mitigations - Risk: ... → Mitigation: ... ### Rollout / rollback ### Open questions - ... ### Recommended implementation tier ``` Pair every implementation slice with both an observable outcome and the evidence that proves it. The pair is the slice's acceptance contract, not a duplicate test plan: - **Runnable check:** give the repository-supported command and the expected decisive signal. - **CI evidence:** name the check/artifact and what success demonstrates; a future green status without the relevant artifact or commit coverage is not enough. - **Manual UAT:** give the smallest necessary flow, environment, and expected observation when behavior cannot responsibly be proven by automation. - **Source evidence:** use a rendered preview, link check, schema/config inspection, or specialist review for documentation-only or inherently non-executable work. Do not manufacture a shell command merely to fill the table. If proof depends on unavailable infrastructure or an unresolved decision, say `TBD`, name the owner or prerequisite, and keep the slice blocked rather than presenting vague acceptance. The broader **Test strategy** section still covers cross-slice happy/sad/edge cases and project gates; it should reference rather than restate the per-slice evidence. Always render **Tracking recommendation**, but keep it proportionate. Choose exactly one form: - **No additional item:** the existing Jira ticket, bead, card, or request already owns the whole coherent outcome. Say so in one line and cite the decisive duplicate/related-work evidence when Beads is active; there is no proposal status to render. - **One focused item:** one independently valuable durable outcome is not already tracked. Keep it to one or two lines: `Proposal — not created`, suggested title, and the essential outcome/scope. Add type, priority, acceptance, or dependency detail only when it materially changes the proposal. - **Epic with children:** use only when several child outcomes are independently reviewable, deliverable, and worth tracking even if another child changes. Label the epic and every child `Proposal — not created`; give title/type/priority, scope, acceptance, and only genuine blocking dependencies. Do not turn every implementation slice into a child. - **Tracker-neutral breakdown:** use when no tracker is established but the work genuinely needs a durable multi-item shape. Keep the same outcome/dependency discipline without prescribing a system. Implementation slices are delivery mechanics, not automatically tracker items. Never propose one item per test, review pass, commit, subagent, retry, handoff, or other ephemeral activity. For an approved structured plan in an active Beads repository: - A one-focused-item or epic recommendation with a stable source should end with a paste-ready `/plan-to-backlog ` handoff. - A no-additional-item recommendation needs no materialization handoff. - Architect must not invoke `/plan-to-backlog` automatically or reproduce its proposal/apply logic. #### Human decision ownership for unapproved plans When an unapproved recommendation needs durable human decision ownership, render: ```text /triage --human-review ``` `` is the existing source selector/reference or this exact inline plan. Include the decision question, proposed owner (not created or updated), and disposition for approval, rejection/defer, or revision. Do not invoke triage automatically or treat approval of the plan as permission to write tracking. No durable owner exists until the receiving workflow verifies its confirmed write. The [triage-owned human-review lifecycle](../triage/references/human-review.md) owns duplicate checks, source reuse versus a dedicated blocked human decision, per-action confirmation, partial recovery, and rationale/disposition recording. Do not reproduce or execute that mutation procedure here. Keep unowned input inline; never create an orphan planning document. Informational answers, approved plans, and plans without a pending human decision need no review item. If another tracker already owns the decision, recommend its normal explicit workflow rather than shadowing it in Beads. Approved implementation materialization remains a separate `/plan-to-backlog ` handoff, not human-review intake. ### 5. External Validation, When Requested If the tier is `second-opinion` or `all-in`, perform exactly one review-and-revision pass: 1. Complete the full architecture draft before requesting review. 2. Build a review packet containing: - A concise context summary: requirements, constraints, relevant tracker/docs, repository evidence with file paths, assumptions, and open questions. Do not include secrets. - The complete finalized draft. - This review rubric: - Requirements coverage and unsupported assumptions - Technical feasibility and simpler or stronger alternatives - Interfaces, ownership boundaries, and internal/external dependencies - Migration, backwards compatibility, and data integrity - Security, privacy, permissions, and abuse cases - Reliability, failure modes, concurrency, and performance - Testability, adequacy of the proposed test strategy, and whether each slice's observable outcome is paired with evidence capable of proving it - When prior-art research was triggered, whether the candidate evidence supports the Adopt/Extend/Compose/Build recommendation and justifies any new implementation - Whether tracking recommendations reflect independently valuable durable work, account for existing related items, and avoid mirroring implementation mechanics - Rollout, rollback, observability, and operational burden - YAGNI, unnecessary abstractions, and decisions still missing 3. Invoke the tier-specific route once: - `second-opinion`: `/second-opinion validate-plan "" --agent peer`. Keep its vendor-independent single-route selection. - `all-in`: `/second-opinion validate-plan "" --agent quorum --panel focused`. This is one bounded parallel batch across the selected focused panel, not a sequence of follow-up reviews. 4. Invoke only through `/second-opinion`; do not probe authentication or call the CLIs directly. Let that skill apply its independence, availability, timeout, and cost rules. When it classifies a selected route as metered/BYOK or unknown-cost, ask for explicit consent with `AskUserQuestion` immediately before the invocation. Declining that route reduces the attempted reviewer set; it does not block the plan. 5. Treat each response as advisory. Check claims against repository, tracker, and documentation evidence. Do not use majority vote as truth: one well-evidenced unique finding may outweigh agreement, while repeated unsupported claims remain invalid. 6. Revise the draft only for validated findings, then stop. Do not send the revision out for a second review batch or loop until reviewers agree. The built-in `focused` panel contains no OpenRouter routes, but a user-local profile may override it. Let `/second-opinion` apply its metered-route consent policy, and do not substitute another named panel unless the user explicitly requests it. Append this validation record to the final plan: ```markdown ### External validation - Review tier: - Coverage: - Reviewer findings: - : - Consensus / agreements: - Disagreements: - Unique findings: - Rejected findings: - Plan changes: - Residual uncertainty: ``` For partial results, synthesize only the reviewers that returned and identify every unavailable, declined, or timed-out route; never describe partial coverage as a complete panel. If no external reviewer succeeds or `/second-opinion` is unavailable, preserve the in-session plan, set coverage accordingly, and explicitly state that external validation was skipped. ### 6. Guardrails - Do not implement code changes. - Do not create or mutate Jira issues or Beads. Tracker writes belong only to the explicit receiving workflow; confirmation never expands Architect's read-only boundary. - Do not create implementation tracker items. Label implementation proposals as not created and route approved-plan materialization through `/plan-to-backlog`. - Prefer small, reversible implementation slices with observable outcomes and proportionate proof. - Do not invent commands for documentation-only or inherently manual acceptance; name the necessary source evidence or UAT flow instead. - Flag YAGNI: avoid introducing new abstractions unless they pay for themselves now. - Do not claim the ecosystem lacks a solution without bounded, source-backed research; do not run that research when a routine local change already has an obvious path. - Prefer repository and installed-capability evidence before external lookup, and prefer official or upstream evidence over commentary when external lookup is warranted. - Call out when the right answer is “do the simple thing” rather than architecting. - If requirements are unclear, list open questions and recommend the smallest discovery step. - End with the next concrete action the implementation agent should take.