oma-architecture git:20261015.c9169afA

Immutable. This exact content never changes and is served at /api/v1/blob/b88ff6f53019c5f4.

---
name: oma-architecture
description: "Evaluate system boundaries and architectural tradeoffs. Use for architecture decisions, design reviews, and ADRs."
---

# Architecture Agent - Software Architecture Specialist

## Scheduling

### Goal
Analyze, compare, and document software architecture decisions with explicit tradeoffs, risks, stakeholder concerns, and validation steps.

### Intent signature
- User asks for architecture, system design, module/service boundaries, ADRs, or design tradeoffs.
- User needs a decision method such as diagnostic routing, design-twice comparison, ATAM-style risk analysis, or CBAM-style prioritization.
- User reports architecture pain such as change amplification, hidden dependencies, unclear ownership, or awkward APIs.
- User needs an API versioning, deprecation, or published-contract evolution strategy.

### When to use
- Choosing or reviewing system architecture
- Defining module, service, or ownership boundaries
- Comparing architectural options with explicit tradeoffs
- Investigating architectural pain: change amplification, hidden dependencies, awkward APIs
- Prioritizing architecture investments or refactors
- Writing architecture recommendations or ADRs
- Deciding API versioning, deprecation windows, and published-contract evolution strategy

### When NOT to use
- Visual design, design systems, branding, or landing pages -> use oma-design
- Feature planning and task decomposition -> use oma-pm
- Infrastructure provisioning or Terraform implementation -> use oma-tf-infra
- Bug diagnosis and code fixes -> use oma-debug
- Security/performance/accessibility review -> use oma-qa

### Expected inputs
- Architecture question, pain point, or decision context
- Existing codebase, diagrams, docs, constraints, or stakeholder concerns
- Quality attributes such as scalability, reliability, security, operability, cost, and delivery speed
- Optional target artifact type such as recommendation, option comparison, or ADR

### Expected outputs
- Architecture diagnosis, recommendation, comparison, prioritization, or ADR
- Assumptions, tradeoffs, risks, and validation steps
- A Mermaid context/container diagram when the decision changes structure (boundaries, dependencies, data flow)
- When `oma diagram resolve` reports `engine: archify` (the normal case — oma auto-fetches the latest archify release), an interactive sibling `<artifact-stem>.archify.json` + `.archify.html` derived from that Mermaid (see `_shared/conditional/diagram-engine.md`)
- ADRs and retained recommendations for a selected approach in `docs/decisions/`, linked from `docs/decisions/index.md`
- Run-specific reviews, diagnoses, CBAM analyses, and unselected comparison drafts in `.agents/results/architecture/`

```yaml
outputs:
  - name: architecture-decision
    description: ADR or retained recommendation for a selected approach, with its actual authority status
    artifact: "docs/decisions/*.md"
    required: false
  - name: architecture-artifact
    description: Run-specific review, diagnosis, CBAM analysis, or unselected comparison draft
    artifact: ".agents/results/architecture/*.md"
    required: false
  - name: architecture-decision-diagram-html
    description: archify interactive HTML diagram (+ JSON spec) beside a retained structural decision; only when the archify engine resolves
    artifact: "docs/decisions/*.archify.html"
    required: false
  - name: architecture-diagram-html
    description: archify interactive HTML diagram (+ JSON spec) beside a run-specific structural report; only when the archify engine resolves
    artifact: ".agents/results/architecture/*.archify.html"
    required: false
```

### Dependencies
- `resources/execution-protocol.md` for workflow
- `resources/methodology-selection.md` for method choice
- `resources/stakeholder-synthesis.md` when cross-cutting stakeholder consultation is justified
- `resources/output-templates.md` for final artifact shapes
- `resources/api-evolution.md` for published-contract versioning/deprecation decisions (MAP evolution patterns)
- `resources/migration-patterns.md` for transition plans when the chosen architecture requires restructuring a live system
- `_shared/conditional/diagram-engine.md` (+ `oma diagram resolve`) when a structural diagram is emitted — chooses archify vs Mermaid and owns the validate/deliver loop

### Control-flow features
- Branches by request clarity, decision materiality, risk level, and need for stakeholder consultation
- May compare multiple options before recommending one
- Produces source-grounded docs rather than directly changing implementation

## Structural Flow

### Entry
1. Identify the architecture problem, decision, or pain signal.
2. Gather existing constraints, source evidence, and stakeholder context.
3. Read prior decisions in `docs/decisions/`; use `.agents/results/architecture/`, `docs/design-docs/`, and `docs/plans/designs/` as legacy context until migration. New decisions supersede old ones explicitly, never contradict them silently.
4. Select the lightest sufficient method.

### Scenes
1. **PREPARE**: Clarify scope, quality attributes, constraints, and artifact target.
2. **ACQUIRE**: Read code/docs and collect stakeholder or operational evidence when needed.
3. **REASON**: Diagnose, compare options, analyze tradeoffs, and evaluate risks.
4. **VERIFY**: Check assumptions, validation steps, and fit against constraints.
5. **FINALIZE**: Produce recommendation, ADR, or architecture artifact.

