Skip to main content
skill CX Codex

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

oma-architecture is a Claude Code skill that helps design module and service boundaries, compare alternatives, and document architecture decisions as ADRs.

MIT ★ 1,472 updated 2026-10-29

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

What oma-architecture does

The skill acts as an architecture specialist inside your coding agent. It evaluates design pain points such as hidden dependencies, change amplification, and ambiguous service ownership. The workflow adapts to request clarity: it diagnoses vague symptoms, applies ATAM-style risk evaluation, or compares at least two materially distinct designs before issuing a recommendation.

Execution flows through five discrete stages: scope preparation, codebase context acquisition, tradeoff reasoning, constraint verification, and artifact generation. Output documents land directly in .agents/results/architecture/.

The skill avoids altering application code directly. It generates evidence-backed decision records and architectural guidance, leaving the actual implementation to separate tasks.

What it helps with

  • Define boundaries between services and codebase modules
  • Compare competing architecture options with explicit tradeoffs
  • Document system design decisions as formal ADR records
  • Prioritize technical debt and structural refactoring work

Example prompts for the agent

  • Evaluate module boundaries across our codebase and identify coupling issues
  • Compare two database partitioning approaches and produce an ADR
  • Run an ATAM-style risk analysis on the notification pipeline

How to install oma-architecture

1Plugin marketplace

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

This installs the whole oma 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?

Add the marketplace source with /plugin marketplace add first-fluke/oh-my-agent, then run /plugin install oma@oh-my-agent.

What does oma-architecture do?

It examines architecture pain points, compares structural alternatives, assesses operational risks, and outputs structured decision records.

Does oma-architecture modify application source code?

No, it focuses purely on analysis and writes its reports into .agents/results/architecture/.

Source text

SKILL.md · MIT
---
name: oma-architecture
description: 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.
---

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

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

### 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
- Saved architecture artifacts under `.agents/results/architecture/` when producing durable outputs

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

### 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. 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
```bash
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 |
| `LOCAL_FS` | `.agents/results/architecture/` artifacts |
| `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 architecture artifacts to `.agents/results/architecture/`.

### 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
Follow `resources/execution-protocol.md` step by step.
See `resources/examples.md` for output examples.
Use `resources/methodology-selection.md` to select the right method.
Use `resources/stakeholder-synthesis.md` when stakeholder consultation is needed.
Use `resources/output-templates.md` to format the final artifact.
Before submitting, run `resources/checklist.md`.
- Execution steps: `resources/execution-protocol.md`
- Checklist: `resources/checklist.md`
- Examples: `resources/examples.md`
- Method selection: `resources/methodology-selection.md`
- Stakeholder protocol: `resources/stakeholder-synthesis.md`
- Output templates: `resources/output-templates.md`
- Context loading: `../_shared/core/context-loading.md`
- Difficulty guide: `../_shared/core/difficulty-guide.md`
- Reasoning templates: `../_shared/core/reasoning-templates.md`
- 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 — 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. 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 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 architecture-decision jwynia architecture-decision evaluates architectural trade-offs, guides pattern selection, and structures decisions as ADRs. Useful when choosing tech stacks or tackling debt. CX Codex +1 505installs architecture-compass stark-ai-de architecture-compass is a Claude Code and Codex skill that manages architecture decisions and checks code against them. It audits repositories, governs ADRs, and guides scoped refactors. CX Codex +1 2,700installs 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

From the same set69

The whole set →
oma-design oma-design resolves a project's design direction and maintains DESIGN.md as the visual contract. Picks an external design skill — Interface Design, Taste, or Impeccable — for the task at hand. CX Codex +1 ★ 1,472repo stars oma-hwp oma-hwp converts Korean HWP, HWPX, and HWPML documents into Markdown or JSON for LLM prompts and retrieval pipelines. CX Codex +1 ★ 1,472repo stars oma-search The oma-search skill picks a search channel for docs, web research, code, or local project files, then labels external sources by domain trust. Use it when the right place to search is unclear. CX Codex +1 ★ 1,472repo stars oma-image oma-image routes image generation requests across Codex, Pollinations and Gemini, and turns a reference picture into a new variation matching its style or layout. CX Codex +1 ★ 1,472repo stars oma-coordination The oma-coordination skill guides manual coordination across specialist agents on multi-domain projects. It covers task planning, progress checks, contract alignment, and a final QA review. CX Codex +1 ★ 1,472repo stars oma-hwp oma-hwp turns Korean HWP, HWPX and HWPML documents into Markdown via kordoc. Extracts text, tables, lists, images and footnotes. CX Codex +1 ★ 1,472repo stars oma-pdf oma-pdf converts PDF documents into structured Markdown while preserving tables, headings, and lists. Runs when preparing files for LLM context or RAG pipelines. CX Codex +1 ★ 1,472repo stars oma-market oma-market runs community-signal research on customer pain, trends, and competitors, then saves a market brief for the requested topic. CX Codex +1 ★ 1,472repo stars

Project sponsors

Companies that keep this analytics open