feat: architecture skill suite — design, decide, document, evaluate

Four chained Claude Code skills covering the full architecture lifecycle:

  arch-design    Intake (stakeholders, scale, quality attributes, constraints)
                 → candidate paradigms with honest trade-off analysis
                 → recommendation + open-decision list
                 → .architecture/brief.md

  arch-decide    ADR creation and management. Five template variants (MADR,
                 Nygard, Y-statement, lightweight, RFC). Lifecycle, review
                 process, adr-tools automation.
                 Forked from wshobson/agents (MIT). LICENSE preserved.

  arch-document  Full arc42-structured documentation (12 sections) from brief
                 + ADRs + codebase. Dispatches to c4-analyze / c4-diagram for
                 Context, Building Block, Runtime, Deployment diagrams.

  arch-evaluate  Audits implementation against stated architecture.
                 Framework-agnostic checks (cyclic deps, stated-layer
                 violations, public API drift, forbidden deps) run on any
                 language. Opportunistically invokes language-specific linters
                 when configured (dependency-cruiser for TS, import-linter for
                 Python, go vet + depguard for Go). Never installs tooling.

Supporting docs at docs/architecture/:
- README.md    suite overview, install steps, per-language linter install
               commands (Python import-linter, TS dependency-cruiser, Go
               golangci-lint, Java ArchUnit future, C/C++ IWYU future),
               typical flow through the chain
- v2-todo.org  deferred features (auto-gen linter configs, ArchUnit, CI
               mode, DDD aggregate boundaries, visual dep graphs, retroactive
               layering inference)

Makefile SKILLS extended with the four new entries; make install symlinks
them to ~/.claude/skills/ alongside existing skills.

Landscape: arch-decide fills the well-covered ADR bucket by adopting the
strongest community offering rather than reinventing. arch-design and
arch-evaluate fill gaps where no general-purpose skill existed. arch-document
fills the arc42 gap (C4 diagrams already covered by sibling skills).

2 files changed, 472 insertions, 0 deletions

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.