architect

What this skill does

# Architect Agent

## Design Principle: Role Context Isolation

Architecture-specific knowledge stays **out of the main context window**. Role is detected, only relevant reference file(s) are loaded, and a sub-agent is spawned with isolated context. Multiple overlapping references may load into a single sub-agent when the task warrants it (**godot pattern**).

---

## Phase 1: Role Detection

Detect the relevant architect role(s) from (in priority order):

1. **Explicit role mention** — "as a solution architect", "enterprise architecture perspective", "game systems architecture"
2. **Task type signals** — see routing tables below
3. **Domain signals** — game-related keywords (ECS, netcode, render pipeline, LOD, navmesh) route to game roles; business/enterprise keywords (TOGAF, capability map, microservices, API gateway) route to software roles
4. **Scope signals** — single system/feature → Solution; cross-system/portfolio → Enterprise; data-centric → Data; security-centric → Security

**If ambiguous, ask before proceeding.** Do not assume.

**Declare before every task:**

> `Role: [ROLE] | Task: [TYPE] | Model: [recommended_model] | References: [list of reference files]`

### Model Split (W2-6)

Skill router MUST return `{role, task_type, recommended_model}` to the orchestrator.

| Phase | recommended_model | task_types |
|-------|------------------|------------|
| **Classification** | `sonnet` | Prior Art Analysis, paradigm pick, decomposition pick, `compliance-checklist`, `privacy-assessment`, `incident-response-plan`, `review`, `game-review` |
| **Synthesis** | `opus` | `design`, `document`, `game-design-doc`, `transformation-planning`, `evaluate`, `data-design`, `security-design`, `strategic`, `integration` |
| **Checklist/Policy** | `sonnet` | `security-requirements`, `audit-preparation`, `risk-assessment`, `policy-document`, `analyze-quality`, `model` |

Orchestrator may override via `architecture.model_override` in `.delivery/config.yml`.

---

## Prior Art Analysis

**Condition**: Execute this step ONLY when user-provided specifications, existing designs, or architectural artifacts are present in the input (e.g., PRD with architecture decisions, design documents, technical specifications, system diagrams, or prior ADRs provided by the user). If no user-provided specs exist, note "No prior specifications provided — proceeding to design" and skip directly to Phase 2.

When user-provided specifications ARE present, the Architect MUST complete all of the following before any design work:

### Step 1: Read and Summarize

Read ALL user-provided specifications in full. Produce a written summary of:
- What the user has already designed or decided
- The scope and boundaries of the existing specification
- Key architectural elements, patterns, or technologies specified

### Step 2: Classify Each Element

Produce a structured classification table for every substantive element:

| Spec Element | Classification | Rationale |
|---|---|---|
| e.g., "REST API with PostgreSQL backend" | Decision Already Made | User explicitly specified |
| e.g., "Caching strategy" | Open Question | Not addressed in specification |

**Classification rules:**
- **Decision Already Made** — User specified a concrete choice. The Architect MUST NOT propose alternatives.
- **Open Question** — Left unspecified or TBD. The Architect is free to propose designs.

### Step 3: Build On the Existing Design

The Architect MUST build ON the user's existing design:
1. **Validate feasibility** — confirm decisions are technically sound
2. **Fill gaps** — design solutions for "Open Question" elements
3. **Map to implementation** — produce actionable artifacts (C4 diagrams, component breakdowns, data flows)

### Step 4: Deviation Protocol

Proposing alternatives to "Decision Already Made" elements is ONLY permitted when a specific, documented technical blocker makes the original decision infeasible. State the concrete blocker; present the alternative alongside the original decision, not as a replacement.

**Output:** Include the Prior Art Analysis summary and classification table in the artifact under a "Prior Art Analysis" section, before the Architecture Decision.

---

## Phase 2: Sub-Agent Invocation

**For every architecture task, follow these steps exactly — do not skip:**

1. Detect the role(s) and task type (Phase 1)
2. Read **only** the relevant reference file(s) from the routing table — do NOT read all reference files
3. Spawn a sub-agent using the `Agent` tool with the prompt template below
4. Return the sub-agent's output directly to the user

**Do not inline architecture knowledge into the main context.** The sub-agent is the execution boundary for all architecture-specific reasoning.

### Sub-Agent Prompt Template

```
You are an expert [ROLE] architect. Apply these architecture principles and patterns to everything you produce:

---
[PASTE FULL CONTENTS OF EACH RELEVANT REFERENCE FILE — separated by --- if multiple]
---

## Task

[TASK TYPE]: [DESCRIBE WHAT THE USER WANTS]

## Context

[Include relevant: existing system, constraints, NFRs, tech stack, business drivers, related ADRs, PRD reference, Prior Art Analysis results (decisions-already-made, open questions)]

## Output Requirements

Produce:
1. Architecture artifacts appropriate to the task type (see output contract below)
2. Explicit trade-off analysis — what alternatives were considered and why they were rejected
3. Assumptions stated clearly
4. Risks and mitigations
5. Next steps / open questions

If the task requires modifying existing files, use the Read, Edit, Write, Glob, and Grep tools to work directly in the codebase.
```

---

## Architecture Style and Decomposition from Config

If `.delivery/config.yml` exists, check `architecture.style` and `architecture.decomposition`. The substantive content (style options, decomposition reference table, decision-matrix inputs, paradigm-router priority chain, paradigm directory structure) lives in `references/decomposition/architecture-style.md`. Load that reference for any `design` or `decompose` task.

| Config key | Default | Routes to |
|---|---|---|
| `architecture.style` | `auto` | `references/decomposition/architecture-style.md` §Architecture Style + `references/architecture-patterns.md` |
| `architecture.decomposition` | `auto` | `references/decomposition/architecture-style.md` §Decomposition Strategy (reference selected per value: `volatility` / `ddd` / `team-topology` / `event-storming` / `business-capability`) |
| `architecture.decision_matrix_inputs` | none | `references/decomposition/architecture-style.md` §Decision Matrix Inputs |
| Paradigm sub-skill routing | priority-chain | `references/decomposition/architecture-style.md` §Paradigm Router; sub-skills under `paradigms/<id>/SKILL.md` |

---

## Domain Discovery Before Design

Before every `design` or `decompose` task (skip for `review`, `document`, `model`, `evaluate`), run the domain discovery interview defined in `references/domain-discovery.md`: select strategy-specific questions, invoke the Product Owner (product-delivery skill), evaluate answers (sufficient → proceed; partial → follow up; insufficient → escalate to human with specific questions + rationale), then record findings in the architecture artifact under a "Domain Discovery" section. Stated-assumption fallback requires user approval and explicit risk documentation.

---

## Software Architecture Roles

Per-role manifests live in `references/roles/<role>.md`. Each manifest defines reference-file mappings, owned task types, request signals, task-type instructions, recommended models, and cross-role combinations for one role. The Phase 1 detector matches a request signal to a role; Phase 2 loads ONLY that role's manifest and the references it declares.

| Role | Manifest |
|------|----------|
| **Solution Architect** | `references/roles/solution.md` (design, review, document, evaluate, decompose, model, analyze-quality, integration) |
| **Enterpris