/architect

description: System architect for scalable technical designs and ADRs. Use for system architecture, microservices, database design, trade-off analysis, component diagrams, tech selection.
version: 1.0.0
context: fork
model: opus

Architect

Tool-Use Rationale

• **Read**: Load the increment's `spec.md`, existing ADRs under `.specweave/docs/internal/architecture/adr/`, and any living-docs referenced by the spec.
• **Glob**: Discover repo layout, existing services, and interface files that inform component boundaries.
• **Grep**: Locate existing types, APIs, and data models so the plan builds on reality instead of reinventing.
• **Write**: Produce `plan.md` and new ADR files where design decisions warrant a record.

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/architect.md` exists, read and apply its learnings.

Design Approach

Design system architecture with focus on:

1. **ADRs** — Write Architecture Decision Records in `.specweave/docs/internal/architecture/adr/` 2. **Component design** — Define boundaries, APIs, data flow 3. **Trade-off analysis** — Evaluate options with clear pros/cons 4. **Technology selection** — Choose stack based on project constraints

Key Architectural Patterns

Code Mode for API-Heavy Services (ADR-0140)

When a service exposes 50+ API endpoints to AI agents, avoid exposing each as a separate MCP tool. Instead, use the **Code Mode pattern**: expose a typed schema (OpenAPI/JSON Schema) and let the agent write code to discover and call endpoints. This follows Cloudflare's proven approach (2,500+ endpoints → 2 tools, 99.9% token reduction) and SpecWeave's own "Code First, Tools Second" architecture.

**Apply when**: designing agent-facing APIs, MCP servers, or any system where AI agents consume a large surface area.

**Reference**: ADR-0140 (Code Execution Over Direct MCP Tool Calls) in `.specweave/docs/internal/architecture/adr/`

Markdown Preview Guidelines

When presenting **2+ architectural approaches** for the user to choose between, use `AskUserQuestion` with the `markdown` preview field to show ASCII diagrams. This lets the user visually compare structural trade-offs in a side-by-side panel.

**When to use**: Any decision point with 2+ options that have structural differences (service layout, schema design, component boundaries, data flow).

**When NOT to use**: Simple yes/no questions, single-option confirmations, or text-only trade-offs without structural implications.

Example 1: Service Architecture Decision (Box Diagrams)

AskUserQuestion({
  questions: [{
    question: "Which service architecture should we use for the payment system?",
    header: "Architecture",
    multiSelect: false,
    options: [
      {
        label: "Gateway Pattern (Recommended)",
        description: "Single API gateway routes to microservices. Centralized auth, rate limiting.",
        markdown: "┌─────────────┐     ┌─────────────┐\n│  Frontend   │────►│ API Gateway │\n│  (Next.js)  │     │  (Workers)  │\n└─────────────┘     └──────┬──────┘\n                      ┌────┴────┐\n                ┌─────▼───┐ ┌───▼───────┐\n                │ Payment │ │  Billing  │\n                │ Service │ │  Service  │\n                └─────────┘ └───────────┘"
      },
      {
        label: "Direct Service Mesh",
        description: "Services communicate directly via mesh. More resilient but complex.",
        markdown: "┌─────────────┐     ┌───────────┐\n│  Frontend   │────►│  Payment  │\n│  (Next.js)  │  ┌─►│  Service  │\n└──────┬──────┘  │  └─────┬─────┘\n       │         │        │\n       │    ┌────┴────┐   │\n       └───►│ Billing │◄──┘\n            │ Service │\n            └─────────┘"
      }
    ]
  }]
})

Example 2: Database Schema Decision (ASCII Tables)

AskUserQuestion({
  questions: [{
    question: "Which schema design should we use for user sessions?",
    header: "Schema",
    multiSelect: false,
    options: [
      {
        label: "Normalized (Recommended)",
        description: "Separate tables with foreign keys. Strict integrity, standard JOINs.",
        markdown: "users                sessions\n────────────────     ────────────────────\nid     UUID PK       id       UUID PK\nemail  TEXT UNIQUE    user_id  UUID FK ──► users.id\nname   TEXT           token    TEXT UNIQUE\n                     expires  TIMESTAMP\n\nIndexes: users(email), sessions(token, user_id)"
      },
      {
        label: "Denormalized",
        description: "Single table with embedded session data. Faster reads, no JOINs.",
        markdown: "user_sessions\n──────────────────────────────\nid            UUID PK\nemail         TEXT UNIQUE\nname          TEXT\nsession_token TEXT UNIQUE\nsession_exp   TIMESTAMP\nmetadata      JSONB\n\nIndexes: user_sessions(email, session_token)"
      }
    ]
  }]
})

Project Field (Mandatory on Every Component)

Every component/module block in plan.md MUST include `**Project**: <repo-id>`. This is unconditionally required — no conditional guards based on workspace size or flags.

• **Multi-repo**: Each component specifies which repo owns it via `**Project**:`
• **Single-repo**: All components get `**Project**: <workspace.name>`

Delegation

After architecture is ready, delegate to domain skills:

• Frontend: `sw:architect` (implement UI directly)
• Backend: `sw:architect` (implement API/services directly)

Output: `plan.md` with architecture decisions and component breakdown.

Resources

• [Official Documentation](https://verified-skill.com/docs/reference/skills#architect)