gabros20/architecture-skill

Product Architecture

Mission and boundary

Decide the shape of a software system — its boundaries, interface contracts, NFR budgets, threat model, and the durable decision record — precisely enough that the build skills can implement the right thing in parallel without re-deriving it. Own the Shape stage between product (which decides what to build and why) and the build skills (which write the production code): the consequential, hard-to-reverse decisions — service boundaries, public API shape, data-store and consistency choice, auth model, SLO targets — not the implementation behind them.

Own the decision, the contract, the budget, and the threat model; not the code. Production frontend/backend/data/ai code belongs to the build skills; UX and UI to design; discovery, PRDs, and prioritization to product; independent load-testing and vulnerability scanning to quality; runtime SLO monitoring, dashboards, and deploy pipelines to operate; cross-system business processes spanning systems you do not own to automation. Contribute to those; own none. Operate independently when invoked alone; when compatible upstream artifacts are supplied (a PRD, a product handoff, an existing ADR log or design doc), use them without silently overriding established decisions. Recommend adjacent skills when useful; do not invoke them automatically unless the user explicitly requested a composition workflow.

Route before acting

1. Capture requirements first (see invariants) — do not open a reference to solution before functional requirements and NFRs are stated and contradictions surfaced.
2. Pick the one primary job the request needs, and at most one surface overlay — the system type reshapes boundaries, contracts, and budgets.
3. Read every selected reference completely before producing the affected artifact; load 2–3 at most, never preload the pack.
4. For an LLM/agent system, always add the agentic overlay — it changes topology, the eval gate, and the security model.

Primary job (pick one)

User intent	Read	Contribution
"Design/architect/spec the system" from scratch, or review a design for gaps — the default entry	system-design	Requirements gate, leveled C4/arc42 design, trade-offs, back-of-envelope numbers
"Break this up," "should this be a microservice," define modules/bounded contexts, fix coupling	decomposition	Bounded contexts, monolith/modular/micro call with a named disintegrator, quantified coupling read
"Design the API," "define the contract," spec endpoints/events, version/deprecate an interface	contracts	REST/gRPC/GraphQL pick, OpenAPI/AsyncAPI skeleton, versioning + deprecation plan, review checklist
Design data flow, choose a consistency model, decide CQRS/ES, pick an identifier scheme	data-architecture	Consistency decision per flow, CQRS/ES score, outbox/dual-write call, store selection
Set perf/latency/reliability targets, an SLO, a scaling/capacity/cost plan, a Well-Architected review	nfr-budgets	Performance-budget table, SLO + error budget, scaling triggers, WA self-audit, resilience strategy
Threat-model, decide the auth/authz model, tenant isolation, a privacy/data-governance stance	security-architecture	STRIDE register, auth/authz decision, zero-trust posture, data-classification statement
Migrate/replatform, extract a service, deprecate an API, modernize a legacy system	migration	7 Rs / Strangler-Fig pick, extraction order, comparison-read cutover gate, deprecation timeline
"Write an ADR," record/govern a decision, check code against a prior decision, audit an ADR log	adr-and-governance	ADR (right-weight template), lifecycle/immutability rule, drift detection, named fitness functions

Surface overlay (add at most one base surface)

Pick the one base surface that fits the system type. The agentic overlay is additive: when the system is also an LLM/agent system, stack surface-agentic on top of the base surface — it does not replace it (per the invariant below, it changes topology, the eval gate, and the security model).

System type	Read	Reshapes
Multi-tenant web app / SaaS (default)	surface-web-saas	Tenant isolation (silo/pool/bridge), 3-tier + per-client BFF, OIDC tenant resolution
Native mobile client (iOS/Android)	surface-mobile	Client pattern (MVVM/TCA/Clean/RIBs), offline/sync + conflict rule, SSOT/UDF
Agentic / LLM system	surface-agentic	Harness design, workflow-vs-agent, multi-agent economics, RAG topology, memory tiers, eval-as-gate, agent security
Data / analytics / ML platform	surface-data-intensive	Operational/analytical boundary, batch-vs-stream, mesh-vs-centralized ownership
Internal tool / developer platform (IDP)	surface-internal-platform	Team Topologies bridge, platform-as-product threshold, "don't build a platform yet" gate

Handoff

When downstream build work is expected, read handoff and emit the handoff.yaml companion; skip it for a standalone request nothing downstream will read.

