From ce951b692300d9f8d96af1ef01142748b4ea2bc0 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 19 Apr 2026 14:08:30 -0500
Subject: feat: architecture skill suite — design, decide, document, evaluate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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).
---
 Makefile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'Makefile')

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/*))
 
-- 
cgit v1.2.3