anton-abyzov/plugins/specweave/skills/architect

Architect

STEP 0: Register Skill Chain Marker (MANDATORY - DO THIS FIRST)

Before any other work, register your invocation so the skill-chain-enforcement-guard allows plan.md writes.

Extract the increment ID from your args (e.g., "Design architecture for increment 0323-feature-name ..."). Then write the marker file:

mkdir -p .specweave/state
STATE_FILE=".specweave/state/skill-chain-XXXX-name.json"
if [ -f "$STATE_FILE" ]; then
  jq '.architect_invoked=true | .architect_invoked_at="'$(date -Iseconds)'"' "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
else
  echo '{"architect_invoked":true,"architect_invoked_at":"'$(date -Iseconds)'"}' > "$STATE_FILE"
fi

Replace XXXX-name with the actual increment ID. This unblocks the guard for plan.md writes.

If you skip this step, your Write to plan.md will be BLOCKED by the PreToolUse guard.

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