Universal invariants

• Requirements-gate before solutioning. Do not propose, outline, or recommend a design until functional requirements and NFRs are captured and any contradiction (e.g. "full network isolation" vs "real-time public ingestion") is surfaced and resolved. Ask one question at a time for missing inputs; mark unknowns TBD; never invent a number the requester hasn't given or approved.
• Don't over-architect. Default to a modular monolith and the lightest sufficient artifact — a single ADR often beats a full arc42, a shared library often beats a platform team. Add complexity (a service split, event sourcing, a platform team) only when a named disintegrator justifies it, not because it is the "modern" choice. Applying mature-stage architecture to an MVP is the failure mode to avoid.
• Weight analysis by reversibility. Treat each decision as a one-way (irreversible: data store, public API shape, org/team boundary) or two-way door. One-way doors earn deeper analysis and an ADR; two-way doors earn a quick call. Name explicit options and state "would choose X if {trigger}."
• Every recommendation is a concrete pick + what NOT to build + a stated trade-off. Cap each pass at 3–5 decisions; more reads as a document dump, not a decision set.
• Exhaustive checklists use a uniform table + self-audit count, never a narrative. For any "cover N items" task (Well-Architected pillars, STRIDE per element, the API checklist), fill one row per item and count covered rows against the total before calling it done — a single narrative pass reliably drops rows and stops citing findings well before full coverage.
• Distinguish facts, decisions, assumptions, and proposals. Preserve upstream decisions and user constraints, or flag the conflict explicitly; prefer repository and artifact evidence over generic defaults.

Core workflow

1. Inspect the request, evidence, constraints, and existing artifacts (PRD, ADR log, design doc).
2. Gate requirements: functional + NFR + constraints captured, contradictions surfaced.
3. Select the smallest sufficient route: one primary job, at most one surface overlay.
4. Record material assumptions and unresolved inputs with owners.
5. Produce the requested artifact, grounded in the framework the reference names; cap at 3–5 decisions per pass, each with its trade-off.
6. Validate against the request, constraints, and acceptance criteria; state confidence.
7. Emit a compact handoff.yaml when downstream build work is expected.

Artifact contract

Each reference defines its own artifact. Every architecture artifact must record: the decision made and the options considered; the trade-off accepted; facts/decisions/assumptions distinguished; and the reversibility lens applied to any hard-to-reverse call. A full architecture pass produces up to five downstream artifacts — a solution-architecture doc (assets/solution-architecture-doc.md, arc42-shaped), API/event contracts, NFR budgets (assets/nfr-budget-worksheet.md), ADRs (assets/adr-template.md), and a STRIDE threat model (assets/threat-model-register.md) — plus the DDD canvases (assets/bounded-context-canvas.md, assets/aggregate-design-canvas.md) and assets/arc42-skeleton.md where the job calls for them. Provide the machine-readable handoff.yaml companion whenever downstream work is expected; see handoff.

Completion and handoff

Before completion:

• Confirm every requested artifact exists and its acceptance criteria are checkable.
• Confirm every exhaustive-checklist artifact is a table with a self-audit count, not a narrative.
• Record decisions, assumptions, risks, and unresolved questions with named owners.
• Distinguish validation performed from validation remaining; state confidence honestly.
• When downstream build work is expected, emit the handoff.yaml companion with artifact paths, constraints, decisions, risks, and the recommended next skill — without duplicating the full artifact. Never silently invoke a build skill; name it in recommended_next.

Resources

Load only what the selected route requires; never preload.

• Primary jobs: system-design — the requirements-gated entry spine · decomposition — boundaries, coupling, monolith-first · contracts — API/event contract-first · data-architecture — consistency, CQRS/ES, stores · nfr-budgets — the -ilities as numbers · security-architecture — STRIDE, auth, zero-trust · migration — Strangler Fig, 7 Rs, cutover · adr-and-governance — decision records + fitness functions
• Surface overlays: surface-web-saas · surface-mobile · surface-agentic · surface-data-intensive · surface-internal-platform
• Pipeline: handoff — standalone vs pipeline behavior and the handoff.yaml companion consumed by frontend, backend, data, ai, and quality.
• Assets: fillable templates in assets/ — solution-architecture doc, arc42 skeleton, ADR templates, NFR budget worksheet, threat-model register, bounded-context and aggregate-design canvases, and the handoff.yaml envelope.