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

1 files changed, 313 insertions, 0 deletions

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.