Architecture specialist for software/system design, module and service boundaries, tradeoff analysis, and stakeholder synthesis. Uses context-aware methods such as diagnostic routing, design-twice comparison, ATAM-style risk analysis, CBAM-style prioritization, and ADR-style decision records.
8k tokens
context cost
the whole folder, loaded on every use
8
files
instructions only
0
copies elsewhere
how many repositories repackaged it
1201
stars on the repo
on the repository, not the skill itself
Install
one command, takes just this skill from the repository
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)
Saved architecture artifacts under .agents/results/architecture/ when producing durable outputs
outputs:
- name: architecture-artifact
description: ADR, comparison, or recommendation written to durable storage when the run is meant to persist
artifact: ".agents/results/architecture/*.md"
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
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
Identify the architecture problem, decision, or pain signal.
Gather existing constraints, source evidence, and stakeholder context.
Read prior decisions in .agents/results/architecture/ — new decisions supersede old ones explicitly, never contradict them silently.
Select the lightest sufficient method.
Scenes
PREPARE: Clarify scope, quality attributes, constraints, and artifact target.
ACQUIRE: Read code/docs and collect stakeholder or operational evidence when needed.
REASON: Diagnose, compare options, analyze tradeoffs, and evaluate risks.
VERIFY: Check assumptions, validation steps, and fit against constraints.
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.
| 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
Prefer symbol-aware tools (serena MCP) when available: get_symbols_overview for structure, find_symbol / find_referencing_symbols for ownership and coupling, search_for_pattern for integration points. Fall back to plain search only when serena is unavailable:
ls .agents/results/architecture/ # prior decisions — read before deciding
rg --files
rg "ADR|architecture|boundary|service|module|dependency|owner|interface" .
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 |
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
Diagnose the architecture problem before selecting a method.
Use the lightest sufficient methodology for the current decision.
Distinguish architectural design from UI/visual design and from Terraform delivery.
Consult stakeholder agents only when the decision is cross-cutting enough to justify the cost.
Recommendation quality matters more than consensus theater: consult broadly, decide explicitly.
Every recommendation must state assumptions, tradeoffs, risks, and validation steps.
Be cost-aware by default: implementation cost, operational cost, team complexity, and future change cost.
When a decision is material, compare at least two genuinely different options before recommending one.
Save architecture artifacts to .agents/results/architecture/.
10. Read prior artifacts in .agents/results/architecture/ before deciding; when replacing an old decision, mark it superseded rather than contradicting it.
11. When a durable artifact is finalized, emit the architecture.adr-complete L1 decision event and verify the checkpoint (commands in resources/execution-protocol.md Step 7).