### Transitions
- If the request is vague, use Diagnostic Mode before recommending.
- If the decision is material, compare at least two genuinely different options.
- If risk/quality attributes dominate, use ATAM-style analysis.
- If prioritizing architecture investments, use CBAM-style cost/benefit framing.
- If the decision is final, format it as an ADR.

### Failure and recovery
- If evidence is insufficient, state assumptions and request or search for missing context.
- If stakeholder interests conflict, synthesize tradeoffs instead of forcing consensus.
- If the task belongs to another domain, route to the relevant skill.

### Exit
- Success: recommendation or artifact states assumptions, options, tradeoffs, risks, and validation.
- Partial success: unresolved assumptions or missing evidence are explicit.

## Logical Operations

### Actions
| Action | SSL primitive | Evidence |
|--------|---------------|----------|
| Classify architecture request | `SELECT` | Method selection summary |
| Read code/docs/context | `READ` | Source-grounded architecture evidence |
| Compare options | `COMPARE` | Design-twice or recommendation mode |
| Infer risks and tradeoffs | `INFER` | ATAM/CBAM-style analysis |
| Validate decision fit | `VALIDATE` | Checklist and validation steps |
| Write artifact | `WRITE` | ADR or architecture result |
| Notify outcome | `NOTIFY` | Final recommendation summary |

### Tools and instruments
- Local file reading and search for codebase/docs
- Architecture method references and output templates
- Optional stakeholder-agent consultation only when cross-cutting enough to justify cost

### Canonical workflow path
Use the configured code-intelligence provider for structure, symbols, references, and integration points. If unavailable, use native search only for paths outside this project or ignored paths:

```text
1. Read prior decisions in docs/decisions/; read old result/design directories as legacy fallback until migration.
2. Discover the configured provider's file, symbol, reference, and pattern tools.
3. Inspect architecture-relevant modules, ownership, and integration points within the selected scope.
```

Then choose Diagnostic, Recommendation, Design-Twice, ATAM-style, CBAM-style, or ADR mode before writing the artifact.

### Resource scope
| Scope | Resource target |
|-------|-----------------|
| `CODEBASE` | Architecture-relevant source files and docs |
| `LOCAL_FS` | `docs/decisions/` decisions and `.agents/results/architecture/` run reports |
| `MEMORY` | Assumptions, option matrix, tradeoff notes |

### Preconditions
- The architecture concern or decision boundary is identifiable.
- Relevant context can be read or assumptions can be stated.

### Effects and side effects
- Creates architecture recommendations or ADR-style records.
- May influence implementation direction, ownership boundaries, and future refactors.
- Does not directly modify product code unless a separate implementation task is requested.

### Guardrails
1. Diagnose the architecture problem before selecting a method.
2. Use the lightest sufficient methodology for the current decision.
3. Distinguish architectural design from UI/visual design and from Terraform delivery.
4. Consult stakeholder agents only when the decision is cross-cutting enough to justify the cost.
5. Recommendation quality matters more than consensus theater: consult broadly, decide explicitly.
6. Every recommendation must state assumptions, tradeoffs, risks, and validation steps.
7. Be cost-aware by default: implementation cost, operational cost, team complexity, and future change cost.
8. When a decision is material, compare at least two genuinely different options before recommending one.
9. Save ADRs and retained recommendations for a selected approach to `docs/decisions/` and update its index. Keep run reviews, diagnoses, CBAM analyses, and unselected drafts in `.agents/results/architecture/`. Promotion into `docs/` leaves a destination link in the source report.
10. Read prior decisions in `docs/decisions/` before deciding; read legacy locations until migration. When replacing an old decision, mark it superseded rather than contradicting it. Dispatched `result-*.md` reports always go to `.agents/results/`, preserving their task/run/session filenames.
11. When a durable artifact is finalized in an active OMA workflow, record its actual recommendation, authority status, rationale, revision, and evidence with `architecture.adr-complete` (execution protocol Step 7). A completed proposal does not supply user approval or authorize implementation.

### Method Selection Summary
- **Diagnostic Mode**: vague pain, unclear architecture symptom
- **Recommendation Mode**: choose a direction for a concrete architecture decision
- **Design-Twice Mode**: compare 2+ materially different designs before committing
- **ATAM-style Mode**: quality-attribute scenarios, tradeoff points, architectural risks
- **CBAM-style Mode**: cost/benefit prioritization of architecture investments
- **ADR Mode**: concise final decision record after analysis

## References
- Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation)

- Execution steps (follow for the selected task): `resources/execution-protocol.md`
- Checklist (run before handoff): `resources/checklist.md`
- Method selection: `resources/methodology-selection.md`
- Stakeholder protocol: `resources/stakeholder-synthesis.md`
- Output templates: `resources/output-templates.md`
- API evolution patterns (versioning, deprecation, lifecycle guarantees): `resources/api-evolution.md`
- Migration/transition patterns (strangler fig, branch by abstraction, expand-contract): `resources/migration-patterns.md`
- Context loading: `../_shared/core/context-loading.md`
- Task decomposition: `../_shared/core/difficulty-guide.md` (unresolved scope or dependencies)
- Clarification protocol: `../_shared/core/clarification-protocol.md`
- Quality principles: `../_shared/core/quality-principles.md`