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).

8 files changed, 1977 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index 98fca36..5a27392 100644
--- a/Makefile
+++ b/Makefile
@@ -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.