AL-JANEF/janef-forge / skills/engineering/architecture-integrity
architecture-integrity
VerifiedDesign or change system structure without breaking invariants: module and domain boundaries, dependency direction, new services, queues, caches, datastores, or frameworks, and lasting trade-offs recorded as ADRs. Use when a change crosses components, introduces a durable boundary, or is hard to reverse.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.7 KB |
| capability.json | config | 2.0 KB |
SKILL.md
View on GitHub---
name: architecture-integrity
description: >-
Design or change system structure without breaking invariants: module and
domain boundaries, dependency direction, new services, queues, caches,
datastores, or frameworks, and lasting trade-offs recorded as ADRs. Use when
a change crosses components, introduces a durable boundary, or is hard to
reverse.
license: MIT
---
# Architecture Integrity
Architecture should reduce the cost of known change, not speculate about every future possibility. Preserve ownership, dependency direction, invariants, and clear boundaries; do not redesign unrelated layers to make a local change look cleaner.
## Decision frame
- Which current and expected use cases must the design serve? Which quality attributes matter here: reliability, security, latency, scale, operability, portability, cost?
- What is the smallest boundary that localizes change without hiding essential behavior?
- Which option is easiest to test, observe, migrate, and remove?
- Start from requirements, trust boundaries, failure modes, deployment constraints, and the existing sources of truth.
## Design rules
- Keep domain policy separate from transport, storage, framework, and vendor adapters.
- Depend toward stable contracts. Avoid circular dependencies, shared mutable authority, duplicated business rules, and cross-domain database ownership.
- Make ownership of data, transactions, retries, timeouts, and cleanup explicit.
- Do not introduce a service, queue, cache, datastore, framework, or abstraction unless the existing architecture cannot meet the requirement cleanly. Prefer boring, existing technology.
- Model failure, recovery, operability, and ownership, not only the happy path. Keep distributed systems no more complex than necessary.
- Design migrations for mixed versions, rollback, and partial failure. Add observability at boundaries where failures would otherwise be ambiguous.
## Record the decision
Write an ADR in the repository's established mechanism when the choice affects multiple components, introduces infrastructure or a dependency, changes a public contract, has meaningful alternatives, or will be costly to reverse. Capture context, decision, alternatives, consequences, migration, and rollback. Do not turn the ADR into a tutorial.
## Verify
Validate the architecture against implementation reality before claiming compliance: imports and dependency direction, ownership of data and transactions, and the actual deployment topology. A diagram that does not match the code is a finding.
## Output
```
## Design: <scope>
Requirements & constraints: ...
Options considered: <A> / <B> — chosen <X> because ...
Boundaries & ownership: ...
Failure & migration model: ...
ADR: <path or "not needed because ...">
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |