oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-architecture/SKILL.md

@@ -0,0 +1,203 @@
+---
+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.
+
+### 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`

package/skills/oma-architecture/resources/api-evolution.md

@@ -0,0 +1,41 @@
+# API Evolution - Versioning and Deprecation Decision Patterns
+
+> Pattern vocabulary from Microservice API Patterns (MAP - Zimmermann, Stocker, Lübke, Pautasso, Zdun; "Patterns for API Design"). Use in Recommendation or ADR mode when the decision concerns a **published API contract** with consumers the provider does not control. `oma-refactor` routes here when an expand-contract refactoring crosses a published-contract boundary.
+
+## When this file applies
+- Choosing a versioning scheme for a public, partner, or cross-team API
+- Deciding how long old versions live and how consumers migrate off them
+- Writing the ADR for a breaking change to a published contract
+- Reviewing an expand-contract plan whose "contract" phase removes something external consumers may use
+
+## Core tension
+The provider wants freedom to change; consumers want stability. Every pattern below is a **named position on that tradeoff**. An API evolution ADR must state which guarantee is being sold, to whom, and when it expires - Hyrum's Law means anything observable is part of the de-facto contract regardless of what the docs promise.
+
+## Versioning patterns
+| Pattern | Decision | Notes |
+|---------|----------|-------|
+| Version Identifier | Make the version explicit in the contract (URL path, media type, header, or payload field) | Prerequisite for every lifecycle pattern below; "no version marker" is itself a decision (forces Eternal Lifetime or breakage) |
+| Semantic Versioning | MAJOR.MINOR.PATCH signals whether a change breaks, extends, or fixes | Only MAJOR needs a migration decision; publish the compatibility rules, not just the numbers |
+
+## Lifecycle guarantee patterns
+| Pattern | Promise to consumers | Choose when |
+|---------|----------------------|-------------|
+| Experimental Preview | None - may change or vanish without notice | Pre-GA feedback gathering; keeps early adopters off your back-compat hook |
+| Aggressive Obsolescence | Old versions deprecated quickly with published sunset dates | Provider velocity dominates; few, reachable consumers |
+| Limited Lifetime Guarantee | Each version supported for a fixed window (e.g., 24 months from publication) | B2B defaults; lets consumers budget migrations |
+| Two in Production | Exactly N (typically 2) versions live concurrently; shipping version N+1 retires N-1 | Rolling migration with a bounded support burden - the workhorse for internal and partner APIs |
+| Eternal Lifetime Guarantee | Published contracts never break | Huge or unknown consumer base (public web APIs); the most expensive promise - make it deliberately or not at all |
+
+## Decision guidance
+- Internal service-to-service default: **Two in Production + Semantic Versioning + Version Identifier**. It bounds support cost while never forcing a consumer to migrate under fire.
+- Deprecation is a protocol, not an event: announce with sunset date -> run old+new concurrently (the expand phase) -> drive migration with telemetry on old-version traffic -> contract only when traffic is zero or the sunset date passes, whichever the guarantee dictates.
+- The guarantee is set at **publication time**: retrofitting a shorter lifetime onto an already-published version is itself a breaking change to the meta-contract.
+- Telemetry precondition: if you cannot measure per-version consumer traffic, you cannot safely run anything more aggressive than Eternal Lifetime - instrument first.
+- The wider MAP catalog (foundation, responsibility, structure, and quality patterns: Pagination, Wish List, Rate Limit, API Key, ...) covers API *design*; this file deliberately scopes to *evolution*, which is where refactoring and architecture meet.
+
+## ADR checklist for a published-contract change
+- What lifetime guarantee did the old version's publication imply (explicitly or by Hyrum)?
+- Who consumes it today (telemetry, not assumption), and what is migration cost per consumer class?
+- Which lifecycle pattern governs the transition, and what are the announced sunset dates and channels?
+- Can old and new run concurrently during migration (Two in Production / expand phase), and what is the rollback path?
+- How will old-version traffic be monitored to zero before the contract phase?

package/skills/oma-architecture/resources/checklist.md

@@ -0,0 +1,42 @@
+# Architecture Agent - Checklist
+
+## Framing
+- [ ] The architecture problem is stated explicitly
+- [ ] Constraints and quality attributes are identified
+- [ ] Non-goals are listed
+
+## Consistency with Prior Decisions
+- [ ] Prior artifacts in `.agents/results/architecture/` were reviewed
+- [ ] Conflicts with prior ADRs are resolved by superseding (old ADR `Status` updated), not ignored
+
+## Method Choice
+- [ ] The chosen methodology matches the problem
+- [ ] The analysis is not heavier than necessary
+- [ ] Diagnostic routing was used when the initial problem was vague
+
+## Tradeoffs
+- [ ] At least two options were compared when the decision was material
+- [ ] Tradeoffs are concrete, not generic
+- [ ] Implementation cost is considered
+- [ ] Operational cost is considered
+- [ ] Team cognitive load / maintenance cost is considered
+
+## Synthesis
+- [ ] Stakeholder input was gathered only if justified by scope
+- [ ] Agreements and tensions are separated clearly
+- [ ] A recommendation is explicit
+- [ ] Rejected options are documented when relevant
+
+## Decision Quality
+- [ ] Assumptions are listed
+- [ ] Risks are listed
+- [ ] Validation steps are listed, with an executable check (fitness function / dependency rule) where feasible
+- [ ] A Mermaid diagram is included when the decision changes structure
+- [ ] A transition plan is included when the decision restructures a live system
+- [ ] Output artifact matches the selected mode
+- [ ] Durable artifact saved and the `architecture.adr-complete` event emitted and verified
+
+## Boundaries
+- [ ] Visual/UI design concerns were not conflated with software architecture
+- [ ] Terraform/IaC concerns were not allowed to take over system-design reasoning
+- [ ] PM planning work was not duplicated

package/skills/oma-architecture/resources/execution-protocol.md

@@ -0,0 +1,115 @@
+# 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 decisions in `docs/decisions/` first; consult `.agents/results/architecture/`, `docs/design-docs/`, and `docs/plans/designs/` as legacy context until migration:
+  - 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 ADRs and retained recommendations for a selected approach to `docs/decisions/`; update `docs/decisions/index.md`.
+- Keep run-specific reviews, diagnoses, CBAM analyses, and unselected comparison drafts in `.agents/results/architecture/`. When promoting a document into `docs/decisions/`, leave the destination in the source report.
+- Filename patterns (kebab-case topic, no sequence numbers):
+  - `docs/decisions/adr-<topic>.md`
+  - `docs/decisions/architecture-recommendation-<topic>.md` for a retained selected approach
+  - `.agents/results/architecture/architecture-review-<topic>.md`
+  - `.agents/results/architecture/cbam-<topic>.md`
+  - `.agents/results/architecture/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>`. Keep a user-owned unresolved choice `Proposed`; a completed artifact or event is not acceptance. Use `Accepted` only when existing decision authority supports it. Update a prior ADR as superseded only when the replacement is authorized.
+- When dispatched, also write the injected claim and the task/run-scoped report per `../../_shared/runtime/result-contract.md` and `memory-protocol.md`. Use `.agents/results/result-{agentId}-{taskId}-{runId}-{sessionId}.md`, preserving injected IDs. Existing reports under configured coordination memory or `.serena/memories/` remain read fallback; write new reports only to `.agents/results/`. Link the architecture artifact from this report.
+- In an active OMA workflow, record and verify the actual recommendation with its authority status and current artifact revision. This records completion of the analysis without granting implementation approval:
+
+```bash
+oma state emit "decision.made" '{"subject":"architecture.adr-complete","instanceId":"<artifact path and revision>","decision":"<Proposed|Accepted>: <recommended or authorized option and boundary>","rationale":"<option comparison and actual acceptance authority when Accepted>","evidence":["<architecture artifact and supporting evidence paths>"]}'
+oma state verify --workflow architecture --checkpoint adr-complete --instance "<artifact path and revision>"
+```
+
+## 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

package/skills/oma-architecture/resources/methodology-selection.md

@@ -0,0 +1,92 @@
+# Methodology Selection Guide
+
+Choose the lightest method that fits the problem.
+
+## 1. Diagnostic Mode
+
+Use when:
+- the complaint is vague
+- the user feels pain but cannot name the architecture issue
+- it is unclear whether the problem is architecture, planning, QA, or debugging
+
+Output:
+- clarified problem statement
+- why this is an architecture concern
+- recommended next mode
+
+## 2. Recommendation Mode
+
+Use when:
+- the decision is concrete
+- the user wants an architectural direction
+- the analysis does not require formal quality-attribute scenarios
+
+Output:
+- options
+- tradeoff comparison
+- recommendation
+
+## 3. Design-Twice Mode
+
+Use when:
+- the decision is structural and likely to harden into the codebase
+- the first obvious option may anchor the team too early
+- interface, boundary, or decomposition choices are material
+
+Output:
+- two or more materially different options
+- comparison and synthesis
+
+## 4. ATAM-style Mode
+
+Use when:
+- the user asks for architecture review, tradeoffs, risks, or quality attributes
+- reliability, performance, modifiability, security, or operability are central
+- scenario-based evaluation is needed
+
+Output:
+- scenarios
+- sensitivity points
+- tradeoff points
+- risks and non-risks
+
+## 5. CBAM-style Mode
+
+Use when:
+- the user asks what to prioritize or invest in first
+- the decision is economic or sequencing-oriented
+- multiple architecture improvements compete for time and budget
+
+Output:
+- cost/benefit comparison
+- sequencing recommendation
+
+## 6. ADR Mode
+
+Use when:
+- the analysis is done and the team needs a portable record
+- a concise decision artifact is the deliverable
+
+Output:
+- context
+- decision
+- alternatives
+- consequences
+
+## Recommendation vs Design-Twice
+
+Both modes compare options; the difference is where the discipline sits:
+
+- **Recommendation Mode** starts from options that already exist or are obvious — the work is the comparison and the call.
+- **Design-Twice Mode** exists to *generate* a genuinely different second design before comparing — use it when the obvious first option would anchor the team too early.
+
+Litmus test: if you cannot name a materially different second decomposition, you are in Recommendation Mode.
+
+## Selection Heuristics
+
+- Start with Diagnostic Mode if the problem is fuzzy
+- Default to Recommendation Mode if the decision is clear and moderate in scope
+- Upgrade to Design-Twice Mode for material structural choices
+- Upgrade to ATAM-style Mode for quality-attribute and risk-heavy reviews
+- Upgrade to CBAM-style Mode for investment prioritization
+- Finish with ADR Mode when a durable decision record is useful

package/skills/oma-architecture/resources/migration-patterns.md

@@ -0,0 +1,28 @@
+# Architecture Migration - Transition Plan Patterns
+
+> Use when a chosen target architecture requires restructuring a **live system**. `api-evolution.md` covers evolving published API contracts; this file covers the structural transition itself. Output: a Transition Plan section appended to the recommendation or ADR.
+
+## When this file applies
+- The recommendation implies moving between architectures: monolith → service extraction, synchronous → event-driven, datastore split or replacement
+- The system must keep serving traffic during the change
+- A "big bang" cutover is being proposed and needs a safer alternative
+
+## Core tension
+The safest migration is many small reversible steps, but every coexistence mechanism (facade, flag, dual write) is temporary complexity that costs money while it lives. A transition plan must name both the increment safety story and the exit date for the scaffolding — half-finished migrations are the most expensive architecture of all.
+
+## Patterns
+| Pattern | Move | Choose when |
+|---------|------|-------------|
+| Strangler Fig | Route traffic incrementally from old to new behind a stable facade; retire old paths as coverage grows | Large legacy replacement; increments must be independently shippable and reversible |
+| Branch by Abstraction | Introduce an abstraction over the old implementation, build the new one behind it, flip, then delete both the old code and the abstraction if no longer needed | In-process restructuring without long-lived VCS branches |
+| Expand-Contract (Parallel Change) | Add the new interface/schema alongside the old → migrate callers → remove the old | Any interface or schema change with existing callers; pairs with `api-evolution.md` for published contracts |
+| Dual Write / Change Data Capture | Write to (or replicate into) the new store while the old remains source of truth; reconcile, then flip | Datastore split or extraction; never flip before reconciliation reports zero drift |
+| Feature-flag Cutover | Gate the new path behind a flag; ramp by cohort/percentage | Behavior-level switches where per-request routing is cheap; flags must have a removal date |
+
+## Transition Plan checklist
+- **Cutover unit**: what moves per increment, and what evidence proves an increment safe (tests, shadow traffic, reconciliation)
+- **Coexistence**: how old and new run together — routing rule, flag, facade — and who owns it
+- **Rollback**: defined per increment, not just for the whole migration
+- **Data**: which store is source of truth at each stage; reconciliation check before every flip
+- **Contract impact**: if a published API changes, apply the lifecycle patterns in `api-evolution.md`
+- **Exit**: what deletes the old path and the scaffolding, and what stops the migration from stalling half-done (owner + target date)

package/skills/oma-architecture/resources/output-templates.md

@@ -0,0 +1,111 @@
+# Output Templates
+
+Templates track ISO/IEC/IEEE 42010 concepts: stakeholders and concerns (Problem / Constraints), viewpoints (Diagram), and rationale (Tradeoffs / Decision).
+
+## Diagram Guidance
+
+Include a Mermaid diagram whenever the decision changes structure — boundaries, dependencies, or data flow. Default to a C4-style context or container view, scoped to only the elements the decision touches:
+
+```
+graph LR
+  Client[Web Client] --> API[API Service]
+  API --> Notif[Notification Module]
+  Notif -->|extracted?| NotifSvc[Notification Service]
+  NotifSvc --> Queue[(Queue)]
+```
+
+Skip the diagram for non-structural decisions (e.g., a versioning policy).
+
+The Mermaid block is the text SSOT. When `oma diagram resolve --json` returns `engine: archify`, additionally derive an interactive artifact per `_shared/conditional/diagram-engine.md` and link it directly under the Mermaid block:
+
+```md
+Interactive: [adr-<topic>.archify.html](./adr-<topic>.archify.html)
+```
+
+Never replace the Mermaid block with the link — readers of the Markdown (and git diffs) must not depend on the HTML.
+
+## Recommendation Template
+
+```md
+# Architecture Recommendation: <topic>
+
+## Problem
+
+## Constraints and Quality Attributes
+
+## Options
+
+## Diagram (if structural)
+
+## Tradeoff Comparison
+
+## Recommendation
+
+## Transition Plan (if restructuring a live system)
+
+## Risks
+
+## Assumptions
+
+## Validation Steps
+```
+
+## ATAM-style Template
+
+```md
+# Architecture Review: <topic>
+
+## Scope
+
+## Quality Attribute Scenarios
+
+## Architectural Approaches
+
+## Sensitivity Points
+
+## Tradeoff Points
+
+## Risks / Non-Risks
+
+## Recommendations
+```
+
+## CBAM-style Template
+
+```md
+# Architecture Investment Analysis: <topic>
+
+## Candidate Investments
+
+## Benefit Estimate
+
+## Cost Estimate
+
+## Operational / Team Impact
+
+## Priority Ranking
+
+## Recommended Sequence
+```
+
+## ADR Template
+
+```md
+# ADR: <topic>
+
+- Status: Proposed | Accepted | Superseded by <adr-file>
+- Date: <YYYY-MM-DD>
+- Supersedes: <adr-file or none>
+
+## Context
+
+## Decision
+
+## Diagram (if structural)
+
+## Alternatives Considered
+
+## Consequences
+
+## Follow-up Validation
+```