diff options
| -rw-r--r-- | Makefile | 3 | ||||
| -rw-r--r-- | arch-decide/LICENSE | 25 | ||||
| -rw-r--r-- | arch-decide/SKILL.md | 447 | ||||
| -rw-r--r-- | arch-design/SKILL.md | 245 | ||||
| -rw-r--r-- | arch-document/SKILL.md | 313 | ||||
| -rw-r--r-- | arch-evaluate/SKILL.md | 332 | ||||
| -rw-r--r-- | docs/architecture/README.md | 359 | ||||
| -rw-r--r-- | docs/architecture/v2-todo.org | 254 |
8 files changed, 1977 insertions, 1 deletions
@@ -3,7 +3,8 @@ SHELL := /bin/bash SKILLS_DIR := $(HOME)/.claude/skills RULES_DIR := $(HOME)/.claude/rules -SKILLS := c4-analyze c4-diagram debug add-tests respond-to-review review-pr fix-issue security-check +SKILLS := c4-analyze c4-diagram debug add-tests respond-to-review review-pr fix-issue security-check \ + arch-design arch-decide arch-document arch-evaluate RULES := $(wildcard claude-rules/*.md) LANGUAGES := $(notdir $(wildcard languages/*)) diff --git a/arch-decide/LICENSE b/arch-decide/LICENSE new file mode 100644 index 0000000..8a8b38e --- /dev/null +++ b/arch-decide/LICENSE @@ -0,0 +1,25 @@ +MIT License + +Copyright (c) 2024 Seth Hobson + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +Origin: https://github.com/wshobson/agents/blob/main/plugins/documentation-generation/skills/architecture-decision-records/SKILL.md diff --git a/arch-decide/SKILL.md b/arch-decide/SKILL.md new file mode 100644 index 0000000..e0fd05f --- /dev/null +++ b/arch-decide/SKILL.md @@ -0,0 +1,447 @@ +--- +name: arch-decide +description: Create, update, and manage Architecture Decision Records (ADRs) that capture significant technical decisions — context, options, chosen approach, consequences. Five template variants (MADR, Nygard, Y-statement, lightweight, RFC). Covers ADR lifecycle (proposed → accepted → deprecated / superseded), review process, and adr-tools automation. Use when documenting an architectural choice, reviewing past decisions, or establishing a decision process. Part of the arch-* suite (arch-design / arch-decide / arch-document / arch-evaluate). +--- + +# Architecture Decision Records + +Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions. + +## When to Use This Skill + +- Making significant architectural decisions +- Documenting technology choices +- Recording design trade-offs +- Onboarding new team members +- Reviewing historical decisions +- Establishing decision-making processes + +## Core Concepts + +### 1. What is an ADR? + +An Architecture Decision Record captures: + +- **Context**: Why we needed to make a decision +- **Decision**: What we decided +- **Consequences**: What happens as a result + +### 2. When to Write an ADR + +| Write ADR | Skip ADR | +| -------------------------- | ---------------------- | +| New framework adoption | Minor version upgrades | +| Database technology choice | Bug fixes | +| API design patterns | Implementation details | +| Security architecture | Routine maintenance | +| Integration patterns | Configuration changes | + +### 3. ADR Lifecycle + +``` +Proposed → Accepted → Deprecated → Superseded + ↓ + Rejected +``` + +## Templates + +### Template 1: Standard ADR (MADR Format) + +```markdown +# ADR-0001: Use PostgreSQL as Primary Database + +## Status + +Accepted + +## Context + +We need to select a primary database for our new e-commerce platform. The system +will handle: + +- ~10,000 concurrent users +- Complex product catalog with hierarchical categories +- Transaction processing for orders and payments +- Full-text search for products +- Geospatial queries for store locator + +The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID +compliance for financial transactions. + +## Decision Drivers + +- **Must have ACID compliance** for payment processing +- **Must support complex queries** for reporting +- **Should support full-text search** to reduce infrastructure complexity +- **Should have good JSON support** for flexible product attributes +- **Team familiarity** reduces onboarding time + +## Considered Options + +### Option 1: PostgreSQL + +- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text + search, PostGIS for geospatial, team has experience +- **Cons**: Slightly more complex replication setup than MySQL + +### Option 2: MySQL + +- **Pros**: Very familiar to team, simple replication, large community +- **Cons**: Weaker JSON support, no built-in full-text search (need + Elasticsearch), no geospatial without extensions + +### Option 3: MongoDB + +- **Pros**: Flexible schema, native JSON, horizontal scaling +- **Cons**: No ACID for multi-document transactions (at decision time), + team has limited experience, requires schema design discipline + +## Decision + +We will use **PostgreSQL 15** as our primary database. + +## Rationale + +PostgreSQL provides the best balance of: + +1. **ACID compliance** essential for e-commerce transactions +2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce + infrastructure complexity +3. **Team familiarity** with SQL databases reduces learning curve +4. **Mature ecosystem** with excellent tooling and community support + +The slight complexity in replication is outweighed by the reduction in +additional services (no separate Elasticsearch needed). + +## Consequences + +### Positive + +- Single database handles transactions, search, and geospatial queries +- Reduced operational complexity (fewer services to manage) +- Strong consistency guarantees for financial data +- Team can leverage existing SQL expertise + +### Negative + +- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax) +- Vertical scaling limits may require read replicas sooner +- Some team members need PostgreSQL-specific training + +### Risks + +- Full-text search may not scale as well as dedicated search engines +- Mitigation: Design for potential Elasticsearch addition if needed + +## Implementation Notes + +- Use JSONB for flexible product attributes +- Implement connection pooling with PgBouncer +- Set up streaming replication for read replicas +- Use pg_trgm extension for fuzzy search + +## Related Decisions + +- ADR-0002: Caching Strategy (Redis) - complements database choice +- ADR-0005: Search Architecture - may supersede if Elasticsearch needed + +## References + +- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html) +- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html) +- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md` +``` + +### Template 2: Lightweight ADR + +```markdown +# ADR-0012: Adopt TypeScript for Frontend Development + +**Status**: Accepted +**Date**: 2024-01-15 +**Deciders**: @alice, @bob, @charlie + +## Context + +Our React codebase has grown to 50+ components with increasing bug reports +related to prop type mismatches and undefined errors. PropTypes provide +runtime-only checking. + +## Decision + +Adopt TypeScript for all new frontend code. Migrate existing code incrementally. + +## Consequences + +**Good**: Catch type errors at compile time, better IDE support, self-documenting +code. + +**Bad**: Learning curve for team, initial slowdown, build complexity increase. + +**Mitigations**: TypeScript training sessions, allow gradual adoption with +`allowJs: true`. +``` + +### Template 3: Y-Statement Format + +```markdown +# ADR-0015: API Gateway Selection + +In the context of **building a microservices architecture**, +facing **the need for centralized API management, authentication, and rate limiting**, +we decided for **Kong Gateway** +and against **AWS API Gateway and custom Nginx solution**, +to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**, +accepting that **we need to manage Kong infrastructure ourselves**. +``` + +### Template 4: ADR for Deprecation + +```markdown +# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL + +## Status + +Accepted (Supersedes ADR-0003) + +## Context + +ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility +needs. Since then: + +- MongoDB's multi-document transactions remain problematic for our use case +- Our schema has stabilized and rarely changes +- We now have PostgreSQL expertise from other services +- Maintaining two databases increases operational burden + +## Decision + +Deprecate MongoDB and migrate user profiles to PostgreSQL. + +## Migration Plan + +1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled +2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency +3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor +4. **Phase 4** (Week 6): Remove MongoDB writes, decommission + +## Consequences + +### Positive + +- Single database technology reduces operational complexity +- ACID transactions for user data +- Team can focus PostgreSQL expertise + +### Negative + +- Migration effort (~4 weeks) +- Risk of data issues during migration +- Lose some schema flexibility + +## Lessons Learned + +Document from ADR-0003 experience: + +- Schema flexibility benefits were overestimated +- Operational cost of multiple databases was underestimated +- Consider long-term maintenance in technology decisions +``` + +### Template 5: Request for Comments (RFC) Style + +```markdown +# RFC-0025: Adopt Event Sourcing for Order Management + +## Summary + +Propose adopting event sourcing pattern for the order management domain to +improve auditability, enable temporal queries, and support business analytics. + +## Motivation + +Current challenges: + +1. Audit requirements need complete order history +2. "What was the order state at time X?" queries are impossible +3. Analytics team needs event stream for real-time dashboards +4. Order state reconstruction for customer support is manual + +## Detailed Design + +### Event Store + +``` +OrderCreated { orderId, customerId, items[], timestamp } +OrderItemAdded { orderId, item, timestamp } +OrderItemRemoved { orderId, itemId, timestamp } +PaymentReceived { orderId, amount, paymentId, timestamp } +OrderShipped { orderId, trackingNumber, timestamp } +``` + +### Projections + +- **CurrentOrderState**: Materialized view for queries +- **OrderHistory**: Complete timeline for audit +- **DailyOrderMetrics**: Analytics aggregation + +### Technology + +- Event Store: EventStoreDB (purpose-built, handles projections) +- Alternative considered: Kafka + custom projection service + +## Drawbacks + +- Learning curve for team +- Increased complexity vs. CRUD +- Need to design events carefully (immutable once stored) +- Storage growth (events never deleted) + +## Alternatives + +1. **Audit tables**: Simpler but doesn't enable temporal queries +2. **CDC from existing DB**: Complex, doesn't change data model +3. **Hybrid**: Event source only for order state changes + +## Unresolved Questions + +- [ ] Event schema versioning strategy +- [ ] Retention policy for events +- [ ] Snapshot frequency for performance + +## Implementation Plan + +1. Prototype with single order type (2 weeks) +2. Team training on event sourcing (1 week) +3. Full implementation and migration (4 weeks) +4. Monitoring and optimization (ongoing) + +## References + +- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html) +- [EventStoreDB Documentation](https://www.eventstore.com/docs) +``` + +## ADR Management + +### Directory Structure + +``` +docs/ +├── adr/ +│ ├── README.md # Index and guidelines +│ ├── template.md # Team's ADR template +│ ├── 0001-use-postgresql.md +│ ├── 0002-caching-strategy.md +│ ├── 0003-mongodb-user-profiles.md # [DEPRECATED] +│ └── 0020-deprecate-mongodb.md # Supersedes 0003 +``` + +### ADR Index (README.md) + +```markdown +# Architecture Decision Records + +This directory contains Architecture Decision Records (ADRs) for [Project Name]. + +## Index + +| ADR | Title | Status | Date | +| ------------------------------------- | ---------------------------------- | ---------- | ---------- | +| [0001](0001-use-postgresql.md) | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 | +| [0002](0002-caching-strategy.md) | Caching Strategy with Redis | Accepted | 2024-01-12 | +| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles | Deprecated | 2023-06-15 | +| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 | + +## Creating a New ADR + +1. Copy `template.md` to `NNNN-title-with-dashes.md` +2. Fill in the template +3. Submit PR for review +4. Update this index after approval + +## ADR Status + +- **Proposed**: Under discussion +- **Accepted**: Decision made, implementing +- **Deprecated**: No longer relevant +- **Superseded**: Replaced by another ADR +- **Rejected**: Considered but not adopted +``` + +### Automation (adr-tools) + +```bash +# Install adr-tools +brew install adr-tools + +# Initialize ADR directory +adr init docs/adr + +# Create new ADR +adr new "Use PostgreSQL as Primary Database" + +# Supersede an ADR +adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL" + +# Generate table of contents +adr generate toc > docs/adr/README.md + +# Link related ADRs +adr link 2 "Complements" 1 "Is complemented by" +``` + +## Review Process + +```markdown +## ADR Review Checklist + +### Before Submission + +- [ ] Context clearly explains the problem +- [ ] All viable options considered +- [ ] Pros/cons balanced and honest +- [ ] Consequences (positive and negative) documented +- [ ] Related ADRs linked + +### During Review + +- [ ] At least 2 senior engineers reviewed +- [ ] Affected teams consulted +- [ ] Security implications considered +- [ ] Cost implications documented +- [ ] Reversibility assessed + +### After Acceptance + +- [ ] ADR index updated +- [ ] Team notified +- [ ] Implementation tickets created +- [ ] Related documentation updated +``` + +## Best Practices + +### Do's + +- **Write ADRs early** - Before implementation starts +- **Keep them short** - 1-2 pages maximum +- **Be honest about trade-offs** - Include real cons +- **Link related decisions** - Build decision graph +- **Update status** - Deprecate when superseded + +### Don'ts + +- **Don't change accepted ADRs** - Write new ones to supersede +- **Don't skip context** - Future readers need background +- **Don't hide failures** - Rejected decisions are valuable +- **Don't be vague** - Specific decisions, specific consequences +- **Don't forget implementation** - ADR without action is waste + +--- + +## Attribution + +Forked from [wshobson/agents](https://github.com/wshobson/agents) — MIT licensed. +See `LICENSE` in this directory for the original copyright and terms. diff --git a/arch-design/SKILL.md b/arch-design/SKILL.md new file mode 100644 index 0000000..d1381e3 --- /dev/null +++ b/arch-design/SKILL.md @@ -0,0 +1,245 @@ +--- +name: arch-design +description: Shape the architecture of a new or restructured software project through structured intake (quality attributes, stakeholders, constraints, scale, change drivers), then propose candidate architectural paradigms with honest trade-off analysis and a recommended direction. Paradigm-agnostic — evaluates options across layered, hexagonal, microservices, event-driven, CQRS, modular-monolith, serverless, pipe-and-filter, DDD, and others. Outputs a brief at `.architecture/brief.md` that downstream skills (arch-decide, arch-document, arch-evaluate) read. Use when starting a new project or service, restructuring an existing one, choosing a tech stack, or formalizing architecture before implementation. Do NOT use for bug fixing, code review, small feature additions, documenting an existing architecture (use arch-document), evaluating an existing architecture against a brief (use arch-evaluate), or recording specific individual decisions (use arch-decide). Part of the arch-* suite (arch-design / arch-decide / arch-document / arch-evaluate). +--- + +# Architecture Design + +Elicit the problem, surface the real drivers, propose a fit, and commit it to writing. One working session yields a `.architecture/brief.md` that anchors every downstream architectural decision. + +## When to Use This Skill + +- Starting a new project, service, or major subsystem +- Restructuring or re-platforming an existing system +- Selecting a primary tech stack for a green-field effort +- Establishing a formal architecture before a team scales +- Preparing a spike or prototype you want to keep coherent + +## When NOT to Use This Skill + +- Bug fixing or defect investigation +- Small feature additions inside an existing architecture +- Recording a single decision (use `arch-decide`) +- Producing formal documentation from a known architecture (use `arch-document`) +- Auditing an existing codebase against its stated architecture (use `arch-evaluate`) + +## Workflow + +The skill runs in five phases. Each produces a section of the output brief. Do not skip phases — the trade-off analysis is only as good as the intake. + +1. **Intake** — elicit stakeholders, domain, scale, timeline, team +2. **Quality attributes** — prioritize (can't have everything) +3. **Constraints** — technical, organizational, legal, cost +4. **Candidate paradigms** — shortlist 2-4 with honest trade-off analysis +5. **Recommendation** — pick one, justify it, flag open questions for ADRs + +## Phase 1 — Intake + +Ask the user to answer each. Short answers are fine; vague answers mean return to the question. + +**System identity** +- What is this system? (One sentence.) +- Who uses it? Human end users, other services, both? +- What domain is it in? (commerce, health, comms, finance, ops, etc.) + +**Scale** +- Expected traffic at launch and in 12 months? (RPS, MAU, payload sizes) +- Data volume at launch and in 12 months? (rows/docs, GB) +- Geographic distribution? (single region, multi-region, edge) + +**Team** +- Team size now? Growing? +- Existing language/stack expertise? +- Operational maturity? (on-call rotation, observability tooling, CI/CD) + +**Timeline** +- When does it need to be in production? +- Is this replacing something? What's the migration path? + +**Change drivers** +- What forces are likely to reshape this system? (new markets, regulatory, volume, organizational) + +## Phase 2 — Quality Attributes + +List the relevant quality attributes and force the user to rank them 1-5 (1 = critical, 5 = nice-to-have). You can't optimize everything; the ranking surfaces real priorities. + +Standard list (use this set; add domain-specific ones if relevant): + +- **Performance** (latency, throughput under load) +- **Scalability** (horizontal, vertical, elastic) +- **Availability** (uptime target, failure tolerance) +- **Reliability** (data durability, correctness under partial failure) +- **Security** (authn/z, data protection, threat model) +- **Maintainability** (readability, testability, onboarding speed) +- **Observability** (logs, metrics, tracing, debuggability) +- **Deployability** (release cadence, rollback speed) +- **Cost** (infra, operational, total cost of ownership) +- **Compliance** (regulatory, audit, data residency) +- **Interoperability** (integration with existing systems, APIs, standards) +- **Flexibility / evolvability** (ease of adding features, changing direction) + +Document the ranking verbatim in the brief. Future decisions hinge on it. + +## Phase 3 — Constraints + +Enumerate what's fixed. Each constraint narrows the design space — make them explicit so trade-offs don't hide. + +- **Technical**: existing infrastructure, mandated languages/platforms, integration points that can't move +- **Organizational**: team structure (Conway's Law — the org shape becomes the arch shape), existing expertise, hiring plan +- **Legal/regulatory**: GDPR, HIPAA, FedRAMP, data residency, audit retention +- **Cost**: budget ceiling, licensing limits, infra cost targets +- **Timeline**: hard dates from business, regulatory deadlines +- **Compatibility**: backward-compatibility with existing clients, API contracts, data formats + +## Phase 4 — Candidate Paradigms + +Pick 2-4 candidates that plausibly fit the quality-attribute ranking and constraints. Analyze each honestly — include the reasons it would fail, not just succeed. + +Common paradigms to consider: + +| Paradigm | Fits when… | Doesn't fit when… | +|---|---|---| +| **Modular monolith** | Small team, fast iteration, strong module boundaries, single deployment OK | Independent team scaling, different availability SLAs per module, polyglot requirements | +| **Microservices** | Multiple teams, independent deploy cadences, polyglot, different scaling needs | Small team, tight transactional consistency needs, low operational maturity | +| **Layered (n-tier)** | CRUD-heavy, clear request/response, team familiar with MVC | Complex domain logic, event-driven needs, async workflows dominate | +| **Hexagonal / Ports & Adapters** | Business logic isolation, multiple interface types (HTTP + CLI + queue), testability priority | Trivial domains, overhead outweighs benefit | +| **Event-driven / pub-sub** | Async workflows, fan-out to multiple consumers, decoupled evolution | Strong ordering + consistency needs, small team, low operational maturity | +| **CQRS** | Read/write workload asymmetry, different optimization needs, audit trail required | Simple CRUD, no asymmetry, overhead not justified | +| **Event sourcing** | Audit trail critical, temporal queries needed, reconstruction from events valuable | Simple state, team lacks event-sourcing expertise, storage cost prohibitive | +| **Serverless (FaaS)** | Event-driven + variable load + fast iteration + accept vendor lock-in | Steady high load, latency-sensitive, long-running processes, tight cost control | +| **Pipe-and-filter / pipeline** | Data transformation workflows, ETL, stream processing | Interactive request/response, low-latency | +| **Space-based / in-memory grid** | Extreme throughput, elastic scale, in-memory OK | Strong durability required from day one, small scale | +| **DDD (tactical)** | Complex domain, domain experts available, long-lived system | Simple CRUD, no real domain complexity, short-lived system | + +For each candidate, document: + +- **Summary** — one paragraph on what the architecture would look like +- **Why it fits** — map to the ranked quality attributes +- **Why it might not** — the honest cons for this specific context +- **Cost** — team learning curve, operational overhead, infra impact +- **Open questions** — what would need to be answered or decided via ADR + +## Phase 5 — Recommendation + +Choose one paradigm. Justify it by: + +- Which top-3 quality attributes the choice serves +- Which constraints it respects +- Why the rejected alternatives were rejected (not just "we picked X"; say why *not* Y) +- What you're trading away (be explicit) + +Flag items that need their own ADRs — use `arch-decide` to record them. Examples: + +- Primary database choice +- Message bus vs. direct calls +- Sync vs. async inter-service comms +- Multi-tenancy approach +- Authentication/authorization boundary + +## Output: `.architecture/brief.md` + +Write the final brief to `.architecture/brief.md` in the project root. Use this structure: + +```markdown +# Architecture Brief — <Project Name> + +**Date:** <YYYY-MM-DD> +**Authors:** <names> +**Status:** Draft | Accepted | Revised + +## 1. System + +<One-paragraph description of what the system does.> + +## 2. Stakeholders and Users + +- **Primary users:** … +- **Secondary users:** … +- **Operators:** … +- **Integrators / dependent systems:** … + +## 3. Scale Targets + +| Metric | Launch | +12 months | +|---|---|---| +| RPS | … | … | +| Data volume | … | … | +| Geographic spread | … | … | + +## 4. Quality Attributes (Prioritized) + +| Rank | Attribute | Notes | +|---|---|---| +| 1 | … | critical driver | +| 2 | … | … | + +## 5. Constraints + +- **Technical:** … +- **Organizational:** … +- **Legal/Regulatory:** … +- **Cost:** … +- **Timeline:** … + +## 6. Candidates Considered + +### Candidate A — <paradigm> + +Summary. Fit. Cons. Cost. Open questions. + +### Candidate B — <paradigm> + +… + +## 7. Recommendation + +**Chosen paradigm:** … + +**Rationale:** +- … + +**Trade-offs accepted:** +- … + +**Rejected alternatives and why:** +- … + +## 8. Open Decisions (Candidates for ADRs) + +- [ ] Primary database — driver: … +- [ ] … + +## 9. Next Steps + +- Run `arch-decide` for each open decision above +- Run `arch-document` to produce the full arc42 document +- Run `arch-evaluate` once implementation begins to audit conformance +``` + +## Review Checklist + +Before marking the brief Accepted: + +- [ ] Every quality attribute is ranked; no "all critical" +- [ ] Every constraint is explicit; no "we probably can't" +- [ ] At least 2 candidates considered; each has real cons +- [ ] Recommendation names what it's trading away +- [ ] Open decisions listed; each will become an ADR via `arch-decide` +- [ ] Stakeholders have seen and (ideally) approved + +## Anti-Patterns + +- **"All quality attributes are critical."** They aren't. Force ranking. +- **"Let's go microservices."** Without a ranking, constraints, and team context, that's cargo-culting. +- **Single candidate.** One option means the user already decided; you're documenting, not designing. +- **Silent trade-offs.** If you choose availability, you're trading latency or cost. Say so. +- **No open decisions.** A real architecture has open questions. Listing none means you haven't looked hard. +- **"Design doc" with no implementation implications.** The brief must be actionable — it drives ADRs, documentation, and evaluation. + +## Hand-Off + +After the brief is Accepted: + +- `arch-decide` — record each Open Decision as an ADR under `docs/adr/` +- `arch-document` — expand into a full arc42-structured document under `docs/architecture/` with C4 diagrams +- `arch-evaluate` — once code exists, audit it against this brief diff --git a/arch-document/SKILL.md b/arch-document/SKILL.md new file mode 100644 index 0000000..fa3e798 --- /dev/null +++ b/arch-document/SKILL.md @@ -0,0 +1,313 @@ +--- +name: arch-document +description: Produce a complete arc42-structured architecture document from a project's architecture brief and ADRs. Generates all twelve arc42 sections (Introduction & Goals, Constraints, Context & Scope, Solution Strategy, Building Block View, Runtime View, Deployment View, Crosscutting Concepts, Architecture Decisions, Quality Requirements, Risks & Technical Debt, Glossary). Dispatches to the c4-analyze and c4-diagram skills for building-block, container, and context diagrams. Outputs one file per section under `docs/architecture/`. Use when formalizing an architecture that already has a brief + ADRs, preparing documentation for a review, onboarding new engineers, or satisfying a compliance requirement. Do NOT use for shaping a new architecture (use arch-design), recording individual decisions (use arch-decide), auditing code against an architecture (use arch-evaluate), or for simple systems where a brief alone suffices. Part of the arch-* suite (arch-design / arch-decide / arch-document / arch-evaluate). +--- + +# Architecture Documentation (arc42) + +Turn an architecture brief and a set of ADRs into a full arc42-structured document. The result is the authoritative reference for the system — engineers, auditors, and new hires read this to understand what exists and why. + +## When to Use This Skill + +- A project has completed `arch-design` and has a `.architecture/brief.md` +- Open decisions from the brief have been answered via `arch-decide` (ADRs) +- The team needs documentation suitable for review, onboarding, or compliance +- An existing system needs retroactive architecture docs + +## When NOT to Use This Skill + +- Before a brief exists (run `arch-design` first) +- For small systems where a brief alone is sufficient (don't over-document) +- To record a single decision (use `arch-decide`) +- To audit code (use `arch-evaluate`) +- When the team doesn't need arc42 — a lighter structure may serve better + +## Inputs + +Expected files, in order of preference: + +1. `.architecture/brief.md` — output of `arch-design` +2. `docs/adr/*.md` — ADRs from `arch-decide` +3. Codebase (for inferring module structure, dispatched to `c4-analyze`) +4. Existing `docs/architecture/` contents (if updating rather than creating) + +If `.architecture/brief.md` is absent, stop and tell the user to run `arch-design` first. Do not fabricate the brief. + +## Workflow + +1. **Load and validate inputs** — brief present? ADRs found? Any existing arc42 docs? +2. **Plan section coverage** — which of the twelve sections need content from the brief, ADRs, code, or user? +3. **Generate each section** — draft from available inputs; explicitly mark gaps +4. **Dispatch to C4 skills** — for sections needing diagrams (Context & Scope, Building Block View, Runtime View, Deployment View) +5. **Cross-link** — ensure every ADR is referenced; every diagram has a narrative +6. **Output** — one file per section under `docs/architecture/`, plus an index + +## The Twelve arc42 Sections + +For each: what it's for, what goes in it, where the content comes from, and what to dispatch. + +### 1. Introduction and Goals → `01-introduction.md` + +**Purpose:** Why does this system exist? What are the top business goals? + +**Content:** +- One-paragraph system description (from brief §1) +- Top 3-5 business goals (from brief §1-2) +- Top 3 stakeholders and their concerns (from brief §2) +- Top 3 quality goals (from brief §4, pulling the top-ranked attributes) + +**Sources:** brief §1, §2, §4. + +### 2. Architecture Constraints → `02-constraints.md` + +**Purpose:** What's non-negotiable? What narrows the solution space? + +**Content:** +- Technical constraints (stack mandates, integration points) +- Organizational constraints (team, expertise, timeline) +- Conventions (style guides, naming, review process) +- Legal/regulatory/compliance + +**Sources:** brief §5. Expand with any inherited constraints not in the brief. + +### 3. Context and Scope → `03-context.md` + +**Purpose:** What's inside the system? What's outside? What are the boundaries? + +**Content:** +- **Business context:** external users, upstream/downstream systems, human actors. One diagram. +- **Technical context:** protocols, data formats, deployment boundaries. One diagram or table. + +**Dispatch:** call the `c4-diagram` skill with a C4 System Context diagram request. Pass the brief's §1-2 (system identity + stakeholders) + integration points from §5 constraints. + +### 4. Solution Strategy → `04-solution-strategy.md` + +**Purpose:** The fundamental decisions that shape everything else. + +**Content:** +- Primary architectural paradigm (from brief §7, the recommendation) +- Top-level technology decisions (link to ADRs) +- Decomposition strategy (how the system breaks into modules/services) +- Approach to the top 3 quality goals (one sentence each: how does the strategy achieve performance / availability / security / whatever ranked highest) + +**Sources:** brief §7, ADRs. + +### 5. Building Block View → `05-building-blocks.md` + +**Purpose:** Static decomposition. Layer-by-layer breakdown. + +**Content:** +- **Level 1** (whiteboard view): the handful of major components +- **Level 2** (for significant components): internal structure +- For each component: responsibility, key interfaces, dependencies, quality properties + +**Dispatch:** call `c4-analyze` on the codebase if code exists; it produces Container and Component diagrams. Embed those diagrams + narrative here. If no code exists, call `c4-diagram` with the decomposition from brief §7. + +### 6. Runtime View → `06-runtime.md` + +**Purpose:** Dynamic behavior. The interesting interactions. + +**Content:** 3-5 scenarios that matter (not every flow — the ones that illustrate key architecture). Each scenario: +- What triggers it +- Which components participate +- Data flow +- Error handling / failure modes + +**Dispatch:** sequence diagrams via `c4-diagram`. One per scenario. + +### 7. Deployment View → `07-deployment.md` + +**Purpose:** Where does the system run? How is it packaged? + +**Content:** +- Deployment environments (dev, staging, prod; regions; edge) +- Infrastructure topology (VMs, containers, serverless, managed services) +- Allocation of building blocks to infrastructure +- Network boundaries, data flow across them + +**Dispatch:** deployment diagram via `c4-diagram`. + +### 8. Crosscutting Concepts → `08-crosscutting.md` + +**Purpose:** Concerns that span the system — not owned by one module. + +**Content:** one subsection per concept. Typical concepts: +- Security (authn/z, data protection, secrets management) +- Error handling (retries, circuit breakers, dead-letter queues) +- Logging, metrics, tracing +- Configuration and feature flags +- Persistence patterns (ORM? repository? direct SQL?) +- Concurrency model +- Caching strategy +- Internationalization +- Testability approach + +Only include concepts that are actually crosscutting in *this* system. If error handling is owned by one service, it's not crosscutting. + +### 9. Architecture Decisions → `09-decisions.md` + +**Purpose:** Index of the significant decisions. Not the ADRs themselves — a curated summary. + +**Content:** a table linking out to every ADR in `docs/adr/`: + +| ADR | Decision | Status | Date | +|---|---|---|---| +| [0001](../adr/0001-database.md) | Primary database: PostgreSQL | Accepted | 2024-01-10 | + +Plus a one-sentence summary of *why this set of decisions, not others*. The meta-rationale. + +**Sources:** `docs/adr/*.md`. Auto-generate the table from the filesystem; update on each run. + +### 10. Quality Requirements → `10-quality.md` + +**Purpose:** Measurable quality targets. Not "the system should be fast" — specific scenarios. + +**Content:** +- **Quality tree** — the ranked quality attributes from brief §4, each with refinements +- **Quality scenarios** — specific, testable. Format: "Under [condition], the system should [response] within [measure]." + +Example: + +> Under peak traffic (10,000 concurrent users), a cart checkout should complete in under 2 seconds at the 95th percentile. + +Minimum 1 scenario per top-3 quality attribute. + +**Sources:** brief §4, §7 (rationale). + +### 11. Risks and Technical Debt → `11-risks.md` + +**Purpose:** Known risks and liabilities. A snapshot of what could go wrong. + +**Content:** + +| Risk / Debt | Impact | Likelihood | Mitigation / Plan | +|---|---|---|---| +| Single DB becomes bottleneck at 50k RPS | High | Medium (12mo) | Add read replicas; monitor query latency | + +Plus a short narrative on known technical debt, what caused it, and when it'll be addressed. + +**Sources:** brief §7 (trade-offs accepted), team knowledge. Refresh regularly. + +### 12. Glossary → `12-glossary.md` + +**Purpose:** Shared vocabulary. Terms, acronyms, and domain-specific words with agreed definitions. + +**Content:** table, alphabetical. + +| Term | Definition | +|---|---| +| Cart | A customer's in-progress selection of items before checkout. | +| Order | A confirmed, paid transaction resulting from a checked-out cart. | + +Keep disciplined: when two people use the same word differently, the glossary is where the disagreement surfaces. + +## Output Layout + +``` +docs/architecture/ +├── README.md # Index; generated from the 12 sections +├── 01-introduction.md +├── 02-constraints.md +├── 03-context.md +├── 04-solution-strategy.md +├── 05-building-blocks.md +├── 06-runtime.md +├── 07-deployment.md +├── 08-crosscutting.md +├── 09-decisions.md +├── 10-quality.md +├── 11-risks.md +├── 12-glossary.md +└── diagrams/ # C4 outputs land here + ├── context.svg + ├── container.svg + ├── component-<module>.svg + └── runtime-<scenario>.svg +``` + +### README.md (auto-generated index) + +```markdown +# Architecture Documentation — <Project Name> + +arc42-structured documentation. Read top to bottom for context; skip to a +specific section via the index. + +## Sections + +1. [Introduction and Goals](01-introduction.md) +2. [Architecture Constraints](02-constraints.md) +3. [Context and Scope](03-context.md) +4. [Solution Strategy](04-solution-strategy.md) +5. [Building Block View](05-building-blocks.md) +6. [Runtime View](06-runtime.md) +7. [Deployment View](07-deployment.md) +8. [Crosscutting Concepts](08-crosscutting.md) +9. [Architecture Decisions](09-decisions.md) +10. [Quality Requirements](10-quality.md) +11. [Risks and Technical Debt](11-risks.md) +12. [Glossary](12-glossary.md) + +## Source Documents + +- Brief: [`.architecture/brief.md`](../../.architecture/brief.md) +- Decisions: [`../adr/`](../adr/) + +## Last Updated + +<YYYY-MM-DD> — regenerate by running `arch-document` after brief or ADR changes. +``` + +## Dispatch to C4 Skills + +Several sections need diagrams. The `arch-document` skill does not generate diagrams directly; it dispatches: + +- **Section 3 (Context and Scope)** → `c4-diagram` for a System Context diagram. Input: system name, external actors, external systems. +- **Section 5 (Building Block View)** → `c4-analyze` if the codebase exists (it infers Container + Component diagrams). Otherwise `c4-diagram` with decomposition from brief. +- **Section 6 (Runtime View)** → `c4-diagram` for sequence diagrams, one per scenario. +- **Section 7 (Deployment View)** → `c4-diagram` for a deployment diagram. + +When dispatching, include: the relevant section narrative + the specific diagram type + any identifiers needed. Capture outputs in `docs/architecture/diagrams/` and embed via relative markdown image links. + +## Gap Handling + +If information is missing for a section: + +- **Brief gap:** stop and ask the user, or mark the section `TODO: resolve with arch-design` +- **ADR gap:** stub the section with a `TODO: run arch-decide for <decision>` and proceed +- **Code gap:** if dispatching to c4-analyze fails (no code yet), fall back to c4-diagram with brief-derived decomposition + +Never fabricate content. A `TODO` is honest; a plausible-sounding but made-up detail is misleading. + +## Review Checklist + +Before marking the documentation complete: + +- [ ] Every section has either real content or an explicit TODO +- [ ] Every ADR is referenced in section 9 +- [ ] Diagrams are present for sections 3, 5, 6, 7 +- [ ] Quality scenarios (§10) are specific and measurable +- [ ] Risks (§11) include likelihood and mitigation +- [ ] Glossary (§12) captures domain terms, not just jargon +- [ ] README index lists all sections with correct relative links + +## Anti-Patterns + +- **Template filling without thought.** Copying section headings but making up the content. If you don't have the data, mark TODO. +- **Diagrams without narrative.** A diagram in isolation tells half the story. Each diagram needs a paragraph saying what to notice. +- **Every concept as crosscutting.** If security is owned by one service, it's not crosscutting — put it in that service's building-block entry. +- **Uncurated ADR dump.** Section 9 should be a curated index with the *reason* these decisions hang together, not just a directory listing. +- **Vague quality requirements.** "The system should be fast" is useless. Specify scenarios with measurable bounds. +- **Risk-free architecture.** Every real system has risks. A blank risks section means you didn't look. + +## Maintenance + +arc42 is a living document. Re-run `arch-document` when: + +- A new ADR is added → section 9 refreshes +- The brief is revised → sections 1, 4, 10 may change +- The codebase restructures → section 5 (via re-running c4-analyze) +- A new deployment target is added → section 7 +- A scenario's behavior or SLO changes → section 6 or 10 + +Commit each regeneration. The document's Git history is part of the architecture record. diff --git a/arch-evaluate/SKILL.md b/arch-evaluate/SKILL.md new file mode 100644 index 0000000..cc43779 --- /dev/null +++ b/arch-evaluate/SKILL.md @@ -0,0 +1,332 @@ +--- +name: arch-evaluate +description: Audit an existing codebase against its stated architecture brief and ADRs. Runs framework-agnostic checks (cyclic dependencies, stated-layer violations, public API drift) that work on any language without setup, and opportunistically invokes language-specific linters (dependency-cruiser for TypeScript, import-linter for Python, go vet + depguard for Go) when they're already configured in the repo — augmenting findings, never replacing. Produces a report with severity levels (error / warning / info) and pointers to the relevant brief section or ADR for each violation. Use when auditing conformance before a release, during code review, when an architecture is suspected to have drifted, or as a pre-merge CI gate. Do NOT use for designing an architecture (use arch-design), recording decisions (use arch-decide), or producing documentation (use arch-document). Part of the arch-* suite (arch-design / arch-decide / arch-document / arch-evaluate). +--- + +# Architecture Evaluation + +Audit an implementation against its stated architecture. Framework-agnostic by default; augmented by language-specific linters when they're configured in the repo. Reports violations with severity and the rule they break. + +## When to Use This Skill + +- Auditing a codebase before a major release +- During code review of a structurally significant change +- When architecture is suspected to have drifted from its documented intent +- As a pre-merge check (output can feed CI) +- Before an architecture review meeting + +## When NOT to Use This Skill + +- No brief or ADRs exist (run `arch-design` and `arch-decide` first) +- Shaping a new architecture (use `arch-design`) +- Recording a single decision (use `arch-decide`) +- Generating documentation (use `arch-document`) +- Deep code-quality review (this skill checks *structural* conformance, not line-level quality — use a code review skill for that) + +## Inputs + +1. `.architecture/brief.md` — the source of truth for paradigm, layers, quality attributes +2. `docs/adr/*.md` — specific decisions that the code must honor +3. `docs/architecture/*.md` — if present, used for additional structural context +4. The codebase itself + +If the brief is missing, stop and tell the user to run `arch-design` first. Do not guess at intent. + +## Workflow + +1. **Load the brief and ADRs.** Extract: declared paradigm, layers (if any), forbidden dependencies, module boundaries, API contracts that matter. +2. **Detect repo languages and linters.** Inspect `package.json`, `pyproject.toml`, `go.mod`, `pom.xml`, etc. +3. **Run framework-agnostic checks.** Always. These never need tooling. +4. **Run language-specific tools if configured.** Opportunistic — only if the repo already has `.dependency-cruiser.cjs`, `.importlinter`, `.golangci.yml` with import rules, etc. Never install tooling. +5. **Combine findings.** Deduplicate across sources. Label each finding with provenance (native / tool). +6. **Produce report.** Severity-sorted markdown at `.architecture/evaluation-<date>.md`. + +## Framework-Agnostic Checks + +These work on any language. Claude reads the code and applies the policy from the brief. + +### 1. Cyclic Dependencies + +Scan imports/requires/includes across the codebase. Build the module graph. Report any cycles. + +**Severity:** Error (cycles are almost always architecture bugs). + +**Scale limit:** for codebases over ~100k lines, this check is noisy — prefer the language-specific tool output (much faster and complete). + +### 2. Stated-Layer Violations + +If the brief declares layers (e.g., `presentation → application → domain → infrastructure`), scan imports for arrows that go the wrong way. + +**Policy format in the brief:** + +``` +Layers (outer → inner): + presentation → application → domain + presentation → application → infrastructure + application → infrastructure (repositories only) + domain → (none) +``` + +**Check:** each import statement's target must be reachable from the source via the declared arrows. Flag any that isn't. + +**Severity:** Error when the violation crosses a top-level layer. Warning when it's a within-layer oddity. + +### 3. Public API Drift + +If the brief or an ADR documents the public interface of a module/package (exported types, functions, endpoints), compare the declared interface to what the code actually exports. + +**Sources for expected interface:** + +- ADRs with code-block signatures +- Brief §7 or Candidate description +- Any `docs/architecture/05-building-blocks.md` section + +**Check:** listed public names exist; no additional exports are marked public unless recorded. + +**Severity:** Warning (intended additions may just lack an ADR yet). + +### 4. Open Decision vs Implementation + +For each item in brief §8 (Open Decisions): has it been decided via an ADR? Is the implementation consistent with that ADR? + +**Severity:** Warning (drift here usually means someone made a decision without recording it). + +### 5. Forbidden Dependencies + +The brief may list forbidden imports explicitly. Example: "Domain module must not import from framework packages (Django, FastAPI, etc.)." Check. + +**Severity:** Error. + +## Language-Specific Tools (Opportunistic) + +These run only if the user's repo has a config file already present. If not configured, skip silently — the framework-agnostic checks still run. + +### TypeScript — dependency-cruiser + +**Detected when:** `.dependency-cruiser.cjs`, `.dependency-cruiser.js`, or `dependency-cruiser` config in `package.json`. + +**Invocation:** + +```bash +npx dependency-cruiser --validate .dependency-cruiser.cjs src/ +``` + +**Parse:** JSON output (`--output-type json`). Each violation becomes a finding with severity mapped from the rule's `severity`. + +### Python — import-linter + +**Detected when:** `.importlinter`, `importlinter.ini`, or `[tool.importlinter]` in `pyproject.toml`. + +**Invocation:** + +```bash +lint-imports +``` + +**Parse:** exit code + text output. Contract failures are errors; contract warnings are warnings. + +### Python — grimp (supplementary) + +If `import-linter` isn't configured but Python code is present, a lightweight check using `grimp` can still detect cycles: + +```bash +python -c "import grimp; g = grimp.build_graph('your_package'); print(g.find_shortest_chains('a.module', 'b.module'))" +``` + +Skip unless the user enables it. + +### Go — go vet + depguard + +**Detected when:** `.golangci.yml` or `.golangci.yaml` contains a `depguard` linter entry. + +**Invocation:** + +```bash +go vet ./... +golangci-lint run --disable-all --enable=depguard ./... +``` + +**Parse:** standard Go-style output. Depguard violations mapped to layer rules in the brief. + +### Future Languages + +For Java, C, C++ — tooling exists (ArchUnit, include-what-you-use, cpp-linter) but isn't integrated in v1. Framework-agnostic checks still apply. + +## Tool Install Commands (for reference) + +Included so the skill can tell the user what to install if they want the tool-augmented checks. The skill never installs; the user does. + +### Python + +```bash +pipx install import-linter # or: pip install --user import-linter +pipx install grimp # optional, supplementary +``` + +### TypeScript / JavaScript + +```bash +npm install --save-dev dependency-cruiser +``` + +### Go + +```bash +# golangci-lint includes depguard +brew install golangci-lint # macOS +# or +go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest +``` + +### Java (future v2+) + +```xml +<!-- pom.xml --> +<dependency> + <groupId>com.tngtech.archunit</groupId> + <artifactId>archunit-junit5</artifactId> + <version>1.3.0</version> + <scope>test</scope> +</dependency> +``` + +### C / C++ (future v2+) + +```bash +brew install include-what-you-use +# or on Linux: package manager, or build from source +``` + +## Config Generation + +The skill does not auto-generate linter configs. That's v2+. For now, if the user wants tool-augmented checks, they configure the linter themselves, using the brief as a guide. Document the desired rules in the brief so humans (and future Claude sessions) can translate consistently. + +Example — mapping brief layers to `import-linter` contracts: + +```ini +# .importlinter +[importlinter] +root_package = myapp + +[importlinter:contract:layers] +name = Core layers +type = layers +layers = + myapp.presentation + myapp.application + myapp.domain + myapp.infrastructure +``` + +## Output: `.architecture/evaluation-<date>.md` + +Write the report to `.architecture/evaluation-<YYYY-MM-DD>.md`. Use this structure: + +```markdown +# Architecture Evaluation — <Project Name> + +**Date:** <YYYY-MM-DD> +**Brief version:** <commit hash or date of `.architecture/brief.md`> +**Checks run:** framework-agnostic + <detected tools> + +## Summary + +- **Errors:** <N> +- **Warnings:** <N> +- **Info:** <N> + +## Findings + +### Errors + +#### E1. Cyclic dependency: domain/user ↔ domain/order + +- **Source:** framework-agnostic +- **Files:** `src/domain/user.py:14`, `src/domain/order.py:7` +- **Rule:** Brief §7 — "Domain modules must not form cycles." +- **Fix:** extract shared abstraction into a new module, or break the cycle by inverting one direction. + +#### E2. Forbidden dependency: domain imports Django + +- **Source:** import-linter (contract: framework_isolation) +- **Files:** `myapp/domain/user.py:3` +- **Rule:** Brief §5 — "Domain layer must not depend on framework packages." +- **Related ADR:** [ADR-0004 Framework isolation](../docs/adr/0004-framework-isolation.md) +- **Fix:** move the Django-specific logic to `myapp/infrastructure`. + +### Warnings + +#### W1. Public API drift: `OrderService.cancel()` added without ADR + +- **Source:** framework-agnostic +- **File:** `src/domain/order.py:142` +- **Rule:** Brief §8 — "Public API additions require an ADR." +- **Fix:** run `arch-decide` to record the rationale, or make `cancel()` non-public. + +### Info + +#### I1. Open decision unresolved: message bus vs direct calls + +- **Source:** framework-agnostic +- **Rule:** Brief §8 item 3. +- **Fix:** run `arch-decide` to select and record. + +## Tool Output (raw) + +<Collapsed raw output from each tool that ran, for reference.> + +## Next Steps + +- Address all Errors before merge +- Triage Warnings: either fix, record as ADR, or update the brief +- Review Info items at the next architecture meeting +``` + +## Severity Mapping + +| Severity | Meaning | Action | +|---|---|---| +| **Error** | Structural violation of declared architecture. Code contradicts brief/ADR. | Block merge. Fix or update the brief (with an ADR). | +| **Warning** | Deviation that may be intentional but wasn't recorded. | Discuss. Record via `arch-decide` or fix. | +| **Info** | Open question or unresolved decision. Not a violation, but attention-worthy. | Triage. | + +## Review Checklist + +Before handing off the report: + +- [ ] All framework-agnostic checks ran +- [ ] Detected linters ran if configured; skipped silently if not +- [ ] Each finding has: severity, source (native or tool name), file/line, rule reference, suggested fix +- [ ] Each finding links to the brief section or ADR that establishes the rule +- [ ] Raw tool output preserved at the bottom for traceability +- [ ] Report timestamped and commit-referenced + +## Anti-Patterns + +- **Silent failures.** A tool that errored out is a finding too — report it (Info: "dependency-cruiser failed to parse config; no TypeScript import checks ran"). +- **Swallowing open decisions.** An unresolved item in brief §8 is a legitimate warning. Don't treat it as "not a violation." +- **Tool-only reports.** If the language-specific tool is configured and clean, don't skip the framework-agnostic checks — they cover things the tool doesn't (API drift, open decisions). +- **Rule references missing.** Every finding must cite the rule. If you can't find the rule, the finding isn't actionable. +- **Error inflation.** Reserve Error for real violations. Warnings exist to avoid crying wolf. + +## Integration with CI (future) + +v1 produces a markdown report. v2+ will add: + +- JSON output (machine-readable) +- Exit-code behavior (non-zero when any Error) +- `--fail-on-warnings` flag for strict mode +- Delta mode (only report *new* findings since last evaluation) +- Auto-generation of linter configs from the brief + +See `docs/architecture/v2-todo.org` in the rulesets repo for the full deferred list. + +## Hand-Off + +After the report: + +- **Errors** → fix or justify (each justification becomes an ADR via `arch-decide`) +- **Warnings** → record ADRs for the deliberate ones; fix the rest +- **Info** → resolve open decisions via `arch-decide` +- After significant fixes, re-run `arch-evaluate` to verify +- Consider re-running `arch-document` if the brief or ADRs changed as a result diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..e09efb0 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,359 @@ +# Architecture Suite + +Four chained Claude Code skills for the full architecture lifecycle: **design**, **decide**, **document**, **evaluate**. Paradigm-agnostic (supports layered, hexagonal, microservices, event-driven, CQRS, DDD, and others). Language-aware (framework-agnostic checks work everywhere; language-specific linters augment when configured). + +## The Chain + +``` + ┌─────────────────┐ + New project → │ arch-design │ → .architecture/brief.md + └────────┬────────┘ + │ + (for each open decision) + │ + ▼ + ┌─────────────────┐ + │ arch-decide │ → docs/adr/NNNN-*.md + └────────┬────────┘ + │ + (when ready to formalize) + │ + ▼ + ┌─────────────────┐ + │ arch-document │ → docs/architecture/*.md + └────────┬────────┘ (dispatches to c4-analyze, c4-diagram) + │ + (once code exists, periodically) + │ + ▼ + ┌─────────────────┐ + │ arch-evaluate │ → .architecture/evaluation-YYYY-MM-DD.md + └─────────────────┘ +``` + +Skills are standalone — invoke any one directly. The flow above is the canonical path; you can enter at any point if the prerequisite artifacts already exist. + +## What Each Skill Does + +### [arch-design](../../arch-design/SKILL.md) + +Elicits the architecture: intake (stakeholders, scale, team, timeline), quality-attribute prioritization, constraints, then proposes 2-4 candidate paradigms with honest trade-off analysis. Picks one with rationale. Lists open decisions that become ADRs. + +**Output:** `.architecture/brief.md` + +### [arch-decide](../../arch-decide/SKILL.md) + +Records significant technical decisions as ADRs. Five template variants (MADR, Nygard, Y-statement, lightweight, RFC). Covers ADR lifecycle (proposed / accepted / deprecated / superseded), review checklist, and `adr-tools` automation. + +**Output:** `docs/adr/NNNN-<title>.md`, plus an index at `docs/adr/README.md`. + +**Forked from [wshobson/agents](https://github.com/wshobson/agents) — MIT.** + +### [arch-document](../../arch-document/SKILL.md) + +Produces full arc42-structured documentation from the brief + ADRs + codebase. All twelve arc42 sections. Dispatches to `c4-analyze` (for code-present systems) and `c4-diagram` (for textual descriptions) for the diagrams in sections 3, 5, 6, and 7. + +**Output:** `docs/architecture/01-introduction.md` through `12-glossary.md`, plus diagrams under `docs/architecture/diagrams/`. + +### [arch-evaluate](../../arch-evaluate/SKILL.md) + +Audits the codebase against the brief + ADRs. Four framework-agnostic checks (cyclic deps, stated-layer violations, public API drift, forbidden deps). Opportunistically invokes language-specific linters if they're already configured in the repo. + +**Output:** `.architecture/evaluation-YYYY-MM-DD.md` + +## Installation + +These skills live in this rulesets repo alongside the other skills (`debug`, `add-tests`, `c4-analyze`, etc.). Install globally once: + +```bash +make -C ~/code/rulesets install +``` + +This symlinks every skill (including the four `arch-*`) into `~/.claude/skills/`. Any Claude Code session on this machine will see them. + +To uninstall: + +```bash +make -C ~/code/rulesets uninstall +``` + +To check install state: + +```bash +make -C ~/code/rulesets list +``` + +## Optional: Language-Specific Linters + +`arch-evaluate` works without any external tooling — its framework-agnostic checks cover cycles, layer violations, API drift, and forbidden deps on any language Claude can read. **Installing the linters below is optional** and augments those checks with dedicated tooling: faster on large codebases, CI-friendly, and precise. + +Install only the ones you need for your active languages. + +### Python — import-linter + +Declarative import contracts. Config in `.importlinter` or `[tool.importlinter]` in `pyproject.toml`. + +```bash +pipx install import-linter +# or: pip install --user import-linter +# or (in a uv-managed project): uv add --dev import-linter +``` + +Verify: + +```bash +lint-imports --help +``` + +Example config (`.importlinter`): + +```ini +[importlinter] +root_package = myapp + +[importlinter:contract:layers] +name = Core layers +type = layers +layers = + myapp.presentation + myapp.application + myapp.domain + myapp.infrastructure + +[importlinter:contract:framework_isolation] +name = Domain isolation +type = forbidden +source_modules = + myapp.domain +forbidden_modules = + django + fastapi +``` + +### TypeScript / JavaScript — dependency-cruiser + +Rich import analysis with a JS config file. The de-facto standard for TS architectural linting. + +```bash +npm install --save-dev dependency-cruiser +# or globally: npm install -g dependency-cruiser +``` + +Verify: + +```bash +npx dependency-cruiser --version +``` + +Generate an initial config: + +```bash +npx dependency-cruiser --init +``` + +Then edit `.dependency-cruiser.cjs` to encode your architecture. Example rule: + +```javascript +module.exports = { + forbidden: [ + { + name: 'domain-no-infrastructure', + severity: 'error', + from: { path: '^src/domain' }, + to: { path: '^src/infrastructure' }, + }, + ], + options: { tsPreCompilationDeps: true, tsConfig: { fileName: 'tsconfig.json' } }, +}; +``` + +### Go — golangci-lint (with depguard) + +`go vet` (part of the stdlib) covers built-in checks. `depguard` (via golangci-lint) enforces import rules. + +```bash +# macOS +brew install golangci-lint + +# Linux / anywhere with Go +go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest +``` + +Verify: + +```bash +golangci-lint --version +go vet ./... +``` + +Example `.golangci.yml`: + +```yaml +linters: + disable-all: true + enable: + - depguard + +linters-settings: + depguard: + rules: + domain: + list-mode: lax + files: + - "$all" + - "!**/infrastructure/**" + deny: + - pkg: "github.com/yourorg/yourapp/infrastructure" + desc: "domain must not depend on infrastructure" +``` + +### Java — ArchUnit (v2+) + +Test-driven: architectural rules live in JUnit tests. Not invoked by `arch-evaluate` in v1. + +**Maven:** + +```xml +<dependency> + <groupId>com.tngtech.archunit</groupId> + <artifactId>archunit-junit5</artifactId> + <version>1.3.0</version> + <scope>test</scope> +</dependency> +``` + +**Gradle:** + +```groovy +testImplementation 'com.tngtech.archunit:archunit-junit5:1.3.0' +``` + +Example rule (`src/test/java/archtest/LayerRules.java`): + +```java +@AnalyzeClasses(packages = "com.yourorg.yourapp") +class LayerRules { + @ArchTest + static final ArchRule layered = + layeredArchitecture().consideringAllDependencies() + .layer("Presentation").definedBy("..presentation..") + .layer("Application").definedBy("..application..") + .layer("Domain").definedBy("..domain..") + .whereLayer("Presentation").mayNotBeAccessedByAnyLayer() + .whereLayer("Application").mayOnlyBeAccessedByLayers("Presentation") + .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Presentation"); +} +``` + +Then run `mvn test` or `gradle test`. + +### C / C++ — include-what-you-use (v2+) + +Checks each source file's `#include` discipline. Not invoked by `arch-evaluate` in v1; listed for completeness. + +```bash +# macOS +brew install include-what-you-use + +# Arch Linux +sudo pacman -S include-what-you-use + +# Ubuntu/Debian +sudo apt install iwyu +``` + +Integrate via CMake: + +```cmake +set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE include-what-you-use) +``` + +Verify: + +```bash +include-what-you-use --version +``` + +## Typical Flow + +### New project + +```bash +# 1. Shape the architecture +# In Claude Code: +/arch-design +# Answer intake questions, rank quality attributes, review candidates. +# Output: .architecture/brief.md + +# 2. Record each open decision +/arch-decide +# Once per significant decision. Output: docs/adr/0001-*.md, 0002-*.md, etc. + +# 3. Formalize (when ready) +/arch-document +# Generates all twelve arc42 sections + diagrams. +# Output: docs/architecture/*.md + +# 4. Audit (once code exists) +/arch-evaluate +# Report at .architecture/evaluation-YYYY-MM-DD.md +``` + +### Existing project with no architecture docs + +```bash +# 1. Retroactively capture +/arch-design # reconstruct the brief from what exists +/arch-decide # write ADRs for past decisions (date them honestly) +/arch-document # produce current-state arc42 docs + +# 2. Audit against the reconstructed intent +/arch-evaluate +``` + +### Continuous + +- Re-run `/arch-evaluate` periodically (on PR, before release, monthly) +- Every significant new decision → `/arch-decide` +- Brief or ADR changes → `/arch-document` to refresh + +## Where Things Land + +``` +<project-root>/ +├── .architecture/ +│ ├── brief.md ← arch-design +│ └── evaluation-YYYY-MM-DD.md ← arch-evaluate +├── docs/ +│ ├── adr/ +│ │ ├── README.md ← arch-decide (index) +│ │ └── NNNN-<title>.md ← arch-decide +│ └── architecture/ +│ ├── README.md ← arch-document (index) +│ ├── 01-introduction.md … ← arch-document +│ ├── 12-glossary.md +│ └── diagrams/ ← arch-document (via c4-*) +│ ├── context.svg +│ ├── container.svg +│ └── runtime-<scenario>.svg +``` + +## Dependencies Between Skills + +- `arch-decide` is standalone; nothing required from the others +- `arch-document` reads the brief and ADRs; without them, it stubs sections as TODO +- `arch-evaluate` requires the brief; without it, the skill stops and tells the user to run `arch-design` +- `arch-document` dispatches to `c4-analyze` (if code exists) and `c4-diagram` (otherwise) — both live in this same rulesets repo + +## Versioning and Deferred Work + +v1 covers the four core skills with the chain above. The deferred feature list — CI integration, auto-generated linter configs, ArchUnit integration, DDD aggregate boundaries, etc. — is tracked at [`v2-todo.org`](v2-todo.org). + +## Licensing + +- `arch-design`, `arch-document`, `arch-evaluate` — part of this rulesets repo +- `arch-decide` — forked from [wshobson/agents](https://github.com/wshobson/agents), **MIT**. See `arch-decide/LICENSE`. + +## Contributing / Modifying + +These are personal skills; fork as needed. If you change a skill and want to re-sync the global install symlink, re-run `make -C ~/code/rulesets install`. Symlinks point back at this repo, so edits propagate without re-install. diff --git a/docs/architecture/v2-todo.org b/docs/architecture/v2-todo.org new file mode 100644 index 0000000..4d40ad3 --- /dev/null +++ b/docs/architecture/v2-todo.org @@ -0,0 +1,254 @@ +#+TITLE: Architecture Suite — v2+ TODO +#+AUTHOR: Craig Jennings +#+DATE: 2026-04-19 + +Deferred work for the arch-* skill chain. v1 ships with the four core skills +and opportunistic linter integration. Items here extend capability, +precision, or scope and were intentionally deferred. + +* About + +Each item lists motivation, scope, and the skill(s) it touches. Priority hints +(=[#A/B/C]=) reflect rough judgement, not firm commitment. Rearrange freely. + +Related: [[file:README.md][README.md]] for the v1 architecture suite overview. + +* v2 Candidates + +** TODO [#A] Auto-generate linter configs from the brief :arch-evaluate: +SCHEDULED: <2026-05-15 Fri> + +Today the user hand-writes =.importlinter= / =.dependency-cruiser.cjs= / =.golangci.yml= +from the brief's declared layers. The skill should be able to emit a starter +config for the detected language. + +*** Scope +- Parse layers section of =.architecture/brief.md= +- Emit minimal config matching declared structure +- Place in repo with =--dry-run= mode to preview +- Never overwrite an existing config without =--force= + +*** Complication +- Each tool has different semantics (forbidden vs layer-based vs import rules) +- Mapping from "paradigm + layers" to tool-specific rules has edge cases +- Want to avoid generating wrong/incomplete rules that mislead users + +*** Touches +- =arch-evaluate= (config generation) +- =arch-design= (formalize the layers syntax in the brief) + +** TODO [#A] CI mode: exit codes and --fail-on :arch-evaluate: + +Today the skill produces a markdown report. For CI, need machine-readable +output and non-zero exit on violations. + +*** Scope +- =--output json=: structured findings for parsing +- Exit code: 0 (no errors), 1 (errors present), 2 (tool failures) +- =--fail-on=warning= flag for strict mode +- =--delta-since=<git-ref>=: only report findings introduced since that ref + +*** Touches +- =arch-evaluate= only + +** TODO [#A] ArchUnit integration (Java) :arch-evaluate: + +Java architectural linting happens via ArchUnit, which runs as JUnit tests. +The skill needs to know how to invoke it and parse its output. + +*** Scope +- Detect =archunit-junit5= dependency in =pom.xml= / =build.gradle= +- Invoke via =mvn test -Dtest=*ArchTest*= or =gradle test --tests *ArchTest= +- Parse JUnit XML or surefire reports for failures +- Map to unified finding format + +*** Complication +- ArchUnit requires someone to have written the rule classes +- Skill could also suggest generating rule tests from the brief (overlap with auto-gen task above) + +*** Touches +- =arch-evaluate= (invocation + parsing) + +** TODO [#B] include-what-you-use / cpp-linter integration (C/C++) :arch-evaluate: + +C and C++ have weaker architectural linting options than the dynamic +languages. =include-what-you-use= is the main tool; needs CMake integration +to run usefully. + +*** Scope +- Detect =.iwyu.imp= or CMake option =CMAKE_CXX_INCLUDE_WHAT_YOU_USE= +- Run a build with IWYU enabled, collect output +- Parse and report + +*** Complication +- Requires a full build (slow) +- Output is verbose; much is noise (re-sorting includes vs. real violations) +- May need a user-provided mapping file for vendored deps + +*** Touches +- =arch-evaluate= (invocation + parsing) + +** TODO [#B] DDD aggregate boundary checks :arch-evaluate: + +When the brief declares DDD tactical patterns (aggregates, repositories, +domain events), check that code respects the boundaries: aggregates only +referenced via their root, repositories only for aggregate roots, events not +crossing bounded contexts directly. + +*** Scope +- Extend brief syntax to declare aggregates + bounded contexts +- Framework-agnostic check: aggregate internals only accessed via root path +- Framework-agnostic check: repositories match declared aggregate roots 1:1 +- Flag direct cross-aggregate references + +*** Complication +- DDD is heterogeneous in practice — no single canonical structure +- Risk of being too prescriptive + +*** Touches +- =arch-design= (formalize DDD declaration in brief) +- =arch-evaluate= (checks) + +** TODO [#B] Auto-detect declared architecture from existing code :arch-design: + +For retroactive briefs: instead of asking the user to describe their +existing architecture, infer a likely layering from import patterns, propose +it, and let the user confirm/edit. + +*** Scope +- Dispatch to =c4-analyze= for module graph +- Cluster modules into implied layers using dep direction + naming +- Propose: "Looks like these layers: presentation → application → domain → infrastructure. Confirm or edit." +- Save confirmed layering to brief §7 + +*** Complication +- Inference can mislead — mixed codebases produce bad clusters +- Requires code organization that isn't already chaotic to work well + +*** Touches +- =arch-design= only + +** TODO [#B] ADR ⇄ brief cross-referencing :arch-decide: + +Currently the brief links to "ADRs TBD" and ADRs don't link back. Bidirectional +linking improves navigation and ensures the brief stays current. + +*** Scope +- =arch-decide= adds a "Brief section" field to new ADRs +- When an ADR is accepted, update brief §8 (Open Decisions) to check the box and link +- =arch-document= §9 generates a cross-reference table + +*** Touches +- =arch-decide= (write-back to brief) +- =arch-document= (index table) + +** TODO [#B] Visual dependency graph output :arch-evaluate: + +Beyond text report, emit a visual graph of cycles and layer violations. + +*** Scope +- Graphviz / mermaid output with violating edges highlighted in red +- Optional per-layer coloring +- Link to SVG/PNG from the markdown report + +*** Touches +- =arch-evaluate= (output rendering) + +** TODO [#C] Expanded paradigm library :arch-design: + +Add more paradigm entries to the candidate-considered table in arch-design: +CQRS+Event-Sourcing combined, saga orchestration, choreography, CRDTs, +space-based, reactive, etc. + +*** Complication +- More options isn't always better — risk of analysis paralysis +- Must keep trade-off analysis honest per paradigm + +*** Touches +- =arch-design= only + +** TODO [#C] Quality attribute scenario generator :arch-design: + +Given a top-ranked quality attribute ("performance"), generate concrete +testable scenarios in the format: "Under X, the system should Y within Z." + +*** Scope +- Scenario template per attribute class +- Measurable by default; flag vague ones for the user + +*** Touches +- =arch-design= (optional phase 2.5) + +** TODO [#C] Support for non-arc42 documentation formats :arch-document: + +Some teams prefer C4-only, ISO/IEC 42010 terminology, or a lighter 4+1 views +format. Add alternate templates. + +*** Scope +- Selectable =--format= in =arch-document=: arc42 (default), c4-only, 4+1, minimal +- Each format maps a subset of content + +*** Complication +- Duplicates effort; arc42 is already comprehensive +- May mean maintaining parallel templates + +*** Touches +- =arch-document= only + +** TODO [#C] PlantUML / Structurizr output :arch-document: + +Generate text-based architecture DSLs (PlantUML C4, Structurizr DSL) from the +decomposition, for teams that prefer those toolchains. + +*** Scope +- Output option in =arch-document=: emit structurizr or plantuml alongside markdown + +*** Touches +- =arch-document= (via c4-* dispatch) + +** TODO [#C] ATAM-style trade-off analysis :arch-design: + +For complex decisions, enable a deeper Architecture Trade-off Analysis +Method pass: identify sensitivity points, trade-off points, risks per +paradigm option. + +*** Complication +- ATAM is heavy; not appropriate for most projects +- Optional mode; don't make it default + +*** Touches +- =arch-design= (optional deep-dive) + +** TODO [#C] Interactive mode :arch-design: + +Instead of one-shot Q&A, walk the user through each phase as a guided +conversation with branching based on answers. + +*** Complication +- Hard to make conversational in a skill context +- Probably belongs as a slash command workflow, not a skill + +*** Touches +- =arch-design= (or a new =/arch-wizard= command) + +* Won't-Do + +** DONE Auto-implementation of architecture + +Generating code from a brief would sound appealing but crosses into tooling +that's inherently scoped to a language/framework. Out of scope for an +architectural skill suite. Leave to project-specific generators. + +** DONE Real-time collaboration + +These skills operate on filesystem artifacts (brief, ADRs, arc42 docs). +Concurrent editing is git's problem, not the skills'. + +* Notes + +- Tag entries with the skill(s) they affect (=:arch-design:=, =:arch-decide:=, + =:arch-document:=, =:arch-evaluate:=) so you can filter. +- Priority A items are what would most improve v1 for Craig's current stack + (Python / TS / Go). +- Java and C/C++ integration (ArchUnit, IWYU) is A-priority when Craig starts + using those languages, B otherwise. |