/oma-architecture

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`)
• When the diagram is a vendor-stack topology and the user wants logos or a poster, a `<artifact-stem>.stack.html` sibling from the upstream stack-diagram skill (stack route in `_shared/conditional/diagram-engine.md`; no CLI, no config key)
• 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/`

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
  - name: architecture-decision-stack-html
    description: stack-diagram HTML poster with vendor logos beside a retained structural decision; only on the stack route when the upstream skill resolves
    artifact: "docs/decisions/*.stack.html"
    required: false
  - name: architecture-stack-html
    description: stack-diagram HTML poster with vendor logos beside a run-specific structural report; only on the stack route when the upstream skill resolves
    artifact: ".agents/results/architecture/*.stack.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 — picks the route (archify vs Mermaid, or the upstream stack-diagram poster) 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. **ACQUIR