mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
fix(architecture): route distributed mechanisms to DDIA (#367)
Add progressive DDIA handoff and focused replication, partitioning, fencing, and isolation eval coverage.\n\nAI-assisted: Jasper orchestrated implementation and verification with OpenCode. Signed-off-by: Magnus Hedemark <magnus919@pm.me>
This commit is contained in:
Magnus Hedemark
@@ -1119,7 +1119,7 @@
|
||||
"./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."
|
||||
"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, replication, partitioning, coordination, ordering, transaction isolation, 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",
|
||||
|
||||
@@ -125,7 +125,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](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, replication, partitioning, coordination, ordering, transaction isolation, 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.
|
||||
|
||||
@@ -15,7 +15,7 @@ It is useful for greenfield systems, target-state design, modular-monolith decis
|
||||
| `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 |
|
||||
| `evals/evals.json` | Twelve output-quality cases covering design, distributed-data mechanism choices, and routing boundaries |
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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.
|
||||
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, replication, partitioning, coordination, ordering, transaction isolation, 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:
|
||||
@@ -37,6 +37,7 @@ Produce an architecture decision brief or review that includes drivers, stakehol
|
||||
- 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`.
|
||||
- Design and exercise degradation, failover, restore, or recovery evidence with `resilience-and-recovery`.
|
||||
- Create structural diagrams with `c4-diagramming` or `mermaid-diagrams`.
|
||||
- Govern a technology portfolio, radar, or proportional technology governance path with `technology-radar`.
|
||||
|
||||
@@ -52,11 +53,14 @@ Do not use this skill as a substitute for those specialist owners, as a code rev
|
||||
| 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` |
|
||||
| Choosing replication, partitioning, coordination, ordering, or transaction-isolation mechanisms | `references/distributed-workflows-and-consistency.md`, then the [DDIA mini reference](../programming-principles/references/designing-data-intensive-apps.mini.md); load the [full reference](../programming-principles/references/designing-data-intensive-apps.full.md) only when deeper mechanism analysis is necessary |
|
||||
| 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` |
|
||||
|
||||
Keep the ownership split explicit when loading DDIA: this skill owns the system-level architecture decision and its tradeoffs; `programming-principles` supplies distributed-data principles and mechanism detail. Route message-handler implementation to `backend-engineering`, API or event contracts to `api-design-and-evolution`, data-platform design to `data-architect`, and exercised recovery evidence to `resilience-and-recovery`.
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -93,6 +93,50 @@
|
||||
"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"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "multi-writer-replication-decision",
|
||||
"prompt": "Choose a replication architecture for a multi-region document service that must accept offline edits in two regions. Define read freshness, concurrent-write conflict behavior, failover, and repair.",
|
||||
"expected_output": "A system architecture decision that states write authority and visibility semantics, compares replication options against latency and failure constraints, defines conflict detection and resolution, and names reconciliation and recovery evidence. It loads DDIA progressively for mechanism detail while preserving specialist handoffs.",
|
||||
"assertions": [
|
||||
"The decision makes writable replicas, durability, visibility, staleness, and read-your-writes expectations explicit",
|
||||
"Concurrent multi-writer conflict detection, resolution, reconciliation, and repair are defined",
|
||||
"The response uses DDIA as mechanism guidance while software-architecture retains the system decision",
|
||||
"Message handling, contracts, data-platform work, and recovery exercises are routed to their specialist owners"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "partition-skew-rebalancing-decision",
|
||||
"prompt": "Design the partitioning approach for a tenant-aware event store where a few tenants and hot keys dominate traffic, ordinary queries sometimes cross partitions, and rebalancing must not silently violate ordering or availability promises.",
|
||||
"expected_output": "A system architecture decision that evaluates partitioning by workload locality and consistency boundaries; covers skew, routing, secondary indexes, rebalancing, and cross-partition operations; and defines a reversible evidence plan. DDIA supplies mechanism principles while data-platform implementation remains with data-architect.",
|
||||
"assertions": [
|
||||
"Partitioning is evaluated by workload locality and consistency boundary rather than node count or convenience",
|
||||
"Tenant or hot-key skew, routing metadata, secondary indexes, rebalancing cost, and cross-partition behavior are addressed",
|
||||
"The proposed option has measurable evidence, failure behavior, and a reversible stop condition",
|
||||
"The response preserves software-architecture, DDIA, data-architect, and implementation ownership boundaries"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "stale-leader-fencing-decision",
|
||||
"prompt": "Design authority and coordination for a replicated scheduler that uses leases. During a network partition, an old leader may continue issuing work after its lease expires. Decide the fencing, quorum, timeout, duplicate-work, and recovery behavior.",
|
||||
"expected_output": "A failure-aware architecture decision that states clock, lease, quorum, and coordination assumptions; treats stale leadership as a concrete fault; uses fencing or equivalent authority validation; and defines duplicate-effect prevention, repair, and exercised recovery evidence.",
|
||||
"assertions": [
|
||||
"Stale-leader authority is treated as a concrete failure rather than assuming lease expiry is sufficient",
|
||||
"Clock, quorum, timeout, lease, coordination-service, and fencing assumptions are explicit",
|
||||
"The design explains how conflicting or duplicate work is prevented, detected, or repaired",
|
||||
"Backend implementation and resilience exercise ownership remain separate from the architecture decision"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "transaction-isolation-invariant-decision",
|
||||
"prompt": "Choose the transaction and isolation behavior for an inventory reservation workflow where two concurrent requests can each observe the final unit under snapshot isolation. State what must remain atomic, what may be asynchronous, and how the decision will be verified.",
|
||||
"expected_output": "An architecture decision that names the inventory invariant and transaction scope, identifies the concurrency anomaly, compares isolation or concurrency-control choices, and defines compensating and verification behavior if weaker isolation remains. DDIA supplies mechanism detail without taking ownership of the system decision.",
|
||||
"assertions": [
|
||||
"The inventory invariant and exact atomicity or transaction boundary are named",
|
||||
"The concurrency anomaly is tied to the isolation choice rather than answered with a blanket default",
|
||||
"Locks, compare-and-set, versioning, serializable behavior, or another explicit control and failure path are evaluated",
|
||||
"The response preserves the architecture decision and API, backend, data-platform, and recovery handoffs"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -4,7 +4,7 @@ This skill is an original, task-centered synthesis. Public sources inform concep
|
||||
|
||||
| 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 |
|
||||
| ISO/IEC/IEEE 42010:2022 overview | Architecture description concerns, stakeholders, viewpoints, and rationale | https://www.iso.org/standard/74393.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 |
|
||||
@@ -13,10 +13,11 @@ This skill is an original, task-centered synthesis. Public sources inform concep
|
||||
| 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 |
|
||||
| `programming-principles` DDIA references | Existing repository mechanism guide loaded by progressive disclosure for replication, partitioning, coordination, ordering, and transaction-isolation questions; system decisions remain here | https://github.com/mattpocock/agent-rules-books |
|
||||
|
||||
## 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.
|
||||
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. The separately attributed `programming-principles` DDIA references are an existing repository dependency loaded only for mechanism detail; this skill links to them without reproducing their text or structure. 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user