Skip to main content
skill CX Codex

oma-architecture · first-fluke, frontend — Claude Code skill: what it does, how to install

oma-architecture — a skill for Claude Code and Codex to evaluate system boundaries and architectural tradeoffs. Runs during system design reviews, module boundary audits, and ADR authoring.

MIT ★ 1,472 updated 2026-11-12

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma-frontend@oh-my-agent
Open on GitHub

What oma-architecture does

The skill diagnoses architectural friction points such as hidden dependencies, change amplification, or ambiguous service boundaries. When evaluating competing technical directions, it compares at least two distinct options using ATAM-style risk assessments or CBAM-style trade-off analysis.

All output takes the form of documentation rather than direct code modifications. Accepted recommendations are stored in docs/decisions/ as ADRs linked from docs/decisions/index.md, while drafts and raw reviews go into .agents/results/architecture/. If a decision alters system layout, it emits a Mermaid diagram alongside optional interactive .archify.html files whenever the archify engine resolves.

This workflow focuses strictly on design structure: bug fixing, feature task decomposition, and Terraform provisioning are routed away to separate specialist skills.

What it helps with

  • evaluate system boundaries and cross-module dependencies
  • document architectural decisions as formal ADR records
  • compare structural implementation options with explicit tradeoffs
  • plan API deprecation timelines and contract versioning patterns

Example prompts for the agent

  • Audit service boundaries between billing and inventory, then document the tradeoffs
  • Compare two message broker patterns for our pipeline and write an ADR in docs/decisions/
  • Draft an API deprecation strategy for breaking contract updates

How to install oma-architecture

1Plugin marketplace

/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma-frontend@oh-my-agent

This installs the whole oma-frontend plugin with all its skills

2Skills CLI (Vercel)

npx skills add first-fluke/oh-my-agent --skill oma-architecture -a claude-code

3Manually: put the files in place

~/.claude/skills/oma-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/oma-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about oma-architecture

How to install oma-architecture in Claude Code?

Run npx skills add first-fluke/oh-my-agent --skill oma-architecture -a claude-code in your project terminal.

What does oma-architecture do?

It examines system design proposals, weighs architectural risks, produces structural diagrams, and drafts ADR records.

Does oma-architecture modify application source code?

No, it writes architectural artifacts and documentation into docs/decisions/ and .agents/results/architecture/ without editing codebase implementations directly.

Source text

SKILL.md · MIT
---
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/`

```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
  - 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. **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. Record the mode with subject `architecture.route-selection` per `../_shared/runtime/route-selection.md` (the lightest sufficient method and why heavier ones were not needed).

### 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`

© First Fluke · MIT · first-fluke/oh-my-agent

Similar skills

All skills for Backend and APIs →

oma-architecture by other authors comes first.

oma-architecture First Fluke oma-architecture is a Claude Code skill that helps design module and service boundaries, compare alternatives, and document architecture decisions as ADRs. CX Codex +1 ★ 1,472repo stars architecture-designer https://github.com/Jeffallan architecture-designer designs distributed system architectures, creates Mermaid diagrams, and writes Architecture Decision Records. It helps balance trade-offs before writing service code. CX Codex +1 8,500installs architecture official anthropics Writes an Architecture Decision Record or reviews a system design: options, trade-offs, consequences. Useful when you have to pick between technologies. CX Codex +1 7,200installs technical-spec majiayu000 technical-spec enforces strict structures for technical design docs, RFCs, and ADRs with mandatory alternatives, diagrams, and risk matrices. CX Codex +1 245installs senior-architect borghei senior-architect — a skill for designing systems and documenting architecture decisions as ADRs. Analyzes code coupling, generates diagrams, and guides choices between patterns, databases, and monolith versus microservices. CX Codex +1 244installs architecture-optimization wondelai The architecture-optimization Claude Code skill guides architecture, code-quality, and performance work on a live codebase. It records decisions and measurements across eight phases. CX Codex +1 1,700installs architect CloudAI-X Switches Claude Code into a software architect mode to plan architectures, evaluate trade-offs, and draft ADRs before coding. CX Codex +1 ★ 1,424repo stars

From the same set69

The whole set →
oma-backend oma-backend is a Claude Code skill for implementing server APIs, authentication, and application data access. It activates for endpoint, server-logic, and background-job tasks. CX Codex +1 ★ 1,472repo stars oma-recap oma-recap pulls conversation histories from AI tools across a chosen timeframe and organizes them into a themed project report. Useful for standups and understanding how work distributed across different AI assistants. CX Codex +1 ★ 1,472repo stars oma-tf-infra The oma-tf-infra skill creates and reviews Terraform code, plans, and cloud infrastructure. It covers IAM, networking, state, cost, and destructive-change risk. CX Codex +1 ★ 1,472repo stars oma-mobile oma-mobile is a skill that builds and edits mobile screens and features in Flutter, React Native, Swift, or Kotlin. It inspects existing widgets, providers, and API clients before code changes. CX Codex +1 ★ 1,472repo stars oma-design The oma-design skill shapes and audits a project’s design system, from DESIGN.md to accessibility and responsive guidance. Use it before frontend work or to review an interface. CX Codex +1 ★ 1,472repo stars oma-brainstorm oma-brainstorm — a skill for Claude Code and Codex designed for early feature exploration before task planning. Clarifies ambiguous requests one question at a time and compares technical options. CX Codex +1 ★ 1,472repo stars oma-orchestrator oma-orchestrator — a skill that automates spawning multiple specialist agents at once, coordinates them via MCP Memory, and tracks progress. CX Codex +1 ★ 1,472repo stars oma-explanation oma-explanation turns a PR, branch or commit range diff into a self-contained HTML walkthrough with background, code narration and a five-question quiz. CX Codex +1 ★ 1,472repo stars

Project sponsors

Companies that keep this analytics open