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, 359 insertions, 0 deletions

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.