Skip to content

gracefullight/pkgs / .agents/skills/oma-architecture

oma-architecture

Verified

Evaluate system boundaries and architectural tradeoffs. Use for architecture decisions, design reviews, and ADRs.

resources/execution-protocol.md

View on GitHub
# Architecture Agent - Execution Protocol

## Preparation
Use the task's scope, existing project conventions, and acceptance criteria. Follow `../../_shared/core/execution-policy.md` when it has not already been supplied. Read only references needed by the selected operation; consult lessons or recovery guides for an observed issue. Expand planning depth only when the change requires it.

## Step 1: Frame the Problem
- Separate symptoms from decisions
- Name the architecture concern explicitly:
  - boundary / ownership
  - API shape / caller burden
  - reliability / consistency / scaling
  - migration / investment prioritization
- Record constraints, quality attributes, and non-goals

## Step 2: Gather Context
- Read prior artifacts in `.agents/results/architecture/` first:
  - note decisions that constrain this one
  - if this decision replaces one, plan to mark the old ADR superseded — never silently contradict it
- Analyze only the code and docs relevant to the decision
  - follow `../../_shared/core/code-intelligence.md` for configured symbol, reference, and pattern tools or native fallback
- Map existing architecture:
  - key modules or services
  - ownership boundaries
  - integration points
  - current pain points
- If context is vague, start in Diagnostic Mode before deeper analysis

## Step 3: Decide Consultation Depth
- **Simple**: no stakeholder consultation, analyze inline
- **Medium**: consult 1-3 stakeholder agents via `stakeholder-synthesis.md`
- **Complex**: perform a structured stakeholder sweep, then synthesize

## Step 4: Run the Selected Method

### Diagnostic Mode
- Convert vague pain into a concrete architecture problem
- Route into Recommendation, Design-Twice, ATAM-style, or CBAM-style mode

### Recommendation Mode
- Define 2-3 options when the decision is material
- Compare on:
  - boundary clarity
  - quality attributes
  - implementation cost
  - operational cost
  - future change cost

### Design-Twice Mode
- Force at least two materially different options
- Avoid superficial variations on the same decomposition
- Compare and synthesize if needed

### ATAM-style Mode
- Identify quality attribute scenarios
- Write each scenario as stimulus → environment → response measure
  (e.g., "traffic spikes to 5x baseline [stimulus] during a regional failover [environment] → p99 stays under 800ms [response measure]")
- Surface sensitivity points, tradeoff points, risks, and non-risks
- Prioritize architectural concerns by impact

### CBAM-style Mode
- Compare candidate investments
- Estimate benefit, cost, and sequencing value
- Score benefit and cost on a shared 1-5 scale (1 = minimal, 5 = very high) so rankings are comparable across runs
- Tag each estimate with its confidence (low / medium / high) instead of implying false precision
- Recommend a prioritized investment path

### ADR Mode
- Produce a concise decision artifact after analysis

### Transition planning (any mode)
- If the recommended option requires restructuring a live system (service extraction, sync → event-driven, datastore split), append a Transition Plan section using `migration-patterns.md`
- If the change breaks a published API contract, apply `api-evolution.md`

## Step 5: Synthesize
- Summarize stakeholder perspectives
- Separate:
  - agreements
  - tensions
  - assumptions
- Make an explicit recommendation
- If a decision is still user-owned, frame the options and tradeoffs clearly

## Step 6: Verify
- Run `checklist.md`
- Confirm the recommendation is:
  - method-appropriate
  - cost-aware
  - scoped correctly
  - explicit about risks and assumptions
- Make validation executable where possible: propose an architecture fitness function or dependency rule (dependency-cruiser, import-linter, ArchUnit, or equivalent) that fails CI when the decision is violated — a validation step no one can run will not be run

## Step 7: Document
- Save the durable artifact to `.agents/results/architecture/`
- Filename patterns (kebab-case topic, no sequence numbers):
  - `adr-<topic>.md`
  - `architecture-recommendation-<topic>.md`
  - `architecture-review-<topic>.md`
  - `cbam-<topic>.md`
  - `diagnosis-<topic>.md`
- Rerunning the same topic updates the existing file; record the revision in the ADR `Status` line rather than creating a copy
- ADR lifecycle: `Status` is `Proposed`, `Accepted`, or `Superseded by <adr-file>`; when a new ADR replaces an old one, update the old ADR's `Status` in the same run
- When running as a dispatched subagent, ALSO write the run report to `.agents/results/result-architecture.md` per the agent protocol; the report links to the durable artifact, it does not replace it
- Emit and verify the completion decision event:

```bash
oma state emit "decision.made" '{"subject":"architecture.adr-complete","decision":"<one-line decision>","rationale":"<one-line rationale>"}'
oma state verify --workflow architecture --checkpoint adr-complete
```

## Escalation
- If the question is really about task sequencing -> hand off to oma-pm
- If the decision is really infra implementation -> hand off to oma-tf-infra
- If the issue is primarily code correctness -> hand off to oma-debug
- If the issue is primarily security/performance/accessibility verification -> hand off to oma-qa
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall