feat: add software architecture methodology (#358)

Add system-level architecture design, tradeoff, distributed workflow, evolution, facilitation, template, eval, and adjacent-owner routing guidance.\n\nAI-assisted: Jasper orchestrated implementation and verification with OpenCode.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

.claude-plugin/marketplace.json

@@ -1094,6 +1094,15 @@
       "strict": false,
       "description": "Operate Slack workspaces from a terminal or agent: list channels, read messages, follow threads, search message history, list files, and verify inbound webhook signatures — with a bundled slack-cli script that is read-only by default and gates every send behind a --dry-run/--yes confirmation. Use when an agent needs to read or post Slack data, triage incidents, or answer questions about what was said in a workspace. Do not use for building Slack apps or bots (that is application development) or workspace administration like user provisioning and org settings (that is the Slack admin console)."
     },
+    {
+      "name": "software-architecture",
+      "source": "./",
+      "skills": [
+        "./software-architecture"
+      ],
+      "strict": false,
+      "description": "Design and review software architectures from business drivers through system boundaries, tradeoffs, runtime behavior, evolution, and architecture practice. Use when choosing a greenfield or target architecture, comparing modular-monolith and service shapes, designing distributed consistency or failure behavior, defining architecture fitness evidence, or facilitating a consequential architecture review. Do not use for reverse engineering, API contract semantics, data-platform design, implementation, infrastructure operations, security lifecycle, or migration execution; route those to the named specialist skills."
+    },
     {
       "name": "software-architecture-analysis",
       "source": "./",

.codex-plugin/plugin.json

@@ -139,6 +139,7 @@
     "./seo-audit",
     "./site-reliability-engineering",
     "./slack",
+    "./software-architecture",
     "./software-architecture-analysis",
     "./spec-driven-development",
     "./strategy-frameworks",

README.md

@@ -499,6 +499,10 @@ Build practical reliability practices around the work teams actually perform: me
 
 Operate Slack workspaces from the terminal: list channels, read messages, follow threads, search history, list files, and verify webhook signatures. Ships a bounded stdlib CLI with `--json`, `--limit`, and a `--dry-run`/`--yes` mutation gate for sends.
 
+### [software-architecture](software-architecture/SKILL.md)
+
+Design and review software architectures from business drivers through system boundaries, tradeoffs, runtime behavior, evolution, and architecture practice. Use for greenfield or target architecture, modular-monolith decisions, distributed consistency and failure behavior, fitness evidence, and architecture reviews; route reverse engineering, interfaces, data, implementation, platform, security, and migration execution to their specialist owners.
+
 ### [software-architecture-analysis](software-architecture-analysis/SKILL.md)
 
 Reverse-engineer a software codebase to understand its architecture, data flow, privacy posture, feature surface, coupling, quality characteristics, data ownership, and workflow recovery — then produce an evidence-grounded clean-room design document, PRD, or migration plan under new constraints. Includes interface extraction, decomposition-readiness, and architecture health assessment guidance.

adr-authoring/evals/evals.json

@@ -89,10 +89,10 @@
     {
       "id": "adr-fitness-boundary",
       "prompt": "Should the ADR authoring skill own a complete evolutionary-architecture program with architecture metrics, drift governance, and change sequencing, or should it define how an ADR is confirmed by a fitness function? Explain the boundary and route the work.",
-      "expected_output": "A boundary decision that keeps ADR authoring responsible for the durable decision, rationale, confirmation link, and operational record, while routing system-wide evolutionary architecture, drift governance, and change sequencing to a human architecture decision owner because no current catalog skill owns that complete workflow. It may link to test, telemetry, or governance skills for execution, but it does not absorb their tool or operational runbooks.",
+      "expected_output": "A boundary decision that keeps ADR authoring responsible for the durable decision, rationale, confirmation link, and operational record, while routing system-wide evolutionary architecture, drift governance, and change sequencing to software-architecture. It may link to test, telemetry, or governance skills for execution, but it does not absorb their tool or operational runbooks.",
       "assertions": [
         "ADR authoring is limited to durable decisions and their confirmation links",
-        "System-wide evolutionary architecture and drift governance are routed to a human architecture decision owner because no current catalog skill owns that workflow",
+        "System-wide evolutionary architecture and drift governance are routed to software-architecture",
         "Execution ownership remains with the relevant test, CI, telemetry, runtime, or governance system",
         "The response explains why the boundary prevents duplicated or ambiguous ownership",
         "The proposed output includes an ADR-to-function-to-evidence trace rather than a standalone metric program"

adr-authoring/references/fitness-functions.md

@@ -6,7 +6,7 @@ A fitness function is a repeatable check that supplies evidence about whether an
 
 The ADR owns the durable choice, rationale, consequences, and a link to confirmation. The fitness-function record owns the operational contract for the check. The project's test, CI, telemetry, runtime, or governance system owns execution and raw evidence. Do not put executable implementation in the ADR, and do not let an operational dashboard silently become the decision record.
 
-For system-wide evolutionary architecture, use a human architecture decision owner; no current catalog skill owns that complete workflow. For general SLO, telemetry, or alerting design, use the relevant reliability or telemetry skill. For operating a named tool, use that tool's skill. This reference is about making an ADR's consequential claim confirmable.
+For system-wide evolutionary architecture, use [`software-architecture`](../../software-architecture/SKILL.md). For general SLO, telemetry, or alerting design, use the relevant reliability or telemetry skill. For operating a named tool, use that tool's skill. This reference is about making an ADR's consequential claim confirmable.
 
 ## Decision-to-Evidence Trace
 

adr-authoring/references/source-index.md

@@ -6,4 +6,4 @@
 - **Porting boundary:** Retained portable methodology, templates, scripts, and references. Removed or generalized Hermes profile, task-orchestration, memory, and rigid response-handoff assumptions.
 - **Issue scope:** Issue #339 deepens fitness-function selection and lifecycle guidance without creating a separate evolutionary-architecture skill.
 - **Synthesis boundary:** The fitness-function method, examples, record template, and eval fixtures in this skill are original repository prose synthesized from the existing ADR material, the issue requirements, and the repository's safe architecture gap analysis. No purchased ebook text, tables, diagrams, examples, taxonomies, or chapter structures are reproduced.
-- **Ownership boundary:** `adr-authoring` owns the durable decision and its confirmation link. A human architecture decision owner owns the system-wide evolution method because no current catalog skill owns that complete workflow; implementation and evidence execution belong to the relevant test, CI, telemetry, runtime, or governance owner.
+- **Ownership boundary:** `adr-authoring` owns the durable decision and its confirmation link. [`software-architecture`](../../software-architecture/SKILL.md) owns the system-wide evolution method; implementation and evidence execution belong to the relevant test, CI, telemetry, runtime, or governance owner.

llms.txt

@@ -123,6 +123,7 @@
 - [seo-audit](seo-audit/SKILL.md): Audit websites and pages for technical SEO, on-page SEO, schema markup, content discoverability, and answer-engine readiness. Use when prioritizing search visibility improvements; route AEO-specific implementation and measurement to the dedicated aeo skill.
 - [site-reliability-engineering](site-reliability-engineering/SKILL.md): Design, operate, and improve reliable production systems with SLOs, incident command, observability, error budgets, and operational practices.
 - [slack](slack/SKILL.md): Operate Slack workspaces from a terminal or agent: list channels, read messages, follow threads, search message history, list files, and verify inbound webhook signatures — with a bundled slack-cli script that is read-only by default and gates every send behind a --dry-run/--yes confirmation. Use when an agent needs to read or post Slack data, triage incidents, or answer questions about what was said in a workspace. Do not use for building Slack apps or bots (that is application development) or workspace administration like user provisioning and org settings (that is the Slack admin console).
+- [software-architecture](software-architecture/SKILL.md): Design and review software architectures from business drivers through system boundaries, tradeoffs, runtime behavior, evolution, and architecture practice. Use when choosing a greenfield or target architecture, comparing modular-monolith and service shapes, designing distributed consistency or failure behavior, defining architecture fitness evidence, or facilitating a consequential architecture review. Do not use for reverse engineering, API contract semantics, data-platform design, implementation, infrastructure operations, security lifecycle, or migration execution; route those to the named specialist skills.
 - [software-architecture-analysis](software-architecture-analysis/SKILL.md): Use this skill to reverse-engineer an existing software system, map its architecture, data flow, privacy posture, coupling, quality characteristics, and feature surface, then produce an evidence-grounded clean-room design document, PRD, or migration plan under new constraints. Use for codebase archaeology, implicit contract extraction, architecture health assessment, or decomposition-readiness analysis. Do not use for greenfield architecture design, direct code review, bug hunting, security auditing, or implementation of API, data, platform, or migration changes; route those to the relevant neighboring skill.
 - [spec-driven-development](spec-driven-development/SKILL.md): Spec-Driven Development (SDD) methodology for AI software factories — where structured specifications are the input, AI agents generate the code, and quality gates enforce correctness at each pipeline phase. Use when designing a spec → review → decompose → implement → verify pipeline that any AI coding tool (Claude Code, Cursor, Hermes Agent, Devin, OpenHands) can follow.
 - [strategy-frameworks](strategy-frameworks/SKILL.md): Structure organizational strategy work: strategic direction, competitive and industry analysis, growth options, capital allocation, acquisitions, and portfolio choices. Use when framing consequential choices about where to compete, how to pursue an opportunity, or how to compare strategic options.

migration-engineering/README.md

@@ -67,7 +67,7 @@ Do **not** load this skill when:
 - The change is an in-place refactor or code rewrite with no data or interface migration.
 - You are writing a release pipeline or deployment automation — route to release-engineering.
 - You are debugging a production incident — route to site-reliability-engineering.
-- You are deciding whether to decompose a system or designing its target architecture — route to the software-architecture decision owner.
+- You are deciding whether to decompose a system or designing its target architecture — route to [`software-architecture`](../software-architecture/SKILL.md).
 
 ## Requirements
 

migration-engineering/SKILL.md

@@ -139,7 +139,7 @@ monolith. If the boundary still needs shared writes, frequent cross-boundary
 transactions, unobservable consumers, or has no tested recovery path, stop and
 recommend modular improvement or request more evidence rather than creating a
 distributed shape by default. Route target-boundary justification to the
-software-architecture decision owner without creating a dead catalog link; this
+[`software-architecture`](../software-architecture/SKILL.md) decision owner; this
 skill owns the safe current-to-target transition once authorized.
 
 ## Core workflow
@@ -334,7 +334,7 @@ methodology. Route implementation details to the skill that owns the subsystem.
 
 | Migration concern | Route to |
 |---|---|
-| Decomposition justification and target-boundary decision | Human architecture decision owner (no current catalog skill owns this decision; `software-architecture-analysis` covers reverse engineering only); this skill sequences an authorized transition |
+| Decomposition justification and target-boundary decision | [`software-architecture`](../software-architecture/SKILL.md); this skill sequences an authorized transition |
 | API contract design, versioning policy, deprecation mechanics | [api-design-and-evolution](../api-design-and-evolution/SKILL.md) |
 | Database schema evolution, ETL/ELT pipeline design, backfill operations | [data-engineering](../data-engineering/SKILL.md) |
 | Infrastructure provisioning, service networking, secret management during migration | [platform-engineering](../platform-engineering/SKILL.md) |

migration-engineering/references/service-extraction-patterns.md

@@ -152,9 +152,9 @@ service creation and escalate rather than selecting a pattern by default.
 
 ## Specialist boundaries
 
-- Target-boundary justification and architecture decomposition belong to the
-  software-architecture decision owner; this reference sequences an approved
-  transition.
+- Target-boundary justification and architecture decomposition belong to
+  [`software-architecture`](../../software-architecture/SKILL.md); this reference
+  sequences an approved transition.
 - API contract semantics and compatibility policy belong to
   `api-design-and-evolution`.
 - CDC, backfill, schemas, and reconciliation implementation belong to

references/skill-triggers.md

@@ -22,6 +22,7 @@ Each skill's `description` field is the canonical routing contract. This conveni
 | "weather", "forecast", "temperature", "is it raining", "Tempest" | [tempest-cli](../tempest-cli/SKILL.md) |
 | "traefik", "reverse proxy", "load balancer", "API gateway", "Let's Encrypt", "ACME", "Docker routing", "traefik.yml", "entry point", "middleware", "TLS termination", "forward auth", "rate limit" | [traefik](../traefik/SKILL.md) |
 | "reverse-engineer", "understand this codebase", "PRD from code", "architecture document", "architecture health", "coupling analysis", "modularity", "decomposition readiness", "data ownership map", "distributed workflow analysis", "reconciliation path" | [software-architecture-analysis](../software-architecture-analysis/SKILL.md) |
+| "software architecture design", "greenfield architecture", "target architecture", "architecture tradeoff", "modular monolith", "service decomposition decision", "distributed workflow design", "architecture fitness function", "architecture drift", "architecture review" | [software-architecture](../software-architecture/SKILL.md) |
 | "data architecture", "data platform", "data strategy", "data mesh", "governance" | [data-architect](../data-architect/SKILL.md) |
 | "AI governance", "AI governance program", "responsible AI", "model risk", "AI risk tier", "AI risk tiering", "use-case risk tier", "governance operating model", "AI decision rights", "AI governance council", "AI risk framework", "NIST AI RMF", "ISO 42001", "AI lifecycle gate", "AI fairness review", "AI transparency", "explainability review", "LLM governance review", "agent safety review", "prompt injection governance", "AI regulatory compliance", "EU AI Act", "AI compliance plan", "GxP AI governance", "ALCOA+", "data integrity governance", "computerized system validation", "AI in regulated life sciences", "AI QMS interface", "governance maturity assessment", "AI board reporting", "board AI governance", "third-party AI due diligence", "model card" | [ai-governance](../ai-governance/SKILL.md) |
 | "de-spin", "is this spin", "propaganda", "misdirection", "true lies", "what is this leaving out", "misleading claim", "selective framing", "evidence theater", "separate what is true false complicated" | [de-spin](../de-spin/SKILL.md) |

software-architecture-analysis/SKILL.md

@@ -27,7 +27,7 @@ metadata:
 - You need to extract an **implicit contract** — the storage operations a codebase performs — to design a formal provider abstraction
 - You need to assess architecture health, coupling, modularity, data ownership, distributed workflows, or readiness for a boundary change from repository evidence
 
-**Don't use for:** Greenfield or proactive architecture design (route to a human architecture decision owner; no current catalog skill owns that workflow), direct code review, bug hunting, or security auditing. Route API/interface semantics to `api-design-and-evolution`, data-platform strategy to `data-architect`, implementation to the relevant engineering skill, deployment substrate to `platform-engineering`, and execution of an approved cross-system migration to `migration-engineering`.
+**Don't use for:** Greenfield or proactive architecture design (route to [`software-architecture`](../software-architecture/SKILL.md)), direct code review, bug hunting, or security auditing. Route API/interface semantics to `api-design-and-evolution`, data-platform strategy to `data-architect`, implementation to the relevant engineering skill, deployment substrate to `platform-engineering`, and execution of an approved cross-system migration to `migration-engineering`.
 
 ## Build Workflow
 

software-architecture/README.md

@@ -0,0 +1,42 @@
+# software-architecture
+
+Make consequential system design choices explicit, testable, and easier to evolve.
+
+## Why Install This Skill
+
+Architecture decisions often fail because teams jump from a technology preference to a deployment shape without agreeing on drivers, quality scenarios, ownership, or failure behavior. This skill gives an agent a practical way to compare options and expose the costs of each choice.
+
+It is useful for greenfield systems, target-state design, modular-monolith decisions, distributed workflows, cloud topology discussions, and architecture reviews. It keeps specialist work with the owners that already do it, so an architecture brief can coordinate API, data, backend, platform, security, capacity, diagramming, ADR, and migration follow-ups without absorbing them.
+
+## What You Get
+
+| Path | Provides |
+|---|---|
+| `SKILL.md` | Thin workflow index and ownership boundaries |
+| `references/` | Seven focused decision guides plus public source index |
+| `templates/` | Architecture design brief, tradeoff record, and review worksheet |
+| `evals/evals.json` | Eight output-quality cases covering design and routing boundaries |
+
+## Quick Start
+
+Ask for a concrete architecture decision, for example:
+
+```text
+Compare a modular monolith and service decomposition for our checkout system, including data ownership, failure behavior, and an evidence plan.
+```
+
+Expected output: a decision brief with scenarios, alternatives, consequences, open evidence, and specialist handoffs.
+
+## Triggers
+
+- Greenfield or target-state software architecture
+- Modular monolith versus service decomposition
+- Architecture characteristics and tradeoffs
+- Distributed workflow consistency and failure design
+- Cloud application topology and deployment granularity
+- Architecture fitness functions, drift, or evolutionary change
+- Facilitated architecture reviews and decision records
+
+## Requirements
+
+No runtime dependencies or API keys. Use the repository's relevant specialist skills and public sources when evidence is needed.

software-architecture/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: software-architecture
+description: Design and review software architectures from business drivers through system boundaries, tradeoffs, runtime behavior, evolution, and architecture practice. Use when choosing a greenfield or target architecture, comparing modular-monolith and service shapes, designing distributed consistency or failure behavior, defining architecture fitness evidence, or facilitating a consequential architecture review. Do not use for reverse engineering, API contract semantics, data-platform design, implementation, infrastructure operations, security lifecycle, or migration execution; route those to the named specialist skills.
+license: MIT
+compatibility: Platform-agnostic methodology. No runtime dependencies.
+metadata:
+  tags: software-architecture, architecture-design, tradeoffs, modularity, distributed-systems, evolutionary-architecture, architecture-review
+---
+
+# Software Architecture
+
+Use this skill to make system-level design decisions and leave an inspectable path from drivers to evidence. It owns the architecture decision workflow, not the implementation of any subsystem.
+
+## Workflow
+
+1. **Frame the decision.** Establish the desired outcome, stakeholders, constraints, decision horizon, reversibility, affected systems, and evidence gaps. Do not invent scale, regulatory, latency, or ownership facts.
+2. **Turn qualities into scenarios.** Name the architecture characteristics that matter, express each as an observable scenario, prioritize them, and expose conflicts. Load `references/architecture-characteristics-and-tradeoffs.md`.
+3. **Choose boundaries and shape.** Compare styles, topology, and deployment granularity against the scenarios and team operating capacity. Load `references/styles-topologies-and-granularity.md`.
+4. **Test ownership and coupling.** Identify policy, data, change, runtime, and team boundaries. Treat a service split as a hypothesis, not a default. Load `references/coupling-modularity-and-data-ownership.md`.
+5. **Make runtime behavior explicit.** For asynchronous or distributed flows, specify authority, consistency, ordering, retries, duplicates, timeouts, partial failure, recovery, and reconciliation. Load `references/distributed-workflows-and-consistency.md`.
+6. **Record and verify.** Capture the decision and rejected alternatives in `templates/architecture-design-brief.md` and `templates/tradeoff-record.md`; use `templates/architecture-review.md` for challenge and sign-off. Define fitness evidence and drift response with `references/evolution-fitness-functions-and-drift.md`.
+7. **Plan change without hiding execution ownership.** Identify evolutionary slices, coexistence assumptions, and handoff conditions. Load `references/migration-and-coexistence.md`; route an approved transition to `migration-engineering`.
+8. **Facilitate proportionately.** Match review depth to blast radius, irreversibility, uncertainty, and cross-team impact. Load `references/architecture-practice-and-facilitation.md`.
+
+## Output Contract
+
+Produce an architecture decision brief or review that includes drivers, stakeholders, constraints, prioritized scenarios, candidate options, explicit tradeoffs, boundaries and ownership, runtime and failure behavior, operational implications, decisions, evidence gaps, fitness checks, evolution slices, and named owners. State what is decided, what remains open, and which specialist owns follow-up work.
+
+## Ownership Boundaries
+
+- Reverse engineer an existing codebase or infer architecture from repository evidence with `software-architecture-analysis`.
+- Design interface contracts, schemas, compatibility, or API topology with `api-design-and-evolution`.
+- Design data platforms, data products, data models, or data governance with `data-architect`.
+- Implement services, integrations, transactions, or application code with `backend-engineering` and the relevant engineering owner.
+- Provision or operate cloud, network, CI/CD, containers, secrets, or observability substrate with `platform-engineering` and its tool owners.
+- Define security requirements, threat models, authorization, secrets, or security evidence with `secure-software-engineering`.
+- Author the durable ADR with `adr-authoring`; this skill supplies the architecture decision context and tradeoff analysis.
+- Execute an approved cross-system transition with `migration-engineering`; this skill decides whether the target shape and boundary are justified.
+- Model capacity, unit cost, load evidence, or SLO-cost tradeoffs with `capacity-and-cost-engineering`.
+- Create structural diagrams with `c4-diagramming` or `mermaid-diagrams`.
+- Govern a technology portfolio, radar, or proportional technology governance path with `technology-radar`.
+
+## When Not To Use
+
+Do not use this skill as a substitute for those specialist owners, as a code review workflow, or as a vendor/tool runbook. If the request is only one interface, data platform, implementation, infrastructure, security, capacity, diagram, ADR, or migration concern, load the narrower owner directly. If the architecture question depends on facts from an existing system, start with `software-architecture-analysis` and return here for a target decision.
+
+## Reference Guide
+
+| Load when | Reference |
+|---|---|
+| Prioritizing qualities and comparing conflicting outcomes | `references/architecture-characteristics-and-tradeoffs.md` |
+| Comparing styles, deployment topology, or granularity | `references/styles-topologies-and-granularity.md` |
+| Testing modularity, coupling, boundaries, and data authority | `references/coupling-modularity-and-data-ownership.md` |
+| Designing distributed workflows, consistency, or failure behavior | `references/distributed-workflows-and-consistency.md` |
+| Defining fitness evidence, drift response, or evolutionary change | `references/evolution-fitness-functions-and-drift.md` |
+| Planning coexistence and handing execution to migration engineering | `references/migration-and-coexistence.md` |
+| Running architecture workshops, reviews, and decision facilitation | `references/architecture-practice-and-facilitation.md` |
+| Checking provenance and the licensed-books transformation boundary | `references/source-index.md` |
+
+## Completion
+
+Stop when the architecture decision has an accountable owner, explicit alternatives and consequences, evidence or a named gap for each material claim, a verification path for prioritized characteristics, and specialist handoffs. Escalate rather than silently resolve missing authority, security, data ownership, or operational evidence.

software-architecture/evals/evals.json

@@ -0,0 +1,98 @@
+{
+  "schema_version": 1,
+  "skill_name": "software-architecture",
+  "evals": [
+    {
+      "id": "greenfield-design",
+      "prompt": "Design the architecture for a new appointment platform. It has a small team, uncertain demand, strict audit needs, and a requirement to keep booking responsive when a notification provider is down. Compare a modular monolith with a distributed option and define the first evidence to collect.",
+      "expected_output": "A decision brief that starts with drivers and scenarios, compares deployment shapes, makes audit and notification failure behavior explicit, recommends a proportionate starting shape, records uncertainty, and names specialist handoffs.",
+      "assertions": [
+        "Drivers and observable scenarios are stated before technology choices",
+        "Modular monolith and distributed alternatives are compared with negative consequences",
+        "Notification-provider failure has an explicit user-visible and recovery behavior",
+        "Uncertain demand is treated as an evidence gap rather than an invented scale fact",
+        "The output names specialist handoffs without absorbing implementation or security ownership"
+      ]
+    },
+    {
+      "id": "modular-monolith-service-choice",
+      "prompt": "Should we split checkout pricing into a service? It shares a transaction with order creation, four jobs read its tables directly, traffic is low and stable, and no team owns pricing data end to end. Give an architecture recommendation and next steps.",
+      "expected_output": "A recommendation to retain or strengthen the modular monolith pending evidence, citing shared transactions, direct table consumers, unclear authority, and low independent scaling benefit. It distinguishes target architecture from migration execution.",
+      "assertions": [
+        "Shared transaction and direct table access are identified as boundary risks",
+        "Unclear data ownership is identified as a blocker or explicit evidence gap",
+        "Low stable traffic is used against a service-specific scaling justification",
+        "The recommendation does not assume service decomposition is the desired outcome",
+        "Migration sequencing is routed separately from the architecture decision"
+      ]
+    },
+    {
+      "id": "distributed-consistency-failure",
+      "prompt": "Design a payment authorization workflow across an order service, payment provider, and ledger. The provider can timeout after charging, messages can duplicate or arrive out of order, and users must not see a confirmed order without a durable payment outcome.",
+      "expected_output": "A workflow design that defines authority, acknowledgement, consistency scope, idempotency, duplicate and ordering behavior, timeout ambiguity, reconciliation, user-visible pending state, and recovery evidence.",
+      "assertions": [
+        "The design distinguishes durable payment authority from derived order state",
+        "Timeout after a possible charge has an explicit pending or reconciliation path",
+        "Duplicate and out-of-order delivery behavior is defined",
+        "The user-visible confirmation rule is tied to a durable payment outcome",
+        "Recovery and reconciliation have named owners and evidence"
+      ]
+    },
+    {
+      "id": "evolutionary-fitness",
+      "prompt": "Our architecture decision requires dependencies to point toward domain policy and forbids new cross-module database writes. Define an evolutionary fitness plan and drift response without turning the ADR skill into a full architecture governance program.",
+      "expected_output": "A plan linking the architecture decision to bounded structural checks, evidence owners, cadence, threshold rationale, exceptions, drift classification, and ADR confirmation while routing execution to project tooling.",
+      "assertions": [
+        "Each architectural claim maps to a bounded observable check",
+        "The plan names cadence, owner, threshold rationale, and missing-result behavior",
+        "Drift is classified into defect, exception, changed requirement, stale rule, or unknown",
+        "Execution remains with test, CI, telemetry, or governance systems",
+        "ADR authoring is limited to the durable decision and confirmation trace"
+      ]
+    },
+    {
+      "id": "cloud-topology",
+      "prompt": "Review a proposed multi-region cloud topology for a read-heavy public catalog. It includes regional replicas, a global entry point, asynchronous replication, and a single write region. Identify the architecture questions and tradeoffs before anyone chooses provider-specific services.",
+      "expected_output": "A provider-neutral topology review covering authority, replication lag, stale reads, regional failure, write routing, recovery, network and identity boundaries, deployment blast radius, and handoff to platform and capacity owners.",
+      "assertions": [
+        "Single write authority and replica staleness are made explicit",
+        "Regional failure and recovery behavior are analyzed",
+        "Logical architecture is separated from provider-specific provisioning",
+        "Network, identity, and deployment blast radius questions are included",
+        "Platform and capacity implementation or evidence ownership is routed explicitly"
+      ]
+    },
+    {
+      "id": "api-routing-boundary",
+      "prompt": "Write an OpenAPI contract for a new search endpoint with pagination, error semantics, and backward compatibility rules.",
+      "expected_output": "A routing response that sends the task to api-design-and-evolution rather than producing a system architecture method, while optionally noting that a broader topology decision would return to software architecture.",
+      "assertions": [
+        "The request is routed to api-design-and-evolution",
+        "Pagination, error, and compatibility semantics are identified as API ownership",
+        "The architecture skill does not duplicate an OpenAPI contract workflow"
+      ]
+    },
+    {
+      "id": "data-platform-routing",
+      "prompt": "Choose between a lakehouse and warehouse for event analytics, including data product ownership, freshness, governance, and platform migration sequencing.",
+      "expected_output": "A routing response that sends data platform, data product, governance, and modeling decisions to data-architect, with migration-engineering involved only for an approved transition.",
+      "assertions": [
+        "Data platform and data product design are routed to data-architect",
+        "Modeling and governance are not reimplemented by software-architecture",
+        "Migration execution is conditional on an approved target decision"
+      ]
+    },
+    {
+      "id": "implementation-security-migration-routing",
+      "prompt": "Implement the chosen architecture by adding OAuth authorization, Kubernetes manifests, retry logic, and a zero-downtime data migration from the old service.",
+      "expected_output": "A multi-owner routing response: security to secure-software-engineering, service code to backend-engineering, substrate to platform-engineering, and approved migration execution to migration-engineering. It does not pretend architecture design owns those implementations.",
+      "assertions": [
+        "OAuth and authorization are routed to secure-software-engineering",
+        "Retry logic and service implementation are routed to backend-engineering",
+        "Kubernetes manifests and substrate operations are routed to platform-engineering",
+        "Zero-downtime cross-system migration is routed to migration-engineering",
+        "The response preserves the architecture skill as the decision owner rather than an implementation owner"
+      ]
+    }
+  ]
+}

software-architecture/references/architecture-characteristics-and-tradeoffs.md

@@ -0,0 +1,32 @@
+# Architecture Characteristics And Tradeoffs
+
+## Start with scenarios
+
+Do not list qualities as adjectives. Write a scenario with a stimulus, affected boundary, measurable response, and context. For example: "During a regional dependency outage, checkout preserves order acceptance for 15 minutes, returns a clear pending state, and reconciles accepted orders when the dependency returns." The scenario makes the tradeoff and evidence surface visible.
+
+Classify each driver as business outcome, user expectation, operational need, legal or contractual constraint, team constraint, or technical constraint. Mark each claim as observed, reported, inferred, or unknown.
+
+## Prioritize without pretending precision
+
+Rank scenarios using a short rationale such as must-preserve, differentiating, enabling, or deferrable. Record who supplied the priority and what would change it. Avoid universal numeric weights when evidence cannot support them. If a score is useful, show the inputs and uncertainty.
+
+## Compare options
+
+For each candidate, assess:
+
+- value delivered for the drivers;
+- cost paid in complexity, latency, coordination, and operations;
+- failure and recovery behavior;
+- reversibility and migration burden;
+- team capability and ownership fit;
+- evidence available now and evidence still needed.
+
+Separate hard constraints from preferences. A candidate that violates a hard constraint is not a lower-scoring option; it is rejected unless the constraint changes.
+
+## Conflicts are decisions
+
+Common tensions include consistency versus availability, isolation versus cost, autonomy versus duplicated capability, latency versus durability, flexibility versus simplicity, and local ownership versus cross-system reuse. State which side is favored, for which scenario, and what consequence is accepted. A tradeoff record is incomplete if it names only benefits.
+
+## Review questions
+
+Ask: What user or operator harm occurs if this characteristic is missed? Where is the boundary that can enforce it? What is the tail behavior, not just the average? Which assumption is most likely to be wrong? What evidence would reverse the choice?

software-architecture/references/architecture-practice-and-facilitation.md

@@ -0,0 +1,25 @@
+# Architecture Practice And Facilitation
+
+Architecture practice is a decision-making activity, not a ceremony. Start with the smallest group that owns the drivers, affected boundaries, operations, security, data, and delivery consequences. Invite specialists for their decisions, not as a substitute for accountable ownership.
+
+## Review flow
+
+1. Share the decision brief and evidence gaps before the session.
+2. Confirm the decision to be made and the authority to make it.
+3. Test drivers and scenarios before debating technologies.
+4. Compare options using the same criteria and expose rejected alternatives.
+5. Challenge failure, ownership, operability, security, capacity, cost, and evolution assumptions.
+6. Record decisions, dissent, open questions, owners, and due dates.
+7. Define the evidence that can confirm or reverse the choice.
+
+## Proportionality
+
+Use lightweight peer review for local, reversible decisions. Increase evidence and cross-team participation for broad, irreversible, regulated, expensive, or safety-sensitive decisions. Do not turn every choice into a central board review; route technology portfolio governance to `technology-radar` and durable decision records to `adr-authoring`.
+
+## Facilitation guardrails
+
+Separate facts, assumptions, preferences, and decisions. Make the quietest stakeholder's constraint visible without manufacturing consensus. Time-box exploration only after the decision boundary is clear. If authority or evidence is missing, stop the decision, name the blocker, and assign the next discovery rather than filling the gap with confidence.
+
+## Outputs
+
+The minimum useful record is a decision brief, one or more tradeoff records, an architecture view or diagram handoff, an evidence plan, and a review outcome. The record should tell a future reader what changed, why, what was rejected, and what would cause reconsideration.

software-architecture/references/coupling-modularity-and-data-ownership.md

@@ -0,0 +1,24 @@
+# Coupling, Modularity, And Data Ownership
+
+Assess a candidate boundary across several coupling surfaces:
+
+- **Policy coupling:** one invariant requires coordinated changes;
+- **data coupling:** components share tables, records, keys, or write authority;
+- **temporal coupling:** one step must be available or ordered before another;
+- **runtime coupling:** latency, availability, or resource pressure propagates;
+- **deployment coupling:** changes must ship together;
+- **organizational coupling:** ownership, incentives, or skills require coordination.
+
+High coupling is not automatically bad. Shared coupling can be cheaper inside one process when the invariant is strong and the team is one owner. The question is whether the proposed boundary reduces the costly coupling without creating a worse failure or coordination surface.
+
+## Modularity checks
+
+Inspect change history, dependency direction, call paths, data access, transaction scope, and operational ownership when evidence exists. For a greenfield design, mark these as hypotheses and define a probe. Prefer a cohesive module with a narrow interface over a distributed component whose interface exposes internal data or transaction assumptions.
+
+## Data authority
+
+For each important fact, identify the authoritative writer, derived views, caches, replicas, audit history, and deletion authority. State who may mutate it, what an accepted write means, and how conflicting updates are resolved. Data platform and data-model decisions belong to `data-architect`; architecture owns the cross-boundary ownership decision.
+
+## Decomposition decision
+
+Recommend a modular monolith or staged boundary when ownership is unclear, transactions span the candidate, consumers bypass an interface, load is not independently shaped, or recovery cannot be tested. Recommend separate deployment only when the benefit is concrete and the team can own the new operational surface. Hand an approved transition to `migration-engineering`.

software-architecture/references/distributed-workflows-and-consistency.md

@@ -0,0 +1,19 @@
+# Distributed Workflows And Consistency
+
+For every cross-process workflow, describe the command or event path, authority, durable state, acknowledgement point, and recovery path. Use a sequence or state table when prose would hide timing.
+
+## Consistency contract
+
+State what must be atomic, what may be eventually consistent, the allowed staleness or lag, the visibility point, and the conflict rule. Do not say "strong consistency" without naming the invariant and scope. Route message or API contract semantics to `api-design-and-evolution` and implementation patterns to `backend-engineering`.
+
+## Failure inventory
+
+Cover timeouts, retries, duplicate delivery, lost or delayed messages, reordering, partial commits, dependency outage, process restart, poison input, overloaded consumers, and operator intervention. For each, state detection, user-visible result, retry or compensation rule, idempotency key or deduplication scope, and reconciliation owner.
+
+## Orchestration and choreography
+
+Choose orchestration when a coordinator makes progress and compensation legible; choose choreography when independent facts and local reactions reduce central coordination. Either choice must expose observability, completion detection, stuck-work handling, and ownership. Do not treat asynchronous messaging as automatically decoupled or reliable.
+
+## Recovery evidence
+
+Name the state that can be rebuilt, the source of truth, the replay or reconciliation mechanism, and the test or exercise that proves recovery. Route RTO/RPO, game days, and restore verification to `resilience-and-recovery`; route service SLOs and incident operation to `site-reliability-engineering`.

software-architecture/references/evolution-fitness-functions-and-drift.md

@@ -0,0 +1,23 @@
+# Evolution, Fitness Functions, And Drift
+
+Treat architecture as a sequence of decisions exposed to change. For each important decision, identify the characteristic it protects, the boundary where violation can be observed, the evidence type, cadence, owner, threshold rationale, exception path, and retirement condition.
+
+## Fitness evidence
+
+Use structural checks for dependency direction or forbidden relationships, scenario tests for recovery or isolation, runtime evidence for latency or saturation, and human review for intent that cannot be mechanized. A check is not proof outside its scope. Record denominator, exclusions, missing-data behavior, and known false-positive or false-negative paths.
+
+`adr-authoring` owns the durable decision and its link to confirmation. The project test, CI, telemetry, runtime, or governance system owns execution. Load `adr-authoring` for the ADR and fitness-function record.
+
+## Drift loop
+
+1. Detect a deviation or changed driver.
+2. Classify it as defect, intentional exception, changed requirement, stale rule, or unknown.
+3. Record impact, affected scenarios, owner, and expiry or review date.
+4. Choose repair, accepted exception, decision revision, or retirement.
+5. Re-run evidence and update the decision record.
+
+Avoid metrics that can improve while architecture intent worsens. Review tails, exclusions, boundary shifts, and gaming paths. Route portfolio governance to `technology-radar` and operational telemetry to its specialist owner.
+
+## Evolution slices
+
+Prefer increments that preserve a selectable path, create evidence, and keep recovery legible. State what becomes irreversible, what must coexist, and what observation closes the slice. This is architecture sequencing, not migration execution.

software-architecture/references/migration-and-coexistence.md

@@ -0,0 +1,26 @@
+# Migration And Coexistence
+
+Architecture decides whether a target boundary is justified and what properties the transition must preserve. `migration-engineering` owns the current-to-target execution method: compatibility windows, dual-running, reconciliation, cutover, recovery classification, deprecation, and cleanup.
+
+## Handoff fields
+
+Before handoff, provide:
+
+- current and target boundaries;
+- decision drivers and rejected alternatives;
+- authority and ownership changes;
+- interface and data contracts to be designed by specialists;
+- coupling and consumer inventory with evidence gaps;
+- consistency and failure invariants;
+- coexistence assumptions and selectable paths;
+- fitness evidence and cutover conditions;
+- irreversible steps and explicit acceptance needs;
+- named architecture, migration, implementation, platform, security, data, and operations owners.
+
+## Patterns as roles
+
+Name a transition pattern by the risk it controls: routing controls traffic selection, an abstraction controls call-site change, a translation boundary protects semantic ownership, change capture carries state, and parallel comparison creates evidence. Do not select a pattern merely because extraction was requested. Load `migration-engineering` once the boundary is approved.
+
+## Retain the monolith when
+
+The candidate still needs shared writes, frequent cross-boundary transactions, unowned data, hidden consumers, untestable recovery, or no measurable independent scaling or ownership benefit. Record modular improvements and the evidence that would reopen the decision.

software-architecture/references/source-index.md

@@ -0,0 +1,25 @@
+# Source Index
+
+This skill is an original, task-centered synthesis. Public sources inform concepts and terminology; they are not copied as instructional text.
+
+| Source | Use in this skill | URL |
+|---|---|---|
+| ISO/IEC/IEEE 42010:2011 overview | Architecture description concerns, stakeholders, viewpoints, and rationale | https://www.iso.org/standard/50508.html |
+| C4 model | Choosing a communication level for structural views | https://c4model.com/ |
+| arc42 | Practical architecture documentation sections and review prompts | https://arc42.org/ |
+| AWS Well-Architected Framework | Public quality-area questions and tradeoff framing; not provider prescription | https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html |
+| Google SRE resources | Reliability, service behavior, and evidence-oriented operational thinking | https://sre.google/sre-book/table-of-contents/ |
+| Martin Fowler, Monolith First | Reasons to delay distribution and learn boundaries before splitting | https://martinfowler.com/bliki/MonolithFirst.html |
+| Martin Fowler, StranglerFigApplication | Coexistence and incremental replacement vocabulary | https://martinfowler.com/bliki/StranglerFigApplication.html |
+| Thoughtworks Technology Radar | Public technology adoption and uncertainty vocabulary; portfolio governance remains with `technology-radar` | https://www.thoughtworks.com/radar |
+| NIST SP 800-160 Vol. 1 Rev. 1 | Systems security engineering as a neighboring lifecycle owner | https://csrc.nist.gov/pubs/sp/800/160/v1/r1/final |
+
+## Licensed-books boundary
+
+The private architecture comparison report and purchased books may inform research only. This repository does not reproduce their prose, tables, diagrams, examples, taxonomies, chapter order, or distinctive presentation. The skill was written from the user-task workflow, repository ownership boundaries, and public sources above. No purchased ebook is a source file for this deliverable, and no purchased ebook should be read or quoted as part of using it.
+
+## Provenance and review
+
+- Research input: a safe synthesized architecture comparison supplied for this task.
+- Transformation: claims and failure pressures were compared across public sources and existing repository owners, then rewritten as original procedures, templates, and eval prompts.
+- Review rule: if future edits resemble a source's distinctive expression or structure, rewrite from the user task and re-check this boundary before publication.

software-architecture/references/styles-topologies-and-granularity.md

@@ -0,0 +1,23 @@
+# Styles, Topologies, And Granularity
+
+Choose a shape because it fits the scenarios and ownership, not because the label is fashionable.
+
+## Style comparison
+
+Compare a modular monolith, separately deployed services, event-oriented collaboration, batch or workflow-oriented integration, and managed platform capabilities by the same questions: where policy lives, where data is authoritative, how callers coordinate, how failures surface, how teams deploy and operate, and how the shape changes later.
+
+## Deployment topology
+
+Describe runtime placement and trust boundaries separately from logical boundaries. Include process and network hops, regions or zones, data stores, queues, ingress and egress, and operator paths. Show which parts are managed by the application team and which are substrate responsibilities. Route concrete cloud resource selection or provisioning to `platform-engineering`.
+
+## Granularity test
+
+A boundary is promising when it has a coherent policy, an owner who can change and operate it, a stable interaction surface, data authority that can be stated, and a failure behavior that callers can tolerate. A boundary is premature when it exists only to reduce file size, mirrors team names without ownership, requires frequent distributed transactions, or adds a hop without a scenario that benefits.
+
+## Cloud topology questions
+
+For a cloud design, document regional assumptions, availability zones, state placement, network admission, identity boundaries, dependency failure, deployment blast radius, data movement, and recovery. Do not claim provider resilience from a service name alone. Load `platform-engineering` for substrate implementation and `capacity-and-cost-engineering` for measured capacity or spend.
+
+## Diagram handoff
+
+Use `c4-diagramming` for context, container, component, or code views. A diagram supports the decision; it does not replace ownership, runtime behavior, or evidence.

software-architecture/templates/architecture-design-brief.md

@@ -0,0 +1,53 @@
+# Architecture Design Brief
+
+## Decision
+
+- Decision to make:
+- Accountable decision owner:
+- Date and horizon:
+- Reversibility:
+
+## Drivers and stakeholders
+
+| Driver or outcome | Source | Priority | Evidence status |
+|---|---|---|---|
+| | | | |
+
+Stakeholders and constraints:
+
+## Scenarios
+
+| ID | Stimulus | Boundary | Required response | Measure or evidence |
+|---|---|---|---|---|
+| | | | | |
+
+## Options
+
+| Option | Fits | Costs | Failure and recovery | Ownership fit | Evidence gap |
+|---|---|---|---|---|---|
+| | | | | | |
+
+## Boundaries and runtime shape
+
+- Policy ownership:
+- Data authority and derived state:
+- Logical boundaries:
+- Deployment topology:
+- Interaction paths:
+- Team and operational ownership:
+
+## Decision and consequences
+
+- Chosen option:
+- Rejected alternatives and reasons:
+- Benefits accepted:
+- Costs and risks accepted:
+- Open questions and assumptions:
+
+## Verification and handoffs
+
+| Claim or characteristic | Check or evidence | Owner | Trigger | Failure action |
+|---|---|---|---|---|
+| | | | | |
+
+Specialist handoffs: API, data, backend, platform, security, capacity, diagrams, ADR, migration, operations.

software-architecture/templates/architecture-review.md

@@ -0,0 +1,37 @@
+# Architecture Review
+
+## Scope and authority
+
+- Decision under review:
+- Review owner and accountable decider:
+- Reviewers and affected teams:
+- Decision deadline:
+- Review mode and rationale:
+
+## Evidence check
+
+- Facts observed:
+- Assumptions:
+- Unknowns requiring discovery:
+- Sources and artifacts:
+
+## Challenge checklist
+
+- [ ] Drivers and prioritized scenarios are explicit.
+- [ ] Alternatives use comparable criteria and rejection reasons are recorded.
+- [ ] Boundaries, data authority, and coupling are named.
+- [ ] Consistency, ordering, retries, duplicates, timeout, partial failure, and recovery are explicit.
+- [ ] Security, capacity, cost, and operational evidence have owners or explicit gaps.
+- [ ] Deployment topology is distinct from logical architecture.
+- [ ] Evolution slices, drift response, and irreversible steps are visible.
+- [ ] Specialist handoffs do not duplicate their methods.
+
+## Outcome
+
+- [ ] Accept
+- [ ] Accept with conditions
+- [ ] Rework
+- [ ] Defer pending evidence
+- [ ] Reject
+
+Decision, dissent, conditions, owners, evidence triggers, and reconsideration criteria:

software-architecture/templates/tradeoff-record.md

@@ -0,0 +1,37 @@
+# Architecture Tradeoff Record
+
+- Topic:
+- Decision owner:
+- Date:
+
+## Driver or scenario
+
+- Required outcome:
+- Hard constraints:
+- Evidence and uncertainty:
+
+## Options compared
+
+| Criterion | Option A | Option B | Option C |
+|---|---|---|---|
+| User or business outcome | | | |
+| Consistency and correctness | | | |
+| Failure and recovery | | | |
+| Change and deployment | | | |
+| Team operability | | | |
+| Capacity and cost evidence | | | |
+| Reversibility | | | |
+
+## Decision
+
+- Selected option:
+- Why it fits the highest-priority scenario:
+- Negative consequences accepted:
+- Rejected options and rejection reasons:
+- What evidence would reverse this choice:
+
+## Follow-up
+
+| Action or evidence | Owner | Due or trigger | Handoff |
+|---|---|---|---|
+| | | | |

technology-radar/SKILL.md

@@ -15,7 +15,7 @@ CTO methodology for making technology decisions, governing architecture, measuri
 
 ## When Not to Use
 
-- Route enterprise capability maps, operating-model design, and current/target-state roadmaps to a human enterprise-architecture owner; no current catalog skill owns that workflow. This skill stays focused on technology portfolio posture and governance mechanics.
+- Route enterprise capability maps, operating-model design, and current/target-state roadmaps to the appropriate enterprise-architecture owner. This skill stays focused on technology portfolio posture and governance mechanics; use [`software-architecture`](../software-architecture/SKILL.md) for system-level target design.
 - Route the durable record of one consequential decision to `adr-authoring`; use this skill to choose the governance path and connect the decision to standards or radar feedback.
 - Route system design and code changes to the relevant engineering skill, security requirements and threat modeling to `secure-software-engineering`, and live operations or SLO work to `site-reliability-engineering`.