solutions-architect-skills

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

Solutions Architect Skills

Version License Claude Code

Professional architecture documentation workflow for Claude Code: Transform business requirements into technical architecture, compliance documents, and development handoffs.

Overview

This Claude Code plugin provides a complete four-phase workflow for enterprise architecture documentation:

Phase 1: Business Requirements (PO Spec)
    ↓
Phase 2: Technical Architecture (ARCHITECTURE.md)
    ↓
Phase 3: Compliance Documents (10 contracts)
    ↓
Phase 4: Development Handoff & Export (.md + .docx)

Claude Code Marketplace & Plugin System

This project is distributed as a Claude Code Plugin via the shadowX4fox Marketplace:

  • Marketplace: A catalog of available plugins (Learn more)
  • Plugin: This repository, installable from the marketplace
  • Skills: Sixteen specialized skills within the plugin

For detailed information about Claude Code's plugin system, see the official Claude Code documentation.

What's Included

  • 16 Integrated Skills

    • architecture-readiness: Requirements Elicitation + Product Owner Specifications
    • architecture-enterprise-alignment (v3.25.0): Maps the PO Spec onto the 8-domain BIAN v14 capability map (Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler — 47 capabilities total) → ENTERPRISE_ALIGNMENT.md. Mandatory gate before architecture-docs Workflow 1 (Step 0.3 — no SKIP override; cascades-skip only if the PO Spec gate was skipped). Bundled enterprise model is overridable via project-local ENTERPRISE_MODEL.md. The Summary, Cross-Cutting Findings, and Owner Engagement Plan are lifted into Section 1.5 of docs/01-system-overview.md during architecture creation.
    • architecture-docs: ARCHITECTURE.md creation and maintenance (with diagram generation)
    • architecture-component-guardian: Single owner of docs/components/README.md index + C4 migration
    • architecture-definition-record: Create, update, and manage Architecture Decision Records (ADRs)
    • architecture-compliance: Generate 10 compliance contracts from ARCHITECTURE.md
    • architecture-compliance-review: Compliance portfolio health review + gap explorer playground
    • architecture-peer-review: Interactive peer review with playground tool + JSON persistence
    • architecture-traceability: PO Spec use cases vs architecture coverage report (markdown, portable)
    • architecture-analysis: 10-analysis risk & design-characteristics dashboard (SPOF, Blast Radius, Bottleneck, Cost Hotspots, STRIDE, Vendor Lock-in, Latency Budget, Tech Debt/EOL, Coupling, Data Sensitivity)
    • architecture-dev-handoff: Component development handoffs (C4 L2 only) with deliverable assets
    • architecture-docs-export: On-demand Word (.docx) export for architecture docs and handoffs
    • architecture-blueprint: Business & Application blueprint files (datos de iniciativa) from ARCHITECTURE.md
    • architecture-onboarding: Interactive concept map playground for new team members
    • architecture-icepanel-sync (beta): Sync C4 model to IcePanel via import YAML or REST API
    • architecture-explorer-headers (v3.14.0): Backfill <!-- EXPLORER_HEADER --> blocks into legacy docs so the universal architecture-explorer agent can classify them accurately. Slash command: /sa-skills:regenerate-explorer-headers (with --dry-run, --force, scope glob)

  • Universal architecture-explorer Agent (v3.16.0)

    • Haiku-tier doc navigator — front door for every doc-consuming workflow (compliance, analysis, peer-review, dev-handoff, free-form Q&A, ADR application)
    • Walks the canonical layout (ARCHITECTURE.md + docs/ + adr/) and emits an EXPLORE_MANIFEST listing every file in the corpus along with its <!-- EXPLORER_HEADER --> metadata (key_concepts, technologies, related_adrs, …)
    • No ranking, no cache, no per-task configs. Downstream skills consume the manifest and pick what to read using their own domain configs (e.g. agents/configs/<contract>.json:phase3.required_files for compliance, hardcoded base file lists per analysis lens). The dev-handoff orchestrator passes a component_file parameter to enable a per-component focus_component.related_adrs block sourced directly from that component's EXPLORER_HEADER.
    • <!-- EXPLORER_HEADER --> blocks in docs/NN-*.md and docs/components/**/*.md files (5–10 lines after the H1, listing key concepts, technologies, components, scope, related ADRs) maximize downstream filtering accuracy. Legacy docs without a header are listed in the manifest with has_header: false and treated conservatively by downstream filters.

  • C4 Model Integration (IcePanel)

    • Components follow C4 Level 2 (Container diagram) rules — every component must be a separately deployable unit (App or Store)
    • 5 architecture types with reference docs + C4 translation guides: Microservices, 3-Tier, N-Layer, META, BIAN
    • C4 L1 systems become folder structure, C4 L2 containers become component files
    • Component guardian enforces C4 boundary test and IcePanel naming conventions ([Technology in brackets])

  • 10 Compliance Contracts (CC-001 to CC-010)

    • Universal generator + 10 domain validators with personality and EOL checks
    • 4-tier approval workflow (Auto-approve, Manual review, Needs work, Rejected)
    • External Validation Summary in every contract
    • EOL-first validation via WebSearch (6-month safety period)

  • Automatic Validation

    • External validation system (0-10 scoring) for all 10 contracts
    • Template-specific validation configurations
    • Metric consistency checking
    • Design Drivers calculation

  • Optional MCP Integration — context7

    • Fetches current library/framework documentation during asset generation and component documentation
    • Used by architecture-dev-handoff (spec validation for OpenAPI, AsyncAPI, K8s, etc.) and architecture-docs (technology context briefs)
    • Fully optional — all skills degrade gracefully without it

  • Complete Documentation

    • Installation guide, Quick Start tutorial, Workflow guide, Troubleshooting

Quick Start

Installation

See Installation Guide for detailed instructions.

Step 0 — Install Bun (one-time prerequisite)

The plugin requires Bun (v1.0+) for template expansion, contract validation, and the cross-platform helper scripts (scripts/today.ts, scripts/ensure-dir.ts, scripts/remove-glob.ts). As of v3.25.2 the UserPromptSubmit hook layer is pure-native shell/cmd/PowerShell with zero JS-runtime dependency — if you only want the hook (architecture-routing context injection) and not the full skill suite, you can install the plugin without Bun. Pick the install path that matches your OS:

Windows (native cmd / PowerShell) — recommended path:

npm install -g bun

This is the most reliable Windows-native install. Requires Node.js (which is already on most Windows dev machines because of the broader JavaScript tooling). The official irm bun.sh/install.ps1 | iex one-liner also works on PowerShell, but it occasionally trips on execution-policy restrictions, corporate proxies, or signed-script enforcement — npm install -g bun sidesteps all three because npm is already trusted in your PowerShell profile if Node is installed.

macOS / Linux

curl -fsSL https://bun.sh/install | bash

Or, on macOS only, via Homebrew:

brew install bun

WSL2 or Git Bash on Windows — use the Linux/macOS curl one-liner above. The plugin works identically inside WSL or Git Bash because both expose a POSIX userland; v3.21.1's native wrappers also work natively in either, so you don't have to choose between them.

Verify (any OS):

bun --version
# 1.0.0 or higher

If bun is not on PATH after install, restart your terminal (or, on Windows, sign out and back in so the system PATH update takes effect).

Step 1 — Install the plugin

Quick Start (Using Marketplace — Recommended on every OS):

# Register marketplace (one-time)
/plugin marketplace add shadowX4fox/solutions-architect-skills

# Install plugin
/plugin install sa-skills@shadowx4fox-solution-architect-marketplace

# Verify installation
/plugin list

Alternative: Direct Git Clone

# Clone directly to plugins directory
git clone https://github.com/shadowX4fox/solutions-architect-skills.git ~/.claude/plugins/solutions-architect-skills

# Restart Claude Code and verify
/plugin list

You should see sa-skills v3.28.8 in the list.

Important: Marketplace registration is a security feature — you must explicitly add marketplaces before installing plugins. See docs/INSTALLATION.md for detailed setup instructions.

Step 2 — Configure for your platform with /sa-skills:setup

Plugin slash-command namespace: Claude Code namespaces every plugin's slash commands under the plugin name. The three commands shipped by this plugin (commands/setup.md, commands/release-architecture.md, commands/regenerate-explorer-headers.md) appear after install as:

  • /sa-skills:setup
  • /sa-skills:release-architecture
  • /sa-skills:regenerate-explorer-headers

Older docs and changelog entries refer to the bare names (/setup, /release-architecture, /regenerate-explorer-headers); read those as shorthand for the namespaced form. Type / in Claude Code to see the namespaced commands in autocomplete.

The plugin's UserPromptSubmit hook ships in three native variants under hooks/:

  • route-architecture-docs.sh (Linux, macOS, WSL, Git Bash)
  • route-architecture-docs.cmd (Windows native cmd.exe)
  • route-architecture-docs.ps1 (PowerShell on any OS)

Each wrapper self-resolves its own directory and emits the static route-architecture-docs.payload.json file when ARCHITECTURE.md is present at the project root — no ~ expansion, no JavaScript runtime, no Bun cold start. On every OS, run:

/sa-skills:setup

The setup helper:

  1. Detects process.platform at install time.
  2. Computes the absolute path to the matching wrapper.
  3. Writes that absolute path into your project's .claude/settings.json under hooks.UserPromptSubmit.
  4. Sweeps any legacy hook entry from earlier sa-skills versions (v3.19.0 sh ~/...sh, v3.21.0–v3.25.1 bun ~/...ts) in the same pass.
  5. Reports which platform was detected and the resolved hook command in its stdout summary.

Bun is no longer required for the hook layer (as of v3.25.2). Skill workflows still use Bun via Bash(bun *) permission for cross-platform helpers (scripts/today.ts, scripts/ensure-dir.ts, scripts/remove-glob.ts), so the Step 0 Bun install in the table below stays useful — it's just no longer a hook prerequisite. If you only need the hook (UserPromptSubmit context injection) and not the full skill suite, you can install the plugin without Bun and the hook will work pure-natively.

Why per-OS sections matter: the plugin's wrappers each target a different native shell (POSIX sh, Windows cmd.exe, PowerShell). /sa-skills:setup auto-detection eliminates the choice — Windows cmd, Windows PowerShell, Linux, macOS, WSL, and Git Bash all install with the same one-line /sa-skills:setup command and end up with a hook command that runs natively on the host shell.

Your OS / Shell Bun install (Step 0, for skill workflows) What /sa-skills:setup writes (Step 2)
Windows cmd.exe npm install -g bun (skills only — hook works without it) cmd /c "<abs-path>\\hooks\\route-architecture-docs.cmd"
Windows PowerShell npm install -g bun (skills only — hook works without it) cmd /c "<abs-path>\\hooks\\route-architecture-docs.cmd" (cmd wrapper still chosen — universally available; if you specifically want the .ps1, edit settings.json by hand)
Windows + WSL2 curl -fsSL https://bun.sh/install | bash (inside WSL; skills only) sh <abs-path>/hooks/route-architecture-docs.sh
Windows + Git Bash curl -fsSL https://bun.sh/install | bash (inside Git Bash; skills only) sh <abs-path>/hooks/route-architecture-docs.sh
macOS brew install bun or curl one-liner (skills only) sh <abs-path>/hooks/route-architecture-docs.sh
Linux curl one-liner (skills only) sh <abs-path>/hooks/route-architecture-docs.sh

Optional: Enable context7

context7 provides up-to-date library documentation to improve generated assets (OpenAPI specs, K8s manifests, DDL, etc.). Two skills use it when available:

Skill Usage
architecture-dev-handoff Fetches current spec docs (OpenAPI, AsyncAPI, Kubernetes, Protobuf, Avro, DDL, Redis) to validate generated asset syntax
architecture-docs Fetches framework docs for technologies in new component files; presents a Technology Context Brief

MCP server setup (recommended):

Add to your Claude Code MCP settings (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["@upstash/context7-mcp"]
    }
  }
}

Alternative — automatic setup via CLI:

npx ctx7 setup --claude

This authenticates via OAuth, generates an API key, and configures context7 automatically.

For headless/remote environments, pass your API key directly:

npx ctx7 setup --claude --api-key YOUR_API_KEY

Generate your API key at the context7 dashboard.

context7 is fully optional. All skills complete successfully without it — no errors or warnings.

First Workflow

Phase 1 — Business Requirements (Product Owner)

/skill architecture-readiness

The skill has 4 modes (ordered by priority):

  1. Async Intake — provide a file (ticket, email, requirements doc) → gap report with email-ready questions → STOPS (never enters elicitation)
  2. Requirements Elicitation — guided discovery interview (4 phases):
    • Foundation → Value & Boundaries → Behavior → Experience & Measurement
    • Discovery Summary → draft PO Spec → self-scored to ≥ 7.5/10 → PRODUCT_OWNER_SPEC.md
  3. PO Spec Creation — template-guided document creation
  4. PO Spec Evaluation — score existing PO Spec (0-10 weighted rubric)

Phase 2 — Technical Architecture

/skill architecture-docs

Hand off PRODUCT_OWNER_SPEC.md to your architecture team. The skill produces a multi-file structure:

ARCHITECTURE.md          ← navigation index (~130 lines)
docs/                    ← all section content
└── components/          ← one file per architectural component
adr/                     ← Architecture Decision Records

Phase 3 — Compliance Documents

/skill architecture-compliance

Generates 10 compliance contracts from ARCHITECTURE.md into /compliance-docs/. To remediate gaps found in compliance contracts, use /skill architecture-docs — the skill guides you through updating ARCHITECTURE.md for each finding.

Phase 4 — Development Handoff

/skill architecture-dev-handoff

Generates per-component handoff documents with deliverable assets into handoffs/. Produces an 8-section audience-segmented guide per component (HANDOFF_TEMPLATE v2.1.0) with Dev / QA / Ops tracks (API contract, data model, security, observability, acceptance criteria, etc.) plus type-specific assets (OpenAPI specs, DDL scripts, K8s manifests, and more). Scoped to C4 Level 2 (Container) components only.

Phase 4.5 — Word Export (optional)

/skill architecture-docs-export

Exports architecture documents to professional Word (.docx) files: SA executive summary (synthesized from overview + component index + compliance manifest), individual ADRs, or component handoffs.

Quality Gates (recommended after Phase 2)

/skill architecture-peer-review       # Quality review — 3 depth levels, 13 categories, scorecard
/skill architecture-traceability      # PO Spec coverage check — generates TRACEABILITY_REPORT.md
/skill architecture-compliance-review # Portfolio health + concept gap explorer (after Phase 3)

Supporting Skills

Skill When to Use
/skill architecture-peer-review After ARCHITECTURE.md is complete — interactive quality review with approve/reject/fix workflow (JSON persistence for fast regeneration)
/skill architecture-traceability Check if architecture covers all PO Spec requirements — generates portable markdown report
/skill architecture-analysis Risk and design-characteristics dashboard — 10 analyses (SPOF, Blast Radius, Bottleneck, Cost Hotspots, STRIDE, Vendor Lock-in, Latency Budget, Tech Debt/EOL, Coupling, Data Sensitivity) run individually or all-ten in parallel
/skill architecture-blueprint When organizational blueprint forms (datos de iniciativa) are required
/skill architecture-compliance-review After compliance contracts are generated — explore gaps across all 10 contracts
/skill architecture-component-guardian Adding, removing, updating components, or migrating flat components to C4 multi-system structure
/skill architecture-definition-record All ADR write operations — create, update, supersede
/skill architecture-onboarding Onboarding new team members — interactive concept map of the architecture suite
/skill architecture-icepanel-sync Sync architecture C4 model to IcePanel (beta)

Features

Phase 1: Architecture Readiness (Product Owner)

Create comprehensive Product Owner Specifications before technical design begins. Includes a structured discovery interview when starting from scratch.

Key Features:

  • Requirements Elicitation — 4-phase guided discovery interview (Foundation → Value & Boundaries → Behavior → Experience & Measurement)
    • Probing techniques: scenario walking, quantification, negative probing, assumption surfacing
    • Industry defaults when PO is unsure; unknowns logged as Open Questions
    • Discovery Summary checkpoint before drafting; self-scoring gap loop until ≥7.5
  • Async Intake — file-based requirements extraction from tickets, emails, or documents
    • Scores input against the PO Spec rubric (same 8 sections, same weights)
    • Produces PO_SPEC_GAP_REPORT.md with ready-to-send questions per gap, prioritized by section weight
    • No interactive interview — output is a written gap report the architect forwards to the requester
    • If score ≥ 7.5, also drafts PRODUCT_OWNER_SPEC.md automatically
  • 8-section template (Business Context, User Personas, Use Cases, Success Criteria, etc.)
  • Weighted scoring methodology (0-10 scale)
  • Readiness threshold: ≥7.5 for architecture handoff
  • Focus: Business requirements, no technical implementation
  • Bilingual interview support (language auto-detected from user's first message)

Output: PRODUCT_OWNER_SPEC.md

Phase 1.5: Enterprise Alignment Gate (Architecture Governance)

Maps the accepted PO Spec onto the organisation's 8-domain BIAN v14 capability map before technical design begins. Identifies which corporate domains are impacted, which governance rules will constrain the initiative, and which owner counterparts must be engaged at kickoff. Mandatory gate — architecture-docs Workflow 1 Step 0.3 blocks new ARCHITECTURE.md creation until this file exists (no SKIP ENTERPRISE ALIGNMENT override; cascades-skip only when the PO Spec gate itself was skipped).

Key Features:

  • 8-domain BIAN v14 model (47 capabilities): Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler
  • Bundled default model overridable by a project-local ENTERPRISE_MODEL.md at the project root
  • Status taxonomy: 🟢 Impacted / 🟡 Partial / ⚪ Not Applicable
  • Verbatim citation of governance rules from the model (no paraphrasing)
  • Cross-cutting mandatory checks (Enterprise Management, Finance & Risks, Business Enabler) regardless of per-domain status
  • Owner Engagement Plan with engagement timing derived from rule wording (Before kickoff / Before architecture sign-off / Before production)
  • Lifts Summary + Cross-Cutting Findings + Owner Engagement table into Section 1.5 of docs/01-system-overview.md after the gate passes

Output: ENTERPRISE_ALIGNMENT.md at the project root

Phase 2: Architecture Documentation

Create and maintain technical architecture documentation following enterprise standards.

Key Features:

  • Multi-file structure — ARCHITECTURE.md at project root is a navigation index (~130 lines); all content lives in docs/ as numbered section files; components in docs/components/ (one file per component); see RESTRUCTURING_GUIDE.md
  • 5 architecture types with reference docs + C4 translation guides:
    • STANDARD: Microservices (1), 3-Tier (2), N-Layer (3)
    • ENTERPRISE: META (4), BIAN (5)
  • C4 component process: C4 L1 systems → confirm → select focus system → C4 L2 boundary test → create component files
  • Interactive Mermaid diagrams in docs/03-architecture-layers.md
  • Metric consistency validation across document
  • Design Drivers calculation (Value Delivery %, Scale, Impacts)
  • 9 mandatory Architecture Principles + 1 optional
  • ADR (Architecture Decision Record) templates with automatic file generation
  • ADR ID Format Gate (v3.25.1, BLOCKING) — ^ADR-\d{3,}$ regex enforced at every ADR write; phase-prefixed forms (ADR-P1-001, ADR-Phase1-001, ADR-001-P1, etc.) abort with a documented error. Project ADRs start at ADR-101; institutional range 001–100 is reserved
  • Phase Catalog mode (v3.23.0, default for Section 6 — docs/04-data-flow-patterns.md) — multi-UC architectures compose shared phases via a phase × UC matrix instead of duplicating flows. Mode is auto-selected when the doc has 2+ UCs sharing components, or 1 UC with ≥4 phases; Single-Flow mode is preserved as the fallback. Mode-awareness propagates through Workflow 7 (diagram gate counts P phase mini-flows + U UC wire sequences), peer-review SECTIONS-05 (matrix-vs-Phase-Catalog phase-count drift = Major), and dev-handoff Flows payload extraction
  • Connection Naming Rule (v3.21.9 / v3.21.10) — every C4 L1 + L2 edge's 4th Rel() parameter follows the canonical normal form <PROTOCOL>/<STYLE> [Action Type] (e.g. HTTPS/JSON [Data], gRPC/PROTOBUF [Internal], TLS/AVRO [Event], JDBC/SQL [Query]); via-hop / topic / queue / async metadata moves to the 3rd parameter (description). 10-tag closed action vocabulary. Sequence-diagram message labels are explicitly exempt — reviewers and audit gates skip the rule on sequenceDiagram blocks
  • Infrastructure-as-via Rule (v3.21.7) — APIM, brokers, topics, queues, service mesh, load balancers, and iPaaS collapse onto edge labels in C4 L1 + L2 diagrams rather than appearing as standalone nodes; ContainerQueue() is reserved for the rare case where an owned/custom broker IS the architectural unit
  • DIAGRAMS_GATE (v3.21.8, BLOCKING) — Workflow 1 Step 7.3 will not print ✅ Architecture creation complete until every mandatory diagram (Logical View ASCII, C4 L1, C4 L2, Detailed View, plus mode-aware sequence diagrams) is verified present and Pre-Write-Validation-clean. No SKIP DIAGRAMS override
  • Component Naming Fidelity Rule (v3.24.1) — every user-visible artifact (analysis reports, peer reviews, dev handoffs, compliance contracts, .docx exports, traceability reports, prose summaries, diagrams) references documented components by their canonical full name from docs/components/README.md Column 2 — never an abbreviation, alias, or truncation, even when source docs/**/*.md files use a shortened form inline. Enforced via dedicated blocks in all 19 agents under agents/**/*.md, three templates, and the setup-managed CLAUDE.md block
  • Foundational Context Anchor Protocol — dependency-aware editing workflow that loads required upstream context before any downstream section edit
  • Downstream Documentation Propagation — after any substantive section edit, detects affected downstream files via reverse dependency table, presents a user-approval checklist, and cascades updates in tier order following the Context Anchor Protocol
  • All files kept under ~400 lines each for context efficiency

Output structure:

<project-root>/
├── ARCHITECTURE.md          (~130 lines — navigation index only)
├── adr/                     (ADR files — canonical 10-section template)
└── docs/
    ├── 01-system-overview.md
    ├── 02-architecture-principles.md
    ├── 03-architecture-layers.md
    ├── 04-data-flow-patterns.md
    ├── 05-integration-points.md
    ├── 06-technology-stack.md
    ├── 07-security-architecture.md
    ├── 08-scalability-and-performance.md
    ├── 09-operational-considerations.md
    └── components/
        ├── README.md                (5-column index grouped by system)
        ├── <system-name>.md         (C4 L1 system descriptor)
        └── <system-name>/           (C4 L1 folder per system)
            └── NN-<name>.md         (C4 L2 containers inside system folder)

Each component file includes a C4 metadata header: Type, Technology [in brackets], C4 Level, Deploys as, Communicates via. All architectures use grouped tables with ### System Name headers in README.md.

Peer Review (Quality Gate)

Use /skill architecture-peer-review after ARCHITECTURE.md is complete, before handing off to compliance.

  • 3 depth levels: Light (22 checks), Medium (44 checks), Hard (82 checks)
  • 13 review categories with weighted 0–10 scoring: Structural Completeness, Naming & Conventions, Section Completeness, Content Coherence, Technology Alignment, Integration Soundness, Metric Realism, Scalability Design, Security Posture, Performance Design, Operational Readiness, ADR Quality, Trade-off Honesty
  • Interactive HTML playground — approve/reject/comment on each finding, live scorecard
  • Fix prompt generation — copy approved findings as a structured prompt to apply changes via architecture-docs

Output: Interactive HTML peer review file (architecture-peer-review-YYYY-MM-DD.html) + scored findings

Blueprint Generation

Use /skill architecture-blueprint when organizational blueprint forms are required.

  • Business blueprint (BLUEPRINT_BUSINESS_EN.md / BLUEPRINT_BUSINESS_ES.md) — fills the "Datos de la Iniciativa" organizational template (business domain, strategy, deployment location, team roles)
  • Application blueprint (BLUEPRINT_APPLICATION_EN.md / BLUEPRINT_APPLICATION_ES.md) — fills an application-level template (Design Drivers, Architecture Decisions, Capacity Sizing, Compliance Approvals)
  • Language auto-detection — reads docs/01-system-overview.md, selects matching EN or ES template
  • NOT FOUND handling — fields not found in architecture docs are marked NOT FOUND with a recommended keyword or section to add the missing data
  • Bilingual (ES/EN) with explicit language override support

Output location: same directory as ARCHITECTURE.md

Architecture Type Selection & C4 Model

When creating a new architecture, the user selects from 5 types. Each type comes with two reference documents that govern the architecture and component structure:

📐 Architecture Type Selection

── Industry Standard ─────────────────────────────
  1. Microservices    STANDARD  RECOMMENDED
  2. 3-Tier           STANDARD
  3. N-Layer          STANDARD

── Enterprise / Domain-Specific ──────────────────
  4. META             ENTERPRISE
  5. BIAN             ENTERPRISE  BANKING

Each type loads:

  • Section 4 + 5 templates — structure and component format
  • Architecture Rules (references/{TYPE}-ARCHITECTURE.md) — defines the pattern, layers, principles
  • C4 Translation (references/{TYPE}-TO-C4-TRANSLATION.md) — maps the architecture to C4 levels

Types without both reference docs are greyed out and cannot be selected.

After type selection, the C4 component process runs:

Step 4a: C4 Level 1 — Identify systems → confirm with user
Step 4b: C4 Level 2 — Confirm focus system
Step 4c: C4 Level 2 — Identify containers per system (boundary test)
Step 4d: Create component files with C4 metadata headers
Step 4e: Create README.md index (5-column, grouped by system)

Phase 3: Compliance Documentation

Generate compliance contracts from ARCHITECTURE.md with full traceability. Each contract follows the CC-NNN naming convention for consistent identification.

Key Features:

  • 1 universal generator reads domain config at runtime — no per-domain agents
  • 10 domain validators with personality, EOL checks (WebSearch), and standard validation
  • EOL-first validation: Technology versions checked against endoflife.date before any compliance scoring (6-month safety period)
  • Automatic Validation (0-10 scoring): All contracts validated with granular scoring
  • 4-Tier Approval Workflow: Auto-approve (8.0-10), Manual review (7.0-7.9), Needs work (5.0-6.9), Rejected (0-4.9)
  • External Validation Summary: Standardized section in every contract referencing the validator agent
  • Compliance manifest (index of all generated documents)

Output: /compliance-docs/ with contracts named CC-NNN-{type}_{project}_{date}.md

Compliance Contract Types

CC Code Contract Type Validator Focus Requirements
CC-001 Business Continuity Aegis RTO/RPO, DR, backup, resilience 43 LACN
CC-002 Cloud Architecture Atlas Deployment model, provider, IaC, security 6 LAC
CC-003 Data & AI Architecture Mnemosyne Data governance, AI/ML, privacy 11 LAD/LAIA
CC-004 Development Architecture Hephaestus EOL validation (sole external check, v3.22.0); coding standards 2 LADES
CC-005 Enterprise Architecture Athena Strategic alignment, governance 7 LAE
CC-006 Integration Architecture Iris API standards, message patterns 7 LAI
CC-007 Platform & IT Infrastructure Vulcan Environments, databases, capacity 9 LAPI
CC-008 Process Transformation Hermes Automation, efficiency, ROI 4 LAA
CC-009 Security Architecture Argus Auth, encryption, vulnerability mgmt 8 LAS
CC-010 SRE Architecture Prometheus SLOs, observability, incident mgmt 57 LASRE

Compliance Generation Architecture

The system uses a two-phase parallel execution model: validators run first (with domain personality and WebSearch for EOL), then a single universal generator is invoked 10 times with each validator's results.

                    ┌─────────────────────────────┐
                    │   architecture-compliance    │
                    │       (orchestrator)         │
                    └──────────┬──────────────────┘
                               │
              Phase 1: Spawn 10 validators (parallel)
                               │
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
  ┌──────────────┐   ┌────────────────┐   ┌────────────────┐
  │ Aegis        │   │ Hephaestus     │   │ Prometheus      │
  │ (BC, 16 items│   │ (Dev, EOL-only │   │ (SRE, 25 items │  ...×10
  │  + EOL)      │   │  via WebSearch │   │  + EOL)        │
  │              │   │  — v3.22.0)    │   │                │
  └──────┬───────┘   └──────┬─────────┘   └──────┬─────────┘
         │                  │                    │
         ▼                  ▼                    ▼
  VALIDATION_RESULT  VALIDATION_RESULT    VALIDATION_RESULT
         │                  │                    │
         │   Phase 2: Spawn 1 generator ×10 (parallel)
         │          (with results in prompt)
         │                  │                    │
         ▼                  ▼                    ▼
  ┌─────────────────────────────────────────────────────┐
  │         compliance-generator (universal)             │
  │                                                      │
  │  Reads config: agents/configs/{type}.json            │
  │  Loads template: cc-NNN-{type}.template.md           │
  │  Parses VALIDATION_RESULT from prompt                │
  │  Fills template placeholders                         │
  │  Writes contract to compliance-docs/                 │
  └──────────────────────────┬──────────────────────────┘
                             │
                             ▼
  ┌─────────────────────────────────────────────────────┐
  │              compliance-docs/                        │
  │  CC-001-business-continuity_Project_2026-03-29.md   │
  │  CC-004-development-architecture_Project_2026-03-29.md │
  │  CC-010-sre-architecture_Project_2026-03-29.md      │
  │  ...                                                 │
  │  COMPLIANCE_MANIFEST.md                              │
  └─────────────────────────────────────────────────────┘

How It Works: CC-004 Development Example

  Orchestrator                Hephaestus Validator           Universal Generator
  ───────────                 ────────────────────           ───────────────────
       │                            │                              │
       │── spawn validator ────────►│                              │
       │                            │                              │
       │                     Phase 1: EOL Gathering                │
       │                     ├─ WebSearch: "Java 17 EOL"           │
       │                     ├─ WebSearch: "Spring Boot 3.2 EOL"   │
       │                     ├─ WebSearch: "Angular 19 EOL"        │
       │                     └─ Build EOL lookup table             │
       │                                                           │
       │                     Phase 2: EOL Verdict (v3.22.0:        │
       │                     stack-validation checklist removed;   │
       │                     EOL is the sole external check)       │
       │                     ├─ DEV-01: Java 17 → PASS (2030)     │
       │                     ├─ DEV-02: Spring 3.2 → FAIL (EOL)   │
       │                     ├─ DEV-13: Angular 19 → FAIL (<6mo)  │
       │                     └─ Per-stack EOL evidence table       │
       │                            │                              │
       │◄── VALIDATION_RESULT ──────┘                              │
       │                                                           │
       │── spawn generator (contract_type: development) ──────────►│
       │   + VALIDATION_RESULT in prompt                           │
       │                                                           │
       │                                       Read config JSON    │
       │                                       Load template       │
       │                                       Parse VALIDATION_RESULT
       │                                       Fill placeholders   │
       │                                       Write CC-004-*.md   │
       │                                                           │
       │◄── contract written ──────────────────────────────────────┘
       │
       │── post-generation pipeline (scoring, manifest)

Key principles:

  • Validators own the personality and domain knowledge — they frame evidence, deviations, and recommendations
  • The generator is a pure template-filler — no domain logic, reads everything from config + VALIDATION_RESULT
  • EOL is a blocking condition — approved + EOL = FAIL (6-month safety period via WebSearch)
  • Every contract has a standardized External Validation Summary referencing its validator

Compliance Review (Quality Gate)

Use /skill architecture-compliance-review after contracts are generated to understand what ARCHITECTURE.md improvements would push contracts to auto-approve (≥8.0/10).

  • Coverage validation: Checks all 10 required contracts are present and ≤6 months old
  • Gap extraction: Reads every contract's compliance summary table and extracts Non-Compliant and Unknown requirements
  • Concept clustering: Groups gaps across contracts by underlying ARCHITECTURE.md concept (load testing, DR/RTO, IAM, observability, etc.) ranked by cross-contract impact
  • Interactive HTML playground — portfolio health panel + concept cluster gap explorer

Architecture Analysis (Risk & Design Dashboard)

Use /skill architecture-analysis to run risk and design-characteristics analyses over the architecture documentation — the kind of assessments that come out of a release-readiness review, pre-incident audit, or annual architecture review.

10 analyses across two groups, each producing a date-stamped report in analysis/. Run individually, by group (1–5 or 6–10), or all ten in parallel via a single-message parallel spawn.

HIGH-priority (runtime / security risk)

# Analysis Key output Invocation
1 SPOF — Single Points of Failure Critical (C) / Degradation (D) / Operational (O) tables + ASCII heat map (Impact × Likelihood) + Top-5 remediations /skill architecture-analysis → 1
2 Blast Radius — Downstream cascade impact S1–S4+Isolated severity tiers, fan-out depth (direct+indirect), cascade vs. bulkhead vs. fail-open, Mermaid cascade path flowcharts for top-3 worst scenarios, ⚡ SPOF+Blast cross-reference 2
3 Bottleneck — Throughput chokepoints B1–B4 tier model (B1=critical chokepoint), capacity metrics table (Max RPS / HPA / connection pool / queue depth), ASCII capacity headroom bar chart, ADR-driven bottleneck tracking 3
4 Cost Hotspots — Cost concentration Q1–Q4 cost quality tiers, Pareto 80% rule, over-provisioning candidates, vendor concentration (≥60% flag), normalization to USD/month, ADR cost decision table 4
5 STRIDE — Security threats per trust boundary Trust boundary inventory (TB-xx), per-boundary S/T/R/I/D/E matrix, High-Priority Threats table, compliance cross-reference with compliance-docs/SECURITY_*.md 5

Strategic / sustainability

# Analysis Key output Invocation
6 Vendor Lock-in — Portability risk L1 (locked) / L2 (lock-prone) / L3 (portable) tiers, per-vendor concentration table (≥60% flag), exit cost ranking (proprietary surface × replacement effort × data export), heat map (lock severity × strategic importance) 6
7 Latency Budget — Per-hop SLO decomposition Per-flow p95 decomposition into hops (Within / Tight / Over Budget / Untracked), ASCII Gantt-style budget bars per flow, Hops Over Budget summary, tail-latency variance flag (p99/p95 > 3×) 7
8 Tech Debt / EOL — Technology currency T1 (EOL now) / T2 (EOL ≤6mo) / T3 (deprecated) / T4 (current) / T5 (unknown) tiers, EOL Hotlist, deprecated SDK keyword scan, ADR architectural debt table (superseded ADRs whose replacement is not implemented), heat map (severity × effort) 8
9 Coupling — Fan-in/fan-out, cycles Fan-in (Ca) / Fan-out (Ce) / Instability (I = Ce/(Ca+Ce)) per component, K1 critical hubs (fan-in ≥5) / K2 volatile leaves (fan-out ≥5) / K3 god objects (both) / K4 cycles with Mermaid subgraphs, ASCII distribution histograms 9
10 Data Sensitivity — PII flow & encryption gaps S1–S4 data classification per store/queue/cache, G1 (unencrypted transit) / G2 (unencrypted at rest) / G3 (retention breach) / G4 (cross-boundary leakage) / G5 (undocumented) gaps, Mermaid sequence diagrams for top-3 S1 flows, compliance cross-reference 10

Key principles:

  • Documentation Fidelity Rule — every finding cites the source file and section; ungrounded findings are marked [NOT DOCUMENTED — add to <source-file>] rather than estimated
  • Parallel spawn — all selected agents issue in a single message (no serial bottleneck)
  • Date-stamped output — analysis/<TYPE>-<YYYY-MM-DD>.md; re-running same day overwrites, new day preserves history

Output location: analysis/ at project root

Permissions required (add to .claude/settings.json):

"Write(analysis/*)", "Read(analysis/*)", "Bash(mkdir *)", "Agent(sa-skills:architecture-analysis-agent)"

Phase 4: Development Handoff & Export

Dev Handoff

Use /skill architecture-dev-handoff when handing off a component to the development team for implementation.

Key Features:

  • 8-section audience-segmented handoff document per component (HANDOFF_TEMPLATE v2.1.0) — Section 0 Metadata + three audience tracks:
    • PART A — DEV: A1 Overview/Scope/Tech/ADRs · A2 API & Data Contract · A3 Integrations & Failure Modes
    • PART B — QA: B1 Acceptance, Performance & Security Tests
    • PART C — OPS: C1 Deployment/Config/Resources · C2 Observability & Runbook · C3 Deliverable Assets
    • APPENDIX: D1 Open Questions and Assumptions
  • Scoped to C4 Level 2 (Container) components only — C4 L1 system descriptors are excluded
  • Component Naming Fidelity Rule enforced (v3.24.1) — canonical full component names from docs/components/README.md Column 2
  • 8 component-type-specific assets:
Component Type Asset Generated
API / REST / Service openapi.yaml (OpenAPI 3.1)
Database / Data Store ddl.sql (DDL with tables, indexes, constraints)
Redis / Cache redis-key-schema.md (key patterns, TTL, eviction, fail-open)
Kubernetes workload deployment.yaml (Deployment + Service + HPA)
Message Consumer/Producer asyncapi.yaml (AsyncAPI 3.0)
Kafka + Avro schema.avsc (Avro schema for Schema Registry)
Kafka + Protobuf schema.proto (Protobuf message definition)
Scheduled Job cronjob.yaml (Kubernetes CronJob)
  • Gap detection — fields not found in architecture docs are marked [NOT DOCUMENTED] and listed in Section 15 as a remediation checklist
  • Compliance enrichment — if compliance-docs/ exists, security/SRE/development contract gaps are surfaced in relevant sections
  • Managed index at handoffs/README.md — 6-column table tracking all handoff docs

Output location: handoffs/NN-<component-name>-handoff.md + handoffs/assets/NN-<component-name>/

Doc Export

Use /skill architecture-docs-export when professional Word deliverables are needed.

Mode What it exports Output
Solution Architecture Executive Summary synthesized from docs/01-system-overview.md + component index + compliance manifest (if present), plus one .docx per ADR exports/SA-<name>.docx + exports/ADR-NNN-<title>.docx
Dev Handoff Selected component handoff(s) from handoffs/ exports/HANDOFF-<component>.docx

Document styling: Corporate blue (#1F4E79) for SA, Amber/Gold (#8B6914) for ADRs, Teal (#0D7377) for handoffs.

Output location: exports/ at project root

Architecture Types & Visualization

5 Supported Architecture Types

Choose the architecture type that best fits your system:

1. META (6-Layer Enterprise) - Large enterprise systems with complex integrations

  • Layers: Channels → UX → Business Scenarios → Business → Domain → Core
  • Best for: Financial services, regulated industries, enterprise platforms
  • Template: Section 4 META with BIAN V12.0 alignment
  • BIAN Standard: Full V12.0 compliance with 12 metadata fields
  • Layer 5 Enhancement: Matches BIAN Layer 4 comprehensiveness with complete service domain metadata

2. 3-Tier (Classic Web Application) - Standard web applications and REST APIs

  • Tiers: Presentation → Application/Business Logic → Data
  • Best for: Web apps, line-of-business applications, standard CRUD systems
  • Template: Section 4 3-Tier with tier separation enforcement

3. Microservices (Cloud-Native) - Distributed systems with independent services

  • Components: API Gateway, Service Mesh, Event Bus, independent services
  • Best for: Cloud-native systems, event-driven architectures, polyglot environments
  • Template: Section 4 Microservices with service catalog

4. N-Layer (DDD/Clean Architecture) - Flexible custom patterns

  • Patterns: Classic DDD (4-Layer), Extended (5-Layer), Clean Architecture
  • Best for: Domain-Driven Design, Hexagonal Architecture, testable systems
  • Template: Section 4 N-Layer with dependency inversion

5. BIAN (Full BIAN V12.0 Certification) - Pure BIAN Service Landscape architecture

  • Layers: Channels → BIAN Business Scenarios → BIAN Business Capabilities → BIAN Service Domains → Core Systems
  • Best for: Banking, financial services requiring full BIAN certification
  • Template: Section 4 BIAN and Section 5 BIAN with comprehensive metadata
  • Compliance: Mandatory full BIAN V12.0 compliance (12 metadata fields, 7 standard operations)
  • Validation: All service domain names validated against official BIAN Service Landscape V12.0
  • Traceability: Full BIAN hierarchy (Service Domain → Business Domain → Business Area)

How to Choose: See ARCHITECTURE_TYPE_SELECTOR.md for decision tree and comparison matrix.

Diagram Generation & Enforcement (Workflow 8)

Architecture diagrams are generated by the architecture-docs skill with strict placement enforcement. All diagrams adapt their grouping, naming, and colors to the detected architecture type (META, BIAN, 3-Tier, N-Layer, Microservices) and support light/dark theme variants.

Mandatory diagrams (always generated, 4 standard + data flow):

All 4 standard diagrams live in docs/03-architecture-layers.md under ## Architecture Diagrams:

# Diagram Format Audience
1 Logical View ASCII art Executives, architects
2 C4 Level 1 — System Context Mermaid C4Context Non-technical stakeholders
3 C4 Level 2 — Container Mermaid C4Container Development teams
4 Detailed View Mermaid graph TB Architects, SREs

Plus Data Flow Diagrams — Mermaid sequenceDiagram blocks in docs/04-data-flow-patterns.md, mode-aware (v3.23.0):

  • Phase Catalog mode (default for 2+ UCs sharing components, or 1 UC with ≥4 phases): one sequenceDiagram per phase H4 in ## Phase Catalog (scoped mini-flow) + one full wire sequenceDiagram per UC in ## End-to-End Wire Sequences
  • Single-Flow mode (legacy fallback for trivial 1-UC, ≤3-flow systems): one sequenceDiagram per H3 flow subsection

On-request diagrams (opt-in):

  • Infrastructure / Deployment → docs/09-operational-considerations.md
  • HA / Failover + Performance → docs/08-scalability-and-performance.md
  • Integration → docs/05-integration-points.md
  • Security → docs/07-security-architecture.md

Enforcement rules:

  • 🛑 DIAGRAMS_GATE (BLOCKING, v3.21.8) — Workflow 1 Step 7.3 audits every mandatory diagram + the mode-aware sequence-diagram count (P phases + U UC wire sequences in Phase Catalog mode; one per H3 in Single-Flow). Creation does not complete until all are present and Pre-Write-Validation-clean. No SKIP DIAGRAMS override
  • 🔗 Connection Naming Rule (L1 + L2, v3.21.9) — every C4 L1 / L2 / Detailed-View edge's 4th Rel() parameter follows <PROTOCOL>/<STYLE> [Action Type] (10-tag closed action vocabulary: Data, Event, Internal, Query, Command, Stream, Sync, Async, Webhook, Control). Free prose, via-hops, topic / queue names move to the 3rd Rel() parameter (description)
  • 🚇 Infrastructure-as-via Rule (L1 + L2, v3.21.7) — APIM, brokers, topics, queues, service mesh, load balancers, iPaaS collapse onto edge labels rather than appearing as separate nodes; ContainerQueue() is reserved for owned/custom brokers that ARE the architectural unit
  • 🧾 Sequence-diagram exemption (v3.21.10) — message labels in sequenceDiagram blocks (A->>B: …, A-->>B: …, A-)B: …) are free prose; the Connection Naming Rule is scoped to C4 L1, C4 L2, and Detailed View only. Reviewers and audit gates skip the rule when the first line inside a Mermaid fence is sequenceDiagram
  • ⛔ Non-canonical placement is denied — diagrams go to their designated docs/ file, no override
  • 🎨 Theme selection — user must choose light or dark theme before diagram generation; persisted as <!-- DIAGRAM_THEME: light|dark -->
  • 📥 External diagram reconciliation — diagrams from external files are classified, matched against architecture docs, and either relocated or discarded (no undocumented flows)
  • 🚫 Semicolon in labels is forbidden — ; terminates Mermaid statements and causes parse errors; use , instead

Target: Mermaid v11.4.1 (VS Code Mermaid Chart extension 2.1.0+).

Comprehensive Guide: See DIAGRAM-GENERATION-GUIDE.md for the 4 standard diagrams with architecture-type-specific templates, C4 color conventions, the Connection Naming Rule + Infrastructure-as-via Rule, sequenceDiagram syntax reference, and generation workflow. See MERMAID_DIAGRAMS_GUIDE.md for authoring reference (syntax patterns, component guidelines, common scenarios).

Documentation

Examples

Real-World Example Repository

Task Scheduling Platform Example

Complete end-to-end demonstration of the four-phase workflow:

Phase 1: Product Owner Specification

  • Business requirements and user personas
  • Use cases and success criteria
  • Weighted readiness scoring (8.3/10)

Phase 2: Technical Architecture (ARCHITECTURE.md)

  • Multi-file structure: navigation index + docs/ section files + docs/components/
  • Microservices architecture pattern
  • Interactive Mermaid diagrams in docs/03-architecture-layers.md
  • Technology stack documentation
  • Complete with metrics, SLOs, and ADRs

Phase 3: Compliance Documentation

  • All 10 generated compliance contracts with validation
  • Development Architecture with live EOL validation via endoflife.date (sole external check as of v3.22.0)
  • Security, Cloud, SRE, and Enterprise Architecture contracts
  • Full source traceability to ARCHITECTURE.md

Phase 4: Development Handoff

  • Per-component handoff documents with deliverable assets
  • Type-specific scaffolded artifacts (OpenAPI, DDL, K8s manifests)

Repository: https://github.com/shadowX4fox/task-scheduling-example

Additional Examples in This Repository:

The examples/ directory contains reference templates:

  • PRODUCT_OWNER_SPEC_example.md - PO Spec template (Job Scheduling Platform)
  • ARCHITECTURE_example.md - Full ARCHITECTURE.md example (multi-file structure: navigation index + docs/ section files)

Want More Examples?

To request specific examples or use cases, open an issue.

Requirements

  • Claude Code (latest version)
  • Bun (v1.0.0 or later) — required for compliance generation, template validation, and the cross-platform helper scripts (scripts/today.ts, scripts/ensure-dir.ts, scripts/remove-glob.ts). Not required for the UserPromptSubmit hook layer as of v3.25.2 — the hook is pure-native shell/cmd/PowerShell
  • Platform: macOS, Linux, or Windows (native cmd / PowerShell, WSL2, or Git Bash — all supported as of v3.21.1)

Why Bun?

The architecture-compliance skill (and several other skills) use Bun for:

  • Template expansion with @include directives
  • Pre-validation of template structure (Phase 4.1)
  • Post-validation of generated contracts (Phase 4.6)
  • The cross-platform helpers under scripts/ (today.ts, ensure-dir.ts, remove-glob.ts) that replaced the v3.19.x POSIX date / mkdir / rm shell-outs
  • High-performance TypeScript execution without a separate transpile step

Installing Bun by OS

OS / Shell Recommended install command Notes
Windows (native cmd / PowerShell) npm install -g bun Most reliable Windows-native path. Requires Node.js. Sidesteps PowerShell execution-policy and proxy issues that the official PowerShell installer occasionally hits in corporate environments.
Windows + WSL2 curl -fsSL https://bun.sh/install | bash (inside WSL) Same as Linux.
Windows + Git Bash curl -fsSL https://bun.sh/install | bash (inside Git Bash) Same as Linux.
macOS brew install bun or curl -fsSL https://bun.sh/install | bash Either works; brew integrates with the rest of your formula updates.
Linux curl -fsSL https://bun.sh/install | bash The official one-liner.

After install, verify with bun --version (must be 1.0.0 or higher). If bun is not on PATH, restart your terminal — or on Windows, sign out and back in so the user PATH update takes effect.

For full Bun installation troubleshooting, see INSTALLATION.md.

Recommended VS Code Setup

For the best experience working with this plugin, install these VS Code extensions:

Extension Publisher Purpose
Claude Code for VS Code Anthropic Run Claude Code skills directly from the editor
Mermaid Chart Mermaid Chart Live preview of Mermaid diagrams (v11.4.1) with pan, zoom, and export

Why these extensions?

  • Claude Code is required to run the plugin's 9 skills from VS Code
  • Mermaid Chart lets you validate architecture diagrams (docs/*.md) in real-time as they are generated — supports native C4 diagrams, sequence diagrams, and all diagram types used by this plugin

Use Cases

Perfect for:

  • Enterprise architects documenting solution designs
  • Product Owners preparing requirements for architecture teams
  • Compliance teams generating organizational contracts
  • Technical leads maintaining architecture documentation
  • Development teams receiving component handoffs for implementation
  • Teams needing standardized architecture workflows

Workflow Integration

graph TD
    A[Product Owner] -->|Creates| B[PO Spec]
    B -->|Input to| C[Architecture Team]
    C -->|Creates| D[ARCHITECTURE.md]
    D -->|Generates| L[ADRs]
    L -->|Status Change| M{Propagation}
    D -->|Section Edit| M
    M -->|Updates| D
    M -->|Updates| J
    D -->|Peer Review| E{Quality Gate}
    E -->|Approved| F[10 Compliance Contracts]
    E -->|Refine| C
    F -->|Score ≥ 8.0| G[Auto-Approved]
    F -->|Score 7.0–7.9| H[Manual Review]
    G --> J[Dev Handoffs + Assets]
    H -->|Approved| J
    J -->|Export| K[Word .docx Deliverables]

External Validation System

All 10 compliance contracts use an external validation system with standardized 0-10 scoring:

Validation States & Scoring

  • ✅ PASS (10 points): Complies with requirements
  • ❌ FAIL (0 points): Non-compliant or deprecated technology
  • ⚪ N/A (10 points): Not applicable to this architecture
  • ❓ UNKNOWN (0 points): Missing data in ARCHITECTURE.md
  • 🔓 EXCEPTION (10 points): Documented exception via LADES2 process

Scoring Formula

Final Score = (Completeness × 0.4) + (Compliance × 0.5) + (Quality × 0.1)

Where:
- Completeness = (Filled required fields / Total required) × 10
- Compliance = (PASS + N/A + EXCEPTION items / Total applicable) × 10
- Quality = Source traceability coverage (0-10)

Approval Workflow

Score Status Review Actor Outcome
8.0-10.0 Approved System (Auto-Approved) Ready for implementation
7.0-7.9 In Review [Approval Authority] Manual review required
5.0-6.9 Draft Architecture Team Address gaps before review
0.0-4.9 Rejected N/A (Blocked) Cannot proceed to review

Validation Configuration

  • 10 JSON config files: One per contract type in /skills/architecture-compliance/validation/
  • Template-specific weights: Each contract can customize Completeness/Compliance/Quality weights
  • Validation schema: VALIDATION_SCHEMA.json defines standard structure
  • Example scenarios: VALIDATION_EXAMPLES.md shows all 4 outcome tiers

Roadmap

v3.28.8 (Current Release) ✅

fix(architecture-dev-handoff): correct relative-link depths in the handoff-document and c4-descriptor templates — they emitted wrong ../ depths on every run, which had to be sed-fixed by hand after each (re)generation

The dev-handoff templates hardcoded the wrong number of ../ segments for repo-back links, and the c4-descriptor template supplied no prefix at all — leaving the Haiku descriptor agent to guess the depth (it guessed ../../, one level short of the descriptor's real depth 3). The result: ../../ARCHITECTURE.md instead of ../ARCHITECTURE.md, ../components/ instead of ../docs/components/, and ../../adr/ instead of ../../../adr/ — every run.

Correct depths, by on-disk location:

  • Handoff document — handoffs/NN-<slug>-handoff.md (depth 1): ../ARCHITECTURE.md, ../docs/components/<file> (the docs/ segment is required).
  • C4 descriptor asset — handoffs/assets/NN-<slug>/c4-descriptor.md (depth 3): ../../../adr/…, ../../../docs/…, ../../../ARCHITECTURE.md.

Scope of this change (5 files, template link-paths + authoring notes):

  • agents/generators/handoff-generator.md — Section 0 metadata links fixed (../ARCHITECTURE.md, ../docs/components/…) plus a new "Link-path convention (do NOT recompute)" note stating the handoff doc's depth-1 location.
  • agents/generators/handoff-asset-generator.md — descriptor ADR links fixed to ../../../adr/… (English + Spanish variants) plus the matching depth-3 verbatim-emission note.
  • skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md, SECTION_EXTRACTION_GUIDE.md, ASSET_GENERATION_GUIDE.md — the reference-guide copies of the same templates kept in sync.

Why a "do NOT recompute" note: the descriptor bug was the agent re-deriving the relative depth and getting it wrong. Pinning the exact prefix in the template and telling the agent to emit it verbatim removes the guessing entirely.

Not affected: principle-quality-reviewer and other agents that reference files by path, and the user's own architecture docs — this was purely a skill-template defect. The agent .md files drive generation at runtime (the reference guides are bundled into them per SKILL.md); the guides were updated in lockstep so they don't drift.

Verification: post-edit greps confirm zero residual wrong-depth links (](../components/, ](../../ARCHITECTURE, bare `adr/ADR-`, ../../adr/) across all five files.

v3.28.7 (Previous Release) ✅

fix(agents): correct sub-agent type names in every orchestrator to match the role-namespaced registry — spawns were failing with Agent type 'sa-skills:<name>' not found because the SKILL.md orchestration strings still used the pre-reorg flat names

The agents were reorganized into role subdirectories (agents/{builders,generators,reviewers,validators}/), and the plugin resolves each agent's type by its subdirectory — so the registered types are sa-skills:builders:handoff-context-builder, sa-skills:generators:compliance-generator, etc. The SKILL.md orchestration instructions (and a few agent-doc prose references) were never updated after that move and still spawned the old flat sa-skills:<name> form, which the registry rejects at Task() time. The first symptom surfaced in architecture-dev-handoff, but the same latent breakage existed across the compliance, analysis, peer-review, and docs-export orchestrators.

Scope of this change (8 files, agent-type strings only):

  • skills/architecture-dev-handoff/SKILL.md — architecture-explorer, handoff-context-builder, handoff-generator, handoff-asset-generator.
  • skills/architecture-compliance/SKILL.md — architecture-explorer, compliance-generator (×13 spawn/prose sites) and all 10 validators (business-continuity, sre, cloud, data-ai, development, process, security, platform, enterprise, integration — ×21 sites).
  • skills/architecture-analysis/SKILL.md — architecture-explorer, architecture-analysis-agent.
  • skills/architecture-peer-review/SKILL.md — peer-review-category-agent.
  • skills/architecture-docs-export/SKILL.md — docs-export-generator.
  • agents/reviewers/architecture-analysis-agent.md, agents/generators/compliance-generator.md, agents/builders/handoff-context-builder.md — architecture-explorer prose references.

Not touched: principle-quality-reviewer references in architecture-docs use the file-path convention (agents/reviewers/principle-quality-reviewer.md), not an agent-type string, so they were never affected.

Verification: post-edit greps confirm zero remaining flat sa-skills:<name> agent-type refs, zero double-namespacing (sa-skills:role:role:), and every corrected type resolves to a real agents/<role>/<name>.md file.

v3.28.6 (Previous Release) ✅

feat(architecture-analysis + architecture-docs-export): consolidated Security Posture validation checklist — a new analysis 12 that merges the STRIDE and Data Sensitivity reports into a single reviewer-fillable list of every security control to validate, plus a Security Posture export mode that renders it to a Word worksheet with editable Status / Owner / Evidence cells

After running the two security-focused analyses (STRIDE per-trust-boundary threats, Data Sensitivity per-store control requirements), an architect is left with two separate reports and no single artifact a reviewer can walk down to confirm "is each required control actually in place?". This release adds that artifact. Analysis 12 (Security Posture) is a consolidation, not a fresh scan: it reads the existing STRIDE-<date>.md and DATA-SENSITIVITY-<date>.md reports and emits analysis/SECURITY-POSTURE-<date>.md — a checklist where every evaluated control becomes one row (PASS → ✅ Documented, FINDING → ⚠️ Gap (<source finding id>)), grouped into STRIDE Controls and Data Protection Controls tables with a counts summary and top-priority list.

Why synthesis lives upstream (in architecture-analysis) and export stays verbatim: the export generator's core contract is "no synthesis, no invention" — every .docx cell is extracted verbatim from a source file. Turning two analyses into a checklist is synthesis, so it belongs where synthesis is already sanctioned (the analysis agent, which cites every row back to a STRIDE cell or data gap id). The export skill then renders the resulting markdown verbatim, exactly like it does ADRs and handoffs — keeping the generator's contract intact and making the checklist independently usable as markdown.

Why a reviewer-fillable worksheet: the deliverable is a validation worksheet, not a briefing. The docgen security-posture type renders the Status, Owner, and Evidence columns as editable yellow cells (dashed borders, like the compliance Questions & Gaps Register) and value-colors the Sev / Tier column (High/Critical/S1 = red, Medium/S2 = amber, Low = green) so a security reviewer can mark each control Pass / Fail / N/A directly in Word.

Scope of this change (7 files + 1 new):

  • tools/docgen/generate-doc.js — new security-posture doc type (code SP, crimson #9C1F2E); docType threaded into parseMarkdown; a validation-checklist table renderer that detects editable columns by header name (Status / Owner / Evidence) so it works regardless of section wording, and color-codes the Sev / Tier column by value; usage / error strings updated.
  • skills/architecture-analysis/analyses/SECURITY_POSTURE.md — new consolidation spec (sources, consolidation model, check-ID scheme, report sections, missing-source fail-soft rule, markdown-only).
  • skills/architecture-analysis/SKILL.md — menu item 12, Step 2.6 dependency resolution (auto-runs STRIDE / Data Sensitivity first if absent), markdown-only rule, explorer-fanout exclusion, Step 3 dispatch row + explicit FILES list, completion summary / output tree / description.
  • agents/reviewers/architecture-analysis-agent.md — security-posture added to the type list + a Consolidation-analyses section (reads prior reports, no heat map, no EOL phase, markdown-only).
  • skills/architecture-docs-export/SKILL.md — new Workflow D (Export Security Posture) + What-Gets-Exported / Styling / Output / Prerequisites / Permissions (Read(analysis/*)) / frontmatter updates.
  • agents/generators/docs-export-generator.md — security-posture job_type + PHASE SP (pure verbatim render, one docgen call per report).
  • CLAUDE.md — trigger phrases (security posture, security posture validation, export security posture).

Backward compatibility: zero impact on the other 10 analyses and the three existing export modes — all additive. Security Posture has no HTML/d3 mode (it is a worksheet); the analysis agent never receives output_format=html for it. Also folds in a pre-existing fix swapping the analysis HTML report's d3 CDN from d3js.org to cdn.jsdelivr.net, matching the documented CDN.

Verification: bun run typecheck passes. docgen exercised end-to-end on the 8-column checklist schema — 15 editable yellow cells (5 rows × 3 columns), correct severity/tier coloring (red/amber), per-table reviewer notes, and the non-checklist Validation Summary table correctly left as a plain table (header-name detection working).

v3.28.5 (Previous Release) ✅

feat(architecture-analysis): right-side selection panel on the blast-radius force-directed network — when you click a node, a 260px-wide panel to the right of the main SVG lists the selected component's upstream callers and downstream consumers by canonical full name, with per-edge cascade-status tags (Cascading / Bulkhead / Fail-open / Fail-closed); auto-refreshes on every selection change, shows an empty-state hint when nothing is selected, wraps below the SVG on narrow screens via flexbox

The v3.28.4 click-to-highlight gesture dimmed everything except the selected node and its 1-hop neighbors visually, which is useful for focusing attention but still requires the reader to mouse over each highlighted circle to learn its name. For an architecture review, the question right after "what's the 1-hop neighborhood?" is "what are those nodes called and how do they connect?" — and the answer to that should be readable at a glance, not unfolded one tooltip at a time. This release adds a persistent side panel that surfaces exactly that information the moment a node is selected.

Why a side panel and not an inline tooltip-on-selection: a tooltip would either follow the cursor (and obscure the network) or pin to the selected node (and overlap with the highlighted neighborhood). A right-side panel keeps the network unobstructed, lists names in a stable location, and scales to selections of any neighborhood size (the panel scrolls internally up to 520px). It also separates the two concerns cleanly — the network shows topology and severity, the panel shows names and per-edge status.

Why upstream + downstream are listed separately: the same 1-hop neighborhood means two different things depending on direction. Upstream callers answer "who depends on this component" (the impact set if this node fails); downstream consumers answer "what does this component depend on" (the cascade set this node triggers). Splitting them in the panel — each with its own count — preserves the directional semantics that the undirected highlight rendering necessarily collapses.

Scope of this change (5 files):

  • skills/architecture-analysis/templates/viz/blast-radius.html — added a flex-row layout (.main-viz-row / .main-viz-col-svg / .main-viz-col-panel) that wraps the existing SVG and a new .selection-panel div side-by-side; a @media (max-width: 720px) rule wraps the panel below the SVG on narrow screens. Self-contained CSS injected via root.append("style") covering the layout, the panel chrome (border-left accent, surface-alt background, max-height + internal scroll), the per-section structure (h5 caption, ul list, item-name + cascade-tag flex row), and the empty-state styling. The existing updateHighlight() function extended with two render paths: when selectedId === null it shows the empty-state hint ("Click a node in the network to see its 1-hop vicinity…"), otherwise it builds two arrays — upstream (links whose target equals the selected) and downstream (links whose source equals the selected) — from the original string-keyed data.graph.links, looks up each neighbor's canonical full name from a precomputed Map<id, node>, HTML-escapes every rendered value, and writes a panel containing the selected node's name + tier/fan-out, followed by Upstream callers (N) and Downstream consumers (N) sections with per-row cascade-status tags color-coded to match the network's edge palette. Legend hint extended: "click a node to highlight its 1-hop neighbors (names listed in the side panel) · click canvas to reset · …".
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.28.4 → 3.28.5; plugin description appended with the new release marker.

Backward compatibility: zero impact on Markdown mode (no skeleton, agent contract, or spec changes). Zero impact on the other 9 viz types — their snippets are untouched. The panel is driven entirely from data already in data.graph (which the agent has been populating since v3.28.0), so no agent-contract changes are needed — older agent payloads still render correctly. The v3.28.2 pan/zoom + v3.28.3 per-scenario trees + v3.28.4 click-to-highlight all continue to work unchanged; the panel is purely additive. Existing analysis/BLAST-RADIUS-<date>.html files are not re-rendered; the next consumer-side run produces the panel-equipped output. All rendered names pass through escapeHtml() to neutralise any </>/&/"/' that might appear in a component name or cascade label.

Verification: bun run typecheck passes (no TypeScript files touched). bun test — 225/225 pass, no regressions. grep -c "selection-panel\|panel-section\|nodeById\|escapeHtml" skills/architecture-analysis/templates/viz/blast-radius.html returns multiple matches (CSS class declarations + their uses + lookup map + escape helper, all referenced consistently). git diff --name-only HEAD shows exactly blast-radius.html + the 3 version files + README — no other viz files touched, no agent contract changes. End-to-end browser check on the account-summary blast-radius HTML report: open the report, see the empty-state hint in the panel; click any node — the panel populates with that node's name, tier, fan-out, upstream caller list, and downstream consumer list each tagged with the appropriate cascade status; click the same node again or click empty canvas — the panel returns to the empty-state hint and the network resets; resize the browser narrower than 720px — the panel wraps below the SVG instead of being pushed off-screen.

v3.28.4 (Previous Release) ✅

feat(architecture-analysis): click-to-highlight 1-hop neighbors on the blast-radius force-directed network — clicking any node dims everything except itself and its immediate upstream / downstream neighbors to 18% opacity (edges to 12%), selected node gets a thicker accent-colored stroke; click the same node again, or click empty canvas, to reset; composes cleanly with the existing pan/zoom + node-drag from v3.28.2 via event.defaultPrevented + stopPropagation guards

The previous blast-radius force-directed network from v3.28.0–v3.28.3 was already navigable (pan, zoom, drag-a-node, hover-for-tooltip) but read-only beyond hover — there was no way to focus attention on a single component's immediate neighborhood. For an 18-node, 20-edge architecture like account-summary this is borderline manageable, but as architectures grow it becomes hard to answer "what depends on X" or "what does X cascade into" without manually tracing edges. This release adds the canonical "neighborhood highlight" interaction.

Why 1-hop both directions (not downstream-only): a blast-radius reviewer cares about two questions simultaneously — "what fails because this node fails?" (downstream cascade) and "who depends on this node?" (upstream callers, the impact set). Highlighting both directions in one gesture answers both at once. If the user needs unidirectional later, the data is already there (link source vs target are preserved on the link objects) so it's a one-flag extension.

Why composition with pan/zoom + drag matters: the d3 zoom behavior calls preventDefault on every gesture step, and the d3 drag behavior calls preventDefault during a drag — both leave event.defaultPrevented === true on the synthetic click event that fires when the gesture ends. The click handler on each node and the click handler on the svg background both guard with if (event.defaultPrevented) return; so neither a pan-end nor a drag-end is mistaken for a "select node" or "clear selection" click. The node-click handler also calls event.stopPropagation() so a deliberate node click does not bubble to the svg background and immediately clear the selection. These guards are why the new feature does not break the v3.28.2 pan/zoom or the original node-drag.

Scope of this change (5 files):

  • skills/architecture-analysis/templates/viz/blast-radius.html — appended a click-to-highlight block after the existing svg.call(d3.zoom()…) registration. Builds an undirected adjacency Map<nodeId, Set<nodeId>> from data.graph.links (using the original string-keyed source/target, not the post-forceLink mutated object references) so each node maps to a set containing itself plus all 1-hop neighbors. Adds a selectedId state variable and an updateHighlight() function that sets style("opacity", …) on nodes and edges (18 % / 12 % dim, 1 full) and switches the selected node's outline to var(--accent) with stroke-width: 3. Node-click handler toggles selectedId (clicking the same node twice deselects); svg-background click clears the selection. Legend hint extended: "… · click a node to highlight its 1-hop neighbors · click canvas to reset · …".
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.28.3 → 3.28.4; plugin description appended with the new release marker.

Backward compatibility: zero impact on Markdown mode (no skeleton, agent contract, or spec changes). Zero impact on the other 9 viz types — their snippets are untouched. The per-scenario cascade tree diagrams added in v3.28.3 remain unchanged. The new interaction is purely additive on the main force-directed network: hover, drag, pan, zoom, and now click-to-highlight all coexist. Existing analysis/BLAST-RADIUS-<date>.html files in consumer projects are not re-rendered; the next HTML run produces the click-highlightable output. d3.zoom and d3.drag are unchanged; no new CDN dependency.

Verification: bun run typecheck passes (no TypeScript files touched). bun test — 225/225 pass, no regressions. grep -c "selectedId\|updateHighlight\|neighbors" skills/architecture-analysis/templates/viz/blast-radius.html returns multiple matches (state variable, function, adjacency map, all referenced consistently). git diff --name-only HEAD shows exactly blast-radius.html + the 3 version files + README — no other viz files touched. End-to-end browser check on the account-summary blast-radius HTML report: click any node → that node and its 1-hop neighborhood stay at full opacity, everything else dims; click the same node again → reset; click empty canvas → reset; pan, zoom, drag, and hover tooltips all continue to work.

v3.28.3 (Previous Release) ✅

feat(architecture-analysis): per-scenario cascade diagrams restored in blast-radius HTML mode — three small standalone d3 hierarchy trees (one per top-severity source node) rendered inside the main <section id="visualization"> immediately below the force-directed network, driven by a new data.scenarios JSON key; root = failed source (red), downstream nodes color-coded cascading-red vs contained-green; no hand-coded SVG, no extra <section> blocks

The v3.28.1 fix had removed the per-scenario cascade diagrams entirely (replaced with an HTML table) because the previous v3.28.0 agent-rendered hand-coded SVGs were broken (Scenario 3 overflow, backwards edges, nested <code> inside SVG <text>). The user confirmed they want the per-scenario individual graphics back — but as proper d3 visualizations this time. This release restores the diagrams as small standalone d3 hierarchy trees, each screenshottable in isolation for slide decks or pre-incident reviews, using the same severity color palette as the rest of the report. The HTML table from v3.28.1 stays in {{FINDINGS_HTML}} as the factual breakdown that accompanies the diagrams.

Why d3 trees and not the original Mermaid translation: d3 hierarchy() + tree() give per-scenario layouts that scale with depth and leaf count automatically (no manual coordinate computation, no overflow, no fragile hand-positioned <rect>/<line>/<text> elements). Markdown mode is unchanged — the spec's Mermaid flowcharts render normally there. HTML mode now has actual interactive diagrams (hover for component name + cascade status), the table for textual scanning, AND the main force-directed network — three complementary projections of the same finding evidence with zero invention.

Why this is a multi-sub-diagram pattern (and why it's not a One-Viz Rule violation): the v3.28.1 One-Viz Rule was about preventing the agent from inventing new <section> blocks or hand-coding SVG. It does NOT constrain what a viz snippet's own d3 code emits inside its single #viz div. The blast-radius snippet now renders the main force-directed network PLUS per-scenario hierarchy trees, all inside the same <section id="visualization"> — a multi-diagram snippet driven by additional data.* keys. The agent contract at Phase 5b.0.5 is extended with an explicit note codifying this distinction so future viz snippets can follow the same pattern when their analysis benefits from per-finding mini-diagrams.

Scope of this change (5 files):

  • skills/architecture-analysis/templates/viz/blast-radius.html — appended a guarded if (Array.isArray(data.scenarios) && data.scenarios.length > 0) { … } block at the end of the existing IIFE. Injects self-contained CSS via root.append("style") (.scenarios-section, .scenario-card, .tree-node), creates a <div class="scenarios-section"> with an <h3> header, and iterates each scenario. Per scenario: a .scenario-card with <h4> title + optional caption + a responsive SVG containing a d3.hierarchy(scenario.tree) laid out by d3.tree().size([innerH, innerW]). Edges colored var(--sev-critical) (solid) for Cascading/Fail-closed and var(--sev-pass) (dashed) for Bulkhead/Fail-open. Nodes colored by cascade status — root always var(--sev-critical), downstream nodes red for cascading, green for contained. Hover tooltips show component name + cascade status. Layout grows with depth (width) and leaf count (height) so trees self-size without overflow. The leading file comment gains the data.scenarios shape annotation.
  • agents/reviewers/architecture-analysis-agent.md — three Phase 5b edits. (1) 5b.0 blast-radius row rewritten: cascade scenarios are NOT omitted; they are rendered as per-scenario d3 trees by the viz snippet (the agent only populates data.scenarios). The HTML table in {{FINDINGS_HTML}} still accompanies the diagrams. (2) 5b.1 shape table extended for blast-radius with the full data.scenarios JSON contract: [{ title, source_id, caption?, tree: { name, cascade: "root", children: [{ name, cascade, children: […] }] } }], exactly the top 3 highest-severity source nodes from the spec's "Cascade Paths" section, with the same finding evidence as the Mermaid block in markdown mode. (3) 5b.0.5 One-Viz Rule gets a clarifying paragraph: a single viz snippet MAY render multiple d3 sub-diagrams inside its #viz div as long as they are driven by data.* keys (no hand-coded SVG, no extra <section> blocks).
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.28.2 → 3.28.3; plugin description appended with the new release marker.

Backward compatibility: zero impact on Markdown mode — the spec, agent Phase 5a, and templates/analysis-report-skeleton.md are untouched. Zero impact on the other 9 viz types — their snippets are unchanged, none of them carry per-scenario data. HTML reports generated before v3.28.3 are not re-rendered automatically; the next blast-radius HTML run produces the new per-scenario tree diagrams. The HTML shell, placeholder set, and CSS palette are all unchanged — the .scenarios-section / .scenario-card styles are injected by the viz snippet itself via root.append("style") so the shared skeleton stays free of viz-specific rules. If data.scenarios is omitted (e.g. an older agent payload), the snippet skips the scenarios block silently — no error, no broken render.

Verification: bun run typecheck passes (no TypeScript files touched). bun test — 225/225 pass, no regressions. grep -c "d3.hierarchy\|d3.tree" skills/architecture-analysis/templates/viz/blast-radius.html returns at least 2. grep -c "scenarios-section\|scenario-card" skills/architecture-analysis/templates/viz/blast-radius.html returns at least 4 (CSS class declaration + uses in append("div").attr("class", ...)). The next consumer-side blast-radius HTML run renders three scenario cards below the main network, each with a d3 horizontal tree, hover tooltips, and the same severity colors as the rest of the report.

v3.28.2 (Previous Release) ✅

feat(architecture-analysis): pan + zoom on the blast-radius force-directed network — d3.zoom() attached to the svg, all link + node groups now live inside a viewport <g> that receives the transform, node-drag behavior preserved unchanged, scaleExtent clamped to 30 %–400 %, legend hint extended so the new gestures are discoverable in-place without reading docs

The d3 force simulation in the blast-radius viz computes positions that occasionally push 2–4 peripheral nodes outside the fixed 760 × 480 viewBox — and once they were off-screen there was no way to navigate to them. The previous behavior only allowed d3.drag() on individual nodes (move one node), with no canvas-level pan or zoom. As architectures grow beyond the 18-component test architecture this becomes a discoverability problem.

Why this matters: an architecture diagram you cannot fully see is not a useful diagram. The user discovered the gap on the first real account-summary run after the v3.28.1 fixes — the d3 viz rendered, but some components were not in the initial view and there was no obvious gesture to find them. This release closes that gap with the canonical d3 pattern (zoomable inner <g> + d3.zoom() on the svg) so the same viz scales to architectures of any size.

Scope of this change (4 files):

  • skills/architecture-analysis/templates/viz/blast-radius.html — three surgical edits inside the existing IIFE body. (1) A new const viewport = svg.append("g").attr("class", "viewport") inserted after the defs block; the arrowhead marker stays in defs (outside the viewport so it scales correctly at any zoom level). (2) Both link and node groups re-anchored from svg.append("g") to viewport.append("g"), so they receive the zoom transform together. (3) After the simulation tick handler, svg.call(d3.zoom().scaleExtent([0.3, 4]).filter(e => !e.button).on("zoom", e => viewport.attr("transform", e.transform))) is registered — left-click drag on empty canvas pans, scroll wheel zooms around the cursor, node drag continues to work because d3.drag() calls event.sourceEvent.stopPropagation() on its mousedown listener so the zoom behavior never sees node-originated mousedowns. The trailing legend hint is extended to "solid edge = cascading · dashed = bulkhead / fail-open · drag canvas to pan · scroll to zoom · drag a node to reposition" so the gestures are discoverable inside the rendered viz.
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.28.1 → 3.28.2; plugin description appended with the new release marker.

Backward compatibility: zero impact on Markdown mode (no skeleton, agent contract, or spec changes). Zero impact on the other 9 viz types — they use bounded layouts (scatter on a fixed 3 × 3 grid, horizontal bars, Pareto, STRIDE matrix, treemap, stacked bars, Gantt timeline, chord on a fixed-radius circle, Sankey on a bounded grid) and none of their snippets are touched. The HTML shell is unchanged; the viewport group is a viz-internal implementation detail invisible to the agent or the orchestrator. Existing analysis/BLAST-RADIUS-<date>.html files in consumer projects are not re-rendered; the next HTML run produces the pan/zoom-capable output. d3.zoom is part of d3 v7 core (already loaded by the skeleton from CDN), so no new dependency.

Verification: bun run typecheck passes (no TypeScript files touched). bun test — 225/225 pass, no regressions. grep -c "d3.zoom" skills/architecture-analysis/templates/viz/blast-radius.html returns 1 (the new zoom registration). grep -c "viewport" skills/architecture-analysis/templates/viz/blast-radius.html returns 4 (one declaration + three uses — append/link/node). git diff --name-only HEAD~1 (after release) shows exactly blast-radius.html + the three version files + README.md, confirming the surgical scope. End-to-end browser test on the account-summary blast-radius report: all 18 nodes reachable via scroll-out, canvas drag pans the entire graph, node drag still moves individual nodes without panning, tooltips remain correctly positioned at every zoom level.

v3.28.1 (Previous Release) ✅

fix(architecture-analysis): three independent HTML-mode bugs from the first real run — empty d3 viz (script-ordering + cross-<script> scope), hand-coded <svg> cascade scenarios with broken layout, and ASCII heat maps rendered verbatim in <pre> blocks. Skeleton restructured so {{ANALYSIS_DATA_JSON}} and {{VIZ_BLOCK}} share ONE <script> block; 10 viz snippets shipped without outer <script> wrappers; agent Phase 5b gains explicit section-omission table, one-viz rule, verbatim viz-snippet rule, and three new pre-write verification checks

The v3.28.0 HTML feature was exercised against a real architecture for the first time and produced analysis/BLAST-RADIUS-2026-05-26.html with three independent failures: the force-directed dependency network rendered as an empty <div>, the "Cascade Paths — Top 3 Worst Scenarios" section appeared as three broken hand-coded <svg> blocks (Scenario 3 had overflowing labels, backwards edges, and nested <code> tags inside SVG <text>), and the ASCII heat map appeared verbatim inside a <pre> block as a duplicate <section id="heatmap">. Root cause for all three: the v3.28.0 skeleton and agent contract were under-specified at exactly the three seams the agent freelanced.

Why this matters: the HTML output mode is the feature stakeholders see — a security officer, finance partner, or compliance reviewer who opens a .html file expects an interactive corporate-grade report, not an empty viz, a broken SVG, and an ASCII art block. Each of the three bugs was a contract gap rather than a logic error: the d3 code was correct, the per-analysis data was correct, the spec content was correct. What was missing was (a) a single shared lexical scope for the embedded data global and the viz IIFE, (b) an explicit rule that the agent must not hand-code SVG, and (c) an explicit list of spec sections that the d3 viz subsumes in HTML mode. All three are closed here, leaving the v3.28.0 feature actually usable.

Why d3's data global needs one <script> block, not two: const and let are block-scoped, so two <script> blocks do not share const data = {...};. The v3.28.0 skeleton placed {{ANALYSIS_DATA_JSON}} in a body-bottom <script> and {{VIZ_BLOCK}} in a mid-body <script> inside the visualization <section> — the viz IIFE could never reach data. The agent compensated by emitting window._FOO_DATA = {...} (cross-script-global pattern, which DOES attach to window), but the body-bottom data block still executed after the viz script in document order, so window._FOO_DATA was undefined at viz-run time and the early-exit guard fired. The v3.28.1 fix is structural: one <script> block holds both tokens. No cross-script global, no script-ordering risk, const data is visible to the viz via plain lexical scope.

Scope of this change (15 files, 1 created → none; 14 modified):

  • skills/architecture-analysis/templates/analysis-report-html-skeleton.html — visualization <section> now wraps {{ANALYSIS_DATA_JSON}} and {{VIZ_BLOCK}} in a single <script> block (with an in-place HTML comment explaining why the two tokens must stay together). Body-bottom <script> reduced to the d3 load-guard only. Header docstring updated to document the new contract for {{ANALYSIS_DATA_JSON}} (single statement, no window. prefix, inlined inside the viz section's <script> block).
  • skills/architecture-analysis/templates/viz/{spof,blast-radius,bottleneck,cost-hotspots,stride,vendor-lockin,latency-budget,tech-debt,coupling,data-sensitivity}.html (10 files) — outer <script> opening tag and </script> closing tag stripped from each file. The IIFE body, the leading HTML comment documenting the expected data.<key> shape, and all d3 logic are unchanged. The bare IIFE bodies are now inlined inside the skeleton's outer <script> block at render time.
  • agents/reviewers/architecture-analysis-agent.md — Phase 5b gains four new constraints. 5b.0 Section Omission Rules: per-analysis table listing spec sections that are markdown-only and MUST be omitted in HTML mode because the d3 viz subsumes them (e.g. SPOF "Risk Heat Map" ASCII → omitted, replaced by d3 scatter; Blast Radius "Cascade Paths" Mermaid → omitted, replaced by an HTML table; Blast Radius "Heat Map" ASCII → omitted; Coupling Mermaid cycle subgraphs → HTML table; Data Sensitivity per-flow Mermaid sequence diagrams → HTML table). 5b.0.5 One-Viz Rule: exactly one <section id="visualization"> is permitted; no extra <section> blocks, no hand-coded <svg> anywhere in any HTML fragment, no <pre> blocks carrying ASCII heat maps / bar charts / histograms / flow diagrams. 5b.3 verbatim viz-snippet rule (tightened): the inlined viz body is copied VERBATIM — do not rename the data global, do not introduce window.foo indirection, do not add <script> tags around the inlined IIFE body, do not edit comments. 5b.4 verification additions: pre-write checks for (i) no leftover {{TOKEN}} placeholders (existing), (ii) exactly one <section class="report-section" id="visualization"> substring (new), (iii) no window._ substring anywhere in any <script> block (new — catches the cross-script-global anti-pattern). Any failure falls back to writing the Markdown render to a .md sibling and reports the error in Phase 7.
  • skills/architecture-analysis/SKILL.md — one bullet appended to the HTML format notes subsection codifying the omission rule for stakeholder reference: ASCII heat maps, ASCII bar charts, ASCII histograms, and Mermaid diagrams are omitted in HTML mode; cascade scenarios, cycle subgraphs, and sequence diagrams surface as HTML tables.
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.28.0 → 3.28.1; plugin description appended with the new release marker.

Backward compatibility: zero impact on Markdown mode — the spec files, agent Phase 5a, and templates/analysis-report-skeleton.md are untouched, so Markdown reports are byte-for-byte identical to v3.28.0 output. The previously-broken analysis/BLAST-RADIUS-2026-05-26.html in any consumer project is NOT re-rendered automatically; the next HTML run produces the corrected output. The HTML skeleton's placeholder contract is unchanged in terms of token names — {{ANALYSIS_DATA_JSON}} still expects const data = { ... }; — but its position in the document moves from body-bottom to inside the visualization <section>'s <script> block. Any consumer who has hand-edited the bundled skeleton or viz snippets would lose those edits at upgrade time, but no in-tree skill or agent edits this content at runtime. The agent's Phase 5b output is now strictly smaller in HTML mode (fewer <section> blocks, no hand-coded SVG, no <pre> ASCII) — purely a reduction in surface area, no behavioural extension.

Verification: bun run typecheck passes (no TypeScript files touched). bun test — 225/225 pass, no regressions. grep -c "^<script>\\|^</script>" skills/architecture-analysis/templates/viz/*.html returns 0 for all 10 files. grep -n "{{ANALYSIS_DATA_JSON}}" skills/architecture-analysis/templates/analysis-report-html-skeleton.html returns exactly one match — inside the visualization <section>. The next consumer-side run of /skill architecture-analysis in HTML mode will produce reports where (a) the d3 viz renders, (b) no hand-coded SVG appears in the findings, and (c) ASCII heat maps from the spec are absent — replaced by the d3 viz alone.

v3.28.0 (Previous Release) ✅

feat(architecture-analysis): interactive d3.js v7 HTML output mode — runtime format selector (Markdown / HTML) lifted into a new blocking Step 2.4 in skills/architecture-analysis/SKILL.md, corporate-styled self-contained HTML shell (templates/analysis-report-html-skeleton.html) with {{PLACEHOLDER}} substitution, and ten per-analysis d3 visualization snippets under templates/viz/ (SPOF scatter heat map, Blast Radius force-directed dependency network, Bottleneck capacity-headroom bars, Cost Hotspots Pareto chart with cumulative-% overlay, STRIDE per-trust-boundary matrix, Vendor Lock-in treemap, Latency Budget per-flow stacked bars with SLO ceiling, Tech Debt EOL Gantt timeline, Coupling chord diagram, Data Sensitivity Sankey via d3-sankey)

Closes the longest-standing presentation gap in architecture-analysis: the skill produced ten high-quality risk and sustainability reports, but every output was ASCII heat maps + pipe tables inside a .md file — readable in a terminal, weak when shared with non-engineering stakeholders. Security officers, finance partners, compliance reviewers, and executive sponsors do not consume Markdown; they consume browser pages and slide decks. The Markdown source-of-truth stays intact and remains the default; HTML is an opt-in alternative chosen at runtime per run.

Why this matters: an analysis report's value is bounded by how widely it can travel. A SPOF heat map with finding IDs plotted in a 3×3 Impact × Likelihood grid lands very differently as an interactive d3 scatter (drag-to-explore, tooltip with full scenario text, severity-tier color band) than as an ASCII block in a code fence. The same observation applies across every analysis type — a Pareto cost chart with a real 80% cumulative line, a force-directed blast-radius graph with cascade-vs-bulkhead edge styling, a chord diagram showing god-object coupling, a Sankey of PII flow with encryption-gap edges highlighted. None of this requires inventing new data — every viz is a projection of the findings already in the report; the JSON payload embedded in the HTML must contain only entries that also appear in the rendered tables (enforced in the agent's Report Quality Rules section as an extension of the no-invention policy). The result: same findings, two presentation surfaces, one runtime choice.

Why d3.js and not a chartless dashboard: each of the ten analyses has a different natural visualization (scatter for SPOF, force-directed for blast radius, treemap for vendor concentration, Sankey for PII flow, chord for coupling). A generic chart library would have forced bar-chart-everything. d3.js v7 + d3-sankey from CDN gives each viz the right primitive without a build step or shared chart abstraction — every snippet is 60–150 lines, reads the data global, and renders into a single <div id="viz">. The shell loads d3 once; viz snippets are self-contained scripts inlined at render time.

Scope of this change (16 files, 14 new + 2 modified skill files; trigger row + plugin manifest also updated):

  • skills/architecture-analysis/templates/analysis-report-html-skeleton.html (new, ~12.9 KB) — shared corporate-themed HTML shell. Muted blue / slate palette with WCAG-AA severity tokens (--sev-critical: #b91c1c, --sev-high: #d97706, --sev-medium: #ca8a04, --sev-low: #65a30d, --sev-pass: #15803d), system-ui typography, print stylesheet, responsive container max-width 1180px. Loads d3.v7.min.js + d3-sankey.v0.12.min.js from CDN with a typeof d3 === "undefined" guard that surfaces a user-visible fallback banner when the page is opened offline (tables/prose still render; only the viz <div> shows an "unavailable without d3.js" notice). Sixteen {{TOKEN}} placeholders cover every render-time slot: title, header meta, exec summary, findings HTML, viz title, viz block, recommendations, verdict, gaps, citations, and the embedded const data = { ... }; payload.
  • skills/architecture-analysis/templates/viz/{spof,blast-radius,bottleneck,cost-hotspots,stride,vendor-lockin,latency-budget,tech-debt,coupling,data-sensitivity}.html (10 new files, ~3.3–4.8 KB each) — one self-contained d3 v7 snippet per analysis type. Each declares its expected data.<key> shape in a leading HTML comment (so the agent can match it without reverse-engineering the script), then renders into the shell's <div id="viz"> with hover-tooltip, severity legend, and viewBox-based responsive sizing. The Sankey snippet checks for typeof d3.sankey === "function" and degrades gracefully if the secondary CDN script fails to load.
  • skills/architecture-analysis/SKILL.md — new Step 2.4 — Select Output Format (blocking, between analysis-selection and the per-analysis explorer fan-out): single prompt 1=Markdown / 2=HTML, no silent default, stores output_format for downstream steps. Step 3 prompt builder gains three conditional inputs (output_format, html_skeleton_path, viz_template_path) emitted to the agent only in HTML mode; output_path extension is swapped to .html accordingly. Step 4 completion summary uses .<ext> placeholders so the printed file list matches the chosen format, and an HTML-mode tip block adds open / xdg-open / start invocations plus the no-internet caveat (tables work offline; viz needs the CDN). The Files-in-This-Skill table gains rows for the new HTML skeleton and the templates/viz/ directory. A new "HTML format notes" subsection under Output Location codifies the self-contained-single-file guarantee, the d3 CDN dependency, and the same-findings-both-formats invariant.
  • agents/reviewers/architecture-analysis-agent.md — Input Parameters section gains output_format (default markdown when absent — backward compatible), html_skeleton_path (HTML mode only), viz_template_path (HTML mode only). Phase 0 forks: markdown mode reads skeleton_path as before; HTML mode reads html_skeleton_path + viz_template_path and ignores skeleton_path. Phase 5 is split into 5a (Markdown — unchanged 8-step render) and 5b (HTML — four sub-steps): 5b.1 builds the analysis_data JSON object matching the per-analysis viz schema (full shape table for all 10 analyses inlined in the agent prompt so the JSON contract is explicit, not inferred); 5b.2 renders findings tables / recommendations / gaps / citations as HTML fragments using the shell's CSS classes (.sev.critical, .row-high, .recommendation, .gaps, etc.); 5b.3 performs the string-substitution of all 16 {{TOKEN}} placeholders including per-analysis {{VIZ_TITLE}} (canonical titles tabulated in the agent prompt); 5b.4 verifies no placeholder leaked through and falls back to writing the Markdown render to the same path with .md extension if any did. The Report Quality Rules section gains an HTML-output addendum that ties (a) the no-invention rule to the embedded JSON ("contain only entries that also appear in the rendered findings tables"), (b) the self-contained-file requirement (only the d3 + d3-sankey CDN refs are permitted), and (c) the Component Naming Fidelity rule to the viz data payload and tooltips (canonical full name in data, visual truncation with … is the viz snippet's job, not the data's).
  • CLAUDE.md — the architecture-analysis row in the Trigger Routing — Exact Phrases table is rewritten to surface the runtime format choice: "Risk & sustainability reports in analysis/ — output format is asked at runtime (Step 2.4) after analysis selection: Markdown (.md, grep-friendly, default) OR HTML (.html, interactive d3.js v7 + d3-sankey, corporate styling, requires internet for viz). The same findings populate either format."
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.27.3 → 3.28.0; plugin description appended with the new release marker.

Backward compatibility: zero impact on existing markdown workflows. The orchestrator defaults to nothing — Step 2.4 is blocking and explicit — but output_format defaults to markdown inside the agent if the orchestrator omits the parameter, so any older caller or replay continues to produce .md files byte-for-byte equivalent to a pre-3.28 run. None of the analysis specs (analyses/*.md) were modified — classification rules, evidence extraction tables, and required Report Sections all produce the same findings data in either render path. Markdown remains the source of truth and the only format that architecture-docs-export (Word .docx generation) consumes; HTML is an additional presentation surface for stakeholder socialisation, not a replacement. Re-running the same analysis on the same day with a different format produces a sibling file (.md and .html coexist on disk) — no overwrite collision.

Verification: bun run typecheck passes (no TypeScript files touched). bun test — 225/225 pass, no regressions. ls skills/architecture-analysis/templates/viz/ lists all ten viz snippets (one per analysis_type). grep -c "{{TOKEN}}\|{{[A-Z_]*}}" skills/architecture-analysis/templates/analysis-report-html-skeleton.html confirms 16 placeholders match the 16 substitutions documented in the agent's Phase 5b.3 table. The HTML shell's CDN URL (https://d3js.org/d3.v7.min.js) is the canonical d3.js v7 minified bundle URL; the secondary d3-sankey URL (https://d3js.org/d3-sankey.v0.12.min.js) is loaded by the shell as well so the Sankey snippet works without a separate import. No new permissions required — Write(analysis/*) already covers .html files alongside .md.

v3.27.3 (Previous Release) ✅

feat(architecture-compliance): data_catalog and pipeline_orchestration added as discrete check items in the Mnemosyne (Data & AI) validator — new "Data Infrastructure" 5th category (DAI-14, DAI-15) in agents/validators/data-ai-validator.md, matching grep patterns and phase3.data_points entries in agents/configs/data-ai.json, and two new template subsections (6.5 Pipeline Orchestration under LAD6, 8.5 Project Data Catalog under LAD8) in cc-003-data-ai-architecture.template.md

Closes a gap where the Mnemosyne validator's 13 inline checks (Data Governance / Data Quality / AI/ML Governance / Privacy & Compliance) did not score two first-class data-platform concerns: discoverability via a data catalog, and reliability/recoverability via pipeline orchestration. Both concepts were previously only mentioned in passing inside template remediation notes (data catalog appeared twice; Airflow/Dagster/Prefect were absent entirely), so generated contracts surfaced them only as optional advice rather than as scored line items.

Why this matters: a data catalog underpins lineage, stewardship, and discovery — it is the addressable map from "which datasets exist" to "who owns them and how to consume them" — and it is the natural project-level counterpart to the already-scored 8.4 Institutional Catalog Compliance subsection. Pipeline orchestration determines whether multi-step ETL/ELT flows have job-scheduling, dependency graphs, retry policy, and SLA monitoring, or whether they rely on bare cron jobs that silently fail. Both belong in the Data & AI contract scoring surface, not in remediation footnotes.

Scope of this change (3 files):

  • agents/validators/data-ai-validator.md — new ### Data Infrastructure (2 items) category appended after Privacy & Compliance with DAI-14 (data catalog: tool identification + coverage + ownership) and DAI-15 (pipeline orchestration: platform + scheduling/dependencies + retry/SLA), two new evidence-collection grep patterns (amundsen|datahub|collibra|alation|glue catalog|unity catalog for catalog; airflow|dagster|prefect|luigi|argo workflows|step functions|cloud composer for orchestration), and two new rows (DAI-14, DAI-15) in the VALIDATION_RESULT output table.
  • agents/configs/data-ai.json — two new entries each appended to key_data_points, focus_areas, and agent_notes; two new phase3.data_points[] entries (Data Catalog → docs/06-technology-stack.md; Pipeline Orchestration → docs/06-technology-stack.md) using the same tool + concept patterns as the validator. domain.requirement_count (11), domain.requirement_range (LAD1-LAD8, LAIA1-LAIA3), and requirement_codes_list are deliberately left unchanged.
  • skills/architecture-compliance/templates/cc-003-data-ai-architecture.template.md — new subsection ### 6.5 Pipeline Orchestration inserted under Section 6 Data Integration (LAD6) after 6.4 Data Consistency Management, with three sub-items (Orchestration Platform / Job Scheduling and Dependencies / Retry and SLA Policy); new subsection ### 8.5 Project Data Catalog inserted under Section 8 Data Architecture Standards (LAD8) after 8.4 Institutional Catalog Compliance, with three sub-items (Catalog Tooling / Catalog Coverage / Catalog Ownership and Maintenance). Both subsections mirror the existing Status / Explanation / Source / Note four-field per sub-item shape used everywhere else in the template.
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.27.2 → 3.27.3; plugin description appended with the new release marker.

Backward compatibility: zero impact on existing consumer architecture documents or already-generated compliance contracts — this is an additive change to the validator's check inventory and the template's subsection inventory, with no renumbering of existing requirement codes (still LAD1-LAD8, LAIA1-LAIA3, count 11) and no renumbering of existing DAI-* IDs (DAI-01 through DAI-13 unchanged). The 13/15 inline-check vs 11-requirement-code mismatch was already present (the validator's checks evaluate coverage in architecture docs while requirement codes structure the contract handed to the Data & AI Architecture Review Board); the new checks extend that coverage surface without disturbing the contract structure. The next time a consumer re-runs architecture-compliance for the Data & AI contract, the Mnemosyne validator will return 15 items (DAI-01…DAI-15) and the generated contract will include populated 6.5 and 8.5 subsections (filled where evidence is found in docs/06-technology-stack.md, marked Unknown/Gap where absent).

Verification: bun -e 'JSON.parse(...)' over agents/configs/data-ai.json succeeds. grep -n "Data Infrastructure (2 items)" agents/validators/data-ai-validator.md outputs 1. grep -n "^### 6.5 Pipeline Orchestration\|^### 8.5 Project Data Catalog" skills/architecture-compliance/templates/cc-003-data-ai-architecture.template.md outputs both new subsections. bun run typecheck passes (no TypeScript files touched). bun test — 225/225 pass, no regressions.

v3.27.2 (Previous Release) ✅

fix(architecture-docs): Anti-Pollution Framing added to the canonical Connection Naming Rule in DIAGRAM-GENERATION-GUIDE.md — explicit one-edge-per-(A→B, [Action Type]) uniqueness constraint plus a "What Does NOT Belong on the Edge" routing table that names docs/04-data-flow-patterns.md and docs/07-security-architecture.md as canonical homes for operational and security detail; all violating worked examples in MERMAID_DIAGRAMS_GUIDE.md (full working example, sync/async/bidirectional sub-sections, Diagram Legend, and all 5 How-To scenarios) rewritten to the canonical <PROTOCOL>/<STYLE> [Action Type] form

This release closes the gap between the canonical Connection Naming Rule (which has been authoritative since the rule landed) and the worked examples that the same guide ships — the examples were leaking <br/>mTLS, 30s timeout, 3 retries, Consumer Group: <name>, and STARTED<br/>COMPLETED<br/>FAILED event-type sequences onto edges, contradicting the very rule the document declares. Architects copying from those examples were propagating the over-rich form into new architectures, where it made L2 / Diagram 4 views unreadable as the system grew. The fix is two-part: tighten the canonical rule with an Anti-Pollution Framing that explains why the form is what it is, and align every example to that form.

Why this matters: C4 L1 / L2 / Diagram 4 are structural overviews. Stacking auth posture, timeouts, retry policy, error codes, sequence numbers, event-type sequences, and consumer-group routing on each edge collapses the diagram into noise and duplicates content that has a dedicated home elsewhere. The Connection Naming Rule was always meant to be a typing constraint — one edge per (A → B, [Action Type]) tuple — but the rationale was never written down, so the rule looked like a stylistic preference instead of a load-bearing anti-pollution mechanism. With the new framing, the rule sits next to a sibling Infrastructure-as-via Rule (also a pre-existing concept) and the two are explicitly described as the two anti-pollution primitives that keep L2 readable as the architecture scales.

Scope of this change (3 files):

  • skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md — new #### Anti-Pollution Framing — Why the Rule Has This Shape subsection inserted under ### Connection Naming Rule (L1 + L2). Adds: (1) a 2-row table tying <PROTOCOL>/<STYLE> [Action Type] (edge pollution constraint) and (via <hop>) (node pollution constraint, links to the existing Infrastructure-as-via Rule L1 / L2 sections); (2) ##### Uniqueness Constraint — One Edge per (A → B, [Action Type]) Tuple with a worked sync/async example showing two edges between the same pair admitted because they carry different action types; (3) ##### What Does NOT Belong on the Edge — a 7-row routing table for each kind of pollutant (timeouts/retry → docs/04-data-flow-patterns.md; auth/TLS posture → docs/07-security-architecture.md; event-type sequences and consumer-group routing → encoded in the topic node label or in docs/04; multi-line <br/> content → forbidden). Closes with a one-line decomposition: L1 / L2 / Diagram 4 answers "who talks to whom, over what protocol, with what data class, through which transit hops"; the data-flow file answers "in what order, with what guarantees, what happens on failure"; the security file answers "under what trust assumptions."
  • skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md — all violating worked examples rewritten to canonical form. Touches: (1) the full working example diagram (Section 3, ~30 edges) — every <br/>-laden multi-line edge label collapsed to one of HTTPS/JSON [Data], HTTPS/JSON [Query], TLS/AVRO [Event], gRPC/PROTOBUF [Internal]; (2) Section 5 Synchronous Flows sub-section — syntax template, examples, and guidelines rewritten to prescribe the canonical form and explicitly route timeouts / retry / circuit-breaker / auth detail to docs/04 and docs/07; (3) Asynchronous Flows sub-section — same treatment, plus an explicit "async flag is implicit in the arrow style" rule (-.-> already means async, do not repeat in text); (4) Bidirectional Flows example collapsed to one canonical-form edge with a note to split into two edges if directions differ; (5) the Diagram Legend section — "Security Protocols" and "Timeouts & Retries" subsections (which previously suggested those values appear on the diagram) replaced with an "Edge Labels" rule + "What's NOT on the diagram" routing block; (6) all five How-To Scenarios — Scenario 3 ("Update Data Flow") additionally reframed from "Change Security Protocol via edge label" (the old framing presumed gRPC/mTLS lived on the edge, which is now wrong) to "Change Protocol" with security/operational guidance routed off the edge. Generic syntax templates at lines 555 and 604 also updated from Protocol<br/>Security placeholder to HTTPS/JSON [Data] worked example.
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.27.1 → 3.27.2; plugin description appended with the new release marker.

Backward compatibility: zero impact on existing consumer architecture documents — this is a guidance change inside the plugin's authoring guides, not a runtime change to any skill workflow. Existing ARCHITECTURE.md and docs/03-architecture-layers.md files with over-rich edge labels continue to render and pass every existing audit gate (the Pre-Write Validation in architecture-docs/VALIDATIONS.md already rejects <br/> inside Rel() 4th parameters; the new framing makes the rationale explicit for graph TB edges that were not previously covered). The next time a consumer re-runs architecture-docs Workflow 8 (diagram generation) or hand-authors a new edge using the guide as a reference, they will produce the canonical form. No version bump of ARCHITECTURE_VERSION is required.

Verification: grep -rn "30s timeout\|3 retries\|<br/>mTLS\|Async Publish\|Consumer Group:\|STARTED<br/>" skills/architecture-docs/ returns no matches in worked examples (all remaining matches are inside prose that names the anti-patterns, not example diagrams). grep -n "Anti-Pollution Framing" skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md outputs 1. The Worked Examples block at lines 367–379 of DIAGRAM-GENERATION-GUIDE.md (which was already correct) sits 50 lines below the new framing subsection so the worked form follows immediately from the new rationale. No TypeScript files touched — bun run typecheck baseline unchanged.

v3.27.1 (Previous Release) ✅

fix(architecture-dev-handoff): per-field Component Naming Fidelity in SECTION_EXTRACTION_GUIDE — Rule 7 added to "How to Use This Guide" binds component-name references extracted from docs/05-integration-points.md and from **Dependencies:** / **Calls:** fields back to the canonical full name in docs/components/README.md Column 2 before they are written into the handoff

This is a per-field tightening of the existing agent-level Component Naming Fidelity rule. The agent-level block at the top of agents/generators/handoff-generator.md was already explicit ("write omn-bs-top-ups-and-bundles every time — never omn-bs"), but the per-field extraction guide bundled inside the same agent did not reinforce the rule at the rows that actually pull component names from secondary sources. Result: the component being handed off was correctly named, but components it referenced (in dependency rows, async integration rows, runbook recovery rows) were being propagated in their source-doc shortened form.

Why this matters: handoffs are read by external dev shops, contracted QA firms, and ops teams who may not have access to the source architecture. When a handoff says Downstream Dependency: omn-spa without resolving to omn-spa-product-summary, the reader cannot deterministically identify the dependency — especially in architectures where multiple components share a prefix (omn-bs-top-ups-and-bundles, omn-bs-billing, etc.). Moving the rule from a one-shot system-prompt header reminder to an explicit per-field extraction rule closes the gap at the exact seam where the agent decides what string to write.

Scope of this change (2 files):

  • agents/generators/handoff-generator.md — Rule 7 added to the bundled SECTION_EXTRACTION_GUIDE "How to Use This Guide" list. Explicitly enumerates the affected rows: Upstream Consumers / Downstream Dependencies / Async Integrations / External System Integrations (A1/A3) and **Dependencies:** / **Calls:** fields plus Failure Recovery (A1/C2). Worked example omn-spa → omn-spa-product-summary. Cross-references the agent-level Component Naming Fidelity block at the top of the system prompt so Rule 7 is positioned as the per-field enforcement of an already-stated agent-level constraint.
  • skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md — identical insertion in the source-of-truth file, so the next regeneration of the bundle into handoff-generator.md preserves the rule.
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.27.0 → 3.27.1; plugin description appended with the new release marker.

Backward compatibility: zero impact on existing handoffs — this is an instruction-only change, no template structure or extraction surface change. Re-running architecture-dev-handoff over an existing component regenerates the handoff with full-name resolution applied; the orchestrator's manifest-based skip check is unaffected (component file hashes drive that, not handoff content). Component files, integration-points docs, and the component index README itself are not touched. The other 18 agent files (validators, builders, reviewers, generators other than handoff-generator) already had complete Component Naming Fidelity coverage per the audit and are unchanged.

Verification: grep -c "Component name resolution (Fidelity Rule)" agents/generators/handoff-generator.md skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md outputs 1 for each file. The two copies of the guide remain textually identical at the inserted region (line 15 in source, line 470 in the bundled copy inside handoff-generator.md). No TypeScript files touched — bun run typecheck baseline unchanged.

v3.27.0 (Previous Release) ✅

feat(architecture-docs + technical-debt-records): new technical-debt-records skill (16 skills total), new Section 13 "Risks and Technical Debt" added to the architecture-docs canonical structure, References file renumbered docs/10-* → docs/11-* so the cross-cutting References file remains the last docs/NN-*.md file, new Workflow 11 (Layout Migration Gate) auto-detects + migrates legacy multi-file projects with no manual intervention

This release introduces TDRs (Technical Debt Records) as a sibling concept to ADRs, integrates them into the architecture-docs canonical structure as a new Section 13, and ships the supporting renumber + auto-migration so existing consumer projects upgrade transparently on next workflow run.

Why this matters: ADRs capture why a decision was made; TDRs capture what was deferred or accepted as suboptimal, and what it will cost later. Until now this concept lived in informal notes or got buried in ADR consequence sections. With a dedicated lean 5-field format (Status / Description / Impact / Possible Solutions / Owner) plus a summary table inside the architecture document itself (Section 13.1 Risks + 13.2 Technical Debt), accepted compromises stay visible to every architecture review, peer review, and dev handoff. The numbering choice — Section 13 file at docs/10-* and References shifted to docs/11-* — preserves the convention that the cross-cutting References file is always the highest-numbered docs/NN-*.md file.

Scope of this change (33 files):

  • New skill — skills/technical-debt-records/ (5 files: SKILL.md, templates/tdr-template.md, examples/TDR-001-centralized-log-aggregation.md, references/index-template.md, references/arc42-section-11-snippet.md). Lean 5-field format, ID scheme (zero-padded TDR-NNN, never reused), workflow for create / status-update / supersede / list, arc42 Section 11 cross-reference snippet for arc42-using projects, generic seed example.
  • New canonical Section 13 — skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md (Section 13: Risks and Technical Debt template + arc42-alignment note explaining why this skill calls it S13 while external arc42 calls it Section 11), skills/architecture-docs/QUERY_SECTION_MAPPING.md (S13 query block + decision-tree routing line for risk / tech debt / TDR / compromise / deferred work), skills/architecture-docs/SKILL.md (S13 row in the canonical S↔file mapping + leaf entry in the Reverse Dependency Table).
  • File path renumber — docs/10-references.md → docs/11-references.md; new docs/10-risks-and-technical-debt.md (S13). 24 path mentions updated across architecture-docs/SKILL.md, ARCHITECTURE_DOCUMENTATION_GUIDE.md, QUERY_SECTION_MAPPING.md, ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md, REVIEW_AUDIT_WORKFLOW.md, RESTRUCTURING_GUIDE.md, architecture-compliance/SECTION_MAPPING_GUIDE.md, architecture-blueprint/SKILL.md.
  • Workflow 11 — Layout Migration Gate — skills/architecture-docs/SKILL.md adds a new workflow that auto-detects the legacy layout signature (docs/10-references.md exists AND docs/10-risks-and-technical-debt.md does not), prompts the user, then performs git mv of the references file, scaffolds the empty S13 file from the GUIDE template, rewrites cross-references across docs/, docs/components/, adr/, and ARCHITECTURE.md, and patches the navigation table. Idempotent — re-runs exit cleanly with ℹ️ Layout already current — nothing to migrate. Auto-trigger preflight declared for Workflows 2 / 3 / 8 / 10; new-project (Workflow 1) and single→multi restructure (Workflow 9) skip the gate since they emit the current layout directly.
  • Section-count + range consistency pass (29 references across 18 files): S1-S12 → S1-S13, 12 sections → 13 sections, 01-10 → 01-11, "12-section structure" → "13-section structure", "11-file structure (Data Flow omitted)" → "12-section structure"; canonical 13-section enumeration with new 13. Risks and Technical Debt row added to architecture-docs/VALIDATIONS.md and architecture-compliance/SECTION_MAPPING_GUIDE.md; both Expected-Output samples in VALIDATIONS.md (full + Data-Flow-omitted) extended with the S13 line; S13 (Risks and Technical Debt) → S12 row added to the Data-Flow-omitted renumber list; checklist "All 12 sections present (or 11)" → "All 13 sections present (or 12)"; standard-order range (1-12) → (1-13); the custom-section anti-pattern example bumped from ## 13. Future Roadmap to ## 14. Future Roadmap so it doesn't collide with the now-legitimate S13.
  • Path enumeration in agents — agents/builders/architecture-explorer.md (added S13 file + renamed References in the docs/*.md enumeration), agents/builders/handoff-context-builder.md (cross-cutting docs/10 → docs/11 to follow the renumbered References file).
  • Compliance configs — all 10 agents/configs/*.json files (business-continuity, cloud, data-ai, development, enterprise, integration, platform, process, security, sre) had identical stale notes referencing (01-10) and S1-S12 — bulk-updated to (01-11) / S1-S13. Domain configs themselves unchanged in extraction logic.
  • Consumer-facing docs + templates — README.md (badge + install verification + this changelog entry), docs/TROUBLESHOOTING.md (×2 "all 12 sections" mentions), skills/architecture-docs/examples/README.md (×2), skills/architecture-onboarding/PLAYGROUND_TEMPLATE.md + SKILL.md (concept-map node count + slot count), skills/architecture-peer-review/SKILL.md (monolithic-structure description), skills/architecture-compliance/SKILL.md + COMPLIANCE_GENERATION_GUIDE.md (file count "12 docs/" → "11 docs/"), skills/architecture-compliance/templates/cc-001-business-continuity.template.md + cc-010-sre-architecture.template.md (S1-S12 → S1-S13 ×2 each).
  • CLAUDE.md trigger routing — added a new row for technical-debt-records: create TDR · new TDR · record technical debt · technical debt record · update TDR status · list TDRs · TDR inventory → sa-skills:technical-debt-records.
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.26.0 → 3.27.0; plugin description appended with the new release marker.

Backward compatibility: existing consumer projects with the legacy multi-file layout (References at docs/10-references.md, no docs/10-risks-and-technical-debt.md) are auto-detected by Workflow 11 on the next architecture-docs invocation. The user is prompted before any rename — refusing the prompt halts the calling workflow without modifying anything. After acceptance the rename is via git mv (preserving file history) or plain mv for non-git projects, the empty S13 file is scaffolded from the GUIDE template, internal cross-references and the navigation table are rewritten in one pass, and control returns to the original workflow. Section content, ADRs, component files, and version metadata are not touched. Single-file (monolithic) ARCHITECTURE.md projects are unaffected — the renumber and S13 only apply to the multi-file docs/ layout.

Verification: git status after release shows the new skills/technical-debt-records/ tracked + 31 modified files staged in this release commit (none unstaged). grep -rn "docs/10-references.md" skills/ agents/ returns only the intentional Workflow 11 description occurrences and the technical-debt-records arc42-layout reference. grep -rn "S1-S12\|all 12 sections\|01-10) differ" skills/ agents/ is empty. bun run typecheck baseline unchanged (no TypeScript files touched). The architecture-docs canonical S↔file mapping in skills/architecture-docs/SKILL.md lines 14-27 lists all 13 sections including S13 → docs/10-risks-and-technical-debt.md.

v3.26.0 (Previous Release) ✅

feat(enterprise-alignment): per-capability impact analysis — ENTERPRISE_ALIGNMENT.md surfaces which of the 47 BIAN v14 capabilities are impacted under each domain (not just the 8 parent domains); Section 1.5 of docs/01-system-overview.md lifts the capability-level detail

This release sharpens the Enterprise Alignment Gate from domain-level to capability-level scope. Today an alignment report says "Customers 🟢 Impacted (3 rules triggered)"; after this release it says "Customers 🟢 — Customer Management 🟢, Prospect Management 🟢, Loyalty Management 🟡, Claims & Inquiry Management 🟢 (not impacted: Offer, Marketing, Campaign, Point-of-Sale, Event, Brand)." Owners now know precisely which of their capabilities are in scope, instead of being summoned for the whole domain.

Why this matters: the 8 BIAN domains span 47 canonical capabilities. A "🟢 Customers" finding under v2.0 of the alignment file covers ten capabilities — that's an over-broad governance call. Architecture Review Boards have been asking which specific capability the initiative touches so the correct sub-domain owner can be engaged (e.g., the Brand Management owner is a different counterpart than the Customer Management owner). Surfacing the canonical capability resolves that.

Scope of this change (6 files):

  • skills/architecture-enterprise-alignment/ENTERPRISE_ALIGNMENT_TEMPLATE.md — <!-- ENTERPRISE_ALIGNMENT_VERSION --> bumped 2.0 → 2.1; Summary table gains a Capabilities Impacted column (N/total, where total is the canonical capability count per domain: 7 / 5 / 5 / 3 / 8 / 10 / 2 / 7); summary footer adds Capabilities impacted: M of 47; every per-domain section (3.1 → 3.8) gains an **Impacted Capabilities** block listing per-capability 🟢 / 🟡 status, one-line rationale, and PO Spec § citation, closed with a (not impacted: <comma-separated canonical names>) parenthetical so the reader can verify the classifier scanned the full domain.
  • skills/architecture-enterprise-alignment/ANALYSIS_METHODOLOGY.md — new § 3.5 Per-Capability Classification with the 🟢 / 🟡 / ⚪ taxonomy applied at the capability level, naming-fidelity rule (verbatim from ENTERPRISE_MODEL.md § 3), and a domain↔capability consistency rule. § 4 Multi-Domain Capabilities gains a parallel fan-out table showing how a single PO Spec capability ("personal loan via mobile app") resolves to specific impacted capabilities under each domain. § 8 Anti-Patterns adds two new entries (empty 🟢-domain capability lists, capability invention with forbidden examples).
  • skills/architecture-enterprise-alignment/SKILL.md — Step 4 capture list adds item 4 Impacted Capabilities (Evidence / Owner Counterparts renumbered to 5 / 6); Step 7 template-fill instructions describe the new column and per-domain block; the sample header-comment block fixed from stale <!-- ENTERPRISE_ALIGNMENT_VERSION: 1.0 --> to current 2.1; Step 8 user-report adds Capabilities impacted: M of 47; Success Criteria gain three new checks (capability enumeration, (not impacted: …) parenthetical, Summary N/total consistency).
  • skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md (Section 1.5 lift template) — the lifted table gains the Capabilities Impacted column; a new **Impacted Capabilities (per domain)** block lifts the per-domain bullet lists from the source report (🟢 / 🟡 only; ⚪ domains and the (not impacted: …) parenthetical are dropped here for brevity); Rules for Section 1.5 add a capability-naming-fidelity rule and a version-aware fallback — alignment files at v1.0 or v2.0 lack the per-capability data, so Section 1.5 cleanly degrades to the legacy 5-column table and skips the capability block.
  • skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md — Step 0.3 load-into-context note extends the lifted artifacts to include the per-domain Impacted Capabilities lists, with the version-aware fallback documented inline.
  • .claude-plugin/plugin.json / .claude-plugin/marketplace.json / package.json — version bumped 3.25.4 → 3.26.0; plugin description appended with per-capability impact analysis in enterprise alignment v3.26.0.

Backward compatibility: existing ENTERPRISE_ALIGNMENT.md files at v1.0 or v2.0 continue to pass the architecture-docs Step 0.3 gate unchanged (the gate parses presence + frontmatter comments, not the new content). The Section 1.5 lift detects the file version and falls back to the legacy domain-only table when the per-capability data is absent. Users who want capability-level Section 1.5 detail re-run /sa-skills:architecture-enterprise-alignment to regenerate at v2.1.

Verification: grep -c "Capabilities Impacted" ENTERPRISE_ALIGNMENT_TEMPLATE.md outputs 1 (the Summary header); grep -c "Impacted Capabilities" ENTERPRISE_ALIGNMENT_TEMPLATE.md outputs 8 (one per domain section); per-domain N/total totals match the model exactly (7 / 5 / 5 / 3 / 8 / 10 / 2 / 7 = 47); ARCHITECTURE_DOCUMENTATION_GUIDE.md Section 1.5 table has the new column and the new bullet block; the version-aware fallback rule documents both v1.0 and v2.0 as legacy. No TypeScript files touched — bun run typecheck baseline unchanged.

v3.25.4 (Previous Release) ✅

feat(enterprise-alignment): bundled ENTERPRISE_MODEL.md rewritten as a generic BIAN v14 8-domain capability map (47 capabilities) — replaces the prior 13-domain Architecture Governance shape; institution-neutral & language-neutral

This release retires the v1.0 bundled enterprise model (13 English-named Architecture Governance domains) and replaces it with a BIAN v14-aligned 8-domain / 47-capability capability map. The bundled file is institution-neutral and language-neutral — no brand attribution, no regional payment-rail names, no Spanish source-name parentheticals — so any organisation can adopt it unchanged, while project-local override semantics (ENTERPRISE_MODEL.md at the project root wins) remain untouched.

Why the restructure: the v1.0 model carried 13 domains keyed off internal Architecture Governance conventions. Downstream skills (architecture-docs Step 0.3 gate, the alignment template, the methodology heuristics, the owner-counterpart table) all hardcoded those 13 domain IDs. Realigning to BIAN v14 collapses 13 domains → 8 (Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler) and re-anchors the cross-cutting mandatory check trio from Risks / IT / Data → Enterprise Management / Finance & Risks / Business Enabler. Every governance rule carries a > Carried from v1.0 § 3.X annotation so reviewers can trace the inheritance.

Why agnostic: the bundled file ships to every project that consumes sa-skills. Brand attribution (Banco Pichincha), Ecuadorian payment-rail names (BANRED, CNB 2.0, DeUna), and Spanish source parentheticals (Customer Management (Gestión de Clientes)) were stripped so the model reads as a generic BIAN v14 reference. Generic equivalents replace the regional names where examples are still useful (interbank settlement networks, agent-banking POS, digital wallets).

Scope of this change (8 files):

  • skills/architecture-enterprise-alignment/ENTERPRISE_MODEL.md — full rewrite v1.0 → v2.0: new 8-domain / 47-capability structure, governance rules adapted from v1.0 with explicit Carried from v1.0 § 3.X provenance lines, header comments updated to <!-- ENTERPRISE_MODEL_VERSION: 2.0 --> / <!-- BIAN_VERSION: v14 --> / <!-- SOURCE: BIAN v14 capability model (institution-neutral, 47 capabilities, 8 domains) -->. A migration note explains that v1.0-shape consumers can drop their own copy at the project root.
  • skills/architecture-enterprise-alignment/SKILL.md — frontmatter description, Step 3 PO Spec → domain mapping table, Step 5 cross-cutting check table (3 new rows), Component Naming Fidelity worked examples, success-criteria checklist, sample output banner — all rekeyed to the 8-domain shape. BANRED example replaced with interbank settlement network.
  • skills/architecture-enterprise-alignment/ANALYSIS_METHODOLOGY.md — § 3 Classification Heuristics rewritten as 8-row trigger table; § 4 Multi-Domain example renumbered to new domain IDs; § 5 Cross-Cutting Mandatory Domains replaced (Risks/IT/Data → Enterprise Management / Finance & Risks / Business Enabler) with a 7-rule Business Enabler check covering data-governance + AI explainability + cross-domain orchestration; § 6 Owner Counterpart Derivation rebuilt for 8 domains.
  • skills/architecture-enterprise-alignment/ENTERPRISE_ALIGNMENT_TEMPLATE.md — Summary table 13 rows → 8 rows; per-domain analysis 13 sub-sections → 8 sub-sections; Cross-Cutting Findings re-skinned (🏛️ Enterprise Management, 🛡️ Finance & Risks, 🖥️ Business Enabler) with the Data check folded under Business Enabler.
  • skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md — Step 0.3 gate prose and the user-facing BLOCK message both updated to the 8-domain BIAN v14 enumeration.
  • skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md — Section 1.5 Component Naming Fidelity worked example updated (Financial & Non-Financial Risks → Finance & Risks; Business Enabler example added to disambiguate against IT/Data).
  • CLAUDE.md — Enterprise Alignment trigger-row description swapped to the 8-domain BIAN v14 capability map enumeration.
  • README.md — three locations (skill callout, feature-list bullet, long-form release-note paragraph for the parent v3.25.0 entry) updated to the 8-domain BIAN v14 wording.

Verification: grep -cE '^### 3\.[1-8] ' ENTERPRISE_MODEL.md outputs 8; grep -cE '^### [1-8]\. ' ENTERPRISE_ALIGNMENT_TEMPLATE.md outputs 8; the 47-capability invariant is preserved (counted between **Capabilities** and **Governance rules** markers across all 8 domain sections). Zero Banco Pichincha, BANRED, DeUna, CNB 2., or (Gestión leaks remain anywhere in solutions-architect-skills/**/*.md. bun run typecheck clean (no TypeScript files were touched).

Behavioral change for users:

  • Existing ENTERPRISE_ALIGNMENT.md reports generated against v1.0 (with 13 rows / 13 sub-sections) are not auto-migrated. Re-running /sa-skills:architecture-enterprise-alignment against the same PO Spec produces a fresh v2.0-shape report (8 rows / 8 sub-sections / new cross-cutting trio).
  • The Step 0.3 gate parser (<!-- ENTERPRISE_ALIGNMENT_VERSION -->, <!-- ENTERPRISE_MODEL_SOURCE -->, <!-- PO_SPEC_SOURCE -->, <!-- GENERATED -->) is unchanged — both v1.0-shape and v2.0-shape reports continue to pass the gate. The structural contract is preserved at the comment layer.
  • Project-local override path is unchanged: drop a customised ENTERPRISE_MODEL.md at the project root and the skill picks it up first; bundled default is the fallback.

Open TODO (in-source, won't block adoption): § 3.5 Products carries a <!-- TODO: confirm canonical English name for the issued-enabler product capability — provisionally "Issued Enabler Management" --> flag for institutions to rename when they adopt the model.

v3.25.3 (Previous Release) ✅

feat(architecture-docs): mandatory HLD Intake Gate (Step 0.4) — Workflow 1 now refuses to create a new ARCHITECTURE.md without a High-Level Design file; accepted formats extended from PDF-only to PDF / SVG / high-res PNG

This release promotes the High-Level Design from optional supplementary context to a mandatory grounding artifact before any architecture work begins, and broadens the accepted formats so architects don't have to re-export from their native diagramming tool.

Why mandatory: the previous Step 0.5 (Supplementary Context Files) treated the HLD as one item in an optional bag — when skipped, S4 (Architecture Layers), S5 (Component Inventory), and S6 (Data Flow Patterns) were reverse-derived from the PO Spec alone, drifting from upstream design intent. The Architecture team wants the HLD treated like the Enterprise Alignment Gate (Step 0.3): a hard gate the user cannot proceed past.

Why PDF / SVG / PNG: architects routinely export HLDs from draw.io / Lucidchart / Excalidraw as SVG, or capture whiteboard / Miro screenshots as PNG. Both are perfectly readable as architectural input — SVG via XML text parsing (labels + structure), PNG via the multimodal Read tool (visual layout). Forcing a PDF re-export was friction with no quality benefit.

Scope of this change (one workflow file):

  • NEW Step 0.4 — HLD Intake Gate (MANDATORY — no skip) in skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md. Mirrors Step 0.3 (Enterprise Alignment) UX: cascades-skip only when an upstream gate (PO_SPEC_GATE: SKIPPED or ENTERPRISE_ALIGNMENT_GATE: SKIPPED) was recorded — there is no SKIP HLD override. Validates the file extension is one of .pdf, .svg, .png (case-insensitive); rejects anything else and re-prompts until valid. Reads the file (PDF via pages parameter, PNG multimodal, SVG as XML text) and seeds S4 / S5 / S6 with extracted components, layers, and integration arrows. Writes <!-- HLD_GATE: PASSED (ref: <filename>, <date>) -->, <!-- HLD_SOURCE: <filename> -->, <!-- HLD_FORMAT: pdf|svg|png --> traceability metadata into docs/01-system-overview.md during Step 5. Conflict resolution: PO Spec wins for business context; HLD wins for structural layout (component decomposition, integration topology); HLD wins over Step 0.5 supplementary files (HLD is the design anchor).
  • PNG resolution: guidance text only — recommends ≥1920px wide or ≥150 DPI for diagram label readability — no programmatic dimension probe (kept simple).
  • SVG visual fidelity note: SVG is parsed as XML text — Claude reads labels, group hierarchy, and arrow directions but does not "see" rendered visual positioning. For HLDs where positioning carries meaning (swimlane layouts, north-south vs east-west arrangement), prefer PDF or high-res PNG.
  • Step 0.5 cleanup: HLD is removed from the optional Supplementary Context Files step entirely (bullet, example file path design/hld.pdf, classification table row, and the old PDF-only enforcement block). HLD now lives exclusively in the new mandatory gate; Step 0.5 keeps its other optional file types (ADRs, tech stack, OpenAPI, data models, NFRs, IaC, security).
  • Pre-existing numbering bug fixed as a side effect: the workflow had Step 0.3 → Step 0.5 → Step 0.5 (no 0.4, duplicate 0.5). Inserting the new HLD gate at 0.4 fills the hole; the duplicate Step 0.5 (Pre-Identify ADRs) is renumbered to Step 0.6 with all four internal back-references updated (ADR ID assignment note, ADR Context Block confirmation marker, Section-5 cross-reference, ADR-skill invocation context-pass).

Behavioral change for users:

  • New ARCHITECTURE.md creation: Workflow 1 will block at Step 0.4 with 📐 HLD Intake Gate (Required) until a .pdf, .svg, or .png file path is supplied. There is no skip keyword.
  • Cascades-skip path preserved: if the architect runs Workflow 1 with SKIP PO SPEC (or the Enterprise Alignment Gate is itself cascade-skipped), Step 0.4 also skips silently — the prompt is never shown.
  • Existing architectures (Workflow 2 edits, Workflow 8 diagrams, Workflow 9 migration, Workflow 10 release): unaffected; the gate runs for new-architecture creation only.

Verification: grep -n "^#### Step 0\." skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md shows the clean sequence 0.3 → 0.4 → 0.5 → 0.6; zero stray HLD references inside Step 0.5; 20 HLD mentions concentrated in the new Step 0.4; all four ADR back-references point to Step 0.6; all three Step 0.3 forward-references ("proceed to next gate") point to Step 0.4.

v3.25.2 (Previous Release) ✅

chore(hooks): pure-native hook layer — UserPromptSubmit wrappers no longer depend on Bun (or any JS runtime); cold start drops from ~10–20 ms to <1 ms; shared static payload file replaces the TypeScript implementation

The three platform wrappers (route-architecture-docs.sh, .cmd, .ps1) installed by sa-skills:setup previously invoked bun route-architecture-docs.ts to stat ARCHITECTURE.md and emit a fixed JSON system-reminder. Bun cold-start added ~10–20 ms per prompt submission, and any user without Bun on PATH could not install the plugin at all. The TypeScript file performed zero computation — a stat + a static JSON emit — so the JS runtime was unnecessary overhead. v3.25.2 removes Bun from the hook layer entirely.

Architectural change: replace the hidden-runtime indirection (each wrapper → bun ...ts → stat + emit) with a direct shell-native path (each wrapper → stat + cat/type/Get-Content of a static JSON file). The system-reminder text — 1150 characters with em-dash, arrow, apostrophe, asterisks, slashes — now lives in one place: hooks/route-architecture-docs.payload.json. All three wrappers emit it verbatim. No per-shell escaping, no payload drift between TS literal and JSON file, no JS runtime.

Scope of this change (5 files in the hook layer + 4 documentation files):

  • NEW hooks/route-architecture-docs.payload.json — single-line valid JSON, the lone source of truth for the UserPromptSubmit payload (hookSpecificOutput.hookEventName + additionalContext). Validated with python3 -m json.tool post-write.
  • REWRITTEN hooks/route-architecture-docs.sh — pure POSIX sh: set -e; SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd); PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"; [ -f "$PROJECT_DIR/ARCHITECTURE.md" ] || exit 0; cat "$SCRIPT_DIR/route-architecture-docs.payload.json". Zero deps beyond cat + [ (both POSIX-standard). Linux, macOS, WSL, Git Bash.
  • REWRITTEN hooks/route-architecture-docs.cmd — pure Windows batch: setlocal; set "PROJECT_DIR=%CLAUDE_PROJECT_DIR%" with %CD% fallback; if not exist "%PROJECT_DIR%\ARCHITECTURE.md" exit /b 0; type "%~dp0route-architecture-docs.payload.json". Zero deps beyond cmd.exe built-ins. Universally available on every Windows install since XP.
  • REWRITTEN hooks/route-architecture-docs.ps1 — pure PowerShell (5.x + Core/pwsh): $ErrorActionPreference='Stop'; project-dir fallback $env:CLAUDE_PROJECT_DIR → (Get-Location).Path; Test-Path -LiteralPath $archMd; Get-Content -Raw -Encoding UTF8 -LiteralPath $payload. Zero deps beyond PS built-ins.
  • DELETED hooks/route-architecture-docs.ts — the 40-line TypeScript implementation. Removed entirely; no fallback / reference path kept. The wrappers are now the implementation, the payload.json is the data.

Wiring (unchanged): scripts/setup-permissions.ts already platform-detects (process.platform) and writes the wrapper path into the user's .claude/settings.json — sh /<abs>/route-architecture-docs.sh on POSIX, cmd /c "<abs>/route-architecture-docs.cmd" on Windows. The wrapper filenames are stable contracts; only the internal implementation changed. Two comment blocks in setup-permissions.ts (lines 25–36 and 195–200) were updated to reflect the no-JS-runtime reality; no logic changes. The legacy-hook removal markers (SA_SKILLS_HOOK_REMOVAL_MARKERS) still detect and sweep the v3.19.0 sh ~/...sh and v3.21.0–v3.25.1 bun ~/...ts forms on every /setup run, so existing installs upgrade transparently.

Settings example + install docs: .claude/settings.json.example — // HOOKS comment updated (Bun no longer required for the hook layer; sub-millisecond cold start instead of ~10–20 ms); example command swapped bun ~/.../*.ts → sh ~/.../*.sh to match the actual POSIX form setup-permissions.ts writes. The // BASH: bun (covers ALL shell needs since v3.21.0...) permission comment stays unchanged — skill workflows still use Bun via Bash(bun *) for the three helper scripts (scripts/today.ts, scripts/ensure-dir.ts, scripts/remove-glob.ts). README install table now explicitly notes that Bun is only needed for the full skill suite, not the hook layer.

Behavioral change for users:

  • Fresh installs: identical hook behavior — same JSON payload on prompt submission when ARCHITECTURE.md is present, same silent no-op otherwise. Only the underlying runtime differs.
  • Existing installs: re-running /sa-skills:setup after upgrading sweeps the old bun ~/.../*.ts hook entry (via the v3.21.0 legacy marker that's been in setup-permissions.ts since v3.22.0) and installs the new wrapper path. No manual settings.json editing required.
  • Bun-less environments: users who never installed Bun can now use the hook layer end-to-end. They still cannot use skill workflows that call bun scripts/*.ts — those will fail with a missing-Bun error from the Bash tool, as designed.

Verification (post-install, all green): python3 -m json.tool hooks/route-architecture-docs.payload.json parses cleanly; grep -nE '\bbun\b' hooks/route-architecture-docs.{sh,cmd,ps1} returns only documentation comments saying "No bun, no node" (zero invocations); test ! -e hooks/route-architecture-docs.ts returns ok (TS file removed); POSIX wrapper smoke test in a tmpdir with ARCHITECTURE.md present emits 1150-char additionalContext with UserPromptSubmit event; POSIX wrapper silent path returns exit 0 with no output; cold-start time measured at 0.001 s (vs ~10–20 ms with Bun — ~10,000× faster); grep -rE 'ARCHITECTURE-GOVERNED PROJECT' . --include='*.{ts,sh,cmd,ps1,json}' returns only hooks/route-architecture-docs.payload.json (no drift between wrappers and the payload); bun run typecheck clean; bun test 225/225 pass (markdown + shell-only changes; tests don't cover the hook wrappers).

v3.25.1 (Previous Release) ✅

feat: new architecture-enterprise-alignment skill (mandatory Phase 1.5 gate before architecture-docs Workflow 1) + fix: ADR ID Format Gate blocks phase-prefixed IDs like ADR-P1-001 and restores canonical ADR-101+ numbering for project ADRs

This release combines a structural addition (new mandatory gate) and a critical bug fix that surfaced once the gate started exercising the ADR creation path.

New skill — architecture-enterprise-alignment (originally planned for v3.25.0): maps the accepted Product Owner Specification onto the organisation's 8-domain BIAN v14 capability map (Enterprise Management, Resource Management, Finance & Risks, Operations, Products, Customers, Channels, Business Enabler — 47 capabilities total) before architecture design begins. Produces ENTERPRISE_ALIGNMENT.md at the project root with: an 8-row summary table (🟢 Impacted / 🟡 Partial / ⚪ Not Applicable per domain), per-domain analysis (verbatim governance-rule citations from the bundled ENTERPRISE_MODEL.md, evidence quotes from the PO Spec, owner counterparts to engage), three mandatory cross-cutting checks (Enterprise Management, Finance & Risks, Business Enabler — these always run regardless of per-domain status), and an Owner Engagement Plan with timing derived from rule wording (Before kickoff / Before architecture sign-off / Before production). The bundled 8-domain model is overridable via a project-local ENTERPRISE_MODEL.md at the project root. Mandatory gate: architecture-docs Workflow 1 Step 0.3 BLOCKS new ARCHITECTURE.md creation until ENTERPRISE_ALIGNMENT.md exists — no SKIP ENTERPRISE ALIGNMENT override exists; the gate cascade-skips only when the PO Spec gate itself was skipped (because alignment cannot be produced without PO Spec content). When the gate passes, the Summary / Cross-Cutting Findings / Owner Engagement Plan are lifted into a new sub-section 1.5 Enterprise Domain Alignment in docs/01-system-overview.md, with a <!-- ENTERPRISE_ALIGNMENT_GATE: PASSED (ref: ENTERPRISE_ALIGNMENT.md, YYYY-MM-DD) --> traceability comment. Files: 4 new under skills/architecture-enterprise-alignment/ (SKILL.md, ENTERPRISE_MODEL.md, ENTERPRISE_ALIGNMENT_TEMPLATE.md, ANALYSIS_METHODOLOGY.md) plus updates to ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md, ARCHITECTURE_DOCUMENTATION_GUIDE.md, architecture-docs/SKILL.md, the plugin CLAUDE.md trigger table, .claude/settings.json.example permissions, and this README.

Bug fix — ADR ID Format Gate: when creating a new ARCHITECTURE.md, the ADR Candidate Table (Step 0.5), the Section 12 ADR table, and the materialised adr/*.md files were being labelled with phase-prefixed IDs like ADR-P1-001, ADR-P2-001 instead of the canonical ADR-101+ sequential numbering. The ADR Scope Partition rule (institutional 001–100, project 101+) was documented correctly in ADR_GUIDE.md, and the number-computation logic in architecture-definition-record/SKILL.md Step 2.1b was correct — but two misleading example IDs in workflow templates were nudging the agent toward improvisation, and no regex validation gate existed to reject malformed IDs at the write boundary. Root cause: (1) the Step 0.5 ADR Context Block example hardcoded ADR-001 / ADR-002 / ADR-003 as IDs assigned at the candidate-table stage — those IDs collide with the institutional range, so for a project with multiple roadmap phases the agent invented ADR-P{phase}-{n} as a (wrong) disambiguation; (2) the Section 12 template example showed ADR-001 as the first row, misleading for a new project where project ADRs start at 101; (3) no regex gate. Fix: replaced the Step 0.5 ADR Context Block example with [Candidate N] [Title] row-counter notation (no IDs until Step 6 materialisation) and added an explicit "Do not assign ADR IDs at Step 0.5" rule listing ADR-P1-001, ADR-Phase1-001, ADR-001-P1, ADR-101-v2 as invalid; updated the Section 12 template to use ADR-101 as the first-row example and added a Scope column (Institutional | User) so the partition is explicit at the registry level rather than inferred from the number range; added a new ## ADR ID Format Rules section to ADR_GUIDE.md with the canonical regex (^ADR-\d{3,}$), a 9-row Invalid Examples table, and the filename regex; added a new ## ADR ID Format Gate (BLOCKING) section to architecture-definition-record/SKILL.md with the abort message format and invocation lines at Workflow 1 Step 1.5b (new sub-step), Workflow 2 Step 2.3, and Workflow 4 Step 4.1. Six total gate references in SKILL.md (one definition, three explicit invocations, two cross-references). Adversarial requests asking the ADR skill to create adr/ADR-P1-001-test.md now hit the gate and abort with a documented error message pointing to ADR_GUIDE.md.

Files (13 total): 4 new skill files under skills/architecture-enterprise-alignment/; updates to skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md (Step 0.3 gate + Step 0.5 ADR rules and Context Block), skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md (Section 1.5 spec + Section 12 Scope column + ID format callout), skills/architecture-docs/SKILL.md (Workflow 1 pre-step + lazy-load table), skills/architecture-definition-record/ADR_GUIDE.md (ADR ID Format Rules section), skills/architecture-definition-record/SKILL.md (ADR ID Format Gate + invocations + example success line updated to ADR-101), the plugin CLAUDE.md (trigger row + Four-Phase Workflow note), .claude/settings.json.example (4 new permissions), CHANGELOG.md, all three version files (.claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json — bumped 3.24.1 → 3.25.1), and this README. Verification: bun run typecheck clean; bun test 225/225 pass (markdown-only changes, no TS impact); 8 plan verification greps all green (0 hardcoded IDs in Step 0.5 Context Block; Scope column present in Section 12; no Phase column anywhere; Format Rules section present; ADR-P1-001 documented as anti-pattern; gate invoked 6 times in SKILL.md).

v3.24.1 (Previous Release) ✅

feat(agents+templates): Component Naming Fidelity rule across all 19 agents, the analysis-report skeleton, HANDOFF_TEMPLATE (TEMPLATE_VERSION 2.0.0 → 2.1.0), the peer-review playground template, plugin CLAUDE.md, and the setup-time managed CLAUDE.md block — generated artifacts must use the canonical full component name from docs/components/README.md regardless of source-doc shortening

Generated artifacts (analysis reports, peer reviews, dev handoffs, compliance contracts, .docx exports, traceability reports, prose summaries, diagrams) must reference documented components by their canonical full name as registered in docs/components/README.md (Column 2 — Component) — never an abbreviation, alias, or truncation, even when the source docs/**/*.md files use a shortened form inline. This closes a gap between the existing Asset Fidelity Rule + "no invention" policy (which bind structured asset values like endpoints, schemas, env vars) and prose / table / citation surfaces where component names were free-form. Concretely: an analysis finding that called the component omn-bs instead of omn-bs-top-ups-and-bundles no longer grepped back to the component file, the index, or any downstream artifact — that traceability break is what this release fixes.

Scope of this change (26 files):

  • All 19 agent files under agents/**/*.md carry a ## Component Naming Fidelity block. 15 files (10 validators + architecture-explorer, handoff-context-builder, handoff-generator, peer-review-category-agent, principle-quality-reviewer) get the block at the top, immediately after frontmatter and the H1. The 4 files with pre-existing fidelity rules (compliance-generator.md, docs-export-generator.md, handoff-asset-generator.md, architecture-analysis-agent.md) get the block placed adjacent to the existing rule with an explicit complementarity note — neither replacing nor duplicating the original (Asset Fidelity Rule, Documentation Fidelity, Template Preservation Mandate, Documentation Fidelity Rule are preserved verbatim). The handoff-asset-generator placement is in pre-bundle prose so the bundler does not regenerate over it.
  • 3 templates carry the rule as authoring-time guidance: skills/architecture-analysis/templates/analysis-report-skeleton.md (HTML comment at file head — does not render in the analysis report), skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md (HTML comment block alongside the existing managed-block markers; TEMPLATE_VERSION bumped 2.0.0 → 2.1.0 with a paired SHA-tripwire fixture update in manifest.test.ts — existing consumer-side handoffs at v2.0.0 in handoffs/.manifest.json will be re-generated on the next architecture-dev-handoff run, intentional so the rule actually propagates through pre-existing artifacts), skills/architecture-peer-review/PLAYGROUND_TEMPLATE.md (markdown subsection — this file is authoring documentation, not a literal output template).
  • Plugin CLAUDE.md gains a new ### Component Naming Fidelity subsection between ### Component Index Policy and ### Dev Handoff Scope.
  • scripts/setup-claude-md.ts blockBody gains a new ### Component naming — always use the canonical full name subsection inside the managed block written into every consumer project's CLAUDE.md. Re-running /sa-skills:setup on existing projects propagates the rule transparently — the helper replaces only the content between the sa-skills:architecture-pointer markers, idempotent.

Why a separate rule — the existing fidelity guarantees (Asset Fidelity Rule at CLAUDE.md:177, EXACT MATCH at skills/architecture-dev-handoff/SKILL.md:106, Documentation Fidelity at agents/generators/docs-export-generator.md:14, "Never localize component names" at agents/generators/handoff-asset-generator.md:89) all bind structured asset values. They do not directly govern prose / table / citation references in reports and reviews — which is precisely where short-form component names were leaking into output. The new rule is complementary, not redundant; the agent-level blocks reference this complementarity explicitly so a future reader does not delete one assuming it duplicates the other.

Verification (post-install, all green): find agents -name '*.md' -print0 | xargs -0 grep -L "Component Naming Fidelity" returns empty (all 19 covered); the 4 fidelity-rich agents have exactly one ## Component Naming Fidelity heading each (no accidental duplication); bun run typecheck clean; bun test reports 225/225 pass (added 0, modified 1 — the HANDOFF_TEMPLATE SHA-tripwire fixture, paired with the TEMPLATE_VERSION bump per the test's documented contract). No source code changed; no permission changes; no marketplace re-registration required.

v3.23.0 (Previous Release) ✅

feat(architecture-docs): introduce Phase Catalog mode as the default authoring pattern for docs/04-data-flow-patterns.md — multi-UC architectures now compose phases rather than duplicating flows; full propagation through Workflow 7 diagram gate, peer-review SECTIONS-05, dev-handoff payload schema, and validations

The previous Section 6 template (ARCHITECTURE_DOCUMENTATION_GUIDE.md lines 1572–1598) modelled data flow as a flat list of H3 flow subsections, each with Flow Steps / Performance / Error Handling and one sequenceDiagram. That shape works for a single-UC CRUD service but breaks down hard the moment an architecture has multiple use cases that share components: every UC re-runs payment / persistence / notification, the differences between UCs disappear into prose, and every change to a shared step (e.g. retry policy) has to be hand-mirrored across N flows. v3.23.0 adopts the richer Phase Catalog mode as the default — modelled directly on the top-ups-and-bundles/docs/04-data-flow-patterns.md reference, where 8 phases compose 3 use cases plus a compensation flow and the per-phase view stays the entry point with full end-to-end wire sequences deferred to the bottom of the document.

The 8-part Phase Catalog structure (Section 6 default):

  1. EXPLORER_HEADER with phase names, UC IDs, and cross-cutting flow vocabulary in key_concepts
  2. Intro blockquote + "How to read this file" navigation (Phase Catalog ↔ Wire Sequences entry-point split)
  3. Flow Inventory table — Flow | Trigger | Use Case | Latency Target
  4. Phase Catalog — phase summary table + one H4 per phase with Purpose / Latency budget (p95) / Side effects + a scoped sequenceDiagram mini-flow (per phase, not per flow)
  5. Use Case Resolutions — phase × UC composition matrix (cell vocab ✓ / skipped / reused / n/a / UC-specific note) + per-UC narrative deltas
  6. Cross-cutting flow concerns — ### Idempotency + ### Latency budget breakdown (per-hop table) + ### Failure classification (one row per phase × failure mode)
  7. End-to-End Wire Sequences — full canonical Mermaid sequenceDiagram per UC, deliberately last
  8. Validation — 6-item self-check checklist

Mode selection rule: Phase Catalog mode is default for any architecture with 2+ use cases that share components OR a single UC with ≥4 distinguishable phases. Single-Flow mode (the legacy template) is preserved as a fallback for trivially-simple systems with 1 UC and ≤3 short linear flows. The mode is auto-detected by grepping the doc for the literal H2 strings ## Phase Catalog, ## Flow Inventory, ## Use Case Resolutions — any two present = Phase Catalog mode.

Why Phase Catalog mode is the default: when multiple UCs share phases, Single-Flow mode forces every UC's flow to duplicate the shared steps and the differences between UCs disappear into prose. Phase Catalog mode names each shared step once, then composes UCs as subsets — keeping the differences visible at a glance. The shape scales down (a 2-phase, 1-UC system still reads cleanly under it); Single-Flow mode does not scale up.

Full propagation through downstream consumers (so Phase Catalog mode is actually enforced end-to-end, not just suggested in a template):

  • Workflow 7 (Mandatory Diagram Generation) is now mode-aware. In Phase Catalog mode the gate counts P phase mini-flows + U full UC wire sequences (UCs that explicitly substitute an out-of-domain narrative clause are excluded from U); in Single-Flow mode the legacy "one diagram per H3 flow" rule stands. The DIAGRAMS_GATE blocking audit at Step 7.3 enforces both counts.
  • Peer-review SECTIONS-05 upgraded from "section has at least one Mermaid diagram" to a structural check: in Phase Catalog mode, the phase × UC matrix must be present AND its phase row count must equal the Phase Catalog summary table's phase row count (silent drift between the two views is the failure mode this pattern is designed to prevent — flagged Major). The ### Latency budget breakdown and ### Failure classification tables must exist; failure classification must cover ≥1 row per phase H4.
  • Dev-handoff Flows payload extraction is mode-aware. In Phase Catalog mode, the per-component handoff slices the doc precisely: phase H4s where the component is a participant (header + Purpose + Latency budget + Side effects + the phase's sequenceDiagram), the matching UC narrative deltas, and the relevant Failure classification rows — explicitly excluding End-to-End Wire Sequences from the per-component payload, because inlining a 200-line wire sequence in every component handoff re-introduces exactly the duplication the Phase Catalog pattern eliminates.
  • VALIDATIONS.md gains 10 Phase Catalog structural checks alongside the existing inclusion-criteria block, plus the canonical mode-detection rule (shared with Workflow 7 and SECTIONS-05 so all three agree on what mode the doc is in).

New reference example: skills/architecture-docs/examples/04-data-flow-patterns.example.md — a synthetic 3-UC e-commerce checkout (UC1 New Order, UC2 Reorder, UC3 Refund composing phases 4 → 5 → 6 in different ways) demonstrating the full 8-part structure end-to-end. Header marks it as a reference example, not generated content. Component / ADR / metric values are illustrative; do not import them.

Changes:

  • skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md — Section 6 rewritten as a two-mode template (Phase Catalog default + Single-Flow fallback) with mode-selection rule and S6-specific EXPLORER_HEADER key_concepts vocabulary (phase names, UC IDs, idempotency, dedup, compensation, out-of-band, fire-and-forget, etc.).
  • skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md — Workflow 7 generation rule (lines 863–868), Step 7.2 menu line (895), and DIAGRAMS_GATE audit (923, 928) made mode-aware.
  • skills/architecture-docs/VALIDATIONS.md — Phase Catalog mode structural checks added; mode-detection rule canonicalised.
  • skills/architecture-peer-review/PEER_REVIEW_CRITERIA.md — SECTIONS-05 upgraded to mode-aware structural check; matrix-vs-Phase-Catalog phase-count drift = Major violation.
  • skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md and SECTION_EXTRACTION_GUIDE.md — Flows and Async Integrations extraction rules made mode-aware; End-to-End Wire Sequences explicitly excluded from per-component payloads.
  • agents/generators/handoff-generator.md and agents/builders/handoff-context-builder.md — re-bundled (bun run bundle:handoff-agent) to absorb the source changes; sync test passes.
  • skills/architecture-docs/SKILL.md — Workflow 1 Step 7 note (line 172) rephrased mode-aware with pointer to the new example file.
  • skills/architecture-docs/examples/04-data-flow-patterns.example.md — new file (~340 lines) demonstrating Phase Catalog mode for a 3-UC system. examples/README.md — entry added describing the new example.
  • 3 version files (.claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json) — bumped to 3.23.0.
  • README.md — version badge, install verification line, roadmap entry.

Backwards compatibility: existing Single-Flow mode docs continue to validate, generate diagrams, and pass peer review unchanged — the legacy template is preserved as a named fallback, not removed. The skill does NOT auto-rewrite an existing Section 6 from Single-Flow into Phase Catalog mode; that would be a structural migration users explicitly invoke. New Section 6 authoring (Workflow 1 Step 5) defaults to Phase Catalog mode unless the project clearly meets the simple-fallback criteria. Test suite: 225/225 passing; typecheck clean.

Net diff: ~10 files changed, ~+800 / −60 lines (the bulk in the new example file and the Section 6 template).

v3.22.3 (Previous Release) ✅

fix(architecture-traceability): apply largest-remainder (Hamilton) rounding to integer-% tables in TRACEABILITY_REPORT.md so multi-row percentage breakdowns always sum to exactly 100%

The Summary table in TRACEABILITY_REPORT.md decomposes a single total into Covered / Partial / Not Covered counts, each rendered as an integer percent. Step 5 of skills/architecture-traceability/SKILL.md was silent on rounding policy, so the model defaulted to plain round() per row — and on a real-world distribution (67 / 6 / 7 of 80 requirements) the row sums became 84 + 8 + 9 = 101%. The exact percentages are 83.75 / 7.50 / 8.75; "round half away from zero" applied independently per row rounds two of three rows up with no global sum constraint, so the table contradicts itself. v3.22.3 fixes this at the spec layer (where the model picks its rounding rule) rather than papering over it in the rendered report.

Changes:

  • skills/architecture-traceability/SKILL.md — Step 5 ("Compute Summary Statistics") gains a mandatory largest-remainder (Hamilton) method for any table where multiple integer percentages must sum to 100%. The five-step procedure is spelled out inline: compute exact pᵢ = 100 × countᵢ / total, floor to fᵢ, track remainders rᵢ, deficit D = 100 − Σ fᵢ, sort by rᵢ descending and add +1 to the top D rows, with a deterministic tie-break (larger countᵢ first, then row order Covered → Partial → Not Covered). Single-value cells (per-phase Coverage column, per-UC N/N (X%) cell, any standalone percentage) are explicitly exempted — round() is fine when there is no sum constraint.
  • Generalised to per-UC / per-phase breakdowns — if the report ever decomposes a single UC, phase, or source into integer percentages across Covered / Partial / Not Covered (e.g., UC-03 — 73% / 18% / 9%), the rule applies per row, not just to the global Summary. Each such row is its own 100%-budget. This keeps the spec future-proof without requiring a re-edit when the report grows new breakdowns.
  • Self-check checklist before writing the report — five-item gate covering: global Summary sums to 100%, each per-UC breakdown sums to 100%, each per-phase breakdown sums to 100%, single-value cells exempt, and Covered + Partial + NotCovered == Total for every breakdown. The last item is intentionally separate from the %-sums-to-100 check: largest-remainder will always produce 100% even if the underlying counts are wrong (e.g., an off-by-one classification bug), so the count assertion catches what the % assertion cannot. The spec is explicit: "Do not paper over a count mismatch by forcing percentages to 100 — that masks a real classification bug."

Worked example for the bug case (67 / 6 / 7 of 80):

Row Exact % Floor Remainder +1? Final
Covered 83.75 83 0.75 ✓ 84
Partial 7.50 7 0.50 7
Not Covered 8.75 8 0.75 ✓ 9
Sum 98 +2 100 ✓

Naive round() produced 84 + 8 + 9 = 101. Largest-remainder produces 84 + 7 + 9 = 100. The corrected Partial row is 7%, not 8%.

Backwards compatibility: pure spec change inside a skill workflow. Existing reports regenerate fresh on each run (the skill's overwrite policy at Step 6), so the next /skill architecture-traceability invocation produces a corrected TRACEABILITY_REPORT.md automatically. No migration step, no permission change, no hook change. The plain round() exemption for single-value cells preserves intuitive integer reads in the per-phase Coverage column and per-UC N/N (X%) cells — those have no cross-row sum constraint.

No code changes. Pure content edit inside one Markdown file; no logic, no schema, no hook, no permission change.

Files:

  • skills/architecture-traceability/SKILL.md — net +25 lines inside Step 5 (rounding rule + per-UC/per-phase generalisation + 5-item self-check checklist).
  • 3 version files (.claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json).
  • README.md — version badge, install verification line, roadmap entry.

Net diff: 5 files changed, ~+60 / −5 lines.

v3.22.2 (Previous Release) ✅

feat(setup): plan-mode-first rule for architecture-doc updates in the consumer-project CLAUDE.md managed block; carve-out for architecture-docs update intent

The /setup skill (Step 5 → scripts/setup-claude-md.ts) injects a marker-delimited "sa-skills architecture pointer" block into every consumer project's CLAUDE.md. Until v3.22.2 that block told Claude what the architecture sources are and how to read them through architecture-explorer, but said nothing about when to slow down before changing them. In practice, this meant Claude could open Edit on ARCHITECTURE.md, a docs/NN-*.md section file, a docs/components/**/*.md descriptor, or an adr/**/*.md decision record on the first turn — without first surfacing the proposed change for user approval. Architecture edits are rarely trivial: a single change can ripple through component versions, ADRs, compliance contracts, downstream handoffs, and diagrams. The plugin's skill workflows already encode plan-style approval internally, but direct edits outside a skill workflow had no enforcement layer at all. v3.22.2 closes that gap by inserting a new ### Architecture doc updates → plan first subsection into the managed block, ahead of the existing ### Routing doc reads through architecture-explorer section.

Changes:

  • scripts/setup-claude-md.ts — blockBody template literal gains a new sibling ### subsection after the sources-list paragraph and before the explorer-routing section. The new section sets one rule and three exemptions:
    • Rule — before any direct edit to ARCHITECTURE.md, docs/**/*.md, docs/components/**/*.md, adr/**/*.md, or handoffs/**/*.md, Claude must enter plan mode and present the proposed change via ExitPlanMode for user approval. The rule is intentionally absolute — no "trivial" carve-out for typo fixes, metric updates, section additions, ADR edits, or component-descriptor changes — because the skill workflows treat all of them as semver-eligible inputs.
    • Exemption 1: skill-routed invocations — when the user types a phrase from the project's CLAUDE.md trigger table (release my architecture, review my architecture, generate compliance contracts, …), Claude invokes the matching sa-skills:architecture-* skill directly. The skill's own workflow handles plan / scope / approval internally; wrapping the invocation in plan mode is redundant.
      • Exception within the exemption — invoking sa-skills:architecture-docs with update intent (modifying existing content in ARCHITECTURE.md, docs/**/*.md, or docs/components/**/*.md) still requires plan mode first. Updates ripple through downstream artifacts in ways the skill cannot fully scope on its own; the user must see the proposed change set before the skill runs. Initial creation (Workflow 1 from scratch), diagram regeneration (Workflow 8), multi-file migration (Workflow 9), and release lifecycle (Workflow 10) are not update intent and remain exempt.
    • Exemption 2: read-only Q&A and discovery — answering questions about the architecture, running architecture-explorer in findings mode, or quoting from existing docs requires no plan.
    • Exemption 3: files outside the architecture surface — code, tests, configs, and other non-architecture files follow normal plan-mode rules, not this one.

Behavior shape: idempotent and unversioned-from-the-helper's-perspective — setup-claude-md.ts already replaces the entire managed block in place on every run, so existing consumer projects pick up the new section the next time they run /setup. No migration step, no marker change, no permission change, no hook change, no .gitignore change required.

Backwards compatibility: pure documentation addition inside an existing managed block. The exemption clauses are explicit and verbose specifically to preserve the project root CLAUDE.md's existing rule that recognized skill phrases override plan-mode's default "Explore → Plan → ExitPlanMode" flow. Without those clauses, the new rule would silently contradict the trigger table for every phrase except update architecture-style edits.

No code changes. Pure content edit inside one TypeScript template literal; no logic, no schema, no hook, no permission change. bun run typecheck clean. Verified end-to-end against a scratch project: fresh run → Created with the new heading present, re-run → Unchanged, hand-edited content above the markers preserved byte-for-byte.

Files:

  • scripts/setup-claude-md.ts — net +13 lines (the new ### Architecture doc updates → plan first subsection inside blockBody).
  • 3 version files (.claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json).

Net diff: 4 files changed, ~+16 / −3 lines.

v3.22.1 (Previous Release) ✅

feat(subagent-contracts): output-contract hardening across architecture-explorer + 10 compliance validators; orchestrator-side malformed-output detection with single retry before degradation; new informational caller parameter on architecture-explorer

In a v3.22.0 field run of the Development compliance contract, sa-skills:architecture-explorer (Haiku-tier, findings mode) returned synthesis prose for the key_data_points[] query instead of the structured EXPLORE_FINDINGS: YAML block the orchestrator expects. The compliance orchestrator's existing degraded-mode rule (status: FAILED or empty files[]) did not detect this case — the agent's reply simply lacked the EXPLORE_FINDINGS: token entirely — so the orchestrator silently dropped the findings block from the generator prompt and fell back to phase3.required_files[] only. The contract still generated correctly, but the per-contract findings fan-out (introduced in v3.16.0 to pre-locate evidence at line+heading granularity) was effectively bypassed and the user never saw a clear signal about the degradation. v3.22.1 hardens this contract at three layers — the agent definitions, the orchestrators, and the spawn-prompt templates — so that prose drift either does not happen, is caught and retried once, or is at least surfaced in run telemetry instead of silently degraded.

Changes:

  • agents/builders/architecture-explorer.md (3.3.0 → 3.5.0) — three additions. (1) New ## Output contract section after Mission with five hard rules ("first character of output is E", "exactly one ```yaml … ``` fence", "no prose outside the fence except the optional headers-missing or no-matches note", "no summary / conclusion / answer section anywhere") and a four-item self-check the agent runs before its final assistant turn. The contract explicitly acknowledges **two consumer types**: orchestrators (compliance / dev-handoff / analysis, string-scanning) AND free-form architecture Q&A (Claude in the user's main session, LLM-read). Both consumer types require YAML — the prose synthesis for Q&A happens in the *caller*, not the explorer. (2) Per-mode self-check gates appended to Step M8 (manifest emit, now Step M9) and Step F9 (findings emit, now Step F10) listing common drift patterns with exact wording (Here is the manifest… preamble, In summary the project covers… trailer, paraphrased EXPLORER_HEADER fields, paraphrased excerpts outside the excerpt: block scalar, bullet-list summaries outside the YAML) so a haiku can pattern-match drift back to a fix. (3) Anti-pattern #2 strengthened from "Don't answer the question" to name the parsing-failure consequence: "Writing a prose preamble … causes orchestrators (which extract via literal string scan, not LLM read) to reject the output and silently degrade to a hardcoded fallback — the user gets a worse result and your run is wasted." (4) New caller input parameter — **optional, recommended, four documented values** (orchestrator-compliance, orchestrator-dev-handoff, orchestrator-analysis, qa); informational only — not a mode switch: the output contract is identical for every value. Acts as a third prompt-engineering anchor (alongside the Output contract section and anti-pattern #2) that all converge on the same rule. When absent, the agent treats the call as ad-hoc Q&A — contract unchanged.
  • agents/validators/*.md (10 files: business-continuity / cloud / data-ai / development / enterprise / integration / platform / process / security / sre) — replaced the trailing one-liner **CRITICAL**: Return the VALIDATION_RESULT block as the LAST thing in your response. The compliance agent extracts it by finding the VALIDATION_RESULT: marker. with a full ## Output contract section: five hard rules ("token at start of its own line", "no prose after the block", "no markdown heading like ## Result or quote prefix", "no extra / renamed fields, no reordering that breaks YAML", "free text stays inside evidence: / deviations: / recommendations:"), a five-item self-check (token presence at start of line, last line in block, numeric counts sum to total_items, status derivation is correct (PASS only when fail == 0), no fenced-code or quote wrapping), and a named consequence ("the generator sets validation_status: PENDING and stamps every validation-dependent field in the published contract as Unknown — your work is wasted"). Identical text across all 10 validators to keep the contract uniform across domains.
  • skills/architecture-compliance/SKILL.md — Step 3.2.5 (per-contract explorer findings fan-out): new "Malformed-output detection + retry-once" rule. After each explorer reply, the orchestrator scans for the literal EXPLORE_FINDINGS: line; if absent, dispatches one fresh Task() retry with a corrective preamble before falling through to the existing degraded-mode rule. Updated degraded-mode rule now records explorer_status: <OK|FAILED|MALFORMED> for the run summary so users see which contracts went degraded and why. Step 3.3 (validator dispatch): same retry-once-on-malformed pattern for VALIDATION_RESULT:; on persistent failure, marks the contract validation_status: PENDING (existing fallback) and continues with the next batch without aborting the orchestration. Step 3.2.5 spawn template now passes caller: orchestrator-compliance to the explorer.
  • skills/architecture-dev-handoff/SKILL.md — Step 3.4a (per-component explorer findings fan-out): same malformed-output retry-once rule before falling through to the existing per-component v3.13.0 legacy in-builder grep slicing fallback. Spawn template now passes caller: orchestrator-dev-handoff.
  • skills/architecture-analysis/SKILL.md — Step 2.5 (per-analysis explorer findings fan-out): same malformed-output retry-once rule before collapsing to the analysis's base FILES table. Spawn template now passes caller: orchestrator-analysis.

Cost shape: the malformed-output retry only fires on the small population of explorer / validator calls that drift into prose. Steady-state cost is unchanged. Worst case (every call drifts) the orchestrator does at most one extra Haiku call per fan-out unit before degrading — bounded and predictable.

Backwards compatibility: all changes are pure prompt-engineering additions. The caller parameter is optional with a safe default (treated as qa when absent). Existing direct callers of sa-skills:architecture-explorer keep working without change. No breaking changes to the explorer's output schema or the validator output schemas.

No code changes. Pure agent definition / SKILL.md edits; no TypeScript / hook / template / config changes. bun run typecheck clean.

Files:

  • agents/builders/architecture-explorer.md — net +96 lines (Output contract + Step M9 / F10 self-checks + caller parameter docs + footer changelog).
  • agents/validators/*.md (10 files) — net +22 lines each, +220 total (Output contract block replacing the one-line CRITICAL note).
  • skills/architecture-compliance/SKILL.md — net +18 lines (Step 3.2.5 retry-once rule + Step 3.3 retry-once rule + caller: field in spawn template).
  • skills/architecture-dev-handoff/SKILL.md — net +10 lines (Step 3.4a retry-once rule + caller: field in spawn template).
  • skills/architecture-analysis/SKILL.md — net +10 lines (Step 2.5 retry-once rule + caller: field in spawn template).
  • 3 version files (.claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json).

Net diff: 18 files changed, ~+360 / −16 lines.

v3.22.0 (Previous Release) ✅

feat(architecture-compliance): remove outdated 26-item Stack Validation Checklist; keep EOL check as sole external validation; tighten development key_data_points[]

The Development compliance contract's "Stack Validation Checklist" (LADES1.6) was a 26-item gate that compared the documented stack against hardcoded approved-tech lists baked into agents/validators/development-validator.md and a manual STACK_VALIDATION_CHECKLIST.md file ("Java 11/17 LTS", "Spring Boot 2.7+", "Angular 12+", "Approved library catalog", "Naming conventions", and so on). Those lists drifted from organizational reality and could not be queried live — every run produced noisy FAIL/UNKNOWN findings that eroded trust in the contract. The EOL portion of the validator (WebSearch lookups against endoflife.date for every documented technology+version pair) was always the highest-value signal: it is a live, objective source, and an EOL technology is unambiguously a problem regardless of whether the org's catalog has been updated. v3.22.0 removes the stale 26-item checklist and promotes EOL to be the validator's sole external check until a new mechanism (MCP server, organizational catalog API, or registry) can be integrated. Stack-shape validation will return when that live mechanism arrives.

Changes:

  • agents/validators/development-validator.md — full rewrite. Dropped Phase 2 (the 26-item DEV-01…DEV-26 list with hardcoded approved-tech rules) and the "Phase 1 / Phase 2" two-phase framing. The validator now performs a single EOL-only pass: extract every technology+version pair from docs/06-technology-stack.md, run a WebSearch lookup against endoflife.date for each, and emit one DEV-EOL-{N} row per pair with PASS (>6 months remaining), FAIL (EOL or within the 6-month safety period), or UNKNOWN (lookup inconclusive). WebSearch tool retained; the endoflife.date priority guidance and the "do not use context7 for EOL" warning remain. Output VALIDATION_RESULT schema updated: dynamic total_items, eol_checked count, FAIL items populate deviations, UNKNOWN items populate recommendations. Net: −362 lines on the heaviest file in the diff.
  • agents/configs/development.json — key_data_points[] tightened from 7 long parenthetical entries ("Technology versions (for EOL/lifecycle tracking)", "Code coverage (minimum 80% for critical paths)", etc.) to 8 short term-of-art entries: Technology stack, EOL, Code coverage, Technical debt, Dependency vulnerabilities, Code review, CI/CD pipeline, ADR exceptions. Mirrors the SRE config's SLO, SLI, Error Budget, MTTR, MTBF, Runbook coverage, Monitoring tools, Incident response pattern. The orchestrator joins these with comma to form the explorer's contract_query; concrete grep-friendly terms make Haiku confident enough to emit the strict EXPLORE_FINDINGS YAML instead of drifting into prose-format output (which would force the orchestrator into degraded mode and skip the findings block in the generator prompt).
  • skills/architecture-compliance/STACK_VALIDATION_CHECKLIST.md — deleted. Git history preserves it for reference when a live mechanism is implemented; keeping it in-tree alongside its removal would create a misleading half-deprecated artifact.
  • skills/architecture-compliance/templates/cc-004-development-architecture.template.md — replaced the **Stack Validation**: [VALIDATION_SUMMARY] (**MANDATORY**...) Compliance-Summary line with **EOL Validation**: .... Replaced "External Validation Required: ⚠️ MANDATORY - Stack Validation Checklist (STACK_VALIDATION_CHECKLIST.md)..." with the EOL equivalent. Stripped 11 "Cross-reference with Stack Validation Checklist Section X" / "Verify against Stack Validation Checklist" notes from LADES1 sub-sections (Backend / Frontend / Container / Database / API / CI/CD / IaC / Naming / Approved Libraries). Removed STACK_VALIDATION_CHECKLIST.md references from the LADES1.6 gap row, the auto-approve score breakdown, the priority order, and the change-history block. Added a v2.1 change-history entry documenting the removal. Updated the "Stack Validation" definition entry in A.1 to point at the new **EOL Validation** flow.
  • skills/architecture-compliance/SKILL.md — domain blurb (line 507) Technology stack validation, code coverage, technical debt management → Technology EOL/lifecycle tracking, code coverage, technical debt management. Validator-orchestration note (line 825) updated to reference EOL only.
  • skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md — Contract 5 description (line 398), the LADES1.6 Stack Validation Checklist summary, the "Example Guidelines" / "Automatic Stack Validation" callout, and the entire 480-line "Edge Case Handling for Automatic Stack Validation" section (Edge Cases 1–7: Backend-Only, Full-Stack, Polyglot Backend, Section 8 Missing, Partial Section 8, Deprecated Versions, Unapproved Technology) replaced with a single short "Edge Case Handling for Automatic EOL Validation" table covering the 5 cases the EOL-only validator actually handles.
  • skills/architecture-compliance/SECTION_MAPPING_GUIDE.md — Contract 5 block (lines 1065–1537, 473 lines) shrunk to a 50-line section. Removed the Step 3.5 "Automatic Stack Validation" sub-section, the LADES1.6: Technology Stack Validation example output, the extract_development_architecture / perform_stack_validation pseudo-code, and the legacy 4-scenario "Missing Data Handling" block. Replaced with concise "Special Feature — EOL Validation" wording and a 4-row "Missing Data Handling" table mirroring how the EOL validator actually behaves (corpus missing → FAIL; tech without version → skip; no conclusive EOL → UNKNOWN; WebSearch unavailable → degrade to UNKNOWN-with-PASS).
  • skills/architecture-compliance/validation/README.md, skills/architecture-compliance/shared/README.md, skills/architecture-compliance/shared/MIGRATION_GUIDE.md — strip / rewrite the LADES1.6 (Stack Validation Checklist) is a blocking requirement reasoning, the STACK_VALIDATION_CHECKLIST.md reference list, the "Migration Strategy" entry, and the "Cannot perform automatic stack validation" edge case row. Replaced with EOL-equivalents.
  • docs/QUICK_START.md, docs/TROUBLESHOOTING.md, docs/WORKFLOW_GUIDE.md — replace user-facing references: "automatic 26-item stack validation" → "automatic EOL validation against endoflife.date"; "Check stack validation here" → "Check EOL validation here"; "Stack validation shows all UNKNOWN" / "Stack validation fails with FAIL status" troubleshooting Q&As rewritten to the EOL flow; the long simulated stack-validation runtime trace in WORKFLOW_GUIDE.md replaced with a corresponding EOL-validator trace; the LADES1.6 example contract output replaced with the new DEV-EOL-{N} table.

Asset fidelity / no-invention guarantees: Architecture-derived data still flows through the existing phase3.required_files[] floor (5 files for Development: 02-architecture-principles.md, components/README.md, 06-technology-stack.md, adr/README.md, 09-operational-considerations.md). The orchestrator's degraded-mode fallback path (when the explorer cannot emit EXPLORE_FINDINGS) is unchanged. Validators continue to ignore the explorer (per the v3.16.0 cleanup) so the EOL check is unaffected by explorer behavior.

No code changes. Pure prompt / template / docs / config edits; no agent TypeScript / hook / utility changes. bun run typecheck clean, bun run build clean, bun test 392 / 392 pass.

Files:

  • agents/validators/development-validator.md — net −362 lines (Phase 2 + 26 items + two-phase framing removed; new EOL-only output schema and edge cases).
  • skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md — net −512 lines (Edge Case Handling section + Stack Validation prose).
  • skills/architecture-compliance/SECTION_MAPPING_GUIDE.md — net −455 lines (Contract 5 block trimmed).
  • skills/architecture-compliance/templates/cc-004-development-architecture.template.md — net −56 lines (checklist references stripped, EOL gate added, change-history bumped to 2.1).
  • docs/WORKFLOW_GUIDE.md — net −109 lines (long simulated trace + LADES1.6 example replaced).
  • skills/architecture-compliance/STACK_VALIDATION_CHECKLIST.md — deleted (67 lines).
  • 8 other secondary edits: agents/configs/development.json, skills/architecture-compliance/SKILL.md, skills/architecture-compliance/validation/README.md, skills/architecture-compliance/shared/README.md, skills/architecture-compliance/shared/MIGRATION_GUIDE.md, docs/QUICK_START.md, docs/TROUBLESHOOTING.md, plus the 3 version files (.claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json).

Net diff: 17 files changed (16 modified + 1 deleted), +220 / −1393 lines.

v3.21.10 (Previous Release) ✅

feat(architecture-docs): bidirectional Connection Naming Rule scope enforcement — sequence diagrams explicitly exempt; reviewers / audit gates skip CNR checks on sequenceDiagram blocks

v3.21.9 introduced the canonical Connection Naming Rule (<PROTOCOL>/<STYLE> [Action Type]) for the 4th Rel() parameter at C4 L1, C4 L2, and Diagram 4. The rule was scoped correctly in the prose (it talked about Rel() and graph TB arrow labels), but the scope itself was not enforced as a first-class section of the rule — a future reader could plausibly try to apply it to sequence-diagram messages too, since sequenceDiagram blocks also live in docs/04-data-flow-patterns.md and the v3.21.9 prose did not say "stop". Sequence-diagram messages (A->>B: ..., A-->>B: ..., A-)B: ...) are deliberately free prose describing what flows step-by-step — appending [Data] / [Event] / [Internal] to a sequence-diagram message degrades the flow narrative without adding signal. v3.21.10 adds explicit bidirectional scope enforcement: the rule MUST be applied to L1 / L2 / Diagram 4 (under-application is a violation), and the rule MUST NOT be applied to sequence-diagram message labels (over-application is also a violation). Audit gates and reviewers now have a deterministic instruction to skip Connection-Naming-Rule checks when the diagram's first line is sequenceDiagram.

Changes:

  • skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md — new #### Scope (ENFORCED — read before applying) subsection inside the Connection Naming Rule (between the rule statement and the Action-Type Vocabulary table) listing exactly what the rule applies to (Diagram 2 — C4 L1 C4Context, Diagram 3 — C4 L2 C4Container, Diagram 4 — Detailed View graph TB arrow labels) and what it explicitly does NOT apply to (Diagram 1 ASCII Logical View — labels are free prose; Sequence Diagrams in docs/04-data-flow-patterns.md — free prose, do NOT append [Action Type] tags, do NOT enforce <PROTOCOL>/<STYLE> casing, do NOT reject a label because it lacks the normal form; element-metadata strings inside Container("name", "technology", "description") are not connections). Includes a worked counter-example showing that a sequence-diagram message reading Frontend->>BFF: GET /orders is correct as-is and must NOT be rewritten to Frontend->>BFF: GET /orders [Data] or Frontend->>BFF: HTTPS/JSON [Data]. Sequence Diagrams (Sequence Diagrams) DO block at line ~787 gains a new "write message labels as free prose" instruction with three flow-narrative examples (Frontend->>BFF: GET /orders, BFF->>OrderSvc: CreateOrder(items, customerId), OrderSvc-)EventBus: OrderPlaced event); DON'T block gains an explicit Do NOT apply the Connection Naming Rule to sequence-diagram message labels directive that calls out over-application as a rule violation in the opposite direction and instructs reviewers and audit gates to skip Connection-Naming-Rule checks entirely when the diagram's first line is sequenceDiagram.
  • skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md — Section 5 cross-reference block (line ~292) extended with a third paragraph stating "Sequence diagrams are exempt from the Connection Naming Rule" and pointing back to the canonical Scope subsection. Reinforces the same audit-gate instruction.

No code changes. Pure scope-clarification edits; no agent / TypeScript / hook / template / config changes. Existing bun run typecheck and bun test (392 pass / 0 fail) remain green.

Files:

  • skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md — net +28 lines (Scope subsection + sequence-diagram Do/Don't extension).
  • skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md — net +2 lines (Section 5 cross-reference block third paragraph).

v3.21.9 (Previous Release) ✅

feat(architecture-docs): canonical Connection Naming Rule for C4 L1 + L2 — <PROTOCOL>/<STYLE> [Action Type] normal form, closed action vocabulary (10 entries), via/topic moved to description

The 4th Rel() parameter (the "protocol" string) had no canonical normal form across this repo. Examples were inconsistent — "REST/HTTPS", "JDBC", "Kafka topic: order-events", "HTTPS via Kong", "Kafka async" — all valid Mermaid C4 input but unparseable by readers and tooling that grep over diagrams (notably the IcePanel importer at skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md, which records the field verbatim into modelConnections.name). v3.21.7's Infrastructure-as-via Rule had also packed via Kong / Kafka topic: order-events (async) into the same field, mixing transport spec with transit context. v3.21.9 settles the field: the 4th parameter is now a strict normal form <PROTOCOL>/<STYLE> [Action Type]; via-hop, topic / queue name, and sync/async flag move to the 3rd parameter (description) in (via Kong) / (Kafka topic: orders, async) form. Action type is a closed vocabulary of 10 tags — [Data] (cross-trust-boundary business data), [Internal] (service-to-service), [Event] (async pub/sub), [Auth] (authn/authz/token validation), [Cache] (Redis/Memcached I/O), [Stream] (WebSocket / SSE / gRPC streaming), [Query] (DB/search read), [Write] (DB/search write — distinguish from [Query] only when CQRS), [Storage] (S3/GCS/Azure Blob), [Telemetry] (OTLP/Prometheus/Jaeger). Anything outside the closed set is rejected by the rule.

Changes:

  • skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md — new canonical ### Connection Naming Rule (L1 + L2) section between the Infrastructure-as-via Rule and Color Conventions, with the rule statement, the 10-entry Action-Type Vocabulary table, the Protocol / Style Common Pairings table (12 protocols × common styles, ~95% of architecture diagrams), 11 worked examples spanning all 10 action types, an explicit Diagram-4 / graph TB form (SVC_A -- "HTTPS/JSON [Data]" --> SVC_B), and an anti-patterns block listing exactly what the rule rejects ("REST/HTTPS" wrong order, "Kafka async" missing style+action, "HTTPS via Kong" via-in-protocol, "Kafka topic: X" topic-in-protocol, bare "HTTPS", lowercase casing). Rule 5 of Diagram 3 rewritten from Use the 4th parameter of Rel() — HTTPS, gRPC, Kafka, JDBC, etc. to a strict-form mandate plus a Rule 6 update specifying that sync/async, via-hop, topic/queue context lives in the 3rd parameter (description). Diagram 2 (C4 L1) template updated — the placeholder Rel(...) calls show the new form. Diagram 3 (C4 L2) template rewritten — every Rel() 4th parameter follows the normal form, every 3rd parameter carries via/topic context. L1 + L2 Infrastructure-as-via Rule example tables (sync via gateway, async via topic, async via queue, multi-hop transit, pub/sub fan-out) every example moved to description+protocol split. C4 Do/Don't list (line ~744) extended — Do bullet specifies the normal form mandate and rejection criteria; Do bullet for Rel() description specifies via/topic encoding; new Don't bullets reject via/topic in 4th parameter and inventing new action tags. Color Conventions table footnote on ContainerQueue() reinforces exception-only use. Duplicate ### Color Conventions heading (artifact from earlier edits) cleaned up.
  • skills/architecture-docs/references/META-TO-C4-TRANSLATION.md — C2 Translation Rules table API Gateway / Message broker rows updated to specify description vs. protocol split with canonical examples ("HTTPS/JSON [Data]", "TLS/AVRO [Event]"). C2 Grouping Convention bullet list aligned. Example C2 Elements block rewritten end-to-end: every [HTTPS via Kong], [REST/HTTPS], [gRPC], [JDBC], [MQ/JMS] converted to em-dash trailing canonical normal form (HTTPS/JSON [Data], HTTPS/REST [Internal], gRPC/PROTOBUF [Internal], JDBC/SQL [Write], MQ/JMS/XML [Internal]); via-hop and Kafka topic context moved to description. Both C3 examples (Layer 3 saga orchestrator, Layer 5 BIAN service domain) rewritten the same way. Section 6 Pattern Translations (SaaS Integration, Transversal Services, BIAN SD Core Banking call) rewritten. Quick Reference Card "API Gateway" and "Event Bus (Kafka)" rows updated to show description+protocol split.
  • skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md — What to Show table API Gateway / Message broker rows updated. Notation Conventions block rewritten — Protocol on arrows now specifies the canonical normal form, via annotation now in 3rd parameter, topic / queue annotation now in 3rd parameter. C2 Grouping Convention aligned. Example C2 Elements block rewritten — Web App calls via Kong on description, broker collapses on description, every Rel() 4th parameter follows normal form. C3 example (lines ~170-191) rewritten. All 5 Pattern-Specific C4 Translations rewritten — 5.1 API Gateway + BFF (kept BFFs as nodes, gateway collapsed), 5.2 Event-Driven Choreography (broker collapses, every producer-consumer pair gets TLS/AVRO [Event] on protocol with topic in description), 5.3 Saga Orchestration, 5.4 CQRS + Event Sourcing (with [Write] / [Query] / [Event] distinguished), 5.5 Database per Service, 5.6 Service Mesh (already-anti-pattern wording preserved), 5.7 External SaaS Integration (Stripe / SendGrid / Twilio with [Data]). Visual Conventions Arrow Conventions table replaced with a 10-row table covering every action type. Quick Reference Card Arrow Labels block rewritten with description+protocol split per kind.
  • skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md — "What IS a Separate Container?" table Kafka and API Gateway rows updated to show description+protocol split with canonical examples. C2 What to Show table aligned. C2 Rules item 4 rewritten from SQL/JDBC, Redis Protocol, REST/HTTPS, AMQP to JDBC/SQL [Write], TCP/RESP [Cache], HTTPS/REST [Internal], AMQP/JSON [Event]. Both Variant-Specific C3 ASCII boxes (DDD 4-Layer, Hexagonal Architecture) updated — the right-hand arrows that previously showed Kafka topic: orders (async) as label now show TLS/AVRO [Event] as protocol with description annotation in parens. Domain Events block rewritten — --[Kafka topic: order-events (async)]--> becomes -- "TLS/AVRO [Event]" --> with description / protocol slots called out. Quick Reference N-Layer → C2 table updated. Arrow-label conventions block (lines ~430-440) replaced — listing 10 canonical 4th-parameter forms (one per action type) plus a description-parameter contract.
  • skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md — C2 What to Show table Event Bus / API Gateway rows updated to description+protocol split. Non-BIAN-container labels block — the v3.21.7-added Rel() examples (Settlement events, Account inquiry) rewritten to put topic / via context in description and "TLS/AVRO [Event]" / "HTTPS/JSON [Data]" in protocol.
  • skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md — C2 Deployment Variants 1, 2, 3, 4, 5 every example rewritten. Pattern Translations 5.1 Authentication Flow (with [Auth] action), 5.2 File Upload (with [Storage]), 5.3 Background Jobs, 5.4 Caching (with [Cache] / [Query]), 5.5 External API Integration all rewritten. Anti-Pattern fix wording aligned (HTTPS/JSON [Data] instead of bare REST/HTTPS). Microservices-comparison parenthetical updated.
  • skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md — Section 5 cross-reference block extended with a paragraph stating that the 4th Rel() parameter at L1 / L2 follows the canonical normal form per DIAGRAM-GENERATION-GUIDE.md → "Connection Naming Rule (L1 + L2)", and that Diagram 4 (graph TB below) follows the same normal form on its arrow labels (with two graph TB examples).
  • skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md — modelConnections.name field example replaced from "Protocol / Description" # e.g. "REST/HTTPS", "Kafka async" to the canonical <PROTOCOL>/<STYLE> [Action] form with examples drawn from the rule. Source File → YAML Mapping table "Connection protocol" / "Connection description" rows annotated with cross-reference to the Connection Naming Rule and the description-parameter contract.
  • skills/architecture-icepanel-sync/SKILL.md — L1 + L2 Rel(from, to, "description", "protocol") extraction steps annotated to state that the 3rd parameter carries the verb plus any via-hop / topic / queue / async context, the 4th parameter follows the canonical <PROTOCOL>/<STYLE> [Action Type] normal form, and the IcePanel modelConnections.name field stores the 4th-parameter value verbatim. ContainerQueue() extraction line annotated as exceptional use only.

No code changes. No agent / TypeScript / hook / setup-permissions / template / config changes. Existing bun run typecheck and bun test (392 pass / 0 fail) remain green.

Files:

  • skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md — net +75 lines (new Connection Naming Rule section + Rule 5/6 rewrite + L1/L2 templates + via-rule example tables + Do/Don't extension + duplicate-heading fix).
  • skills/architecture-docs/references/META-TO-C4-TRANSLATION.md — net +18 lines (table edits + C2 example rewrite + C3 examples + patterns + Quick Reference).
  • skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md — net +25 lines (Notation + grouping + C2/C3 examples + 5 patterns + Visual Conventions table expansion).
  • skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md — net +20 lines (tables + C2 Rules + ASCII boxes + Domain Events + Quick Reference + Arrow conventions).
  • skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md — net +2 lines (C2 table + non-BIAN labels block edits).
  • skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md — net +12 lines (5 deployment variants + 5 patterns + anti-pattern fix + comparison parenthetical).
  • skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md — net +2 lines (cross-reference block extension).
  • skills/architecture-icepanel-sync/ICEPANEL_IMPORT_REFERENCE.md — net +4 lines (schema example + mapping table annotation).
  • skills/architecture-icepanel-sync/SKILL.md — net +2 lines (Rel() / ContainerQueue annotation).

v3.21.8 (Previous Release) ✅

feat(architecture-docs): promote Step 7.3 to a BLOCKING DIAGRAMS_GATE — Workflow 1 cannot complete with missing or invalid mandatory diagrams; Workflow 8 scope clarified as regen-only

Before v3.21.8, the Architecture Type Selection Workflow's Step 7 (Mandatory Diagram Generation) said the right things in prose ("This step is not optional"; "do not skip or defer") but Step 7.3 (Mandatory Diagram Completeness Audit) was a soft check — a single re-read of docs/03-architecture-layers.md and docs/04-data-flow-patterns.md, a list of what should be there, and an instruction to "generate it now" if anything was missing. There was no blocking declaration, no failure-mode protocol, no metadata-stamped outcome, and no protection against the case where re-generation itself produces a malformed diagram (HTML in labels, semicolon in node text, missing mermaid fence). The result: in pathological runs, Step 7.4 ("✅ Architecture creation complete") could print while a Mermaid diagram quietly failed at render time, leaving downstream skills (compliance, dev-handoff, peer-review, release) operating on a partially-illustrated architecture without knowing it. Separately, Workflow 8's trigger block in SKILL.md documented its diagram-generation triggers but never positioned itself relative to Workflow 1, so a user invoking /skill architecture-docs mid-creation could land in Workflow 8 (regen on a non-existent baseline) instead of Workflow 1 Step 7 (initial generation as part of creation). v3.21.8 closes both gaps.

Changes:

  • skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md — Step 7.3 promoted to a BLOCKING gate (renamed Mandatory Diagram Completeness Audit (BLOCKING)). Opening sentence states explicitly that Step 7.4 cannot run until every mandatory diagram is verified present and well-formed; the workflow does NOT print ✅ Architecture creation complete while any required diagram is missing or fails Pre-Write Validation. Audit checks expanded from 3 items to 4: (D1) Logical View ASCII code block under heading #### Diagram: Logical View, (D2/D3/D4) one mermaid block each under their canonical headings in docs/03-architecture-layers.md, plus a sequenceDiagram count check in docs/04-data-flow-patterns.md (count ≥ H3 flow subsection count), plus a per-block Pre-Write Validation re-scan (no <br/> / <br> / HTML, no ; in labels, no emoji, no | in node-label text). A diagram that exists but fails Pre-Write Validation counts as MISSING for the purposes of the gate. Three explicit outcomes documented: PASS (proceed to Step 7.4), FAIL first attempt (regenerate per Step 7.1 rules and re-run audit from item 1; do not skip / defer / proceed), FAIL after second regeneration attempt (stop the workflow and emit a stamped ❌ DIAGRAMS_GATE: FAILED block listing every missing/invalid diagram by name + canonical location, instructing the user to consult references/DIAGRAM-GENERATION-GUIDE.md and MERMAID_DIAGRAMS_GUIDE.md, regenerate, and re-run the gate via the "audit diagrams" trigger; Workflow 1 cannot complete until DIAGRAMS_GATE passes; downstream skills MUST refuse to run on a partial-state ARCHITECTURE.md). No SKIP DIAGRAMS override — diagrams are a delivered artifact of the creation workflow, not a soft prerequisite (deliberately diverging from the PO Spec Gate's SKIP PO SPEC pattern, since unlike PO Spec there is no class of project where mandatory diagrams could be legitimately absent).
  • skills/architecture-docs/SKILL.md — Workflow 8 trigger block (line ~144) gains a new Scope clarification paragraph stating that Workflow 8 is for regenerating, updating, or auditing diagrams on an existing ARCHITECTURE.md and is NOT how new architectures get their first diagrams; new-architecture creation routes to Workflow 1, whose Step 7 auto-runs diagram generation and won't complete until the BLOCKING DIAGRAMS_GATE in Step 7.3 passes. Workflow 1 Note (line ~172) extended from a one-sentence ADR-Context-Block-only summary to a full guarantee block: Workflow 1 always concludes with Step 7 (Mandatory Diagram Generation) producing the 4 standard diagrams (Logical View ASCII, C4 L1, C4 L2, Detailed View) into docs/03-architecture-layers.md and one sequenceDiagram per H3 flow subsection into docs/04-data-flow-patterns.md; Step 7.3 is the BLOCKING DIAGRAMS_GATE; Workflow 1 does NOT print ✅ Architecture creation complete until every mandatory diagram is verified present and Pre-Write-Validation-clean; no SKIP DIAGRAMS override.

No code changes. No agent / TypeScript / hook / setup-permissions / template / config changes. The audit re-uses the Pre-Write Validation rules already documented in Step 7.1 and the canonical diagram headings already documented in Step 7.1; no new permission scopes required. Existing bun run typecheck and bun test (392 pass / 0 fail) remain green.

Files:

  • skills/architecture-docs/ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md — net +28 lines (Step 7.3 rewrite — PASS / FAIL-first / FAIL-second outcomes + DIAGRAMS_GATE failure block + no-override clause).
  • skills/architecture-docs/SKILL.md — net +2 lines (Workflow 8 Scope clarification paragraph + Workflow 1 Note expansion).

v3.21.7 (Previous Release) ✅

feat(architecture-docs): Infrastructure-as-via Rule for C4 L1 + L2 diagrams — collapse APIM, brokers, topics, queues onto edge labels

Before v3.21.7, Workflow 8 of architecture-docs rendered transit infrastructure as first-class nodes at every C4 zoom level: API Management / API Gateway became Container("API Gateway [Kong]") (and at L1, System_Ext("Apigee")); message brokers became ContainerQueue("Event Bus [Apache Kafka]"); iPaaS / service mesh / load balancers showed up as their own boxes. The result was a producer→broker→consumer chain (3 nodes / 2 edges per async hop) and a client→APIM→service chain (3 nodes / 2 edges per sync hop) repeated for every interaction, even though the C4 L1/L2 audience (architects, stakeholders) is asking "which business component talks to which" — not "which infra it transits through". Pub/sub fan-out compounded the problem: a single Kafka topic with N consumers added 1 broker node + 2N edges where N edges with the topic name on the label would have answered the same question. Operational fidelity (every topic, queue, partition) belongs in Diagram 4 (Detailed View, graph TB), which is the diagram SREs actually read — but the C4 L1/L2 templates kept treating it like Diagram 4. v3.21.7 promotes the convention used by experienced architects to a first-class rule.

Changes:

  • skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md — Diagram 2 (C4 L1) gains a new ### Infrastructure-as-via Rule (L1) subsection between the Template and Color Conventions: edge gateways, APIM, iPaaS, edge CDNs used for routing, and service-mesh / load balancers / reverse proxies collapse into the 4th Rel() parameter ("HTTPS via Apigee", "HTTPS via Mulesoft", "HTTPS via CloudFront → AWS APIGW"); external systems that own business logic / state (Stripe, SAP, Core Banking, SWIFT) stay as System_Ext(). Diagram 3 (C4 L2) gains a parallel ### Infrastructure-as-via Rule (L2) subsection with a complete inventory of what collapses (APIM, Kafka/RabbitMQ/SQS/SNS/EventBridge/Service Bus/ActiveMQ/NATS, service mesh, LBs, edge CDNs, iPaaS), what stays as nodes (ContainerDb() always, application containers with business logic, System_Ext() with state/logic), edge-label syntax for sync-via-gateway / async-via-topic / async-via-queue / multi-hop transit, an explicit pub/sub fan-out rule (one Rel() per producer-consumer pair, topic name on each edge — broker is never emitted), and a fallback for subscribers with no in-scope producer (System_Ext("event-source")). Rule 2 of Diagram 3 reworded to drop ContainerQueue() from the default-path bullet list and cross-reference the new rule. The L2 template (lines 208–233) loses its ContainerQueue(q1, ...) declaration and the two queue-direction Rel() lines, gaining a "Kafka topic: order-events" edge label and a "HTTPS via Apigee" edge label to demonstrate the new pattern. Color Conventions table footnotes the exceptional use of ContainerQueue() (owned/custom broker that IS the architectural unit). The "C4 Diagrams — Diagrams 2 and 3" Do/Don't list (line ~660) drops ContainerQueue() from the Do bullet and adds an explicit Do for transit-infra encoding via the protocol parameter.
  • skills/architecture-docs/references/META-TO-C4-TRANSLATION.md — C2 Translation Rules table swaps "API Gateway" and "Message broker" rows from Container()/ContainerQueue() mappings to "Edge label only" with the canonical "HTTPS via Kong" / "Kafka topic: payment-events (async)" examples; C2 Grouping Convention drops ContainerQueue() from the bullet list; both Example C2 Element blocks (Payment Service publishing payment-events, the IAM transversal-services example, and the API Gateway routing block) rewritten to demonstrate the via-style edges with one Rel() per producer-consumer pair; both C3 examples (Layer 4 NotificationClient publishing to Event Bus, Layer 5 AccountEventPublisher publishing to Event Bus) rewritten to target real consumer containers (Notification Service, Audit Service) instead of an "Event Bus" container; final Quick Reference table changes "API Gateway → C2 Container (infrastructure)" and "Event Bus (Kafka) → C2 Container (infrastructure)" rows to edge-label rows with a note that Diagram 4 keeps the broker as a node.
  • skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md — What to Show table splits "API Gateway / BFF" into two rows (BFF stays Container(), API Gateway becomes "Edge label only"); "Message broker" row converted to "Edge label only" with Do NOT emit ContainerQueue("Event Bus") warning. Notation Conventions adds via annotation and topic / queue annotation as first-class arrow-label forms. C2 Grouping Convention drops ContainerQueue(). Example C2 Elements rewritten — Container: "API Gateway [Kong]" removed entirely, Web App's edges relabeled [HTTPS via Kong] to each downstream service; Container: "Event Bus [Apache Kafka]" removed entirely, Order Service publishes via [Kafka topic: order-events (async)] directly to Payment Service and Notification Service; Payment Service publishes via [Kafka topic: payment-events (async)] directly to Notification Service; Stripe call relabeled [HTTPS via Mulesoft]. C3 example rewritten — OrderEventPublisher targets real consumer containers (Notification, Inventory) instead of "Event Bus"; PaymentEventConsumer subscription redirected from "Event Bus" to Payment Service. Pattern 5.2 (Event-Driven / Choreography) rewritten end-to-end as the canonical multi-consumer fan-out illustration: each producer → each consumer pair gets one [Kafka topic: X (async)] edge, no broker node.
  • skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md — "What IS a Separate Container?" table converts the "Kafka / RabbitMQ" row from "YES — separate Container" to "NO at L2 — edge label" with the full canonical-rule cross-reference; "API Gateway / APIM" row added in the same form. C2 Grouping line drops ContainerQueue(). C2 What to Show table swaps "Message broker → Container (App)" for "Edge label only" and adds an "API Gateway / APIM → Edge label only" row. Both Variant-Specific C3 ASCII boxes (DDD 4-Layer, Hexagonal Architecture) rewritten — the right-hand "Event Bus [Kafka]" target box becomes "Inventory Svc [Spring Boot]" with the arrow relabeled Kafka topic: orders (async). Domain Events block in Pattern Translations rewritten to redirect DomainEventDispatcher's edge from "Event Bus [Kafka] (C2 Container)" to "Inventory Service (C2 Container — consumer)" with the topic on the edge. Quick Reference Card N-Layer → C2 table swaps "Message broker → Container [Technology]" for "Edge label only" and adds the API Gateway row. Arrow label conventions block adds HTTPS via Kong and Kafka topic: orders (async) examples.
  • skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md — C2 introduction line drops ContainerQueue() from the default-path enumeration. What to Show table converts "Event Bus → Container [Apache Kafka]" and "API Gateway → Container (App)" rows to "Edge label only" with canonical cross-references. BIAN-Specific Labeling Convention block drops Domain Event Bus [Apache Kafka 3.6] from the non-BIAN-container example list, gaining a paragraph showing the via-style Rel() syntax instead.
  • skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md — C2 introduction line drops ContainerQueue() from the default-path enumeration. Microservices-comparison container list drops "API Gateway [Kong]" and "Event Bus [Apache Kafka]" entries (renumbered 1–10) with an inline note that those collapse to edge labels per the canonical rule.
  • skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md — Section 5 cross-reference block (line ~290) extended with one paragraph stating that C4 L1 / L2 collapse transit infrastructure into edge labels per the new rule, while Diagram 4 (graph TB below) keeps every topic, queue, and broker as a first-class node — operational fidelity lives there.

No code changes. No SKILL.md / agent / TypeScript / hook / setup-permissions / template / config changes outside the architecture-docs references and the MERMAID guide. Existing bun run typecheck and bun test (392 pass / 0 fail) remain green. No permission changes required.

Files:

  • skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md — net +85 lines (new L1 + L2 rule subsections, template rewrite, Rule 2 / color-conventions / Do-Don't edits).
  • skills/architecture-docs/references/META-TO-C4-TRANSLATION.md — net +28 lines (table edits + two C3 example rewrites + Quick Reference edit).
  • skills/architecture-docs/references/MICROSERVICES-TO-C4-TRANSLATION.md — net +27 lines (table + Notation + grouping + C2 example + C3 example + Pattern 5.2 rewrite).
  • skills/architecture-docs/references/N-LAYER-TO-C4-TRANSLATION.md — net +24 lines (Separate-Container table + C2 What to Show + ASCII boxes + Domain Events + Quick Reference + Arrow conventions).
  • skills/architecture-docs/references/BIAN-TO-C4-TRANSLATION.md — net +6 lines (C2 intro + What to Show + Labeling Convention edits).
  • skills/architecture-docs/references/3-TIER-TO-C4-TRANSLATION.md — net +4 lines (C2 intro + Microservices container list).
  • skills/architecture-docs/MERMAID_DIAGRAMS_GUIDE.md — net +2 lines (Section 5 cross-reference paragraph).

v3.21.6 (Previous Release) ✅

feat(component-guardian): write <!-- EXPLORER_HEADER --> blocks at component-creation time — first-class header authoring

architecture-component-guardian is the only sanctioned writer for docs/components/**/*.md (L1 system descriptors and L2 containers), but until v3.21.6 every file it produced went to disk without an EXPLORER_HEADER block. The downstream cost was real: agents/builders/architecture-explorer.md (the universal Haiku navigator) reads only the first 60 lines of each component file and surfaces key_concepts, technologies, component_self, component_type, and related_adrs from the header block into the EXPLORE_MANIFEST. Compliance, dev-handoff, peer-review, and analysis skills filter that manifest by those fields. Components freshly minted by the guardian appeared in the manifest with empty arrays until architecture-explorer-headers was run separately to backfill — degrading every downstream classification. The same gap existed in the C4 multi-system migration workflow (Phases M3/M4): legacy files gained C4 metadata but no EXPLORER_HEADER. v3.21.6 promotes the guardian to first-class header writer; architecture-explorer-headers returns to its true backfill-only purpose.

Changes:

  • skills/architecture-component-guardian/SKILL.md — new ## EXPLORER_HEADER Block — Generation Rules section between the Format Specification and Workflow sections, with format spec for both L2 containers and L1 system descriptors, field derivation rules table, refresh rules per action (add/update/migrate/sync), and post-write validation via the existing header-cli.ts validate CLI. Step 3 action table updated so add/update/migrate rows mention header authoring/refresh; sync explicitly stays read-only. Step 3a.4 templates extended — L1 descriptor and L2 container both now embed the EXPLORER_HEADER + 30-second blockquote between the H1 and the first metadata line, with a new sub-step 4 that validates each written file. New Phase M3.5 (Write EXPLORER_HEADER block) added to the migration workflow with field-derivation rules sourced from the migrated file's existing body; skips files that already have a hand-curated header. Phase M4.1b reuses the same format for L1 descriptors created during migration. Step 5 verification gains two checklist items (header presence + validator pass) plus a header-only revert protocol on validator failure (the C4 file body is never rolled back). Phase M8.4 final report adds an EXPLORER_HEADERs added: H files line.
  • skills/architecture-explorer-headers/SKILL.md — ## When This Skill Is Invoked "NOT activated for" list strengthened: the architecture-component-guardian entry now explicitly states that the guardian is the first-class writer for component files at create/update/migrate time, and this backfill skill must NOT be used to fill gaps left by the guardian — only for legacy docs/NN-*.md files or to repair drift caused by external edits.
  • CLAUDE.md — Trigger Routing table row for architecture-component-guardian extended to note the new EXPLORER_HEADER responsibility ("only sanctioned writer ... and <!-- EXPLORER_HEADER --> blocks for every component file it writes").

No code changes. header-detector.ts (HEADER_OPEN, HEADER_CLOSE, ALLOWED_FIELDS, REQUIRED_FIELDS_*, buildHeader, validateHeader, findInsertionPoint) and header-cli.ts (validate subcommand) already expose everything the guardian needs. The existing Bash(bun *) permission in .claude/settings.json.example:25 covers the validator invocation — no permission changes required.

Files:

  • skills/architecture-component-guardian/SKILL.md — net +127 lines (new section + Step 3a.4 / Phase M3.5 / Step 5 / Phase M8.4 edits).
  • skills/architecture-explorer-headers/SKILL.md — net +1 line (clarification of activation scope).
  • CLAUDE.md — net 0 lines (table row appended in place).

v3.21.5 (Previous Release) ✅

chore(cc-006): drop CloudEvents Compliance field from Integration Architecture contract — scope reduction

The CC-006 Integration Architecture contract (templates/cc-006-integration-architecture.template.md) carried a dedicated CloudEvents Compliance field under §7.1 Event Schema Standards, scored at weight 0.20 inside lai7_event_driven. CloudEvents is one of several valid event-metadata conventions (alongside custom envelopes, AsyncAPI message metadata, and Avro/Protobuf headers); pinning the contract to the CNCF specification produced false-negative deviations against architectures that used equivalent custom metadata schemes documented in §6 — the validator could only return PASS for explicit CloudEvents adoption, FAIL for absence, or UNKNOWN when the documented format wasn't named CloudEvents. The field was removing signal more often than it added. v3.21.5 removes it; the surviving §7.1 control (Event Schema Definition) covers the underlying intent (events have a documented schema format) without privileging one specification.

Changes:

  • templates/cc-006-integration-architecture.template.md — CloudEvents Compliance field block removed from §7.1; CloudEvents removed from the Definitions glossary, the Common Gaps Quick Reference remediation row, the §6.3 "Strengthen Security & Standards Compliance" recommendations bullet, and the FAIL-Items "Missing Standards" remediation list. §7.1 now flows from a single control directly into §7.2 Event Versioning and Compatibility.
  • validation/cc-006-integration-architecture-validation.json — cloudevents_compliance item removed from lai7_event_driven. Remaining LAI7 weights rebalanced to sum to 1.0: event_schema_definition 0.25 → 0.30, event_catalog 0.25 → 0.30, dlq_handling 0.30 → 0.40 (DLQ retains the highest weight as the most operationally consequential async control).
  • SECTION_MAPPING_GUIDE.md — LAI7 Section 6 mapping no longer lists CloudEvents; Section 6 Key Extractions row drops "CloudEvents format"; LAI7 Requirement reframed from "CloudEvents specification with schema registry" to "Schema registry with versioning."
  • COMPLIANCE_GENERATION_GUIDE.md — LAI7 generation guidance and Section 6 extraction note updated to drop CloudEvents; total Validation Items count corrected to 28 (5+4+4+4+4+4+3) — the previous "25" figure was already arithmetically inconsistent with the actual 7-section breakdown.

Out of scope: The integration-validator agent (INT-01..INT-13 item set) never had a CloudEvents check — its INT-05 message-pattern item evaluates pub/sub / event sourcing / CQRS, and INT-06 evaluates message format (JSON / Avro / Protobuf) without specification-name privileging. No validator change was needed. The CC-005 Enterprise Architecture template retains a single CloudEvents mention as one of three example schema standards in a remediation note; that's CC-005 scope, not CC-006.

Impact on existing contracts. Already-generated CC-006 contracts containing the CloudEvents field remain valid as historical artifacts but will not match the new validation JSON shape. Users regenerating CC-006 after upgrading will get the 3-item LAI7 section directly; no migration is needed.

Files:

  • skills/architecture-compliance/templates/cc-006-integration-architecture.template.md — net −12/+1 lines.
  • skills/architecture-compliance/validation/cc-006-integration-architecture-validation.json — net −13 lines (item removed) plus three weight edits.
  • skills/architecture-compliance/SECTION_MAPPING_GUIDE.md — net −2/+2 lines.
  • skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md — net −3/+3 lines.

v3.21.4 (Previous Release) ✅

chore(setup): /setup gitignore step now manages .claude/settings.json — avoids committing platform-resolved absolute hook paths

v3.21.1 introduced platform-aware install in setup-permissions.ts: at /setup time the helper detects process.platform and writes the absolute path to a native hook wrapper (route-architecture-docs.sh on Linux/macOS/WSL/Git Bash, .cmd on Windows native cmd, .ps1 on PowerShell) into the merged .claude/settings.json. Both the wrapper choice and the absolute path differ per host (Linux home dir vs Windows user profile vs WSL mount), so committing .claude/settings.json to a shared repo creates cross-OS friction — a teammate on a different host would inherit a hook command pointing at a non-existent path until they re-ran /setup themselves. v3.21.4 closes this by gitignoring the file.

scripts/setup-gitignore.ts changes:

  • .claude/settings.json added to MANAGED_ENTRIES — the script now manages four entries instead of three (exports/, .cache/sa-skills/, CLAUDE.md, .claude/settings.json). Each developer re-runs /setup locally; the merged settings file stays on disk per-machine instead of being version-controlled.
  • Already-tracked warning loop generalized — the existing one-line warning (which previously only checked CLAUDE.md) now iterates over a FILE_ENTRIES_TO_CHECK array covering both CLAUDE.md and .claude/settings.json. If either file was already committed before the upgrade, the helper prints a git rm --cached <path> instruction so the user can untrack it without losing the file on disk. .gitignore alone never untracks files git already knows about — the warning makes the next step explicit.

commands/setup.md (Step 6) changes:

  • Lists the fourth entry (.claude/settings.json) and spells out the rationale: v3.21.1+ writes platform-resolved absolute hook paths, so the file is per-developer, not committable.
  • Documents the generalized already-tracked warning behavior so users on existing installs understand why they may see the git rm --cached prompt the first time they re-run /setup after upgrading.

Idempotent. Re-running /setup after upgrading prints + .claude/settings.json once, then Unchanged on every subsequent run. Existing user .gitignore entries are never reordered or removed; the helper only appends missing entries under the # sa-skills header.

Migration. Users who previously checked in .claude/settings.json should run /setup once to add the entry to .gitignore, then run git rm --cached .claude/settings.json (the helper prints this command for them) to stop tracking the file. The file stays on disk; only the git index entry is removed. Users who never committed .claude/settings.json see only the new gitignore line — no other action needed.

Files:

  • scripts/setup-gitignore.ts — .claude/settings.json added to MANAGED_ENTRIES; already-tracked warning loop generalized from CLAUDE.md-only to a FILE_ENTRIES_TO_CHECK array covering both file-style entries; net +10/-7 lines.
  • commands/setup.md — Step 6 documentation updated with the fourth entry, the platform-resolved-absolute-paths rationale, and the generalized already-tracked warning note; net +3/-1 lines.

Verification: bun run typecheck ✅. Smoke-tested on a fresh git init directory (first run adds all 4 entries, second run reports Unchanged) and on a repo where both CLAUDE.md and .claude/settings.json were committed before the upgrade (both git rm --cached warnings fire correctly).

v3.21.3 (Previous Release) ✅

feat: BPM / DMS scope reframe of CC-008 Process Transformation contract — applicability gate + platform-specific questions

Before v3.21.3, the CC-008 Process Transformation contract was framed in generic "automation" language (manual effort, automation factors, license efficiency, document management alignment). Anyone running compliance against an architecture that had no BPM platform and no Document Management System would still get the contract scored against generic prose, producing low-signal output and false-negative gaps. Conversely, users with FileNet / Athento / Camunda / IBM BAW architectures got questions that didn't anchor on the platform's actual semantics (PVU, CAL, Object Stores, BPMN node types, External Tasks, Records Management). v3.21.3 reframes the entire contract around the BPM / DMS scope it was always intended to evaluate.

Contract scope change:

  • New Applicability section at the top of the contract enumerates the BPM platforms (Camunda, Camunda 8, IBM BAW, Activiti, jBPM, Bonita, Flowable, Pega, Appian, ProcessMaker, Oracle BPM Suite, TIBCO ActiveMatrix BPM) and DMS platforms (FileNet P8, Athento, SharePoint-as-DMS, OpenText Documentum, Alfresco, OpenText Content Server, Nuxeo, Hyland OnBase, Box Enterprise, M-Files) the contract evaluates. If the architecture contains NEITHER, all four LAA codes are marked Not Applicable and the contract is scored N/A overall — no false-negative gaps on projects this contract was never supposed to apply to.
  • Partial applicability rules documented for BPM-only (LAA1+LAA2+LAA3 apply; LAA4 N/A), DMS-only (LAA1+LAA3+LAA4 apply; LAA2 N/A), and both (canonical case — all four apply).
  • The validator agent is now required to grep ARCHITECTURE.md Sections 4/5/6/7/8 for any BPM or DMS platform name and record the result in External Validation Summary → Applicability Verification.

Template — all 14 subsections reframed:

  • LAA1 (Feasibility & Impact) anchors questions in BPM concepts (BPMN node count, gateway count, escalation paths, sub-process nesting, cycle-time ROI) and DMS concepts (Document Type taxonomy size, classification rules, retention schedule complexity, ingestion-to-availability latency, storage / retrieval ROI).
  • LAA2 (Operational Factors) classifies BPMN task types (User Task with SLA, Service Task sync/async, External Task, Receive Task, Timer Boundary) and DMS ingestion paths (manual upload, scan-to-DMS, email-to-DMS, API push). Throughput questions ask for process-instances/day and documents/day at peak and steady state. Monitoring questions name BPM-specific metrics (per-model active instances, cycle-time p50/p95, External Task fail rate, Incident count) and DMS-specific metrics (ingestion success rate, classification confidence, retention-policy execution, repository free-space).
  • LAA3 (License Usage) enumerates platform-specific licensing metrics: Camunda per-engine/per-cluster, IBM BAW PVU + Authorized User, Pega per-case-type, Appian Application User tier, FileNet PVU + Authorized User CAL + Connection license, Athento per-active-process + per-user + per-document-store, SharePoint per-server+CAL or M365 per-user, Documentum per-repository + Authorized User, Alfresco per-repository + per-active-user. Cost-optimization tactics are platform-aware (engine cluster consolidation, External Task off-peak scaling, OSS for low-criticality flows; DMS storage tiering, Document-Class consolidation, federation, archive-tier migration).
  • LAA4 (Document Management Alignment) uses DMS-native semantics: FileNet (Object Stores + Document Classes + Lifecycle Policies + Records Management), Athento (Dossiers + Document Types + Workflow states + Retention Templates), SharePoint (Site Collections + Libraries + Content Types + Information Management Policies), Alfresco (Sites + Folders + Aspects + Rules). Authentication / authorization questions name DMS-native ACL surfaces (Object Store ACLs, Library permissions, RM record-class security, Information Management Policies / AIP labels).

Definitions (A.1) split into BPM Terms (BPMN, CMMN, Process Instance, Token, External Task, User Task), DMS Terms (Object Store, Document Class, Records Management, CMIS, Federation/Connection license), and Cross-Cutting Terms (Manuality, LOB Integration, ROI). Adds BAW (IBM Business Automation Workflow) abbreviation; removes RPA (out of scope — generic RPA without an underlying BPM engine routes to other contracts).

Common Gaps Quick Reference (A.3.1) rewritten with 13 BPM/DMS-specific entries. The first row is "BPM/DMS platform not named" — flags applicability ambiguity (where the architecture says "workflow engine" or "document store" without naming a platform) as the highest-priority gap, since misclassification at the gate cascades into every downstream LAA evaluation.

Auto-Approve guide (A.3.2) reorganized around the BPM/DMS scope: a Pre-step verifies the applicability gate, then remediation is anchored in BPMN/CMMN diagrams, DMS object models, BPM connector inventories, and platform licensing models.

Validation JSON (cc-008-process-transformation-validation.json) bumped to 2.1.0 with:

  • New top-level applicability block enumerating bpm_platforms, dms_platforms, 5 scoping_rules (neither / BPM-only / DMS-only / DMS-with-embedded-workflow / both), and a verification rule for the validator agent.
  • All 24 questions across 4 sections reframed in BPM/DMS terminology — no question references generic "automation" anymore.
  • outcome_mapping blockers and remediation_guidance rewritten with BPM/DMS scope and explicit applicability_check guidance.

Domain config (shared/config/process-transformation.json) aligned with the BPM/DMS reframe: domain_terms rebuilt around BPM Platform / DMS / BPMN / CMMN / Process Instance / Object Store / Document Class / Records Management / CMIS / Federation; abbreviations updated (added BAW; PVU, CAL, ELA, BPMN, CMMN, CMIS retained); framework_description rewritten to enumerate platform names and explicitly state "Contract is Not Applicable when neither a BPM platform nor a DMS is in the architecture"; primary_source_sections retargeted to Sections 5/6/7/8/10/11.

Pre-existing bug fix bundled. The domain config had compliance_prefix: "LAP" and code_format.prefix: "LAP" while the template (and every reference in the world) used LAA. This silent misalignment would have caused requirement-code injection failures in any future pipeline pass that read compliance_prefix from the config. Aligned all three to LAA.

Migration: none required for users. Anyone running CC-008 against an architecture that genuinely contains a BPM platform or DMS will see noticeably more relevant questions and platform-specific remediation notes; anyone running CC-008 against an architecture with neither will now get a fast Not Applicable exit instead of a flood of irrelevant gaps. Any manually-stored prior CC-008 contract output remains valid as a historical artifact — re-generation is recommended once the underlying architecture is BPM/DMS-bearing.

Files:

  • skills/architecture-compliance/templates/cc-008-process-transformation.template.md — Applicability section added; all 14 subsections (1.1–1.4, 2.1–2.4, 3.1–3.3, 4.1–4.3) reframed in BPM/DMS terminology; A.1 Definitions / A.3.1 Common Gaps / A.3.2 Auto-Approve Guide / A.4 Change History rewritten; net +~330 lines.
  • skills/architecture-compliance/validation/cc-008-process-transformation-validation.json — schema version bumped to 2.1.0; new top-level applicability block; all 24 questions reframed; outcome_mapping + remediation_guidance updated; net +~80 lines.
  • skills/architecture-compliance/shared/config/process-transformation.json — domain_terms, abbreviations, framework_description, primary_source_sections BPM/DMS-aligned; compliance_prefix + code_format.prefix LAP→LAA fix.

Verification: bun run typecheck ✅. bun test reports 392/392 pass (no test changes required — content-only contract scope reframe). Template @include resolution verified with bun resolve-includes.ts (613 → 776 lines after expansion).

v3.21.2 (Previous Release) ✅

docs: OS-specific Bun install + plugin-configure sections in README and INSTALLATION.md — Windows native gets npm install -g bun as the recommended path

v3.21.1 made the plugin technically OS-agnostic (native wrappers + /setup auto-detection), but the README still presented Linux/macOS as the canonical install path with no first-class Windows-native guidance. v3.21.2 closes that documentation gap so a Windows-native developer (cmd / PowerShell, no WSL or Git Bash) can read the README top-to-bottom and end up with a working install in under five minutes.

README.md changes:

  • Quick Start → Step 0 — Install Bun. New per-OS install matrix and prose. Windows native gets npm install -g bun as the recommended install path, with the rationale spelled out: it sidesteps PowerShell execution-policy restrictions, corporate proxies, and signed-script enforcement that occasionally trip the official irm bun.sh/install.ps1 | iex one-liner in enterprise environments. macOS gets brew install bun or the curl one-liner; Linux gets the curl one-liner; WSL/Git Bash explicitly directed at the Linux/macOS path.
  • Quick Start → Step 2 — Configure for your platform with /setup. New subsection documenting the three native hook wrappers (.sh / .cmd / .ps1) and the /setup platform detection added in v3.21.1. Includes a "Your OS / Shell → Bun install command → What /setup writes" table so users can pick the right combination at a glance.
  • Requirements → Installing Bun by OS. Same install matrix repeated in tabular form for users who skip the Quick Start and read Requirements first. Provides verification command and a PATH-not-updated troubleshooting hint specific to Windows.
  • Stale version reference fixed. The "You should see sa-skills v3.19.2 in the list" line — left over from a v3.19.2 release and missed in subsequent bumps — corrected to v3.21.2 (this release).

docs/INSTALLATION.md changes:

  • ### Windows section reordered. npm install -g bun is now the recommended install with rationale, and the official powershell -c "irm bun.sh/install.ps1 | iex" is demoted to alternative (used when Node.js isn't installed and the user doesn't want to install it just for Bun). Verification command now includes the "sign out and back in for PATH update" hint that's specific to Windows installers.
  • New #### Windows + WSL2 or Git Bash subsection. Explicit pointer back at the macOS/Linux instructions so users on those Windows compatibility layers don't get confused about which path to follow.
  • #### Alternative: Using Package Managers extended. npm install -g bun listed as the Windows package-manager path alongside Homebrew (macOS) and Snap (Linux), pointing back at the recommended-path section above.

Why npm install -g bun over the official PowerShell installer for Windows native:

The official Bun installer (irm bun.sh/install.ps1 | iex) is the upstream-recommended path on Windows and works in most home / personal-dev environments. But three classes of friction make it less reliable as a primary recommendation in a plugin README that has to onboard Windows users sight-unseen:

  1. PowerShell execution policy. Corporate Group Policy commonly forces Restricted or AllSigned, blocking the unsigned install.ps1 script. npm install -g is just an HTTP fetch + extract through npm, no script-policy gate.
  2. Corporate proxies. irm (Invoke-RestMethod) inherits PowerShell's proxy resolution, which doesn't always pick up the user's npm-configured proxy. npm's proxy handling is mature and well-documented; users who already have npm working through their proxy get Bun working through it for free.
  3. Signed-script enforcement. Some Windows installs require all PowerShell scripts to be signed by a trusted publisher. The Bun installer is unsigned. npm's package install bypasses this gate entirely.

Because Node.js is already installed on the vast majority of Windows dev machines (it's a near-prerequisite for any modern web tooling), npm install -g bun is the install path with the highest first-try success rate. Keeping the official installer documented as the alternative preserves the option for users on minimal Node-free Windows setups.

No code changes. This is a pure documentation release — no SKILL.md / agent / TypeScript / hook / setup-permissions changes. v3.21.1's runtime behavior is unchanged.

Files: README.md (+OS-specific install matrix in Quick Start + Requirements; stale v3.19.2 reference corrected; net +104 lines), docs/INSTALLATION.md (Windows section reordered to recommend npm install -g bun; new WSL/Git Bash subsection; +28 lines).

Migration: none required. Existing users on any OS continue to work unchanged. New Windows-native users following the README from scratch now get a Windows-first-class install path instead of being implicitly funneled toward WSL/Git Bash.

Verification: bun run typecheck ✅. bun test reports 392/392 pass (no test changes — docs-only release).

v3.21.1 (Previous Release) ✅

fix: native platform-specific hook wrappers + /setup auto-detection — closes the residual ~ expansion gap that v3.21.0 left for Windows native

v3.21.0's bun ~/.claude/plugins/.../hooks/route-architecture-docs.ts hook command still relied on ~ expansion to resolve the user's home directory. POSIX shells expand ~; cmd.exe and PowerShell do not. On Windows native (no Git Bash, no WSL) the hook command would either fail to locate the script or — depending on Claude Code's command runner — silently no-op. The v3.21.0 release notes explicitly flagged this as the only remaining OS-agnosticity gap. v3.21.1 closes it.

Three native wrappers under hooks/:

  1. hooks/route-architecture-docs.sh — POSIX shell wrapper (Linux, macOS, WSL, Git Bash). Self-resolves its directory via cd "$(dirname "$0")" && pwd, then exec bun "$SCRIPT_DIR/route-architecture-docs.ts". Carries an exec bit + #!/usr/bin/env sh shebang for direct invocation, but /setup writes a sh <abs-path> command for harness portability.
  2. hooks/route-architecture-docs.cmd — Windows CMD batch wrapper. Self-resolves via %~dp0 (cmd's batch-script-directory variable; works in every Windows version since XP), invokes bun "%~dp0route-architecture-docs.ts" %*, propagates exit code via exit /b %errorlevel%. cmd.exe is universally available on Windows — no install dependency.
  3. hooks/route-architecture-docs.ps1 — PowerShell wrapper for users running pwsh as their default shell on any OS. Self-resolves via $PSScriptRoot, invokes & bun (Join-Path $PSScriptRoot 'route-architecture-docs.ts') @args, sets $ErrorActionPreference = 'Stop', propagates $LASTEXITCODE. Works on Windows PowerShell 5.x and PowerShell Core 7+ on Linux/macOS/Windows.

All three wrappers invoke the same route-architecture-docs.ts source — only the path-resolution dance differs per shell. The TypeScript implementation is unchanged from v3.21.0.

scripts/setup-permissions.ts platform-aware install (v3.21.1+):

  • New resolveHookCommand() function detects process.platform:
    • linux / darwin / anything-not-win32 → sh <plugin-root>/hooks/route-architecture-docs.sh
    • win32 → cmd /c "<plugin-root>\\hooks\\route-architecture-docs.cmd" (the path is double-quoted so absolute paths containing spaces — common in C:\Users\First Last\... — survive cmd's argument parser)
  • <plugin-root> is computed from import.meta.dir → dirname() → resolved absolute path. No environment-variable acrobatics, no ~ expansion required at any layer.
  • New rewriteSaSkillsHookCommands() runs once after stripComments() parses the example file. It walks example.hooks, finds any command containing one of route-architecture-docs.{ts,sh,cmd,ps1}, and overwrites it with the platform-resolved form. So the example file's literal bun ~/...ts command is documentation only — the actual command written to the user's settings.json is platform-correct.
  • Hook output now leads with two new lines so users can verify selection at a glance: Platform: Linux (sh wrapper) / Hook command: sh /home/user/.claude/plugins/.../hooks/route-architecture-docs.sh.

Marker matching reworked to support compound AND-substring markers:

SA_SKILLS_HOOK_INSTALL_MARKERS and SA_SKILLS_HOOK_REMOVAL_MARKERS now accept either a single substring (legacy form, unchanged) or an array of substrings that must all appear in the command. New compound-marker helper commandMatchesMarker() handles both cases.

  • Install markers (any one matches → "already installed"): "route-architecture-docs.sh", "route-architecture-docs.cmd", "route-architecture-docs.ps1". A Linux user has the .sh; a Windows user has the .cmd; a pwsh user has the .ps1 — all three are recognized.
  • Removal markers (compound, distinguish legacy from current):
    • "header-cli.ts session-log add" (v3.14.1 PostToolUse editlog — kept from v3.19.1)
    • ["sh ~", "route-architecture-docs.sh"] (v3.19.0 form — sweeps because of ~ prefix; the v3.21.1 wrapper has sh /abs/path/... so it matches sh but NOT sh ~, no false-positive)
    • ["bun ~", "route-architecture-docs.ts"] (v3.21.0 form — same logic; v3.21.1 doesn't invoke bun directly in the hook command)

Removal pass moved to BEFORE merge (instead of after):

In v3.21.0 the removal pass ran on mergedHooks (after the merger had already run). That worked when removal markers were unique substrings, but with compound markers and overlapping file basenames (the new .sh wrapper shares the route-architecture-docs.sh substring with the v3.19.0 retired form), the per-marker dedup inside the merger would incorrectly treat the legacy entry as "already present" and block the install of the new wrapper. Refactored to run sweepRetiredHooks(user.hooks) first, take the cleaned result as the merger's input, then merge the example's resolved entry. The removal counter is preserved in the report ("Hooks: added 1 · already present 0 · retired 1").

End-to-end migration verification — four scenarios all pass:

  • Fresh install (empty settings.json): Hooks: added 1, retired 0 → wrapper-based command installed.
  • v3.19.0 legacy (sh ~/.claude/plugins/.../route-architecture-docs.sh): Hooks: added 1, retired 1 → legacy swept, wrapper-based command installed in same pass.
  • v3.21.0 legacy (bun ~/.claude/plugins/.../route-architecture-docs.ts): Hooks: added 1, retired 1 → legacy swept, wrapper-based command installed in same pass.
  • Idempotent re-run (apply /setup twice): run #2 reports Hooks: added 0, already present 1, retired 0. Final entry count = 1, no duplication.

Files: hooks/route-architecture-docs.sh (NEW POSIX wrapper, 16 lines), hooks/route-architecture-docs.cmd (NEW Windows wrapper, 14 lines), hooks/route-architecture-docs.ps1 (NEW PowerShell wrapper, 14 lines), scripts/setup-permissions.ts (+platform detection + compound markers + pre-merge removal sweep + report-line additions; net +90 lines), .claude/settings.json.example (HOOKS comment block updated to describe wrapper-based install; literal hook command kept as Linux/macOS canonical example for documentation), commands/setup.md (Step 3 hook-merge bullet rewritten to document platform detection, compound markers, and pre-merge removal). Existing v3.21.0 helpers (scripts/{today,ensure-dir,remove-glob}.ts, hooks/route-architecture-docs.ts) are unchanged.

Migration: re-run /setup on any existing install (v3.19.0, v3.21.0, or v3.21.1 from a different OS). The single pass:

  1. Detects current platform.
  2. Computes the absolute path to the matching wrapper.
  3. Sweeps any legacy ~-prefixed hook entry from user settings.
  4. Writes the platform-resolved hook command into hooks.UserPromptSubmit.
  5. Reports Platform, Hook command, and Hooks: added/retired counts. Idempotent. Re-runs from the same OS report added 0, already present 1, retired 0. Re-runs from a different OS sweep the previous-OS wrapper entry (it would be classified by the install marker as a route-architecture-docs.* entry but not match the resolved command, so the per-marker dedup recognizes it as "different command, replace") — actually the sweep happens via REMOVAL markers only when the command contains a ~; cross-OS swap is currently a known edge case (the user would end up with two wrapper entries until they manually delete the old one). The 99% path — single-OS users running /setup once or many times — works perfectly.

Verification: bun run typecheck ✅. bun test reports 392/392 pass (no test changes; the new wrappers and refactored migration logic are smoke-tested via the four end-to-end scenarios above). All wrappers smoke-tested live:

  • bun hooks/route-architecture-docs.ts direct (still works) → empty stdout when no ARCHITECTURE.md ✅
  • hooks/route-architecture-docs.sh invoked directly (Linux) → forwards to bun, emits hook JSON when ARCHITECTURE.md present ✅
  • All four migration scenarios produce the expected added/retired counters and the final hook command resolves to the absolute path on the runtime platform ✅

Caveat — the cmd / pwsh wrappers were not run end-to-end on a Windows machine for this release (the dev environment is Linux). The wrapper logic is shell-textbook simple — %~dp0 and $PSScriptRoot have stable semantics in every modern Windows shell — but a Windows-native end-to-end smoke test is the responsible final verification before depending on these in production.

v3.21.0 (Previous Release) ✅

feat: drop POSIX-shell dependency — date/mkdir/rm shell-outs and the .sh UserPromptSubmit hook ported to cross-platform Bun helpers

v3.20.0 moved staging paths off /tmp/. v3.21.0 finishes the OS-agnostic story by retiring the remaining POSIX-shell calls in skill prose and porting the v3.19.0 ARCHITECTURE.md routing hook from sh + heredoc to a Bun TypeScript file. After this release the only Bash permission grant the plugin requires is Bash(bun *) — no Bash(date *), no Bash(mkdir *), no Bash(rm *), no sh hook invocation. The plugin runs identically on Linux, macOS, Windows native (cmd / PowerShell), WSL, and Git Bash, with one caveat documented at the bottom of this entry.

Three new cross-platform helpers under scripts/:

  1. scripts/today.ts — prints today's date as YYYY-MM-DD in the local timezone, identical to date +%Y-%m-%d. Backed by getLocalDateString() from architecture-compliance/utils/date-utils so timezone behavior matches the existing compliance pipeline (no UTC shift after midnight). Replaces seven date +%Y-%m-%d shell-outs across agents/generators/{compliance-generator,docs-export-generator}.md, skills/architecture-compliance-review/SKILL.md, and skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md.
  2. scripts/ensure-dir.ts — idempotent multi-path directory creator using Node's mkdirSync(..., { recursive: true }). Replaces mkdir -p invocations in skills/architecture-analysis/SKILL.md (analysis dir), skills/architecture-icepanel-sync/SKILL.md (icepanel-sync dir + the .cache/sa-skills/icepanel/ cache dir), skills/architecture-dev-handoff/SKILL.md Phase 4 (asset directories — split out from the previous overloaded use of prepare-payload-dir.ts), skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md, skills/architecture-compliance/utils/README.md, and the docs-export-generator's exports/ dir creation.
  3. scripts/remove-glob.ts — deletes files matching one or more glob patterns using Bun's built-in Glob.scanSync() and unlinkSync. Equivalent to rm -f <glob> with shell glob expansion, idempotent on missing files (ENOENT is silently swallowed). Replaces the for prefix in ...; do rm -f compliance_docs_dir/PREFIX_*.md; done shell loop at skills/architecture-compliance/SKILL.md Step 3.2.1 (the only rm -f shell-out the plugin had at runtime).

hooks/route-architecture-docs.ts — Bun TypeScript port of v3.19.0 .sh hook:

  • Same input contract (CLAUDE_PROJECT_DIR env var, falls back to process.cwd()) and same output contract (UserPromptSubmit JSON shape with additionalContext).
  • Same fast-path: missing ARCHITECTURE.md → process.exit(0) with no output.
  • Drops the POSIX requirements that broke Windows native: set -e, cat <<'JSON' heredoc, sh interpreter dependency. Bun's JSON.stringify(payload) is shell-agnostic.
  • Cold-start cost rises from ~3–5 ms (POSIX shell + stat) to ~10–20 ms (Bun startup + stat). Still zero LLM call, still never blocks, still emits zero output when ARCHITECTURE.md is absent. The cost ceiling on a sa-skills project (which always has ARCHITECTURE.md) is ~20 ms per prompt — within the same order of magnitude as the .sh version and well below any user-perceivable threshold.
  • The .sh file is deleted from the repo. Existing user installs keep the stale entry in their settings.json until the next /setup run, which actively strips it (see migration block below).

scripts/setup-permissions.ts migration logic:

  • SA_SKILLS_HOOK_MARKERS flips from ["route-architecture-docs.sh"] to ["route-architecture-docs.ts"]. The install pass on every /setup run now adds the new .ts hook entry to projects that don't have it.
  • SA_SKILLS_HOOK_REMOVAL_MARKERS adds "route-architecture-docs.sh" alongside the v3.19.1 header-cli.ts session-log add entry. The removal pass actively strips any user-side hook entry whose command substring contains route-architecture-docs.sh. Idempotent: a second /setup run is a no-op.
  • End-to-end migration verified by simulation: a synthetic settings.json carrying the v3.19.0 .sh hook entry, after one /setup run, has the .sh entry removed and the .ts entry installed in a single pass — output: Hooks: added 1 · already present 0 · retired 1.

Permission grants pruned from .claude/settings.json.example:

  • Removed: Bash(mkdir *), Bash(date *), Bash(rm *), Bash(grep:*), Bash(rg:*), Bash(awk:*), Bash(ls:*) — none required after the helper migration. (The colon-form Bash(*:*) entries were legacy v2 grants that no skill referenced anymore; the migration was an opportune time to sweep them.)
  • Retained: Bash(bun *) — the only Bash grant the plugin needs at runtime. Existing user installs keep their pruned grants harmlessly (the merger is non-destructive on permissions.allow); they're safe to delete by hand for a clean profile.

Documentation parity: every skill SKILL.md, agent system prompt, and reference guide that previously documented date +%Y-%m-%d / mkdir -p / rm -f as ALLOWED Bash commands now lists the matching bun [plugin_dir]/scripts/{today,ensure-dir,remove-glob}.ts helper, with one-line callouts that this is the cross-platform path. The bundled agents/builders/handoff-context-builder.md was re-bundled via bun run bundle:handoff-agent to pull the updated PAYLOAD_SCHEMA.md table cell that now documents prepare-payload-dir.ts as the date source instead of date +%Y-%m-%d.

Caveat — Claude Code's harness shell on Windows native: the hook command bun ~/.claude/plugins/marketplaces/.../hooks/route-architecture-docs.ts and the agent-side bun [plugin_dir]/scripts/today.ts calls are still passed through whatever shell Claude Code uses on the user's OS. On Linux / macOS / WSL / Git Bash, ~ expansion and bun lookup are routine. On Windows native (cmd / PowerShell), ~ is not a shell expansion — its handling depends on Claude Code's permission matcher and command runner, which may or may not normalize ~ independently. If Claude Code's Windows port doesn't expand ~, the user must rewrite the hook command and Read(~/.claude/plugins/...) permissions to use absolute Windows paths or ${USERPROFILE}. This is the only OS-agnosticity gap remaining after v3.21.0 and is a Claude Code harness concern, not a plugin concern.

Files: scripts/today.ts (NEW, 17 lines), scripts/ensure-dir.ts (NEW, 28 lines), scripts/remove-glob.ts (NEW, 49 lines), hooks/route-architecture-docs.ts (NEW, 36 lines), hooks/route-architecture-docs.sh (DELETED, was 30 lines), .claude/settings.json.example (-7 grants, +1 hook command swap, comment block updated), .claude/settings.json (project's own settings — 3 grants pruned), scripts/setup-permissions.ts (+install marker swap +removal marker entry), agents/generators/compliance-generator.md (TOOL DISCIPLINE block + Step 3.2 invocation), agents/generators/docs-export-generator.md (Step 0.1 + 0.2 + Tool Discipline block), agents/builders/handoff-context-builder.md (table cell — re-bundled), skills/architecture-compliance/SKILL.md (Step 3.2.1 rm-loop replaced with single remove-glob.ts invocation), skills/architecture-compliance/COMPLIANCE_GENERATION_GUIDE.md (3 occurrences), skills/architecture-compliance/utils/README.md (testing example), skills/architecture-compliance-review/SKILL.md (date capture step), skills/architecture-analysis/SKILL.md (Step 0 dir creation), skills/architecture-icepanel-sync/SKILL.md (Step 0.5 + Phase 2 cache dir), skills/architecture-dev-handoff/SKILL.md (Phase 4 asset dir creation switched from prepare-payload-dir.ts → ensure-dir.ts), skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md (table cell).

Migration: re-run /setup on existing installs. The single pass:

  1. Strips the stale .sh hook entry (SA_SKILLS_HOOK_REMOVAL_MARKERS match).
  2. Installs the new .ts hook entry (SA_SKILLS_HOOK_MARKERS match).
  3. Adds Read/Write(.cache/sa-skills/**) if not already present (carryover from v3.20.0).
  4. Adds the project-relative permission grants if not already present. The merger is non-destructive: legacy Bash(date *), Bash(mkdir *), Bash(rm *) grants in user-side settings are not removed; they are simply unused by the plugin going forward and safe to delete by hand.

Verification: bun run typecheck ✅. bun test reports 392/392 pass (no test changes; the four new helper files have no dedicated tests yet — they are smoke-tested manually as part of this release). All four helpers smoke-tested live:

  • bun scripts/today.ts → prints today's date as YYYY-MM-DD ✅
  • bun scripts/ensure-dir.ts /tmp/sa-test-a /tmp/sa-test-b /tmp/sa-test-a/nested → creates 3 dirs incl. nested ✅
  • bun scripts/remove-glob.ts "/tmp/sa-test-a/*.md" → removes 2 .md files, leaves the .txt ✅
  • bun hooks/route-architecture-docs.ts (no ARCHITECTURE.md) → exits 0, zero output ✅
  • CLAUDE_PROJECT_DIR=/tmp bun hooks/route-architecture-docs.ts (with ARCHITECTURE.md) → emits valid JSON to stdout ✅
  • bun scripts/setup-permissions.ts end-to-end on a synthetic settings.json with the stale .sh hook → strips .sh, installs .ts in a single pass, idempotent on second run ✅

v3.20.0 (Previous Release) ✅

feat: project-local cache dir (.cache/sa-skills/) replaces /tmp/ staging — OS-agnostic on Linux, macOS, Windows native, WSL, and Git Bash

Every ephemeral file the plugin writes during a run — handoff payloads (architecture-dev-handoff), expanded compliance templates (architecture-compliance), and IcePanel JSON snapshots (architecture-icepanel-sync) — used to land in /tmp/handoff-payloads/, /tmp/expanded_*, and /tmp/icepanel-*.json. The system tmp dir does not exist on native Windows (only inside Git Bash or WSL), and the matching permission strings (Read(//tmp/*), Write(//tmp/handoff-payloads/*)) used a POSIX //-prefix glob form with no Windows equivalent. Together these made the plugin effectively WSL-or-Git-Bash-only on Windows.

v3.20.0 moves all three staging surfaces to .cache/sa-skills/{handoff-payloads,expanded,icepanel}/ — a project-relative path that resolves identically on every OS. Because the path is project-local, the permission strings collapse to a single project-relative entry (Read(.cache/sa-skills/**) / Write(.cache/sa-skills/**)), no //-prefix needed and no system-tmp dependency.

Coordinated changes:

  1. scripts/setup-gitignore.ts — managed entries flip from ["exports/", "/tmp/", "CLAUDE.md"] to ["exports/", ".cache/sa-skills/", "CLAUDE.md"]. Re-running /setup on an existing install appends .cache/sa-skills/ to .gitignore; the previous defensive /tmp/ entry remains harmlessly (the merger is non-destructive on .gitignore).
  2. skills/architecture-compliance/utils/resolve-includes.ts — adds mkdirSync(dirname(resolve(outputPath)), { recursive: true }) before Bun.write so callers no longer need a separate dir-creation step. Cross-platform — no shell mkdir -p dependency.
  3. skills/architecture-icepanel-sync/SKILL.md — Phase 2 now invokes prepare-payload-dir.ts .cache/sa-skills/icepanel before the curl pair, ensuring the parent dir exists on every OS.
  4. skills/architecture-dev-handoff/SKILL.md — Step 3.3 passes .cache/sa-skills/handoff-payloads to prepare-payload-dir.ts; the sub-agent payload_dir parameter and permissions block (Write/Read(.cache/sa-skills/handoff-payloads/**)) follow. The "POSIX-free, identical behavior on Windows native, WSL, and Git Bash" note is added to the directory-creation prose.
  5. Permissions migration — .claude/settings.json.example collapses Read/Write(//tmp/*) and Read/Write(//tmp/handoff-payloads/*) into a single broader project-relative pair (Read/Write(.cache/sa-skills/**)). Existing installs re-running /setup get the new entry appended; the legacy //tmp/ grants stay (non-destructive merger, harmless to leave, safe to delete by hand).
  6. Documentation parity — commands/setup.md, docs/INSTALLATION.md, skills/architecture-compliance/{shared,utils}/README.md, agents/builders/handoff-context-builder.md (re-bundled via bun run bundle:handoff-agent), agents/generators/{handoff-generator,handoff-asset-generator,compliance-generator}.md, skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md — every example, lifecycle paragraph, frontmatter description, and parameter sample reflects the new path. Stale mkdir -p references in PAYLOAD_SCHEMA.md and handoff-context-builder.md (the dir is already pre-created by the Bun helper) are removed.

What was NOT changed: scripts/build-release.sh still references /tmp/test-plugin in its user-facing post-build example output (the release-build script targets release-engineering laptops where bash is already a hard dependency via set -e + zip + sha256sum). Historical CHANGELOG / README sections describing retired /tmp/ features (v3.13.0 /tmp/handoff-plugin-refs/ staging, v3.14.x /tmp/architecture-explorer/** cache, v3.14.1 PostToolUse editlog) are left intact for archival accuracy.

Migration: re-run /setup on existing installs — it appends Read/Write(.cache/sa-skills/**) to permissions and .cache/sa-skills/ to .gitignore. The legacy Read/Write(//tmp/*) permission grants and the /tmp/ gitignore entry remain untouched by the non-destructive merger; they are harmless to leave and safe to delete by hand for total cleanup. No source-doc rewrites are required.

Verification: bun run typecheck ✅. bun test reports 392/392 pass (one bundle-sync test self-healed after bun run bundle:handoff-agent). Smoke-tested all three live invocation paths:

  • bun skills/architecture-dev-handoff/utils/prepare-payload-dir.ts .cache/sa-skills/handoff-payloads → creates dir, prints date ✅
  • bun skills/architecture-compliance/utils/resolve-includes.ts <template> .cache/sa-skills/expanded/test.md → auto-creates parent, expands template successfully ✅
  • bun scripts/setup-gitignore.ts <test_dir> → emits .cache/sa-skills/ as a managed entry, three baseline entries written ✅

v3.19.2 (Previous Release) ✅

fix: drop stale phase3.key_data_points[] reference in compliance SKILL.md

The architecture-compliance skill's Step 3.4 (Spawn generators) carried a stale phrase: "the explorer already scoped findings to phase3.key_data_points[] via the query parameter." phase3.key_data_points[] does not exist in the config schema — key_data_points[] is a top-level array in agents/configs/<contract_type>.json. The same SKILL.md's Step 3.2.5 (line 776) reads it correctly from the top level. The two passages contradicted each other, and orchestrator sessions that internalised the wrong one constructed broken jq probes (jq -r '.phase3.key_data_points | …' → Cannot iterate over null) before self-correcting on the next attempt.

Resolution: one-line edit to skills/architecture-compliance/SKILL.md:875. The replacement explicitly ties the sentence to Step 3.2.5 so a future LLM reader cannot get a mismatched mental model:

"No metadata cross-reference is needed because the explorer already scoped findings to the top-level key_data_points[] array (the same field used at Step 3.2.5 to construct contract_query) via the query parameter."

Scope verification: searched all of skills/architecture-compliance/, agents/generators/, and agents/builders/ for analogous stale paths (phase3.X, phase4.X, scoring.Y where the field actually lives at top level). No other occurrences. Single touch.

Files: skills/architecture-compliance/SKILL.md (one-line phrasing fix). No agent prompts, no config files, no TypeScript, no test changes.

Verification: grep -rn "phase3.key_data_points" skills/ agents/ returns zero hits. bun run typecheck clean. bun test reports 392/392 pass (unchanged from v3.19.1).

v3.19.1 (Previous Release) ✅

fix: retire silently-broken v3.14.1 PostToolUse session-edit tracker

The v3.14.1 release shipped a PostToolUse[Write|Edit] hook that was supposed to record every architecture doc edit into a session-scoped editlog under /tmp/architecture-explorer/sessions/, so /regenerate-explorer-headers --session could refresh only the files that changed. The hook command interpolated $TOOL_INPUT_FILE_PATH — but Claude Code does not export tool-input fields as environment variables. The tool_input.file_path is only available via JSON on stdin (Hooks Reference, "Input/Output"). The variable always expanded to the empty string, the tracker CLI hit its "no path → exit 0 silently" branch, and the editlog has been empty since v3.14.1 shipped on 2026-04-25.

Five releases (v3.14.1 → v3.19.0) carried this latent bug. The 13 unit tests in session-log.test.ts exercised the JS API directly, never the shell-hook seam, so they passed. Every downstream check ("if editlog count > 0, warn") gracefully reported "no session edits" — indistinguishable from "the user genuinely hasn't edited any docs in this session."

v3.19.1 retires the feature instead of patching it. The fix-it path would have added a jq dependency to the plugin install seed for a feature with zero field-validated value; removal sheds ~600 LOC across hooks, CLI subcommands, six SKILL.md pre-flight blocks, the orchestrator-managed CLAUDE.md TODO loop, and the /tmp/architecture-explorer/** permission grants.

Coordinated removals:

  1. Hook + permissions — .claude/settings.json.example drops hooks.PostToolUse[Write|Edit] and the Write/Read(//tmp/architecture-explorer/**) grants. Only the v3.19.0 UserPromptSubmit router hook remains.
  2. CLI + utility — skills/architecture-explorer-headers/utils/session-log.ts and its 13-test test file are deleted. header-cli.ts loses the session-log {add|list|count|clear} subcommand.
  3. Slash command — /regenerate-explorer-headers --session is removed from the skill, the slash-command doc, and CLAUDE.md's trigger table. --force, --dry-run, and <path-glob> modes stay.
  4. Pre-flight checks — six SKILLs (compliance, analysis, peer-review, dev-handoff, definition-record, docs Q&A) lose their "Pre-flight: Session-Edit Check" sections — they were always reading 0.
  5. Orchestrator TODO loop — scripts/setup-claude-md.ts drops the "Session edit tracker — keep EXPLORER_HEADERs honest" subsection that instructed Claude to maintain a TaskList entry whenever the editlog was non-empty.
  6. Active migration on /setup — scripts/setup-permissions.ts adds a SA_SKILLS_HOOK_REMOVAL_MARKERS array. Re-running /setup on an existing install now actively strips any hook entry whose command contains header-cli.ts session-log add. Idempotent: a second run is a no-op. The /tmp/architecture-explorer/** permission grants are non-destructive and must be removed by hand if the user wants total cleanup.

Files: .claude/settings.json.example (-15 lines), skills/architecture-explorer-headers/utils/{session-log.ts, session-log.test.ts} (deleted, -~400 lines), skills/architecture-explorer-headers/utils/header-cli.ts (-50 lines), skills/architecture-explorer-headers/SKILL.md (-25 lines), commands/regenerate-explorer-headers.md (-12 lines), six SKILL.md pre-flight blocks (-~120 lines total), scripts/setup-claude-md.ts (-16 lines), scripts/setup-permissions.ts (+30 lines for the removal pass), commands/setup.md (v3.19.1 section + v3.14.1 section deletion), CLAUDE.md trigger-table edit, CHANGELOG.md entry.

Verification: bun run typecheck ✅, bun test (465/465 pass — 13 retired tests dropped from the v3.14.1 baseline of 478) ✅.

v3.19.0 (Previous Release) ✅

feat: ARCHITECTURE.md → sa-skills:architecture- routing hook (UserPromptSubmit, harness-level enforcement)*

When a project root contains ARCHITECTURE.md, the architecture is governed by the sa-skills plugin and every architecture-related action — questions about the architecture; edits to ARCHITECTURE.md / docs/**/*.md / docs/components/**/*.md / adr/**/*.md; diagrams; release / version bump; compliance contracts; peer review; dev handoff — must route through the matching sa-skills:architecture-* skill, because the skills enforce validation gates (Section 3 enforcement, downstream propagation, source attribution, drift detection) that direct edits silently skip. Before v3.19.0, this routing relied on three soft layers (the architecture-docs SKILL.md description, the project's CLAUDE.md trigger table, and the SKILL.md descriptions of sibling skills); all three were hints the model could bypass.

v3.19.0 adds a UserPromptSubmit hook that fires on every prompt at the harness level (before Claude reads the prompt), stat's $CLAUDE_PROJECT_DIR/ARCHITECTURE.md, and — when present — injects a one-paragraph additionalContext system-reminder steering the model to the right sa-skills:architecture-* skill. The hook is POSIX shell (~25 lines, ~1–5 ms cold start), exits silently with zero output when no ARCHITECTURE.md is present, never blocks, and never invokes an LLM.

Three coordinated additions ship together:

  1. Hook script — hooks/route-architecture-docs.sh — POSIX shell, executable, emits the documented UserPromptSubmit hookSpecificOutput.additionalContext JSON shape when ARCHITECTURE.md exists, exits silently otherwise.
  2. Settings registration — .claude/settings.json.example adds the UserPromptSubmit entry with a leading // HOOKS — v3.19.0+ comment. (At ship time, this entry sat alongside the v3.14.1 PostToolUse editlog tracker; the tracker was retired in v3.19.1 once it was confirmed silently broken since v3.14.1.)
  3. Merger refactor — scripts/setup-permissions.ts replaces the single-string SA_SKILLS_HOOK_MARKER constant with a SA_SKILLS_HOOK_MARKERS list, and the per-command dedup test now matches by the specific marker for this command instead of "any sa-skills marker present in target." (v3.19.1 reused this multi-marker list to add a parallel SA_SKILLS_HOOK_REMOVAL_MARKERS cleanup pass.)

Existing projects re-running /setup after upgrading get the new hook merged into their .claude/settings.json non-destructively. commands/setup.md documents the v3.19.0 changes inline. Idempotent — re-running /setup reports Hooks: added 0 · already present 2.

Files: hooks/route-architecture-docs.sh (new, ~25 lines), .claude/settings.json.example (+13 lines), scripts/setup-permissions.ts (marker refactor, +20 / -8), commands/setup.md (v3.19.0 section, +9 lines), version bumps in .claude-plugin/{plugin,marketplace}.json, package.json, README.md badge / verification line. No skill behavior or skill workflow changed. All 405 unit tests pass; typecheck clean.

v3.18.0 (Previous Release) ✅

feat: cache-optimized Phase 1.5 fan-out — stable-prefix template + read-once foundational inlining + token-grep pruning

The Section 3 (Architecture Principles) gate's downstream-impact propagation (architecture-docs Phase 1.5) fans the principle-quality-reviewer sub-agent (Opus, by design — "optimized for reliability, not cost") out across every downstream file in batches of 4. Before this change, each parallel sub-agent independently re-read the four foundational files (docs/01-system-overview.md, docs/02-architecture-principles.md post-edit, docs/03-architecture-layers.md, docs/06-technology-stack.md) plus a Glob over adr/*.md — the same ~4 KLOC of byte-identical content was loaded N times per S3 edit, and the per-call discriminator (downstream_file) sat in the middle of the prompt body, splitting Anthropic's prompt cache prefix on every call. Even worse, the fan-out fired against every downstream file in the reverse dependency table (S4–S11 + every component) regardless of whether the file referenced anything that had actually changed.

Three coordinated changes attack both the per-call cost and the call count:

  1. Stable-prefix dispatch template — skills/architecture-docs/SKILL.md Phase 1.5 — orchestrator now reads the four foundational files once and inlines their content as five XML-style blocks (<principles>, <system_overview>, <arch_layers>, <tech_stack>, <adr_index>) at fixed positions in every sub-agent prompt. The downstream_file parameter is the LAST line, the only thing that differs across the batch. Calls 2..N of each batch now hit Anthropic's prompt cache for the entire prefix.
  2. Inlined-blocks fast path on the reviewer — agents/reviewers/principle-quality-reviewer.md Step 1 — agent prefers the inlined-blocks fast path when present (no re-Read of foundational files), with the original path-based reads kept as a fallback for first-write / edit-delta modes and direct invocations outside the orchestrator. The Input Parameters table documents both paths and the precedence.
  3. Pre-fan-out token-grep pruning — skills/architecture-docs/SKILL.md Phase 1.5 step 2 — before dispatching, the orchestrator builds a token set from the diff (changed principle names, ADR IDs cited in the diff, tech tokens added/removed that intersect docs/06-technology-stack.md) and greps each candidate downstream file for any token. Files with zero hits are skipped with a non-blocking Phase 2 note ("no token references to changed principles, cited ADRs, or affected tech; semantic review skipped"); only files that token-match get a sub-agent call. The empty-token-set case (e.g., pure prose rephrase with no concrete tokens) falls back conservatively to the full fan-out so recall is preserved on edits with nothing concrete to grep against.
  4. Cache-warm sequencing (first batch only) — skills/architecture-docs/SKILL.md Phase 1.5 step 3 parallelism note — within the first batch of each fan-out, the orchestrator fires one sub-agent call first and waits for it to settle before firing the remaining 1–3 calls in parallel. The first response writes the stable prefix into Anthropic's prompt cache; subsequent calls (in the same batch and in every later batch within the 5-min TTL) read the prefix from cache instead of re-paying it. Costs ~30–60s of extra wall-clock on the first batch only; subsequent batches dispatch full-parallel as before.
  5. Lazy-Load Contract — skills/architecture-docs/SKILL.md adds a new section (after AUTOMATIC WORKFLOW DETECTION) that codifies which large reference guides (ARCHITECTURE_DOCUMENTATION_GUIDE.md 2K+ lines, ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md 1.1K, MERMAID_DIAGRAMS_GUIDE.md 1K, RELEASE_WORKFLOW.md 687, etc.) load only when their workflow fires. Documents the rule explicitly so neither the model nor a future maintainer pre-loads guides "to be ready" — speculative loads burst the working set and force prefix re-evaluation on every tool call.

Backward-compatible: any caller that still passes paths only (older orchestrator versions, ad-hoc invocations) continues to work unchanged via the fallback path. The pruning step is fail-open — grep errors degrade to the full fan-out with a one-line warning. No skill workflow or output format changed; reliability bias preserved.

Combined effect on the median S3 edit: the call count drops (typically 2–4 sub-agents instead of 8 + N components), and the calls that do fire spend 1× cold + (N−1)× cached prefix instead of N× full-cost.

Files: skills/architecture-docs/SKILL.md (Phase 1.5 audit procedure, ~95 lines added: token-set extraction extension to step 1, new step 2 pruning, renumbered tail), agents/reviewers/principle-quality-reviewer.md (Input Parameters table + Step 1 Load Context, ~25 lines added). No code touched. All 405 unit tests pass.

v3.17.3 (Previous Release) ✅

fix: harden semicolon rule in DIAGRAM-GENERATION-GUIDE (covers Notes + parenthetical sub-clauses)

skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md already forbade ; in sequence-diagram message labels, but the rule wording was too narrow and the Pre-Write Validation row's scan hint missed two real-world cases that broke generated diagrams: (a) a ; inside a parenthetical sub-clause of a message (e.g. A->>B: existing payment path (sync; ORQPagos2002 stateless) → Mermaid parse error "Expecting SOLID_ARROW … got NEWLINE"), and (b) a ; inside Note over … : / Note left of … : / Note right of … : bodies. Three localized edits — the DO NOT bullet now spans message labels and Note text and parenthetical sub-clauses with negative + positive examples for each; the validation table row is broadened with a scannable regex; the Validation Procedure step 1 explicitly requires scanning Note bodies. Documentation hardening only — no skill behavior, no workflow change.

Files: skills/architecture-docs/references/DIAGRAM-GENERATION-GUIDE.md (10 lines: +7/-3). No code touched, no validators changed.

v3.17.2 (Previous Release) ✅

fix: drop incorrect Ctrl+R claim from /setup final reminder

commands/setup.md Step 7 (Final reminder) printed Restart Claude Code (or press Ctrl+R) to reload settings. — the Ctrl+R parenthetical was wrong: Claude Code's Ctrl+R is bound to HistorySearch, not settings reload. On Linux the chord is also intercepted by bash readline's reverse-history-search before it ever reaches Claude Code, so the instruction misled users who tried it. The reminder now reads Restart Claude Code to reload settings. — accurate, terminal-agnostic.

Files: commands/setup.md (1 line). No skill behavior or workflow change. Existing tests unaffected (no code touched).

v3.17.1 (Previous Release) ✅

feat: ADR title and Problem Statement length constraints (blocking gate)

Adds two universal length rules enforced at every ADR write — first-time create (Workflow 2) and bulk generation from Section 12 (Workflow 1):

  • Title ≤ 50 characters — the text after # ADR-NNN: is capped at 50 chars (the prefix itself is not counted). Example: Dynatrace as Mandatory Observability Platform (45) passes; Adopt Dynatrace SaaS as the Mandatory Observability Platform for All Production Workloads (90) blocks.
  • Problem Statement ≤ 200 characters — the body of the ### Problem Statement subsection (between the heading and the next ### or ---, with HTML comments stripped) is capped at 200 chars. Forces compose-then-compress: internally answer the four scaffolding questions, then write one tight sentence.

Both rules apply to all scopes (Institutional and User/Project) and BLOCK the write on violation. Cap at 3 revision rounds; round 4 recommends splitting the ADR — no waivers, because a decision that cannot fit is one decision too many.

Documentation: new "Title and Problem Statement Length Constraints" section in ADR_GUIDE.md with pass/fail examples and exact detection commands. Inline HTML comments in adr/ADR-000-template.md surface the rules at authoring time.

Files: skills/architecture-definition-record/SKILL.md (Steps 1.5a + 2.4b), ADR_GUIDE.md (new section + updated embedded template), adr/ADR-000-template.md (HTML comments). No code changed. All 405 existing tests pass.

v3.17.0 (Previous Release) ✅

feat: Two-layer Section 3 (Architecture Principles) Enforcement Gate — no-code, reliability-first

Hardens the architecture-docs skill across both first-write and edit paths by replacing the advisory Section 3 validation checklist with a two-layer enforcement gate that runs on every write to docs/02-architecture-principles.md.

Layer 1 — Prescriptive checklist (skills/architecture-docs/PRINCIPLE_VALIDATION.md, NEW): single source of truth for principle validation rules. 14 rule IDs covering structural, hygiene, semantic-lite, ADR-reference, cross-principle, and architecture-type-specific concerns. Each rule documents an exact grep command, a pass criterion, and a fail-message template. The model executes rules in order and emits a PRINCIPLE_VALIDATION_REPORT block. Anti-self-attestation rule: every finding MUST quote the grep output verbatim — claims without evidence are treated as FAIL by the orchestrator. Includes a per-architecture-type matrix (Microservices → circuit breakers, BIAN → service domains, etc.) and Appendix A (mandatory-field placeholder map for first-write / edit / release scopes).

Layer 2 — Semantic reviewer (agents/reviewers/principle-quality-reviewer.md, NEW; model: opus): runs after Layer 1 passes. Three modes — first-write, edit-delta, downstream-impact. Seven checkType judgments (decision-rule, specificity, tradeoff-honesty, adr-alignment, cross-principle, conflation, type-sanity) catch failures the regex layer cannot: paraphrased platitudes, tech-name-dropping, trade-offs that look quantified but aren't, ADR citations to nonexistent files, type-incoherent advice, conflations of quality attributes (Section 1) with principles (Section 3). Hallucination guard: every cited ADR file must exist. Fail-open: timeouts → PASS-with-warning, never block forever.

Phase 1.5 Principle Alignment Audit (added to SKILL.md Downstream Documentation Propagation): when docs/02-architecture-principles.md itself is edited, fan out the principle-quality-reviewer sub-agent in mode: downstream-impact over each downstream file (S4–S11 + every component) in parallel batches of 4. Findings flow into the Phase 2 approval checklist labeled [principle-impact]. Skips silently on whitespace/formatting-only diffs.

ADR reference enforcement: the advisory "Trade-offs align with ADR candidates — should reference" is now MUST. Each principle's Implementation OR Trade-offs must contain at least one ADR link or carry the explicit <!-- NO_ADR_GOVERNS --> sentinel.

Quality Attribute vs. Principle disambiguation (added to ARCHITECTURE_DOCUMENTATION_GUIDE.md before Section 3): explicit comparison table (outcomes vs. decision rules) and the "verb of choice" rule. Closes the conflation gap that P-QA-CONFLATION-01 enforces operationally.

Placeholder Elimination Gate (new Step 5.7 in ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md): scans the mandatory-field map for [To be defined] / [TBD] / <TODO> / TODO: etc. Any match in a mandatory field BLOCKS Step 6 (ADR delegation).

Reliability stance: this release optimizes for the correctness of produced documentation, not for token cost. Deeper context loads, more sub-agent calls, hard blockers where there were soft warnings, mandatory grep-output quoting to prevent self-attestation, max-3-round revision loops with explicit user escalation. Pin to v3.16.1 if you need a fast/cheap path.

No new dependencies: pure Markdown changes — the existing Bash(grep:*) permission is the only execution surface (now scoped explicitly via Bash(grep:*), Bash(rg:*), Bash(awk:*), Bash(ls:*) permissions added in .claude/settings.json.example).

v3.16.1 (Previous Release) ✅

docs: Institutional ADR content discipline — codify project-agnostic rules for ADR-001..100 in architecture-definition-record

Adds a new "Institutional ADR Content Discipline" section to skills/architecture-definition-record/ADR_GUIDE.md (between "ADR Scope" and "ADR Template"). The section enumerates the project-specific patterns that institutional ADRs (numbers 001–100) must NOT contain — "Institutional Inheritance Note" headers, "Section 3 — Project Application" tables, specific component names (Inbox Hub, omn-mfa, sda-msa-payments-gateway, etc.), specific operator / carrier / brand names (Claro, Movistar, Tuenti, CNT), specific feature names, project budgets ("$276,411"), project deadlines ("MVP June 30, 2026"), user counts ("7M mobile users / 300K web users"), and cross-references to project ADRs (ADR-101+). Each forbidden pattern is paired with the generic phrasing that replaces it ("platform", "service team", "the workload namespace", "the bank's customer base", "platform delivery timelines", etc.). Captures the recent rewrite of all 14 institutional ADRs as a durable rule rather than oral tradition.

Enforcement at the workflow level: cross-references added at two gates inside architecture-definition-record/SKILL.md:

  • Workflow 1 Step 1.5 (Generate from ARCHITECTURE.md) — institutional content callout fires when generating any ADR with Scope: Institutional, instructing the generator to generalize project-specific source material from ARCHITECTURE.md (and optionally retain those specifics in a paired User/Project ADR).
  • Workflow 2 Step 2.4a (Create Individual ADR) — new content gate after Step 2.4 (Load Template and Populate). When the scope chosen at Step 2.1a is Institutional, the gate verifies the populated content does not contain any forbidden pattern before the write happens; if it does, the skill generalizes per the new ADR_GUIDE section and confirms with the user.

Both gates fire only for institutional scope; user/project ADRs (ADR-101+) are unaffected and may continue to carry project-specific content freely. The canonical template (adr/ADR-000-template.md) gains a one-line HTML comment next to the **Scope** field pointing authors at the new guide section so the rule is visible at the moment of authoring even when the skill is not in the loop.

Modified files:

  • skills/architecture-definition-record/ADR_GUIDE.md — new "Institutional ADR Content Discipline" section with forbidden-pattern table, "why it matters" rationale (translation drift creates compliance gaps when institutional standards leak project specifics), and "when project specifics belong in an ADR" guidance pointing readers to the User/Project range.
  • skills/architecture-definition-record/SKILL.md — Workflow 1 Step 1.5 institutional content callout (line 230); Workflow 2 Step 2.4a institutional content gate (line 415–422).
  • skills/architecture-definition-record/adr/ADR-000-template.md — inline HTML hint comment on the **Scope** line (invisible in rendered output, visible to template editors).

No code changes: pure documentation / skill-content edits. Type-check and test suites are unaffected. The numeric scope partition rule from CLAUDE.md ("ADR Scope Partition" — ADR-001..100 institutional, ADR-101+ user/project) is unchanged; this release adds the content dimension that complements the number range dimension.

Migration: none required. The rule applies to new institutional ADRs created or generated through the skill from this version forward. Existing institutional ADRs that were already rewritten to be project-agnostic continue to comply automatically. Projects with non-compliant historical institutional ADRs can run a manual review against the new ADR_GUIDE section — the skill does not retroactively rewrite already-written ADRs.

v3.16.0 (Previous Release) ✅

feat: architecture-explorer simplified to a structure navigator + Findings mode + consumer migration to per-X fan-out

This release reshapes the universal architecture-explorer agent and migrates its three consumer skills (compliance, analysis, dev-handoff) to a new evidence-driven contract.

1. Explorer simplification (BREAKING — internal contract): the v3.14.x ranking machinery is gone. 36 per-task JSON configs (agents/configs/explorer/*.json), the Bun CLI with 12 subcommands, the mtime-keyed /tmp/ cache, the in-house scoring formula, gap-marker regexes, and ~18 TypeScript modules with their tests have all been deleted. The new agent uses Read + Glob only, walks the canonical layout (ARCHITECTURE.md + docs/ + adr/), extracts <!-- EXPLORER_HEADER --> metadata inline, and emits a single EXPLORE_MANIFEST listing every doc, component, and ADR with key_concepts, technologies, related_adrs. Schema break: EXPLORE_RESULT → EXPLORE_MANIFEST, schema_version 1 → 2; per-task config / cache parameters all removed.

2. Findings mode (Added): a second, mutually exclusive mode keyed on an optional query parameter. When provided, the agent runs Claude's Explore-agent methodology scoped to the architectural surface — plans 3–8 search terms, parallel Grep for every term, parallel context Read (offset: anchor − 5, limit: 30) for nearest H1/H2/H3 heading, and emits an EXPLORE_FINDINGS block with files[] carrying matched_terms, matches[].line, heading, and 3–5-line excerpt. No manifest enumeration in this mode — focuses entirely on what was asked. The agent does not answer the question; it surfaces evidence the caller synthesizes.

3. Consumer migration to per-X findings fan-out: the synthesis tier (Sonnet/Opus) no longer re-greps inside each generator/analysis/context-builder. Haiku pre-locates evidence at line + heading granularity. Hardcoded floors (compliance phase3.required_files[], analysis per-lens base file lists) stay as guarantees; findings ADD line-level evidence on top.

  • Compliance — Step 3.2.5 fans out per-contract findings calls keyed on each domain config's key_data_points[] (already 6–10 vocab terms per contract). Generator consumes EXPLORE_FINDINGS, reads phase3.required_files[] (floor) plus findings.files[] using matches[].line/heading/excerpt as placeholder-extraction starting points. Validators unchanged — they still use their hardcoded read lists.
  • Analysis — Step 2.5 fans out per-analysis findings calls keyed on a hardcoded vocabulary map (8 terms × 10 lenses, lifted from each spec's "Evidence Extraction Priority" table). FILES list = union(base_files[type], findings.files[*].file).
  • Dev-handoff — Step 3.4a per-component spawn now sends component_file AND query: <slug>, <type>, <technologies>. Step 3.5 input renamed manifest → findings_by_component. Context-builder PHASE 3.2 swaps in-builder name+type+technology grep for findings-driven slicing; per-component fallback to v3.13.0 in-builder grep when that slug's explorer call failed. Agent v1.2.0 → 1.3.0. Phase 7 telemetry adds the new findings-evidence line.
  • Explorer agent v3.0.0 → 3.3.0 — component_file + query may be passed together; the agent emits a focus_component block alongside findings so dev-handoff per-component fan-out keeps its ADR allowlist.

4. CLAUDE.md guidance refresh: the injected sa-skills:architecture-pointer block in project CLAUDE.md is rewritten around the manifest-vs-findings two-mode model. Decision tree for re-triggering the explorer is keyed on whether the prior block in conversation is EXPLORE_MANIFEST vs EXPLORE_FINDINGS. /setup now also documents the v3.16.0 changes.

Degraded mode: any explorer call returning status: FAILED or empty files[] triggers per-unit fallback to the hardcoded floor (compliance → phase3.required_files; analysis → base FILES; dev-handoff → v3.13.0 in-builder grep slicing). All three skills still produce output; no run aborts on explorer failure.

Migration: no project-side action required. Existing projects re-running any compliance / analysis / dev-handoff skill after upgrading get the new behavior automatically. The Agent(sa-skills:architecture-explorer) permission grant is unchanged. The /tmp/architecture-explorer/<project_hash>/ cache directory becomes orphaned and clears on reboot. Compliance contracts, analysis reports, and handoffs regenerate identically — the manifest carries everything the previous EXPLORE_RESULT did, plus the full corpus listing for downstream domain-driven selection; findings supply pinpointed excerpts the synthesis tier reads instead of full files.

Verification: bun run typecheck clean. bun test 405/405 pass.

v3.15.1 (Previous Release) ✅

fix: Avro / Protobuf detection misses when wire format is documented outside the canonical 5 fields

The handoff-context-builder resolver scanned only **Type:**, **Technology:**, **Description:**, **Communicates via:**, **Deploys as:** of each component descriptor when deriving asset_types. Real-world component files commonly document the Kafka wire format ("Avro envelope", "Avro — schema-registry validated") in three places the resolver did not read: the <!-- EXPLORER_HEADER --> technologies: line, the inline Subscriptions / Produces / Topics tables further down the component file, and docs/05-integration-points.md. Result: components that consume or produce Avro topics had asset_types: [asyncapi, deployment, c4-descriptor] instead of [asyncapi, deployment, avro, c4-descriptor] — schema.avsc was silently never generated.

Fix — extend the resolver's scanned_text to include (a) the EXPLORER_HEADER body (technologies: and key_concepts: lines) and (b) the cell contents of every table that follows an H2/H3 named Subscriptions / Subscribes To / Produces / Consumes / Topics / Streams / Events. Tighten the messaging-row asset rule to a token-explicit match: [avro] triggers on avro / *.avsc / Schema Registry (the latter only when avro is also present, since Schema Registry alone could be JSON Schema or Protobuf); [protobuf] triggers on protobuf / proto3 / *.proto / gRPC. The canonical 5 fields still drive component_type selection — only the asset_types union is broadened.

Modified files:

  • skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md — secondary-signals list extended (new bullets 3 + 4 for EXPLORER_HEADER and inline tables); messaging-row asset rule made token-explicit.
  • agents/builders/handoff-context-builder.md — Step 3.1.5 now builds scanned_text from the canonical 5 + EXPLORER_HEADER body + the Subscriptions/Produces/Topics-style table rows; messaging avro/protobuf sub-rule applied. Bundle re-synced.

Migration: none required. On the next handoff run, components whose asset_types list expands (because the resolver now sees their Avro signal) will be regenerated automatically — the payload's asset_types value changes → the manifest hash changes → the manifest CLI returns REGEN. Authors who used **Asset Hints:** as a workaround can keep them; they still take precedence.

v3.15.0 (Previous Release) ✅

feat: dev-handoff document refactored to audience-segmented Dev/QA/Ops format (TEMPLATE_VERSION 2.0.0; BREAKING)

The Component Development Handoff document collapses from 16 flat sections to 8 audience-tagged sections in three role tracks plus an appendix. Every Part header and section header carries [DEV] / [QA] / [OPS] badges (with multi-tags like [DEV] [QA-CONTRACT] for shared sections). Section 0 gains a Role Quick Index pointing each role to its starting sections.

Real-world feedback was that downstream teams (external dev shops, contracted QA firms, ops teams in segregated environments) wasted time discovering which of the 16 sections were relevant to their role. The new layout solves both audience targeting and conciseness without breaking self-containment — every value extracted from architecture docs stays embedded verbatim in the handoff itself, since readers may not have access to docs/.

New section structure:

New ID Title Audience Replaces (old §)
Section 0 Metadata + Role Quick Index All §0 (gains Role Quick Index)
A1 Overview, Scope, Tech & ADRs DEV §1 + §2 + §11 + §13
A2 API & Data Contract DEV / QA-CONTRACT §3 + §4
A3 Integrations & Failure Modes DEV / OPS-CONTRIBUTES §5 + §10 (dev-half)
B1 Acceptance, Performance & Security Tests QA / DEV-VERIFIES §12 + §7 (latency/throughput) + §6
C1 Deployment, Config & Resources OPS / DEV-CONTRIBUTES §7 (resources/scaling) + §8 + §11 (runtime)
C2 Observability & Runbook OPS / DEV-ALERTS §9 + §10 (ops-half)
C3 Deliverable Assets OPS / DEV §14
D1 Open Questions and Assumptions All §15

Compression rules baked into the new template:

  1. Self-contained extraction — values embedded verbatim, never linked out (architecture-doc citations are provenance only).
  2. Drop fields that duplicate other handoff sections (intra-handoff redundancy).
  3. Tables over prose where there is a natural key→value structure.
  4. Per-section length budgets (A1 ≤60, A2 ≤100, A3 ≤70, B1 ≤80, C1 ≤70, C2 ≤70, C3 ≤25, D1 ≤30; total target ≤500 lines).

v1 → v2 silent auto-regen: a new Phase 3.6 in architecture-dev-handoff/SKILL.md performs one cheap Read on each decision: SKIP handoff file looking for <!-- TEMPLATE_VERSION: 1.0.0 -->. When found, the decision flips to REGEN and the file is rewritten under v2 on this run. A single summary line is printed at the top of Stage 5 (Detected N v1 handoff(s) → forcing regen to TEMPLATE_VERSION 2.0.0); no prompt, no --force required. Files lacking any TEMPLATE_VERSION marker (e.g., hand-edited files) keep their SKIP decision; users can pass --force to override.

Modified files:

  • skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md — full rewrite to 8-section v2 layout. TEMPLATE_VERSION marker bumped to 2.0.0.
  • skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md — full rewrite using new section identifiers, per-section length budgets, self-containment rule, and an old → new ID mapping table.
  • skills/architecture-dev-handoff/ASSET_GENERATION_GUIDE.md — every "Section N" / "§N" handoff reference renumbered (Spanish c4-descriptor scaffold updated in lockstep).
  • agents/generators/handoff-generator.md — embedded bundles re-synced; agent prose, validation rules, and HANDOFF_RESULT.sections_with_gaps example updated to new identifiers; agent version bumped to 2.0.0.
  • agents/generators/handoff-asset-generator.md — embedded ASSET_GENERATION_GUIDE.md bundle re-synced.
  • agents/builders/handoff-context-builder.md — losslessness rule reference updated.
  • skills/architecture-dev-handoff/SKILL.md — every section reference renumbered; description frontmatter updated; new Phase 3.6 (v1 → v2 detection) added.
  • skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md — losslessness rule reference updated.
  • skills/architecture-dev-handoff/utils/manifest.test.ts — FROZEN_SHA and FROZEN_VERSION updated to match the v2 template.
  • CLAUDE.md — trigger-routing-table description updated to "8-section audience-segmented handoff".

Verification: bun run typecheck clean. bun test 493/493. bun run bundle:check confirms all three handoff agent bundles are byte-identical to their standalones.

Migration: no user action required. Existing handoffs at TEMPLATE_VERSION 1.0.0 auto-regenerate to v2 on the next dev-handoff run. To force regeneration of every component (including hand-edited v1 files), pass --force. handoffs/.manifest.json repopulates with v2 hashes automatically.

v3.14.9 ✅

fix: dev-handoff asset-type resolver — recognize Gateway/BFF/Edge, cloud K8s names (AKS/EKS/GKE/ECS/Fargate/Container/Docker), scan **Communicates via:** + **Deploys as:**, add **Asset Hints:** override

A real-world handoff for a "Gateway" component on AKS publishing to Kafka produced only [openapi, c4-descriptor] — missing deployment.yaml (every other deployable component in the same catalog had one) and asyncapi.yaml. Root cause: the handoff-context-builder resolver in PAYLOAD_SCHEMA.md only scanned the component file's **Type:** field and used a vocabulary that recognized abstract terms ("Kubernetes/K8s/Pod") but not the cloud-specific terms architects actually write ("AKS/EKS/Container/Docker"). "Gateway" was not a first-class archetype at all, so Gateway components had to accidentally match through other fields — and only GraphQL got through for this one (in **Description:**), missing the K8s and Kafka signals that lived in **Deploys as:** and **Communicates via:**.

Fix — three orthogonal changes to the resolver in skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md (re-bundled into agents/builders/handoff-context-builder.md via bun run bundle:handoff-agent):

  1. New "Gateway" row mapping Gateway, API Gateway, Edge, Ingress, Reverse Proxy to [openapi, deployment, c4-descriptor] — gateways are first-class deployables and always run as containers/pods. The row encodes this directly so the resolver does not depend on the architect also writing "K8s" or "Pod" in the same component file.
  2. Wider vocabulary in the K8s row — adds AKS, EKS, GKE, OpenShift, ECS, Fargate, Container, Docker, containerized to Kubernetes, K8s, Deployment, Pod. Also expands the API row (Endpoint, Backend, BFF), the database row (Cassandra, DynamoDB), the cache row (KeyDB), and the messaging row (SQS, SNS, EventBridge, Pub/Sub, NATS).
  3. Wider scan window — the resolver now scans **Type:**, **Technology:**, **Description:**, **Communicates via:**, AND **Deploys as:** (was: **Type:** only, in the prompt's literal wording — though the LLM-driven implementation often read more by accident, never reliably). The instruction is now explicit. Step 3.1 of the agent extracts communicates_via and deploys_as from the component file into the structured YAML so the resolver has them in hand.

Plus an explicit override for one-off corrections — **Asset Hints:** (v3.14.9+). When present in a component file, the field's flow-sequence value (e.g. **Asset Hints:** [openapi, deployment, asyncapi]) replaces the resolver's keyword-derived list (c4-descriptor is still appended unless the literal skip is used). This is the lowest-effort escape hatch for any future resolver miss — the architect adds one line to the component file rather than waiting for a vocabulary patch. The override is reported in the orchestrator's CONTEXT_RESULT.components[i].asset_hints_override = true, so Phase 7 reports surface which components used it.

Modified files:

  • skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md — resolver instruction + table fully rewritten with multi-field scan, expanded keywords, Gateway row, Union semantics example for "GraphQL Gateway on AKS publishing to Kafka", and the **Asset Hints:** override spec.
  • agents/builders/handoff-context-builder.md — re-bundled (table flows in from PAYLOAD_SCHEMA.md). Step 3.1 now extracts communicates_via, deploys_as, and asset_hints from the component file. New Step 3.1.5 codifies the resolver decision flow (override → keyword scan → union → c4-descriptor append). CONTEXT_RESULT.components[i] adds asset_hints_override boolean.

No code changes; no test changes. The resolver lives entirely in the agent's prompt (LLM-driven). The bundle integrity test (bun test tools/bundle-handoff-agent.test.ts) catches drift between PAYLOAD_SCHEMA.md and handoff-context-builder.md.

Migration: no user action required. Re-running any handoff after upgrading to v3.14.9 picks up the new resolver automatically. Components whose previous run produced a too-narrow asset_types list (e.g. a Gateway that only got [openapi, c4-descriptor] instead of [openapi, deployment, c4-descriptor]) will be flagged REGEN on the next run because the payload's asset_types value changed → the manifest hash changes → the manifest CLI returns REGEN. The new run produces the correct asset set and overwrites the under-specified handoff. To force regeneration sooner, pass --force.

To opt-out the resolver for a specific component (e.g., a "Gateway" that intentionally has no deployment because it runs serverless), add **Asset Hints:** [openapi] to the component file — the override wins.

v3.14.8 ✅

perf: three dev-handoff performance improvements (parallel 5A+5B cohort, decoupled template_version, EXPLORER_HEADER fast-path inside the explorer agent)

A profiling pass on a single-component dev-handoff run (~26 min wall, ~340k tokens) surfaced three avoidable bottlenecks. Each ships independently — any single one is safe to revert.

Change 1 — Phase 5 collapses Stages 5A and 5B into one parallel cohort. The handoff-generator (Stage 5A, Sonnet) and handoff-asset-generator (Stage 5B, Sonnet/Haiku per tier) sub-agents both consume only payload_path after Phase 3.5 — they had no real cross-dependency. Spawning them concurrently in one orchestrator message (up to parallelism 5A Tasks + up to asset_parallelism 5B Tasks) reclaims ~min(T(5A), T(5B)) per run (~200 s on the observed run, scaling to 25–35 % off Phase 5 wall-time on multi-component runs). Stage 5C (asset-gap merge into Section 15) still runs after both cohorts. The lost gating means a 5A failure may leave orphaned asset files on disk — these are valid stand-alone artifacts, excluded from handoffs/.manifest.json, and surfaced in Phase 7 as Asset written but handoff doc failed: <abs_path> — will be regenerated next run. The new concurrency budget is parallelism + asset_parallelism (default 4 + 4 = 8); document this if you tune the flags.

Change 2 — architecture-explorer agent gets a single-component EXPLORER_HEADER fast-path (PHASE 2.5). Component files have carried a required <!-- EXPLORER_HEADER --> block with related_adrs: since v3.14.0 — the architect's curated answer to the same question the per-ADR LLM scoring loop produces. The optimization lives inside the explorer agent, not around it: the dev-handoff orchestrator still spawns the explorer the same way and still receives an EXPLORE_RESULT. When the orchestrator passes the new component_file: input parameter and force == false, PHASE 2.5 runs the new bun … explore-cli.ts handoff-shortcut subcommand which synthesizes a complete EXPLORE_RESULT from the header + the config's required_sections[] + a globbed adr/ADR-NNN-*.md resolution. Explorer Haiku token spend drops from ~84 k to ~10–15 k per single-component handoff. Header missing, malformed, or ADR ids unresolvable → transparent fall-through to the normal scoring path. Telemetry: metadata.shortcut: header plus metadata.shortcut_unresolved_adrs: [...] for any unresolved ADR ids; Phase 7 reports Explorer mode: cached | header-shortcut | full-scoring per component.

Change 3 — template_version decoupled from plugin version. Pre-v3.14.8, manifest.ts mixed template_version = plugin_version into every payload's SHA-256 fingerprint, so any plugin patch (e.g. v3.14.6 → v3.14.7) invalidated every component's manifest entry even when HANDOFF_TEMPLATE.md was byte-identical. v3.14.8 adds a <!-- TEMPLATE_VERSION: 1.0.0 --> marker to the template file and a new manifest-cli.ts template-version <template_path> subcommand. Plugin patches no longer trigger spurious REGEN — only an actual template content change (paired with a deliberate TEMPLATE_VERSION: bump) does. A new manifest.test.ts tripwire pins the template's SHA-256 against the declared version, forcing both fixture values to be updated together when the template is edited.

New CLI subcommands:

  • manifest-cli.ts template-version <template_path> — print the parsed marker
  • explore-cli.ts read-component-header <component_file> — print parsed header fields as JSON
  • explore-cli.ts handoff-shortcut <component_file> <config_path> <project_root> <inputs_hash> — synthesize the full EXPLORE_RESULT YAML

New TypeScript modules:

  • skills/architecture-dev-handoff/utils/manifest.ts — readTemplateVersion() exported alongside existing helpers
  • skills/architecture-explorer/utils/handoff-shortcut.ts — synthesizeHandoffShortcut(); reuses parseHeader from skills/architecture-explorer-headers/utils/header-detector.ts (cross-skill import, same pattern as the existing manifest.ts → architecture-compliance/utils/date-utils import)

Modified files:

  • skills/architecture-dev-handoff/HANDOFF_TEMPLATE.md — adds <!-- TEMPLATE_VERSION: 1.0.0 --> marker
  • skills/architecture-dev-handoff/utils/manifest{,-cli}.ts — readTemplateVersion() + template-version subcommand
  • skills/architecture-dev-handoff/utils/manifest.test.ts — +6 cases (frozen-fixture tripwire + CLI smoke)
  • skills/architecture-explorer/utils/explore-cli.ts — read-component-header and handoff-shortcut subcommands
  • skills/architecture-explorer/utils/handoff-shortcut.test.ts — new (9 tests, round-trip-validates synthesized YAML against parseExploreResult())
  • agents/builders/architecture-explorer.md — new PHASE 2.5 section, new component_file input parameter, allowed Bash command #5 added; agent version bumped to 1.1.0
  • skills/architecture-dev-handoff/SKILL.md — Phase 3.4a passes component_file and tracks explorer_mode per component; Phase 3.5 sources template_version via the new CLI subcommand; Phase 5 fully restructured into one cohort + Step 5.3 (gap merge) with the pre-v3.14.8 sequential 5A.x/5B.x preserved inline as a <details> historical reference; Phase 7 report adds Explorer mode, 5A failure rate, and orphaned-asset detail lines

Verification: bun run typecheck clean. bun test 493 / 493 (was 484 — +9 from handoff-shortcut.test.ts). bun run bundle:check all three bundled agents in sync.

Migration: no user action required. Re-running any handoff after upgrading to v3.14.8 picks up all three improvements automatically.

  • Existing handoffs/.manifest.json entries WILL be invalidated on the first run because template_version flips from 3.14.7 (plugin version) to 1.0.0 (the new template version). Subsequent plugin patches no longer invalidate them.
  • Component files without an EXPLORER_HEADER block transparently fall through to normal scoring — the fast-path is purely additive. To activate the fast-path on legacy components, run /regenerate-explorer-headers (the full backfill).
  • The Phase 5 parallel cohort is enabled unconditionally. To bound concurrency, lower --parallelism and/or --asset-parallelism.

v3.14.7 ✅

feat: parallel asset generation in architecture-dev-handoff with per-tier model pinning

A single Sonnet handoff-generator sub-agent did two unrelated jobs back-to-back per component — fill the 16-section handoff document, then sequentially write every deliverable asset (OpenAPI, DDL, Kubernetes Deployment, AsyncAPI, CronJob, Avro/Protobuf, Redis key schema, C4 descriptor). For a component with 4 assets that meant 5 serial Writes inside one Sonnet spawn even though the assets are independent. It also paid Sonnet rates for the c4-descriptor.md — a free-form markdown one-pager that template-fills cleanly on Haiku. v3.14.7 splits asset generation into a parallel sub-agent with model tier pinned per asset.

Architecture change — Phase 5 of architecture-dev-handoff/SKILL.md is now a three-stage pipeline:

  • Stage 5A — handoff-document fan-out. handoff-generator (Sonnet) now produces ONLY the 16-section handoff document. Section 14 (Deliverable Assets) is filled deterministically from the payload's asset_types[] array using a static filename map embedded in the agent's system prompt. Component-level batches sized by --parallelism N (default 4, capped 8) — unchanged from v3.14.6.
  • Stage 5B — NEW — asset fan-out. The orchestrator builds a flat queue of (component, asset_type) tuples for every REGEN component and partitions into batches of --asset-parallelism N (default 4, capped 8, new flag). Each batch dispatches up to N parallel Task(sa-skills:handoff-asset-generator, model=…) calls. The new agent file has no model: frontmatter — the orchestrator passes model: per Task call using a frozen tier table (pattern modeled on architecture-compliance/SKILL.md:863, 890):
    • code tier → Sonnet: openapi, ddl, deployment, asyncapi, cronjob, avro, protobuf, redis
    • descriptor tier → Haiku: c4-descriptor
  • Stage 5C — NEW — gap merge. Each ASSET_RESULT block returns gaps[] for any # TODO: [NOT DOCUMENTED] markers the asset agent emitted. The orchestrator does ONE Edit per component on the handoff document to append asset-level gaps under Section 15 (preserving today's behavior where every gap is consolidated in one place).

New agent file: agents/generators/handoff-asset-generator.md — universal single-asset generator. Tools: Read, Write (no Bash, Grep, or Glob — orchestrator pre-creates output directories, references are bundled). Bundles assets/_index.md and the full ASSET_GENERATION_GUIDE.md (~1050 lines) inline in its system prompt so it never reads plugin files at runtime. Returns ASSET_RESULT block with status, asset_path, and structured gaps[].

Modified files:

  • agents/generators/handoff-generator.md — bundle dropped from ~1976 to ~820 lines (removed assets/_index.md and ASSET_GENERATION_GUIDE.md BEGIN/END_BUNDLE blocks plus the c4-descriptor extraction-fields subsection). Mission rewritten. PHASE 3 (asset generation) deleted; old PHASE 4 → PHASE 3, old PHASE 5 → PHASE 4. output_assets_dir removed from input parameters. HANDOFF_RESULT.assets[] field removed (orchestrator now derives the asset list from asset_types[] and Stage 5B ASSET_RESULT statuses). Tool budget updated to 1 Read + 1 Write + 1 Read = 3 calls/spawn. Agent version bumped to 1.2.0.
  • skills/architecture-dev-handoff/SKILL.md — Phase 1 Step 1.0 adds --asset-parallelism N flag with full validation. Phase 5 fully restructured into 5A/5B/5C with new tier classification table. Phase 6 manifest update note clarifies the assets field source (orchestrator-computed from asset_types[] × Stage 5B success). Phase 7 report adds dedicated lines for handoff batches, asset batches (with Sonnet/Haiku counts), and gap-merge edits. Permissions block adds Agent(sa-skills:handoff-asset-generator).
  • skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md — Section 14 description rewritten for the deterministic-from-asset_types[] flow; Asset 8 extraction-fields subsection moved into the new agent's bundle.
  • tools/bundle-handoff-agent.ts + test — BUNDLE_TARGETS now lists three agents; new entry routes assets/_index.md and ASSET_GENERATION_GUIDE.md into handoff-asset-generator.md.
  • .claude/settings.json.example, commands/setup.md, CLAUDE.md, CHANGELOG.md — all updated. Re-running /setup after upgrade appends one line: Agent(sa-skills:handoff-asset-generator).

Concrete benefit: for a 5-component run averaging 3 assets each (15 total assets), Stage 5A emits 5 Sonnet handoff Tasks (4-parallel batched = 2 message rounds), Stage 5B emits 15 asset Tasks (4-parallel batched = 4 message rounds, with ~10–12 Sonnet + 3–5 Haiku Tasks). Wall-clock for asset writing drops roughly 3× (4-way fan-out instead of in-spawn serialization). Cost on the descriptor-tier asset drops to Haiku rates.

Verification: bun run typecheck clean (no TypeScript files touched). bun test passes (478/478 — 1 sync test updated for the third bundle target). bun tools/bundle-handoff-agent.ts --check reports all three bundles in sync. The static asset → tier classification is inlined in SKILL.md Stage 5B Step 5B.1; no JSON config or runtime resolution needed.

Migration: no user action required. Re-running any handoff after upgrading to v3.14.7 picks up the new flow automatically. Existing handoffs/.manifest.json files remain valid (the assets field semantics are unchanged — same comma-separated filename list). Generated asset content is unchanged for code-tier assets (Sonnet still drives them) and may show stylistic variance only for c4-descriptor.md (now driven by Haiku, but the template scaffold and Asset Fidelity Rule are unchanged).

v3.14.6 ✅

feat: wire architecture-explorer into architecture-analysis — per-analysis FILES allowlists across all 10 analyses

The analysis flow's universal architecture-analysis-agent (Opus) was reading the orchestrator-prepared doc_files corpus in full for every one of the 10 analyses. The corpus is a single shared list (ARCHITECTURE.md + docs/01–09 + adr/* + relevant component files), so a 10-analysis run reread the entire ~20+-file corpus 10 times — even though each analysis only consumes 5–10 of those files (SPOF cares about deployment + topology; STRIDE cares about trust boundaries + data flows; Cost Hotspots cares about technology stack + scalability). The Haiku-tier architecture-explorer plus its 10 already-shipped analysis-<type>.json configs were designed exactly for that trim; v3.14.6 wires them in.

Architecture change:

Orchestrator (architecture-analysis skill)
  │
  ├── Step 2.5 — architecture-explorer (Haiku)        ← NEW: per-analysis fan-out, parallelism-batched (default 4)
  │     for each selected analysis A:
  │       task_type: analysis-<A>
  │       config_path: agents/configs/explorer/analysis-<A>.json
  │     returns EXPLORE_RESULT.relevant_files[] per analysis
  │     cache hits cost zero Haiku tokens
  │
  └── Step 3 — architecture-analysis-agent (Opus, parallel)
        receives FILES = EXPLORE_RESULT.relevant_files[] for its analysis
        reads only its trimmed allowlist (typically 5–10 files instead of 20+)
        emits the date-stamped report per the existing skeleton (template-fill contract preserved exactly)

Concrete savings on a typical 10-analysis run:

  • Opus tier: each analysis agent reads ~5–10 files instead of the full ~20+ corpus. Cumulative across 10 analyses, roughly 50–60% reduction in input tokens for the analysis phase.
  • Haiku tier: ~200 tokens per analysis for classification. Effectively free vs Opus.
  • Cache hits: zero Haiku tokens on repeat runs. The cached EXPLORE_RESULT flows into each analysis agent unchanged.
  • Wall-clock: analysis dashboard runs trim noticeably; the dominant cost (Opus synthesis) shrinks proportional to the file-count reduction.

Required-section safeguard (false-negative protection): each analysis-<type>.json declares the analysis's must-have files (e.g., SPOF requires docs/03-architecture-layers.md + docs/09-operational-considerations.md) as required_sections[]. Every analysis's relevant_files[] includes those files regardless of score. The runtime parser rejects any EXPLORE_RESULT that omits a required entry, falling back to degraded mode.

Degraded mode (fail-open): if any explorer call returns FAILED, the orchestrator falls back to the universal doc_files corpus from Step 1 for that one analysis. The agent runs identically — just without the trim. The user always gets a report.

What changed (single PR, scoped):

  • agents/builders/architecture-explorer.md — already accepts task_family: analysis (no changes needed; the v3.14.0 baseline works).
  • agents/reviewers/architecture-analysis-agent.md — Input Parameters note that the FILES: list is now the per-analysis EXPLORE_RESULT.relevant_files[] rather than the universal doc_files. The agent's contract is unchanged — it reads every path in FILES, in order — only the upstream selection narrowed.
  • skills/architecture-analysis/SKILL.md Phase 3 — new Step 2.5 (per-analysis explorer fan-out, parallelism-batched 4); Step 3 spawn prompt now sources FILES: from the explorer's output with degraded fallback to doc_files.

Verification: bun run typecheck ✅, bun test 478/478 ✅. The 10 analysis-<type>.json explorer configs (shipped in v3.14.0) needed zero changes — already correctly shaped for the new flow.

Migration: no user action required. Re-running any analysis after upgrading to v3.14.6 picks up the new flow automatically. The report skeleton, Documentation Fidelity Rule, and EOL validation flow are all preserved; existing analysis reports on disk remain valid.

Roadmap: peer-review explorer wiring moves to v3.14.7; docs Q&A v3.14.8; ADR application v3.14.9.

v3.14.5 ✅

feat: wire architecture-explorer into architecture-compliance — per-contract relevance allowlists across all 10 contracts

The compliance flow's 10 validators (one per contract domain) hard-coded their "Required Files" lists in their agent prompts; the universal compliance-generator pulled the same list from each domain's agents/configs/<contract>.json phase3.required_files. Both lists are correct but static — they can't adapt when, say, a project documents a security topic in docs/06-technology-stack.md instead of docs/07-security-architecture.md. The Haiku-tier architecture-explorer plus its 10 already-shipped compliance-<domain>.json configs were designed exactly for that adaptation; v3.14.5 wires them in.

Architecture change:

Orchestrator (architecture-compliance skill)
  │
  ├── Step 3.2.5 — architecture-explorer (Haiku)        ← NEW: per-contract fan-out, parallelism-batched (default 4)
  │     for each selected contract C:
  │       task_type: compliance-<C>
  │       config_path: agents/configs/explorer/compliance-<C>.json
  │     returns EXPLORE_RESULT.relevant_files[] per contract
  │     cache hits cost zero Haiku tokens
  │
  ├── Step 3.3 — Validator (Sonnet|Haiku|Opus per preset)
  │     receives EXPLORE_RESULT in prompt
  │     reads relevant_files[] (or hardcoded fallback if explorer failed)
  │     emits VALIDATION_RESULT
  │
  └── Step 3.4 — compliance-generator (universal, model per preset)
        receives VALIDATION_RESULT + EXPLORE_RESULT
        PHASE 3 Step 3.3 reads relevant_files[] (or phase3.required_files fallback)
        emits the contract per the domain template (template-fill contract preserved exactly)

Concrete savings on a typical 10-contract run:

  • Synthesis-tier reads: each validator + generator now reads only the explorer's allowlist (typically 4–9 files per contract). Previously each pair read 5–8 hardcoded files plus ARCHITECTURE.md. The reduction is modest in file count but meaningful in cross-domain reads: when the explorer detects that, say, the Cloud contract's relevant set is docs/02-context.md + docs/06-technology-stack.md (because the project doesn't have a separate docs/cloud-architecture.md), the Cloud validator/generator reads exactly those files. Before, validators that hardcoded a file name now-not-present in the project would emit [NOT DOCUMENTED] for everything and the user would be forced to rename or duplicate docs to satisfy the validator.
  • Haiku tier: ~200 tokens per contract for classification. Effectively free vs Sonnet/Opus.
  • Cache hits: zero Haiku tokens on repeat runs. The cached EXPLORE_RESULT flows into the validator and generator unchanged.
  • Cost-per-10-contract-run: dominated by the synthesis tier (template fill on Sonnet/Opus, unchanged). Validators now see more accurate file lists, so [NOT DOCUMENTED] markers fire only where the architecture genuinely lacks coverage — fewer false-positive gaps in the contracts.

Required-section safeguard (false-negative protection): each compliance-<domain>.json declares the validator's hardcoded file list as required_sections[]. Every contract's relevant_files[] includes those files regardless of score. The runtime parser rejects any EXPLORE_RESULT that omits a required entry, falling back to degraded mode.

Degraded mode (fail-open): if any explorer call returns FAILED, the orchestrator omits the EXPLORE_RESULT block from that contract's validator and generator prompts. Both fall back to their hardcoded / phase3.required_files lists. The user always gets a contract.

What changed (single PR, scoped):

  • agents/builders/architecture-explorer.md — already accepts task_family: compliance (no changes needed; the v3.14.0 baseline works).
  • agents/generators/compliance-generator.md — Input Parameters gain EXPLORE_RESULT; PHASE 3 Step 3.3 reads relevant_files[] when present, falls back to phase3.required_files when absent.
  • 10 validator agents (agents/validators/*-validator.md) — uniform additions: Input Parameters get EXPLORE_RESULT; the existing "### Required Files" hardcoded list is wrapped with a note marking it as the fallback when the explorer block is absent.
  • skills/architecture-compliance/SKILL.md Phase 3 — new Step 3.2.5 (per-contract explorer fan-out, parallelism-batched 4); Step 3.3 + Step 3.4 prompt templates updated to include the EXPLORE_RESULT block.

Verification: bun run typecheck ✅, bun test 478/478 ✅. The 10 compliance-<domain>.json explorer configs (shipped in v3.14.0) needed zero changes — already correctly shaped for the new flow.

Migration: no user action required. Re-running any compliance generation after upgrading to v3.14.5 picks up the new flow automatically. The contract templates, validation rubric, and VALIDATION_RESULT contract are all preserved; existing contracts on disk remain valid.

Roadmap: per-skill compliance integration was previously slated for v3.14.5 (compliance) — now done. Analysis integration moves to v3.14.6; remaining wiring (peer-review, docs Q&A, ADR application) follows.

v3.14.4 ✅

feat: wire architecture-explorer into architecture-dev-handoff — per-component ADR allowlists, ~50% Sonnet token reduction

The dev-handoff flow's I/O-heavy handoff-context-builder (Sonnet) was reading every ADR in full to build its term index, then full-reading the matched subset per component. On a project with 38 ADRs and 8 components, that's ~38×30-line indexing reads + ~50 full ADR reads, all on Sonnet. The infrastructure to fix this has been in place since v3.14.0 (the handoff-component.json explorer config was already shipped); only the wiring was missing. v3.14.4 closes the loop.

Architecture change:

Orchestrator
  ├── architecture-explorer (Haiku)              ← NEW: spawned FIRST, per component, in parallel batches of `parallelism`
  │     loads handoff-component.json
  │     extra_terms = [<slug>, <type>, ...<technology>]   ← per-component differentiation
  │     scans first 60 lines + headings of every candidate (38 ADRs + 7 shared docs + components)
  │     returns EXPLORE_RESULT.relevant_files[] per component (typically 4-9 ADRs + 9 required-section docs)
  │     cache hits cost zero Haiku tokens on repeat runs
  │
  └── handoff-context-builder (Sonnet)           ← consumes per-component explore_results map
        PHASE 1: reads ONLY files in the union of all components' relevant_files[] (the 9 required docs always; ADRs only if any component flagged them)
        PHASE 2: ADR indexing pass SKIPPED — explorer already classified
        PHASE 3.3: per-component ADR allowlist taken directly from explore_results[<slug>].relevant_files[]
        CONTEXT_RESULT contract preserved exactly — handoff-generator unchanged

Concrete savings on a typical run (38 ADRs, 8 components):

  • Sonnet: ~10K tokens saved on the indexing pass (the 38×30-line scan disappears entirely). Per-component ADR full-reads drop ~20-30% as the explorer's score_threshold: 0.20 filters genuinely irrelevant ADRs.
  • Haiku: ~200 tokens per component for classification. Effectively free. Cache hits on repeat runs cost zero.
  • Wall-clock: builder phase drops from 2m+ to ~45s on the same input shape (estimated; depends on doc-tree size).
  • Cost-per-run: dominated by handoff-generator (template fill on Sonnet, unchanged). Builder phase no longer the bottleneck.

Required-section safeguard (false-negative protection): handoff-component.json declares ARCHITECTURE.md, docs/01-system-overview.md, docs/04-data-flow-patterns.md, docs/05-integration-points.md, docs/06-technology-stack.md, docs/07-security-architecture.md, docs/08-scalability-and-performance.md, docs/09-operational-considerations.md, and docs/components/README.md as required_sections[]. Every component's relevant_files[] includes them regardless of score. No content is silently dropped; payload coverage is lossless.

Degraded mode (fail-open): if any explorer call returns FAILED, that component's allowlist falls back to required_sections[] only and the context-builder runs the v3.13.0 indexing pass for it. If every explorer call fails, the orchestrator omits explore_results from the builder spawn entirely — the legacy path runs as before. The user always gets a payload.

What changed (single PR):

  • agents/builders/architecture-explorer.md — extends extra_terms support to task_family: handoff (was previously only question and adr).
  • agents/builders/handoff-context-builder.md — new explore_results input parameter; PHASE 1 reads the union allowlist instead of fixed 7-doc set; PHASE 2 ADR indexing skipped when explorer ran; PHASE 3.3 takes per-component ADR list from explorer output. Legacy fallback preserved when explore_results is absent. Agent version 1.0.0 → 1.1.0.
  • skills/architecture-dev-handoff/SKILL.md Phase 3 — new Step 3.4a (per-component explorer fan-out, parallelism-batched); Step 3.5 spawn prompt now includes the explore_results map. Existing manifest skip-check + dedup + payload-write logic unchanged.

Verification: bun run typecheck ✅, bun test 478/478 ✅. The handoff-component.json explorer config (shipped in v3.14.0) needed no changes — it was already correctly shaped for the new flow.

Migration: no user action required. Re-running any handoff after upgrading to v3.14.4 picks up the new flow automatically. The v3.13.0 manifest format and CONTEXT_RESULT contract are preserved, so existing handoff files remain valid.

Roadmap: per-skill compliance integration was previously slated for v3.14.4; it shifts to v3.14.5. Remaining wiring (analysis, peer-review, docs Q&A, ADR application) shifts by one accordingly.

v3.14.3 ✅

fix: align enabledPlugins key with the marketplace plugin name (sa-skills) + auto-migrate legacy solutions-architect-skills@… registrations

/plugin and /reload-plugins were reporting Plugin "solutions-architect-skills" not found in marketplace "shadowx4fox-solution-architect-marketplace" after a fresh install or a re-/setup. The marketplace.json correctly registers the plugin as sa-skills (matching plugin.json's name field), but four user-facing files still pointed at the older solutions-architect-skills name from before the v3.8.5 marketplace rename — including the enabledPlugins block in .claude/settings.json.example that /setup merges into every consuming project.

The plugin still ran (the cache had already extracted), but Claude Code couldn't reconcile the registration on every /reload-plugins, surfacing as a persistent error in /plugin → Errors.

What v3.14.3 changes:

  • Aligned all four user-facing references with the marketplace name (sa-skills@shadowx4fox-solution-architect-marketplace):
    • .claude/settings.json.example enabledPlugins key.
    • README.md install one-liner.
    • docs/INSTALLATION.md install one-liner and the manual enabledPlugins snippet.
  • Auto-migration in scripts/setup-permissions.ts: on /setup, any existing user enabledPlugins["solutions-architect-skills@<marketplace>"] is renamed to sa-skills@<marketplace> (preserving its boolean value, dropping the stale key). Idempotent — re-running /setup on already-migrated settings is a no-op. Unrelated user plugins under any name are preserved verbatim.
  • Loud merge summary line when migration fires: 🔄 Migrated 1 legacy enabledPlugins entry… so users see exactly what changed and why.

Behavior change: re-running /setup on existing v3.14.0–v3.14.2 installs silently fixes the broken registration. Fresh installs see the corrected name from the start. The /plugin Errors tab clears on the next /reload-plugins.

Verification: bun run typecheck ✅, bun test 478/478 ✅, end-to-end smoke (fixture project with the legacy key + an unrelated some-other-plugin@… entry → migration renames the sa-skills key, preserves the unrelated plugin, second run is fully idempotent).

Migration: re-run /setup once. The migration line in the merge summary confirms the rename. Then /reload-plugins and the previously-reported "Plugin not found" error in /plugin → Errors disappears.

Roadmap: per-skill explorer wiring shifts again — compliance integration moves to v3.14.4 (was v3.14.3 after the v3.14.2 fix bumped the chain by one).

v3.14.2 ✅

fix: tighten architecture-explorer Tool Discipline so the Haiku-tier classifier never triggers permission prompts

A Q&A invocation surfaced that the explorer was emitting a Bash here-doc (cat > /tmp/explore_result.yaml << EOF) to stage its EXPLORE_RESULT before writing the cache. The user's .claude/settings.json deliberately allows file writes only via the Write tool (path-globbed, auditable) or via Bash(bun *) — Bash(cat *) is not allowlisted, so the redirection fired a permission prompt mid-run.

The Haiku model wasn't malicious or buggy — the prompt was. v3.14.1's Tool Discipline section banned cat, head, tail, grep, find, sed, awk "for reading," which left the model an opening to use them for writing via redirection. The cache-write step also offered "use the Write tool — the CLI accepts either" without making those two the only legal forms.

What v3.14.2 changes:

  • Reframed FORBIDDEN list in agents/builders/architecture-explorer.md: bans are now unconditional (any purpose, including via redirect) and call out the redirected forms (cat > file, tee, here-doc, >, >>) explicitly.
  • New WRITES discipline block names exactly two legal write surfaces: bun … explore-cli.ts write-cache (under Bash(bun *)) or the Write tool at the cache path. No third path is permitted.
  • Removed implied scratch-file staging: the EXPLORE_RESULT YAML is emitted inline as the agent's final response. There is no /tmp/explore_result.yaml intermediate — the YAML in the agent's reasoning is the YAML the orchestrator parses.
  • Why-this-is-strict footnote explains the permission model so future maintainers understand the lock isn't arbitrary.

Behavior change: Q&A workflows that route through the explorer now run silently end-to-end. The cache write goes via bun … write-cache (allowlisted) or the Write tool (allowlisted); no permission prompt at any stage of a fresh classification or a cache hit.

Verification: bun run typecheck ✅, bun test 478/478 ✅. No code or test changes — pure agent-prompt rewrite.

Migration: re-run /setup is not required — this fix lives entirely in the plugin agent file and takes effect on the next architecture-explorer invocation after the user picks up the new plugin version. The roadmap shifts: compliance integration moves from v3.14.2 → v3.14.3.

v3.14.1 ✅

feat: session-scoped EXPLORER_HEADER edit tracker + /regenerate-explorer-headers --session batch refresh

The v3.14.0 release introduced <!-- EXPLORER_HEADER ... --> blocks that the architecture-explorer agent samples in the first 60 lines of every doc to classify relevance. Bodies drift faster than headers: rename a component, swap a database, add an ADR reference — the body is updated, the header silently lies, and downstream classification quietly degrades. v3.14.1 closes that feedback loop with a batch model (per-edit autofix was deliberately rejected; per-doc work added complexity without clear wins).

What ships:

  • Session edit tracker — new utility skills/architecture-explorer-headers/utils/session-log.ts exposing appendEdit, readSessionEdits, clearSessionEdits, retainSessionEdits, sessionLogPath. Storage is /tmp/architecture-explorer/sessions/<projectHash>-<sessionId>.editlog, one JSONL line per Write/Edit on a docs/**/*.md file. ARCHITECTURE.md, docs/README.md, and paths outside docs/** are silently dropped (the tracker never blocks an edit). $CLAUDE_SESSION_ID keys per-session; falls back to a per-day token when absent.
  • CLI subcommands — header-cli.ts gains session-log {add | list | count | clear}, all exit-0 on success, suitable for a hot PostToolUse hook path. Project root is auto-inferred from the file's nearest CLAUDE.md / ARCHITECTURE.md / .git ancestor; explicit --project-root flag available where needed.
  • PostToolUse hook (default-on via /setup) — .claude/settings.json.example carries a new hooks.PostToolUse[Write|Edit] block that fires the tracker after every doc edit. Cost ~10 ms per edit (bun startup + JSONL append), no LLM, never blocks. scripts/setup-permissions.ts is extended to merge hooks into the user's settings.json with idempotent recognition of the sa-skills marker (header-cli.ts session-log add); existing user hooks under any matcher are preserved verbatim.
  • /regenerate-explorer-headers --session flag — the existing slash command (and its skill workflow) gains a --session mode that reads the editlog, runs LLM-driven regeneration only on the listed files (with implicit --force since they're already published), and clears the editlog on success. Combine with --dry-run to preview without LLM calls or log mutation. Partial failures retain the failing files in the log so a re-run picks them up.
  • Orchestrator-managed TODO — the user's project CLAUDE.md (managed by scripts/setup-claude-md.ts) gains a new ### Session edit tracker — keep EXPLORER_HEADERs honest subsection that instructs Claude to keep one and only one task on the user-visible task list (Regenerate EXPLORER_HEADERs for N session-edited docs (run /regenerate-explorer-headers --session)) whenever the editlog is non-empty. The orchestrator never auto-runs the slash command — the user decides when to spend the LLM-heavy refresh.
  • Per-skill pre-flight — Pre-flight: Session-Edit Check blocks added to the workflow openings of architecture-compliance, architecture-analysis, architecture-peer-review, architecture-dev-handoff, architecture-docs (Q&A only), and architecture-definition-record. When the editlog is non-empty the skill emits a loud preamble naming the affected files and the /regenerate-explorer-headers --session action, then continues running (non-blocking) with a headers_status: stale-edits-pending flag in the final report's metadata so downstream consumers can grep.

Verification: bun run typecheck ✅, bun test (478/478 pass — 13 new session-log tests on top of the 465 pre-existing) ✅, /setup end-to-end smoke (fresh project, idempotent re-run, hook-merge with pre-existing user hooks under same matcher) all green.

Migration: re-run /setup to merge the new hook block into your project's .claude/settings.json. Existing v3.14.0 installs receive the hook addition under "Hooks: added 1" in the merge summary; the rest of the merge is a no-op (already present). The new CLAUDE.md subsection is appended idempotently via the existing managed-block markers.

v3.14.0 ✅

feat: universal architecture-explorer Haiku classifier + 36 task-typed configs + architecture-explorer-headers skill

The plugin's biggest cost driver pre-v3.14.0 was redundant doc reads: a 10-contract compliance run hit ARCHITECTURE.md + docs/01–09 + adr/* ~20 times (10 validators + 10 generators × full read), ~1.8 MB of duplicate Opus traffic. The 10-analysis dashboard repeated the pattern (~1.5–2 MB). Peer-review at Hard depth, the same.

v3.14.0 introduces a universal architecture-explorer sub-agent (model: haiku, agents/builders/architecture-explorer.md) as the canonical front door for every doc-consuming workflow. It reads a task-typed JSON config, samples the first 60 lines + headings of each candidate file (with ARCHITECTURE.md read in full as the navigation index), and returns an EXPLORE_RESULT allowlist that downstream synthesis agents will honor in v3.14.x patches. Cache hits cost zero Haiku tokens.

Architecture changes:

  • New universal sub-agent — agents/builders/architecture-explorer.md (Haiku). Always-on by design: there is no --no-explorer opt-out. The false-negative safeguard is at the config level — every config declares required_sections[] that bypass scoring; the runtime parser (skills/architecture-explorer/utils/parse-explore-result.ts) rejects any result that omits a required entry, falling back to degraded mode.
  • 36 task-typed configs at agents/configs/explorer/: 10 compliance (sre / security / cloud hand-tuned, 7 auto-derived from the existing agents/configs/<contract>.json phase3.data_points), 10 analysis (spof / blast-radius / bottleneck / cost-hotspots / stride / vendor-lockin / latency-budget / tech-debt / coupling / data-sensitivity), 13 peer-review (one per category in PEER_REVIEW_CRITERIA.md), 3 special (handoff-component, architecture-question, adr-application), plus _schema.json validating every entry.
  • TypeScript utilities at skills/architecture-explorer/utils/: explore-cache.ts (cache + glob expansion + inputs-hash), parse-explore-result.ts (validates EXPLORE_RESULT blocks, ships its own minimal YAML subset parser — zero deps), validate-config.ts (runtime schema validation), explore-cli.ts (Bun CLI: inputs-hash, check-cache, expand-candidates, write-cache, read-cache, project-hash).
  • Auto-derivation script tools/derive-explorer-configs.ts projects from existing source-of-truth into 33 of the 36 configs in one pass; --force flag re-derives.
  • Explorer-Friendly Headers — new ## Explorer-Friendly Headers section in skills/architecture-docs/ARCHITECTURE_DOCUMENTATION_GUIDE.md documents an <!-- EXPLORER_HEADER ... --> block (5–10 lines after the H1, listing key_concepts, technologies, components/component_self, scope, related_adrs) that newly-created docs/NN-*.md and docs/components/**/*.md files should include. Backwards-compatible: legacy docs without the header still work via fallback scoring.
  • New architecture-explorer-headers skill at skills/architecture-explorer-headers/. Backfills EXPLORER_HEADER blocks into legacy docs. Slash command /regenerate-explorer-headers (with --dry-run, --force, <path-glob>). Bun module + CLI (header-detector.ts, header-cli.ts) provide listDocFiles, hasExplorerHeader, findInsertionPoint, parseHeader, validateHeader, insertHeader, removeHeader, buildHeader. Skill orchestrator generates the header content from each doc's actual body, inserts via Edit, validates, and reverts on failure.
  • Setup integration — .claude/settings.json.example extended with Agent(sa-skills:architecture-explorer) + Read/Write(//tmp/architecture-explorer/**). Re-running /setup after upgrading appends them non-destructively (existing entries counted under "already present"). Generated CLAUDE.md (via setup-claude-md.ts) now includes a ### Routing doc reads through architecture-explorer (v3.14.0+) subsection telling the user's session to invoke sa-skills:architecture-explorer (with task_type: architecture-question) before bulk-reading docs for free-form questions.
  • CLAUDE.md trigger routing — new entries for regenerate explorer headers / add explorer headers / backfill explorer headers route to sa-skills:architecture-explorer-headers.

Per-skill integration (deferred to v3.14.x patches):

Patch Skill Work
3.14.6 architecture-analysis Insert Step 2.5 Explore Phase; wire architecture-analysis-agent ✅
3.14.8 architecture-peer-review Insert Step 4.5 Explore Phase (all depths); wire peer-review-category-agent
3.14.9 architecture-docs Q&A workflows route through explorer (architecture-question.json) with runtime keyword injection
3.14.10 architecture-definition-record ADR create/supersede route through explorer (adr-application.json)

(v3.14.1 = session-edit tracker; v3.14.2 = explorer Tool Discipline fix; v3.14.3 = legacy plugin-name rename + auto-migration; v3.14.4 = dev-handoff explorer wiring; v3.14.5 = compliance explorer wiring; v3.14.6 = analysis explorer wiring; v3.14.7 = parallel asset generation in dev-handoff with per-tier model pinning — non-explorer release. Peer-review explorer integration moves to v3.14.8.)

Each patch ships independently — architecture-explorer is self-contained infrastructure in v3.14.0; integrations are additive.

Behavior changes: none for existing flows — explorer is callable but no skill invokes it yet (per-skill wiring is the v3.14.x work). The architecture-explorer-headers skill is opt-in via slash command.

Verification: bun run typecheck ✅, bun test (465/465 pass — 78 new explorer + headers tests added on top of the 387 pre-existing) ✅, bun run bundle:check (both bundles in sync) ✅, 36/36 configs validate against _schema.json ✅, tools/derive-explorer-configs.ts runs cleanly ✅, /setup smoke test confirms idempotent CLAUDE.md generation with the new explorer subsection ✅.

v3.13.1 ✅

chore: reorganize agents/ by role — generators / builders / reviewers / validators / configs

The agents/ directory grew to 6 top-level .md files + a misleadingly-named agents/base/configs/ JSON folder + an agents/validators/ folder over the v3.5–v3.13 series. v3.13.1 groups every agent and config under a role-based subdirectory so discovery is one folder away from "what does this agent do?":

agents/
├── builders/        handoff-context-builder.md          (assembles input for generators)
├── configs/         10 domain JSON files                (was agents/base/configs/)
├── generators/      compliance-generator.md             (produces content)
│                    docs-export-generator.md
│                    handoff-generator.md
├── reviewers/       architecture-analysis-agent.md      (evaluates quality)
│                    peer-review-category-agent.md
└── validators/      10 domain validator agents          (unchanged location)

The base/ parent directory is gone (it only ever held configs and the name suggested base classes).

Behavior changes: none. Agent invocation in Claude Code uses the name: frontmatter (sa-skills:<name>), and the plugin scans agents/**/*.md regardless of subdirectory — no spawn paths break.

Path changes (transparent to skill orchestrators, but visible in git log and any external fork):

  • agents/handoff-generator.md → agents/generators/handoff-generator.md
  • agents/handoff-context-builder.md → agents/builders/handoff-context-builder.md
  • agents/compliance-generator.md → agents/generators/compliance-generator.md
  • agents/docs-export-generator.md → agents/generators/docs-export-generator.md
  • agents/architecture-analysis-agent.md → agents/reviewers/architecture-analysis-agent.md
  • agents/peer-review-category-agent.md → agents/reviewers/peer-review-category-agent.md
  • agents/base/configs/*.json → agents/configs/*.json

All 16 moves use git mv so file history is preserved.

Coordinated reference updates (33 files modified):

  • Runtime path consumers — compliance-generator.md and the 10 validators/*-validator.md files now Read configs from [plugin_dir]/agents/configs/. tools/bundle-handoff-agent.ts (the v3.13.0 multi-agent bundler) now targets agents/generators/handoff-generator.md and agents/builders/handoff-context-builder.md. tools/bundle-handoff-agent.test.ts assertions updated to match. scripts/build-release.sh error-message paths updated.
  • Documentation — CLAUDE.md "Plugin Structure" section rewritten to enumerate the five subdirectories. SKILL.md path mentions in architecture-dev-handoff, architecture-docs-export, architecture-peer-review updated. PAYLOAD_SCHEMA.md Consumers: footer updated and re-bundled into handoff-context-builder.md.
  • Historical CHANGELOG and README roadmap entries (v3.5.x → v3.13.0) intentionally left untouched — they accurately document past file paths at those release points.

Verification: bun run typecheck ✅, bun run bundle:check (both bundles in sync) ✅, 353/353 tests pass ✅, bash scripts/build-release.sh smoke-test ✅.

v3.13.0 (Previous Release) ✅

perf: dev-handoff token + wall-clock overhaul + new handoff-context-builder Sonnet sub-agent

architecture-dev-handoff was instrumented on a captured 8-component run (~481K tokens / ~50 min wall-clock) and ten leaks were fixed in this release. Targets: ~70% token reduction on full runs, ~80% on minor-architecture-bump runs, ~40–50% wall-clock cut.

Architecture changes:

  • New handoff-context-builder sub-agent (agents/handoff-context-builder.md, model: sonnet). Owns all I/O-heavy work the orchestrator's main context (typically Opus) used to do: reading docs/01 + docs/04–09 once, building an ADR term-index from each adr/*.md first 30 lines, per-component slicing, parsing component files into the new ## Component (structured) YAML payload format, dedup of shared excerpts to _shared.md, payload writing, and SHA-256 manifest fingerprint + skip-vs-regen decision per component. Returns a CONTEXT_RESULT: block listing each component's payload_path, payload_hash, decision, reason, asset_types, handoff_file_rel. The orchestrator's main context never loads the ~80–120 KB shared docs + ADR corpus; the file-shuffling work runs on Sonnet at ~5× lower per-token cost.
  • Static references bundled into both sub-agents. agents/handoff-generator.md now bundles HANDOFF_TEMPLATE.md, SECTION_EXTRACTION_GUIDE.md, assets/_index.md, ASSET_GENERATION_GUIDE.md. agents/handoff-context-builder.md bundles PAYLOAD_SCHEMA.md. Bundled content lives in each sub-agent's system prompt and is API-prompt-cached across all spawns within the orchestration window — saving ~300K tokens per 8-component run vs. fresh per-spawn Reads.
  • tools/bundle-handoff-agent.ts — generalized bundler that handles both agents via a BUNDLE_TARGETS array. CI guard: bun run bundle:check exits 1 on drift, runs in scripts/build-release.sh before zipping.

Skip-if-unchanged manifest (handoffs/.manifest.json):

  • SHA-256 fingerprint of payload_file + template_version per component. The orchestrator skips components whose fingerprint matches AND whose handoff file still exists. On the user's measured 2.13.0→2.13.1 architecture bump (3 components touched out of 8), this would mean 3 sub-agent spawns instead of 8.
  • New --force flag bypasses the skip check.
  • New skills/architecture-dev-handoff/utils/manifest.ts + manifest-cli.ts + 18-test unit suite covering hash determinism, manifest round-trip, every skip/regen condition, and the CLI smoke path.

Parallelism + flag plumbing:

  • Sub-agent batches raised from 2 → 4 (default), with --parallelism N orchestrator flag accepting 1–8 (clamped on out-of-range with a warning).
  • --force and --parallelism are documented in CLAUDE.md trigger-routing.

Payload schema 2.0.0:

  • ## Component File verbatim markdown blob → ## Component (structured) typed YAML block (component.name, component.type, component.apis, component.config, component.scaling, …). Denser and more deterministic for sub-agents to consume. Raw fallback (## Component File (raw)) preserved for unfamiliar component-doc structures.
  • New shared_refs frontmatter + > See: _shared.md § Shared: <header> body marker for content that appears verbatim in ≥3 component payloads (typically org-wide ADRs like ADR-012 mTLS, ADR-014 WAF). Sub-agent PHASE 0.3 resolves markers in memory before fill. ~30% smaller payloads on average for multi-component runs.

ADR pre-grep index:

  • First 30 lines of every adr/*.md are read once into a term index (technologies, component names from title or visible Context, domain keywords). Per-component lookup intersects against the index and only full-Reads matched ADRs. Conservative fallback: include any ADR whose title or status header literally mentions the component or its technology even if intersection misses. Cuts orchestrator-side ADR token cost by ~60%.

Sub-agent tool discipline tightened:

  • agents/handoff-generator.md PHASE 2 codifies the Single-Write rule — fill the entire template in memory and emit one Write call. Target: 4–6 tool calls per spawn, down from the 15–31 observed in v3.12.0.
  • agents/handoff-generator.md frontmatter dropped Bash from tools: — sub-agents no longer invoke any shell command (asset directory pre-created by orchestrator, generation_date from payload frontmatter, references bundled).

Removed dead code:

  • SKILL.md Step 0c (plugin-ref staging to /tmp/handoff-plugin-refs/) — obsoleted by the agent bundle. Permissions block dropped /tmp/handoff-plugin-refs/* grants.
  • SKILL.md Step 2.2 (dependency-based component ordering) — sub-agents never read prior handoffs, so the sort provided no information benefit. Components now ordered by component_index_position.

Migration: first run after upgrade has no handoffs/.manifest.json → context-builder returns decision: REGEN for every component → manifest is created. No surprises. Recommended git policy: commit handoffs/.manifest.json so teammates also benefit from skip-if-unchanged.

Permissions delta: added Read(handoffs/.manifest.json), Write(handoffs/.manifest.json), Agent(sa-skills:handoff-context-builder). Removed Read(//tmp/handoff-plugin-refs/*), Write(//tmp/handoff-plugin-refs/*). (Also fixed pre-existing single-slash absolute-path entries in SKILL.md permissions docs to the correct //tmp/... form.)

v3.12.0 (Previous Release) ✅

feat: new Asset 8 — c4-descriptor.md operational one-pager per component, EN/ES

architecture-dev-handoff now generates an eighth asset alongside the existing OpenAPI / DDL / Kubernetes / AsyncAPI / CronJob / Avro / Protobuf / Redis bundle: a C4 Component Descriptor (handoffs/assets/NN-<slug>/c4-descriptor.md). It's the consolidated operational one-pager dev teams hand to SRE, infra, and network partners when a component ships — three sections (Description / Responsibilities / Technical Decisions) with infrastructure metadata (hostname, IP, OS, domain, middleware stack), dependency rollup, ADR references, and resource allocation (TPS sustained/peak, CPU cores, RAM GB, storage GB, latency P99, availability SLO). The descriptor is always-on for every non-skip component — no opt-out flag. Skip-list types (Library, SDK, Utility, Config, Documentation) get nothing, matching the existing asset skip rule.

The template ships in two language variants. The orchestrator detects the architecture-doc language once per run (via explicit <!-- LANGUAGE: es --> marker → Spanish section-heading inference → English default) and stamps the payload with doc_language: en | es. The sub-agent selects the matching template variant at asset-generation time. Values (component names, technology names, hostnames, ADR IDs) stay verbatim regardless of variant; only structural labels and the [NOT DOCUMENTED] / [NO DOCUMENTADO] markers localize. The EN/ES split mirrors the pattern already established by architecture-blueprint.

Asset Fidelity Rule applies identically to the new asset — zero invention. Fields not present in architecture docs get [NOT DOCUMENTED — add to docs/09-operational-considerations.md] (or the specific source file per the section-extraction map) rather than inferred or defaulted values. Most projects today don't capture hostname / IP / OS / domain in their architecture, so first-generation descriptors are mostly markers pointing at the right file to fill in — which is the point: the descriptor doubles as a discovery checklist for operational-metadata gaps.

Changes:

  • skills/architecture-dev-handoff/ASSET_GENERATION_GUIDE.md — +177 lines. New "Always generated (except skip-list)" row in the Asset Detection Rules table; new Asset 8 section with source-data map, EN + ES scaffold templates, filling instructions, post-generation checks. Existing assets shifted +1 line due to the detection row addition.
  • skills/architecture-dev-handoff/assets/_index.md — new c4-descriptor line-range entry (861-1036); updated shared policy range (1-88) and After-Asset-Generation range (1037-1050); all pre-existing ranges updated for the +1 shift; maintenance grep updated to include ^## After Asset.
  • skills/architecture-dev-handoff/PAYLOAD_SCHEMA.md — added doc_language required frontmatter field; appended c4-descriptor to every non-skip component-type's asset_types default; added an explicit skip row documenting the Library/SDK/Utility/Config/Documentation exclusion.
  • skills/architecture-dev-handoff/SKILL.md — new Step 3.3 "Detect architecture-doc language" run once per orchestration; Step 4.1 augmented to append c4-descriptor to asset_types; Step 4.4 frontmatter contract now includes doc_language.
  • skills/architecture-dev-handoff/SECTION_EXTRACTION_GUIDE.md — new "Asset 8 — C4 Component Descriptor extraction fields" table mapping each descriptor field to its primary source / fallback / missing-marker file hint.
  • agents/handoff-generator.md — Phase 0 extracts doc_language; Phase 1.3 gains the language-variant selection rule; Phase 3 asset-file table includes c4-descriptor.

Runtime behavior is strictly additive. Existing handoff runs get one extra file per component; nothing in the 16-section handoff template changes.

v3.11.0 (Previous Release) ✅

feat: architecture release workflow defaults to PR flow, --direct opts out

The architecture release workflow (architecture-docs Workflow 10 — triggered by "release my architecture", "bump architecture version", /release-architecture, etc.) now creates a pull request by default so CI, required reviewers, and branch-protection rules can gate the release before it lands on main. The previous direct-to-current-branch behavior is preserved behind a --direct flag for local-only repos, emergency hotfixes, and projects without a PR review layer.

In PR mode the workflow itself does the branching and committing — the user never has to commit manually between Step 6 (metadata edits) and Step 7 (tag). The workflow creates release/architecture-v{version}, commits ARCHITECTURE.md + docs/CHANGELOG.md + every docs/components/**/*.md (and archive/v{version}/ if the snapshot step ran), tags the commit with architecture-v{version}, pushes branch + tag to origin, and prints host-agnostic PR instructions (GitHub compare URL if origin matches github.com, generic prose for GitLab / Bitbucket / Azure DevOps / self-hosted). PR mode uses standard git commands only — no gh, glab, or host-specific CLI dependency.

Tag timing is before-PR — the tag lives on the release-branch commit so downstream consumers can fetch architecture-v{version} immediately. The PR gates what lands on main, not the tag. Step 8's PR-mode report includes the one-liner to move the tag onto the squash/merge commit if desired (git tag -f … && git push --force), otherwise the tag stays on the pre-squash commit — still fetchable, still semantically valid.

Changes:

  • skills/architecture-docs/RELEASE_WORKFLOW.md — Added a "Release Channels" prelude explaining PR vs --direct. New Step 6.5 detects the channel from invocation arguments (default PR; silent fallback to direct when no origin remote exists). Step 7.5 (Archive Snapshot) moved before Step 7 so the archive is part of the PR commit in PR mode. Step 7 split into parallel Direct (current behavior, unchanged apart from the precondition message mentioning the PR alternative) and PR (new 8-substep branch/commit/tag/push/instructions flow) sections. Step 8 report gets a PR-mode variant. Implementation Notes updated to reflect dual-mode push behavior and the standard-git-only constraint. Recovery path (Step 1.5) is unchanged and runs in direct mode regardless of channel choice.
  • commands/release-architecture.md — Documents --direct / --pr argument passthrough and the eight-step Workflow 10 skeleton including the new Step 6.5 and dual-mode Step 7.
  • CLAUDE.md — Trigger routing table row for "release my architecture" updated to note the PR default and --direct opt-out.

v3.10.1 (Previous Release) ✅

fix: .gitignore helper warns when CLAUDE.md is already tracked by git

Adding CLAUDE.md to .gitignore has no effect if the file is already tracked — git keeps tracking it until the user runs git rm --cached CLAUDE.md. Since v3.10.0 added CLAUDE.md to the baseline .gitignore entries, users with an existing checked-in CLAUDE.md would have silently continued to track it despite seeing + CLAUDE.md in the /setup output.

Changes:

  • scripts/setup-gitignore.ts — After a successful write, if CLAUDE.md was among the newly-added entries, run git -C <project_cwd> ls-files --error-unmatch CLAUDE.md to check tracking status. If the file is tracked, print a warning block showing the exact git rm --cached CLAUDE.md command. The check is conditional on CLAUDE.md being in the missing set — Unchanged re-runs don't re-warn. In non-git directories the check exits non-zero and the warning is silently skipped.

v3.10.0 (Previous Release) ✅

feat: /setup merges sa-skills baseline entries into .gitignore

/setup now also ensures the project's .gitignore contains the three baseline entries every sa-skills project should ignore: exports/ (Word .docx deliverables produced by architecture-docs-export), /tmp/ (local scratch output), and CLAUDE.md (the per-project Claude instructions file managed by Step 5). Before this release, new users routinely committed generated exports/*.docx artifacts and machine-specific CLAUDE.md content into their repos.

Changes:

  • scripts/setup-gitignore.ts — NEW Bun helper. Line-exact append-only merge: for each managed entry, checks if any non-comment line in .gitignore matches (trimmed, with leading-slash normalization so /tmp/ and tmp/ both count). Missing entries are appended under a single # sa-skills header (not duplicated on re-runs). Three outcomes: Created (no .gitignore), Appended (missing entries added), Unchanged (all three already present). User entries are never reordered or removed.
  • commands/setup.md — new Step 6 invokes the helper; Step 7 is now the final Restart reminder. Notes extended with a .gitignore idempotency bullet.

End-to-end idempotency: a re-run on a fully-configured project now reports 0 added / N already present for permissions, Unchanged for the CLAUDE.md block, and Unchanged for .gitignore.

v3.9.1 (Previous Release) ✅

fix: CLAUDE.md pointer block treats ARCHITECTURE.md as the entry point

The v3.9.0 block body described ARCHITECTURE.md as an optional "single-file form" alternative to docs/. That was incorrect — per skills/architecture-docs/SKILL.md:185,196-197, every architecture has ARCHITECTURE.md at the project root as the navigation index (~130 lines) and docs/ as a sibling holding the section files. There is no "single-file vs multi-file" choice today; the multi-file layout with ARCHITECTURE.md as the entry point is the only form.

Changes:

  • scripts/setup-claude-md.ts — Rewrote the first two bullets of the managed block. ARCHITECTURE.md is now listed first and described as "the entry point … always start here". The docs/ bullet drops the conditional language and adds the resolve-via-navigation-table guidance. Existing installations pick up the new wording automatically on the next /setup run (the block is replaced in place via its markers).

v3.9.0 (Previous Release) ✅

feat: /setup now writes a project CLAUDE.md architecture pointer block

/setup previously only merged permissions.allow, enabledPlugins, and extraKnownMarketplaces into .claude/settings.json. It told Claude what it could do but not where the architecture context lived in the user's project. Running /setup now also drops a marker-delimited block into the project's ./CLAUDE.md that points Claude at the canonical architecture surface: docs/ (split layout or ARCHITECTURE.md), docs/components/ (C4 Level 2 descriptors), adr/ (Architecture Decision Records), and handoffs/ (Component Development Handoffs).

Changes:

  • scripts/setup-claude-md.ts — NEW Bun helper. Resolves $project_cwd/CLAUDE.md and writes a block delimited by <!-- sa-skills:architecture-pointer:begin --> / <!-- sa-skills:architecture-pointer:end -->. Four branches: Created (no file), Appended (file exists, no markers), Updated (markers present, content differs), Unchanged (markers present, content identical). Only content between the markers is ever written — surrounding user content is preserved byte-for-byte. Exits non-zero only on I/O errors or malformed marker order.
  • commands/setup.md — Renamed Step 4 to "Report permissions merge"; added Step 5 "Generate CLAUDE.md architecture pointer" (invokes the new helper against the project CWD with failure isolated from the permissions merge); added Step 6 "Final reminder" so the "Restart Claude Code" line appears last. Extended Notes with an idempotency bullet covering the managed block.

Non-destructive and idempotent: re-running /setup on a configured project reports 0 added / N already present for permissions and Unchanged for the CLAUDE.md block. Users can add their own content above, below, or around the managed block — the helper only rewrites what's between the markers.

v3.8.9 (Previous Release) ✅

refactor: remove time estimates from analysis menu

The sa-skills:architecture-analysis skill displays a blocking menu of the 10 available analyses when the user invokes it. Each row previously carried a per-analysis wall-clock estimate (~60s, ~75s, or ~90s) intended to help users pick a subset. In practice those numbers never reflected real runtime — actual durations depend on architecture size, number of selected analyses, model latency, and tool-call overhead, so the estimates drifted from reality and led users to false expectations (particularly the ~90s "All ten (parallel)" row, which rarely completed in that window).

Changes:

  • skills/architecture-analysis/SKILL.md — Removed the ~60s / ~75s / ~90s prefix from all 11 rows of the Step 2 analysis picker (10 individual analyses + "All ten (parallel)"). Kept the 1 agent / 10 agents parallelism column since it accurately reflects the number of sub-agents spawned. Labels now read e.g. 1. SPOF (Single Points of Failure) 1 agent instead of ~60s · 1 agent.

No behavior change — analysis parsing, agent dispatch, spec paths, and output filenames are untouched. Users still select analyses by the same single-number / comma / range / all syntax, and the menu still blocks until they choose.

v3.8.8 (Previous Release) ✅

fix: theme-agnostic colors in Blast Radius cascade diagrams

The sa-skills:architecture-analysis Blast Radius report includes a Mermaid flowchart TD in the "Cascade Paths — Top 3 Worst Scenarios" section with red nodes for cascading failures and green nodes for contained failures. The previous palette used bare fill:#ff6b6b (cascading) and fill:#95e795 (contained) inline styles, leaving Mermaid to pick the default stroke and text color from the host theme — which flipped between light and dark and produced low-contrast labels in whichever mode the renderer happened to choose.

Changes:

  • skills/architecture-analysis/analyses/BLAST_RADIUS.md — Replaced the two inline style X fill:#… statements with Mermaid classDef cascading and classDef contained declarations. New palette: #e57373 fill / #c62828 stroke for cascading; #81c784 fill / #2e7d32 stroke for contained. Both classDefs pin color:#000 so labels stay readable regardless of the theme the Mermaid renderer picks, and set stroke-width:2px for a consistent outline. The example diagram now applies the classes via :::cascading / :::contained node selectors instead of post-hoc style lines.

No agent or runtime changes — the architecture-analysis-agent reads the spec verbatim during Phase 5 report rendering, so the new palette propagates automatically on the next Blast Radius run. Other analyses (SPOF, Bottleneck, Cost Hotspots, STRIDE, Coupling, Data Sensitivity, Latency Budget, Tech Debt, Vendor Lock-in) are ASCII-only and unaffected.

v3.8.7 (Previous Release) ✅

feat: /setup slash command installs the plugin's required permissions into the project

New plugin-level /setup command bootstraps a project's .claude/settings.json by merging the plugin's bundled settings.json.example into it. Non-destructive — existing user entries (custom permissions, enabled plugins, marketplaces, model/theme/hooks/custom keys) are preserved; only missing entries are added. Useful when installing the plugin into a new project, or when recovering a project after the v3.8.5 namespace rename introduced new Agent(sa-skills:*) grants that weren't in older settings.

Changes:

  • commands/setup.md — NEW slash command that resolves plugin_dir (marketplace install, cache install, or dev clone — same {sa-skills,solutions-architect-skills} brace expansion as v3.8.6), then invokes the merge helper.
  • scripts/setup-permissions.ts — NEW bun helper. Reads the example and the user's settings JSON, strips //-prefixed comment keys from the example, and merges three top-level sections: permissions.allow (array union, deduplicated), enabledPlugins (object merge, user wins on key conflict), extraKnownMarketplaces (same). Creates .claude/ if missing. Writes with 2-space indent + trailing newline. Prints a structured summary (added / already-present counts, full list of new grants, and a warning if legacy solutions-architect-skills:* grants are still present).

Usage:

/setup

The helper runs through the Bash(bun *) permission. First-time users will see one Claude Code permission prompt when the script runs; approve once and the prompt does not repeat. Re-running /setup on an already-configured project is idempotent (0 added / N already present).

v3.8.6 ✅

fix: plugin_dir Glob probes now match both sa-skills/ (marketplace install) and solutions-architect-skills/ (dev clone)

v3.8.5 renamed the plugin namespace but left five skills' Step 0 "Resolve Plugin Directory" probes hardcoded to **/solutions-architect-skills/.... On marketplace installs the cached plugin folder is now ~/.claude/plugins/cache/<marketplace>/plugins/sa-skills/, so the Glob missed — orchestrators fell through to the marketplace or /tmp/handoff-plugin-refs/ fallback on every run. Each probe now uses brace expansion to accept either folder name.

Changes:

  • skills/architecture-docs-export/SKILL.md — Glob updated (locates tools/docgen/generate-doc.js).
  • skills/architecture-dev-handoff/SKILL.md — Glob updated (locates SKILL.md).
  • skills/architecture-analysis/SKILL.md — Glob updated (locates SKILL.md).
  • skills/architecture-icepanel-sync/SKILL.md — Glob updated (locates ICEPANEL_IMPORT_REFERENCE.md).
  • skills/architecture-blueprint/SKILL.md — Glob updated (locates BUSINESS_TEMPLATE_EN.md).

Unchanged: skills/architecture-compliance/utils/resolve-plugin-dir.ts was always folder-name-agnostic (uses path.resolve relative to its own location), so no TS changes were needed. Marketplace-fallback paths still reference the marketplace directory (shadowx4fox-solution-architect-marketplace), which is unaffected by the plugin rename.

v3.8.5 (Previous Release) ✅

refactor: rename plugin namespace from solutions-architect-skills to sa-skills

The fully-qualified skill invocation solutions-architect-skills:<skill> (e.g., solutions-architect-skills:architecture-docs) was long enough to be cumbersome in prompts, routing tables, and permission grants. This release shortens the plugin namespace to sa-skills, so invocations become sa-skills:architecture-docs, sa-skills:architecture-compliance, etc. No skills are added, removed, or reorganized — only the namespace prefix changes.

Changes:

  • .claude-plugin/plugin.json, .claude-plugin/marketplace.json, package.json — plugin name field updated to sa-skills.
  • All 20 files carrying qualified skill invocations (CLAUDE.md, README.md, CHANGELOG.md, commands/release-architecture.md, every SKILL.md that references sibling skills, docs/INSTALLATION.md, docs/WORKFLOW_GUIDE.md, docs/MIGRATION.md, .claude/settings.json, .claude/settings.json.example) rewritten from solutions-architect-skills:X to sa-skills:X.
  • GitHub repo URLs, the repo folder name, the marketplace name (shadowx4fox-solution-architect-marketplace), and historical release artifacts are unchanged.

Migration:

  • Existing project .claude/settings.json entries that grant Agent(solutions-architect-skills:<name>) must be updated to Agent(sa-skills:<name>). The new .claude/settings.json.example reflects the rename; copy/merge it.
  • Marketplace-installed plugin caches: after pulling this release, reinstall via /plugin install sa-skills@shadowx4fox-solution-architect-marketplace so Claude Code re-keys the plugin under the new name.
  • Any saved prompt templates, CLAUDE.md trigger tables, or custom hooks that reference solutions-architect-skills: should be updated to sa-skills:.

Known limitation: the plugin_dir Glob probes (used by architecture-dev-handoff and architecture-docs-export to resolve the plugin install path) still look for **/solutions-architect-skills/. Dev-mode (local clone) installs still work because the repo folder name is unchanged; marketplace installs fall back to the staging path (/tmp/handoff-plugin-refs/) when the Glob misses. A follow-up release will update the probe to match both names.

v3.8.4 (Previous Release) ✅

refactor: scope architecture-dev-handoff to architecture docs only; move output to handoffs/ at project root

The dev-handoff skill previously sliced rows from compliance-docs/SECURITY_*.md, SRE_*.md, and DEVELOPMENT_*.md contracts into per-component payloads, which landed as "Compliance Gaps to Address" / "SRE Compliance Gaps" / "Development Compliance Gaps" subsections inside Sections 6, 9, and 11 of the handoff. This mixed compliance audit output into a document meant purely for implementation. Handoffs now draw only from ARCHITECTURE.md, docs/, and adr/. The output directory also moves from docs/handoffs/ to handoffs/ at the project root — docs/ is the authored-architecture source, handoffs/ is derived artifacts; keeping them separate prevents accidental coupling.

Changes:

  • skills/architecture-dev-handoff/ — removed Step 4.4 (slice compliance contracts), the ## Compliance Gaps payload section, and Section 6/9/11 compliance-enrichment blocks from SECTION_EXTRACTION_GUIDE.md. Source comment on Section 6 template no longer mentions compliance-docs/. ADRs remain a source (Section 13 and Section 11 prohibited-tech scan unchanged).
  • agents/handoff-generator.md — per-section guidance for Sections 6/9/11 no longer references ## Compliance Gaps.
  • Output-path migration — all references to docs/handoffs/ updated to handoffs/ across SKILL.md, HANDOFF_TEMPLATE.md, ASSET_GENERATION_GUIDE.md, PAYLOAD_SCHEMA.md, handoff-generator.md, and .claude/settings.json.example (permissions now Write(handoffs/*) / Read(handoffs/*)). Managed-index breadcrumb is now ../ARCHITECTURE.md (one level up instead of two).
  • Downstream consumers synced — architecture-docs-export (Handoff mode Glob + error message), docs-export-generator.md, architecture-docs (cross-reference scan + Phase 5 asset advisory), architecture-definition-record (ADR propagation grep + phase 5 advisory), architecture-component-guardian (C4 migration table — relative path recomputed since handoffs/ is now at root depth), architecture-onboarding (handoffs section scan), and README.md.
  • skills/architecture-docs/RELEASE_WORKFLOW.md — archive snapshot exclusion list updated to handoffs/.

Migration note: existing projects with a populated docs/handoffs/ folder should git mv docs/handoffs handoffs after pulling this release and update the Write(docs/handoffs/*) / Read(docs/handoffs/*) entries in their project .claude/settings.json to Write(handoffs/*) / Read(handoffs/*).

v3.8.3 (Previous Release) ✅

fix: architecture-dev-handoff routes mkdir/date through a bun helper to eliminate permission prompts

The architecture-dev-handoff orchestrator was prompting users for Bash(mkdir -p /tmp/handoff-payloads && date +%Y-%m-%d) on every run. Even though Bash(mkdir *) and Bash(date *) were granted individually, the chained-with-&& form was treated as a new pattern by the permission matcher. This release routes both calls through a single bun helper covered by the project-wide Bash(bun *) grant.

Changes:

  • skills/architecture-dev-handoff/utils/prepare-payload-dir.ts — NEW bun helper that recursively mkdirs the path argument and prints today's date in one call. Reuses getLocalDateString() from architecture-compliance/utils/date-utils.ts so the date logic stays single-source.
  • skills/architecture-dev-handoff/SKILL.md — Step 0c (/tmp/handoff-plugin-refs/ staging) and Phase 4.5 (payload write + generation_date capture) now invoke the bun helper. Permissions block reduced to Bash(bun *).
  • agents/handoff-generator.md — sub-agent reads generation_date from payload frontmatter instead of shelling out to date; asset directory creation goes through the bun helper. mkdir and date are now in the FORBIDDEN list.

No behavior change for any other skill — only the dev-handoff workflow's bash surface changed.

v3.8.2 (Previous Release) ✅

fix: architecture-dev-handoff plugin_dir resolution + sub-agent read-permission safety net

Sub-agents spawned by architecture-dev-handoff were failing their first Read of HANDOFF_TEMPLATE.md when plugin_dir resolved to the cache install path (~/.claude/plugins/cache/…) but the example permission grant only covered the marketplaces manifest path. The workaround — manually staging reference files to /tmp/handoff-plugin-refs/ — now runs automatically when needed.

Changes:

  • skills/architecture-dev-handoff/SKILL.md — added Step 0 — Resolve Plugin Directory (Glob → marketplace fallback → readability probe → /tmp/handoff-plugin-refs/ staging fallback). The orchestrator now verifies sub-agent read permissions on the main thread before spawning, and mirrors the 4 reference files (HANDOFF_TEMPLATE.md, SECTION_EXTRACTION_GUIDE.md, ASSET_GENERATION_GUIDE.md, assets/_index.md) to /tmp when the installed path is not permitted.
  • agents/handoff-generator.md — plugin_dir is now always supplied by the orchestrator; the ambiguous Glob fallback that could silently resolve to the cache path was removed.
  • .claude/settings.json.example — added Read(~/.claude/plugins/cache/…/**), broadened the marketplaces grant to **, and added scoped /tmp/handoff-payloads/* + /tmp/handoff-plugin-refs/* read/write grants.

No behavior change for skills that already resolved plugin_dir via their own Step 0 (architecture-analysis, architecture-docs-export).

v3.8.1 ✅

fix: sync marketplace.json + CLAUDE.md cleanup — catch-up release for v3.7.0 / v3.8.0

Catch-up release. plugin.json was bumped to v3.8.0 in prior commits but marketplace.json and package.json remained at v3.6.1, so /plugin update never served the newer versions. This release re-synchronizes all three version files and backfills README roadmap entries for v3.7.0 and v3.8.0.

Changes:

  • .claude-plugin/marketplace.json and package.json re-synced to match .claude-plugin/plugin.json
  • CLAUDE.md trimmed from 621 → 168 lines (73% reduction): removed per-skill walkthroughs duplicated from each SKILL.md, fixed stale skill count (8 → 14), removed references to non-existent bun run build:agents script and scripts/build-agents.ts file, corrected context7 tool name get-library-docs → query-docs, and corrected compliance-agent description ("10 generators" → "1 universal generator")
  • Git tag v3.8.1 created to re-establish tag sequence after v3.6.1

No skill / agent behavior changes. Documentation and packaging hygiene only.

v3.8.0 (Previous Release) ✅

perf: wrap architecture-docs-export in sonnet sub-agent to pin token cost

architecture-docs-export now runs as a lightweight orchestrator that spawns a docs-export-generator sub-agent pinned to model: sonnet for the actual file reads, markdown composition, and docgen invocation. Export is a zero-synthesis, high-frequency task — Sonnet is the right fit, and the sub-agent wrap prevents cost drift when teams run frequent exports on Opus-configured main contexts.

v3.7.0 (Previous Release) ✅

feat: dev-handoff sub-agent orchestration + release-phrase auto-routing

Two-part release:

  • architecture-dev-handoff refactored to orchestrator + handoff-generator sub-agent (model: Sonnet 4.6) with 2-parallel batching. Main context stays flat even for 10+ component runs: orchestrator reads shared architecture docs once, slices per-component payloads to /tmp/handoff-payloads/<slug>.md, sub-agents consume their slice + template + asset guide (~25–40 KB context each).
  • Release-phrase auto-routing: /release-architecture slash command added at commands/release-architecture.md — deterministic fallback that invokes architecture-docs Workflow 10 directly, bypassing phrase matching. Trigger Routing table in CLAUDE.md updated with the full release phrase set.

v3.6.1 (Previous Release) ✅

perf: batch high-fanout sub-agents to 2-parallel + post-run /compact hint

Three fan-out skills previously dispatched 10–13 sub-agent Task() calls in a single message — architecture-compliance (10 validators + 10 generators), architecture-peer-review (up to 13 category agents), architecture-analysis (up to 10 analyses). This release caps peak parallelism at 2 across all three skills via strict batching barriers, and emits a user-visible /compact hint after the final report.

Changes:

  • architecture-compliance Step 3.3 (validators) and Step 3.4 (generators) — strict 2-agent batches with [BARRIER] between each; 10 contracts = 5 sequential batches
  • architecture-peer-review Step 5 — 2-agent batches (Light=2 batches, Medium=4, Hard=7)
  • architecture-analysis Step 3 — 2-agent batches (10 analyses = 5 batches)
  • All three skills now append a 💡 Tip: ... /compact hint to their final completion output so users can reclaim context after document propagation

Rationale: Spawning 10+ parallel sub-agents concentrates cost, makes early-abort impossible, and holds all responses in the orchestrator context simultaneously. Batches of 2 reduce peak concurrent return volume (~80% drop during the return window) and allow the orchestrator to observe failures before dispatching remaining batches. The /compact hint addresses context-window inflation after fan-out completes.

Tradeoff: Wall-clock slows by ~5× on 10-wide fanouts (5 sequential batches vs 1). Total sub-agent work is unchanged; the reduction is in orchestrator context pressure and early-failure observability.

No API/contract changes. Pure SKILL.md orchestration edits — no TypeScript, pipeline, or agent-definition changes. Backward compatible.

v3.6.0 (Previous Release) ✅

feat: model preset selection for compliance contract generation (eco / balanced / critical-opus / max)

The architecture-compliance skill now exposes four model presets controlling which Claude model each validator and the generator run on. Users can cut full-run token cost by up to ~90% versus the prior all-Opus baseline, while preserving reasoning depth on the audit-sensitive validators.

Presets:

  • eco — Haiku × 10 validators + Sonnet generator (~90% cheaper)
  • balanced (default) — Sonnet × 10 validators + Sonnet generator (~75% cheaper)
  • critical-opus — Opus retained only for Security / SRE / Data & AI / Development validators; Haiku elsewhere; Sonnet generator (~60% cheaper)
  • max — prior behavior (Opus × 10 + Opus generator)

Invocation: /skill architecture-compliance <preset> <selector> (e.g., balanced all, eco SRE,Cloud,Security, critical-opus all). When preset is omitted, the skill prompts via AskUserQuestion and defaults to balanced.

Rationale: Validators perform mechanical Read + Grep classification (PASS/FAIL/N/A/UNKNOWN) — Sonnet matches Opus at ~5× lower cost. The four validators kept on Opus in critical-opus are the ones where reasoning nuance materially affects audit evidence: security-posture wording (Argus), SLO / error-budget math (Prometheus), PII classification (Mnemosyne), EOL date synthesis via WebSearch (Hephaestus).

Backward compatible: Agent frontmatter unchanged (Opus fallback). The override is applied per-Task() call at the skill-orchestration layer — no sub-agent or pipeline code change needed.

Smoke tested: Full validator → generator → post-gen pipeline cycle on balanced preset against a real architecture produces valid contracts with all pipeline fields populated; Sonnet validator is measurably more rigorous on UNKNOWN classifications than Opus.

v3.5.8 (Previous Release) ✅

chore: all 13 sub-agents migrated to model: opus (Claude Opus 4.7)

All sub-agent files under agents/ switched from model: sonnet to model: opus. On the Anthropic API the opus alias currently resolves to Claude Opus 4.7 (1M context window).

Agents migrated (13 total):

  • agents/compliance-generator.md, agents/peer-review-category-agent.md, agents/architecture-analysis-agent.md
  • 10 domain validators under agents/validators/ — business-continuity, cloud, data-ai, development, enterprise, integration, platform, process, security, sre

Rationale: Stronger reasoning improves compliance contract fidelity (template preservation + placeholder extraction), peer-review nuance across 13 category checks, validator evidence extraction with Grep-based citation, and architecture-analysis classification across the 10 risk/design lenses. The 1M context window removes split-read constraints previously planned for large ARCHITECTURE.md suites.

Skills unchanged (14 total): All skill orchestration patterns (parallel agent spawning, template-filling, structured output blocks) are natively supported by Opus 4.7. Skill frontmatter continues to inherit model selection from the calling session — no SKILL.md changes.

v3.5.2 (Previous Release) ✅

docs: architecture-analysis full README documentation — 14-skill count, analysis tables, features section

Complete README documentation for the architecture-analysis skill: version badge corrected to 3.5.1/3.5.2, skills count updated from 13 to 14, architecture-analysis added to the skills list with a 10-analysis summary, added to the Supporting Skills table, installation verification line updated, and a full Architecture Analysis features section added between Phase 3 Compliance and Phase 4 Dev Handoff documenting all 10 analyses (both groups) with per-analysis output tables, key principles, output location, and required permissions.

v3.5.1 (Previous Release) ✅

feat: architecture-analysis — 5 additional analyses (Vendor Lock-in, Latency Budget, Tech Debt, Coupling, Data Sensitivity)

Extends the architecture-analysis skill from 5 to 10 analyses. The dispatcher menu grows to 11 options (10 individual + "All ten"), with grouped sections for HIGH-priority and Strategic/sustainability analyses. Range selection (e.g., "6-10") and group selection ("all") are supported. All ten analyses spawn in a single message via parallel Task() calls.

New analyses:

  • Vendor Lock-in — L1 (locked) / L2 (lock-prone) / L3 (portable) classification per component/capability, per-vendor concentration table (≥60% flag), exit cost ranking (proprietary surface × replacement effort × data export feasibility), lock severity × strategic importance heat map
  • Latency Budget — per-flow p95 SLO decomposition into hops, Within Budget / Tight / Over Budget / Untracked classification per hop, ASCII Gantt-style budget bars, tail-latency variance flag (p99/p95 > 3×), Hops Over Budget summary table
  • Tech Debt / EOL — T1 (EOL now) / T2 (EOL ≤6mo) / T3 (deprecated) / T4 (current) / T5 (unknown) currency tiers, EOL Hotlist table, deprecated SDK scan, ADR architectural debt table (Superseded ADRs whose replacement is not yet implemented), severity × effort heat map
  • Coupling — per-component fan-in (Ca), fan-out (Ce), instability (I = Ce/(Ca+Ce)) metrics, K1 critical hubs (fan-in ≥5) / K2 volatile leaves (fan-out ≥5) / K3 god objects (both) / K4 cyclical dependencies with Mermaid cycle subgraphs, ASCII fan-in/fan-out distribution histograms
  • Data Sensitivity — S1–S4 data classification per store/queue/cache, G1–G5 gap classification (unencrypted transit, at-rest, retention breach, cross-boundary leakage, undocumented), sensitive data flow Mermaid sequence diagrams for top-3 S1 flows, compliance cross-reference to compliance-docs/SECURITY_*.md and DATA_AI_*.md

Files added: analyses/VENDOR_LOCKIN.md, analyses/LATENCY_BUDGET.md, analyses/TECH_DEBT.md, analyses/COUPLING.md, analyses/DATA_SENSITIVITY.md

Files modified: SKILL.md (menu + map), agents/architecture-analysis-agent.md (enum), CLAUDE.md (10-analysis section)

v3.5.0 (Previous Release) ✅

feat: architecture-analysis skill — 5 HIGH-priority risk analyses (SPOF, Blast Radius, Bottleneck, Cost Hotspots, STRIDE)

New architecture-analysis skill delivering a risk and design-characteristics dashboard for architects. Five analyses can be run individually or all five in parallel, each producing a date-stamped report in analysis/ with structured findings, heat maps, and prioritized remediation recommendations. Every finding is grounded in architecture documentation with source citations; missing data is flagged as [NOT DOCUMENTED] rather than estimated.

Analyses:

  • SPOF — Critical (full outage) / Degradation (partial-silent) / Operational SPOFs + ASCII heat map + top-5 remediations. Modeled after the worked Notification Inbox Platform v1.2.0 example.
  • Blast Radius — per-component fan-out and cascade severity, bulkhead vs. cascading classification, Mermaid cascade paths for top-3 worst scenarios, SPOF cross-reference (⚡ SPOF+Blast flag for maximum risk concentration)
  • Bottleneck — throughput chokepoints (B1–B4 tiers), HPA and connection-pool saturation risk, ASCII capacity headroom bar chart, ADR-driven bottleneck tracking
  • Cost Hotspots — Pareto cost ranking (80% concentration rule), over-provisioning candidates, vendor concentration summary, ADR cost decision table, right-sizing recommendations with trade-off analysis
  • STRIDE — trust boundary inventory, per-boundary 6-category threat matrix, High-Priority Threats table, compliance cross-reference with security contract gaps

Files added:

  • skills/architecture-analysis/SKILL.md — dispatcher, BLOCKING menu, parallel Task() orchestration
  • skills/architecture-analysis/analyses/ — 5 analysis spec files (SPOF, BLAST_RADIUS, BOTTLENECK, COST_HOTSPOTS, STRIDE)
  • skills/architecture-analysis/templates/analysis-report-skeleton.md — shared report structure
  • agents/architecture-analysis-agent.md — universal analysis agent (parameterized by analysis_type)
  • CLAUDE.md — new "Using the Architecture Analysis Skill" section
  • .claude/settings.json.example — added architecture-analysis-agent + Write/Read(analysis/*) permissions

v3.4.7 (Previous Release) ✅

fix: architecture release workflow pushes git tag to origin automatically

After git tag -a architecture-v{version} is created, the workflow now immediately pushes the tag to origin. Graceful fallbacks: reports (but does not fail) when no remote is configured, and preserves the local tag on push failure with a manual-push hint.

  • skills/architecture-docs/RELEASE_WORKFLOW.md: Step 7.4 rewritten — checks for origin remote, pushes the tag, handles no-remote and push-failure cases without deleting the local tag.

v3.4.6 (Previous Release) ✅

feat: ADR institutional/user scope with reserved numbering (001–100 / 101+)

Introduces a first-class **Scope** field (Institutional | User) to all ADRs, with the number range encoding the scope: ADR-001–100 are reserved for organization-wide institutional decisions (Architecture Team), and ADR-101+ are used for project-local user decisions.

  • skills/architecture-definition-record/SKILL.md: Workflow 2 Step 2.1 rewritten as a scope-aware partitioned next-number lookup — asks scope first, then scans existing ADR headers to compute the correct next number in the institutional (001–100) or user (101+) range. Overflow of the institutional range is blocked with a reclassify/supersede/cancel prompt. Workflow 1 updated to extract or infer scope from the ARCHITECTURE.md Section 12 table (Case A: explicit Scope column; Case B: number-range inference with user confirmation). Workflow 5 audit output updated with a Scope column and institutional-range utilization line.
  • skills/architecture-definition-record/adr/ADR-000-template.md: Added **Scope**: Institutional | User header field; updated File Naming Convention block with the 001–100 / 101+ partition and annotated examples.
  • skills/architecture-definition-record/ADR_GUIDE.md: New "ADR Scope" subsection explaining the two scope types, their number ranges, and why scope is encoded in the number. Added **Scope** to the template block.
  • CLAUDE.md: Added ADR Scope and numbering partition paragraph to the Architecture Definition Record skill section.

v3.4.4 (Previous Release) ✅

fix: bidirectional routing disambiguation — architecture-docs-export no longer captures release/publish/tag intent

Adds a negative disclaimer to architecture-docs-export/SKILL.md to complement the v3.4.3 positive-routing fix in architecture-docs/SKILL.md. The one-sided fix wasn't sufficient — the export skill's semantic proximity to "produce final output" still caused it to win on "release my architecture". Bidirectional disambiguation makes the routing unambiguous from both sides.

  • architecture-docs-export/SKILL.md: Extended description: with explicit NOT-clause covering release/publish/tag/freeze/bump/finalize intent, listing each mis-routed phrase and redirecting to architecture-docs Workflow 10. Removed unsupported triggers: block (was flagged by VS Code in v3.4.3 diagnostic).
  • architecture-docs/SKILL.md (v3.4.3): Already contains positive routing for all release-intent phrases.

Note: SKILL.md description changes take effect in new Claude Code sessions only — the router caches descriptions at session start. After updating, open a fresh Claude Code window before testing.

v3.4.3 (Previous Release) ✅

fix: architecture-docs skill routes correctly for release/publish/tag phrasing

Fixed skill-router mis-routing where "release my architecture" (and related phrasing) fell through to architecture-docs-export instead of the correct architecture-docs skill (which owns Workflow 10 — architecture version release lifecycle).

  • Root cause: architecture-docs/SKILL.md used an unsupported triggers: frontmatter block (flagged by VS Code). The Claude Code router matches against the description: field, which did not mention release, publish, tag, freeze, bump, or finalize.
  • Fix: Removed the unsupported triggers: block and extended description: to explicitly cover the Draft → Released lifecycle (git tag architecture-v{version}, archive snapshot, semver bump) and added a disambiguation clause directing the router away from architecture-docs-export for release-intent phrases.
  • Result: "release my architecture", "publish architecture", "tag architecture version", "freeze architecture", "bump architecture version", "ship architecture", "finalize architecture" now route to architecture-docs → Workflow 10.

v3.4.2 (Previous Release) ✅

feat: mandatory Description field (≤120 chars) added to all component templates

All four architecture type templates and the component creation workflow now include a dedicated one-line **Description:** field positioned immediately after **Communicates via:**:

  • SECTION_5_META.md: Description field added to all 6 layer templates (L1–L6) and the Mobile Banking App example
  • SECTION_5_3TIER.md: Description field added to all 3 tier templates and 3 example components (User API Controller, User Service, User Repository)
  • SECTION_5_MICROSERVICES.md: Description field added to both the microservice and infrastructure templates, and the Order Service example
  • SECTION_5_BIAN.md: Description field added to all 5 layer templates and 2 example components (Mobile Banking App, Payment Order)
  • ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md: Creation block updated with **Description:** field + enforcement note: mandatory, ≤120 characters, longer prose belongs in Purpose

The field provides a structured, length-bounded tagline that downstream tooling (dev handoffs, IcePanel sync, peer review) can consume without re-parsing the free-form Purpose paragraph. Component Guardian index schema is unchanged (5-column fixed table; description lives in the component file only).

v3.4.1 (Previous Release) ✅

docs: remove obsolete monolithic ARCHITECTURE.md leftovers from architecture-docs skill

Full cleanup of "old Document Index + line ranges" pattern that predated the multi-file docs/NN-*.md migration:

  • ARCHITECTURE_DOCUMENTATION_GUIDE.md: Removed old → Lines [START]-[END] index template; rewrote Instructions for Creating the Index for multi-file structure; 3 Design Drivers examples use file-path + section-anchor citations
  • QUERY_SECTION_MAPPING.md: Deleted 12 Typical line range: Lines NNN-MMM entries; rewrote Example Query Mapping Workflow to read docs/NN-*.md files in full (no offset/limit); updated 4 best-practice bullets
  • METRIC_CALCULATIONS.md: Rewrote entire file — removed Section 1 (Automatic Index Updates); Section 2 (Metric Consistency) now reads docs/01-system-overview.md + scans docs/ instead of using line offsets
  • DESIGN_DRIVER_CALCULATIONS.md: Replaced "load Document Index + offset" blocks with direct file reads; 4 justification examples use file-path citations; sequential loading strategy rewritten for multi-file
  • REVIEW_AUDIT_WORKFLOW.md: LOW.5 "Document Index Maintenance" rewritten as "Navigation Index Maintenance"; observations use file paths; 3 line-range warnings updated
  • VALIDATIONS.md: Section Renumbering Workflow Step 3 rewritten with multi-file navigation table; grep -n "^## [0-9]" ARCHITECTURE.md replaced with ls docs/*.md; 4 checklist/best-practice entries updated
  • SKILL.md: "Automatic Index Updates" section rewritten as "Navigation Index Updates" (no line ranges — just add/remove rows when files change)
  • ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md: 2 Document Index references updated to the multi-file Documentation table format
  • examples/ARCHITECTURE_example_3tier.md: Added prominent HISTORICAL warning at top marking the monolithic format as obsolete

v3.4.0 (Previous Release) ✅

feat: architecture versioning — release baselines, per-component versions, git tag, archive snapshots

Complete 5-phase versioning system across the architecture docs cycle:

Phase 1 — Metadata blocks:

  • ARCHITECTURE.md header now carries <!-- ARCHITECTURE_VERSION: X.Y.Z --> + Status/Released/Architect/Supersedes fields
  • Every docs/components/**/*.md file has Component Version + Architecture Version + Last Updated after the C4 metadata block
  • Updated all 4 Section 5 templates (3-Tier, BIAN, META, Microservices)

Phase 2 — CHANGELOG:

  • docs/CHANGELOG.md auto-created at initial architecture creation with [1.0.0] - Draft entry (Keep a Changelog format)

Phase 3 — Release Workflow (Workflow 10):

  • New RELEASE_WORKFLOW.md with 8-step procedure: read version → detect changes → ask bump type → generate changelog → update all metadata → create annotated git tag → archive snapshot → report
  • Semver rules: MAJOR (breaking structural), MINOR (new components/ADRs), PATCH (clarifications)
  • Git tag convention: architecture-v{version} (namespaced). Refuses to tag on dirty working tree or existing tag
  • Version Drift Detection on every skill invocation (doc version vs latest git tag)

Phase 4 — Downstream integration:

  • All 10 compliance contract templates include Architecture Version: [ARCHITECTURE_VERSION] (compliance-generator resolves the placeholder)
  • Dev handoff Section 0 Metadata now has Architecture Version + Component Version rows
  • Traceability report header + completion message include the Architecture Version
  • Component Guardian auto-updates Last Updated on every edit and suggests version bumps (MAJOR/MINOR/PATCH) based on change type

Phase 5 — Archive snapshots:

  • Immutable archive/v{version}/ snapshot of ARCHITECTURE.md + docs/ + adr/ + RELEASE_NOTES.md + .immutable marker
  • Non-git projects: archive is created automatically (primary snapshot mechanism)
  • Git projects: archive is opt-in for regulated industries / audit compliance (git tag is primary)

Backward compatible: Architectures without version metadata still work — downstream artifacts use unversioned as the value.

v3.3.26 (Previous Release) ✅

feat: META WebSocket L1 → L4 exception + mandatory security requirements

  • Documented that L1 (Channels) MAY connect directly to L4 (Business) via WebSocket for real-time push (market data, live alerts, streaming telemetry, trading events) — the standard top-down rule is preserved for all request/response traffic
  • Mandatory security stack required on the L4 endpoint when accepting direct WebSocket connections: WSS/TLS 1.2+, token auth re-validated on reconnect, per-message authorization, origin checks, rate limiting, audit logging, input validation on all inbound frames
  • Updated: META-TO-C4-TRANSLATION.md (Anti-Pattern 6 extended with two explicit exceptions), SECTION_5_META.md (Layer 1 + Layer 4 Dependencies blocks), META-ARCHITECTURE.md (Layer 1 Key Rules)
  • Exception must be captured as an ADR and security controls documented in the L4 component file Section 9

v3.3.25 (Previous Release) ✅

fix: Pre-Write Validation control prevents Mermaid parse errors

  • Added Pre-Write Validation section to DIAGRAM-GENERATION-GUIDE.md with 6-row forbidden pattern checklist (HTML tags, semicolons, emoji, pipe, quotes, subgraph arrows)
  • Strengthened HTML tag rules: both topology and sequence DO NOT lists now explicitly list <br/>, <br>, <b>, <i>, <sup>, <span> and "any <...> element"
  • New Step 10.5 in Generation Workflow: validate all Mermaid/ZenUML blocks against forbidden patterns before writing
  • Added mandatory Pre-Write Validation block to Step 7.1 in ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md
  • Prevents <br/>, ;, emoji, and other parse-breaking patterns from reaching diagram files

v3.3.24 (Previous Release) ✅

docs: README updated with latest skill count (13) and diagram generation changes

  • Updated "What's Included" list: 9 → 13 skills (added traceability, onboarding, icepanel-sync, definition-record)
  • Rewrote Diagram Generation section: documents 4 standard diagrams (Logical View ASCII, C4 L1, C4 L2, Detailed View) + ZenUML data flow diagrams
  • Added architecture-type adaptation note, theme selection enforcement, semicolon prohibition, Mermaid v11.4.1 target
  • Supporting Skills table expanded with traceability, definition-record, onboarding, icepanel-sync
  • New Quality Gates section highlighting peer-review, traceability, and compliance-review

v3.3.23 (Previous Release) ✅

fix: diagram theme selection skipped + semicolon parse error in labels

  • Theme selection (light/dark) during diagram generation was silently defaulting to light instead of asking the user — made the prompt mandatory with "MUST ask, do NOT default silently"
  • Added semicolon prohibition to Mermaid compatibility rules — ; in message/node/edge labels terminates statements causing parse errors; use , instead
  • Applied to both topology diagrams (graph TB) and data flow diagrams (sequence) sections

v3.3.22 (Previous Release) ✅

fix: architecture-docs must delegate all component structural operations to guardian

  • Added Component Operations Delegation Rule to architecture-docs SKILL.md
  • All structural operations on docs/components/ (create, rename, delete, README update, migration, C4 metadata) MUST delegate to architecture-component-guardian
  • Architecture-docs may read component files for context but must NOT create, restructure, or modify the component index directly

v3.3.21 (Previous Release) ✅

fix: C4 component folder structure missing when using inline PO Spec (option 3)

  • Fixed CLAUDE.md PO Spec gate: listed 3 options but workflow has 4 — numbering mismatch caused "option 2" confusion (inline vs async intake)
  • Added CRITICAL reinforcement note at Step 5 entry: C4 Steps 4a-4g are MANDATORY for all PO Spec paths — no skipping system identification or flat file creation
  • Added Step 4d-VERIFY structural validation gate before guardian invocation: verifies system folders, component files, and descriptor files exist
  • Prevents flat docs/components/ layout bypassing the required C4 system subfolder structure
  • Added missing triggers: to architecture-component-guardian (was relying on description-only matching)
  • 11 trigger phrases for guardian: migrate components to C4, sync components, add component, etc.
  • Added component migration exclusion to architecture-docs "Do NOT activate" list

v3.3.20 (Previous Release) ✅

fix: C4 metadata missing from Section 5 template layers/tiers — all architecture types

  • All Section 5 templates now include **Type:** {C4 type}, **C4 Level:** Container (L2), **Deploys as:**, **Communicates via:** in every layer/tier template, not just Layer 1
  • Previously only the first layer had C4 metadata; subsequent layers used non-canonical type hints (e.g., Application Service, Scenario Orchestrator, BIAN Service Domain) requiring C4 migration afterward
  • Updated: SECTION_5_3TIER.md (Tier 2, Tier 3, all 3 examples), SECTION_5_META.md (Layers 2–6 + example), SECTION_5_BIAN.md (Layers 2–5 + 2 examples), SECTION_5_MICROSERVICES.md (infrastructure template + example)
  • Fixed stale references in ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md: flat component path (docs/components/NN-name.md → docs/components/<system-name>/NN-name.md) and column count (4-column → 5-column index)

v3.3.19 (Previous Release) ✅

fix: traceability triggers use "requirements" prefix to avoid peer-review/docs collision

  • Replaced ambiguous triggers (architecture deviation, deviation check) with requirements-prefixed phrases: requirements deviation, requirements coverage, PO spec deviation
  • Removes collision with peer-review skill ("architecture quality") and architecture-docs skill ("architecture validation")
  • Updated architecture-docs exclusion to reference "requirements deviation checks"

v3.3.18 (Previous Release) ✅

fix: traceability skill description + architecture-docs exclusion for deviation checks

  • Rewrote traceability skill description to lead with "deviation checks, traceability reports, PO Spec coverage" for stronger signal matching
  • Added "Do NOT activate for" section to architecture-docs SKILL.md redirecting deviation/traceability requests to the correct skill
  • Prevents architecture-docs from hijacking "architecture deviation check" via its broad "validating/checking" description match

v3.3.17 (Previous Release) ✅

fix: traceability skill trigger phrases expanded to prevent architecture-docs skill hijacking

  • Added 7 compound trigger phrases: architecture deviation, architecture deviation check, traceability report, traceability matrix, coverage check, PO spec vs architecture, check PO spec
  • Previously, "architecture deviation check" was captured by the broader architecture-docs skill instead of architecture-traceability

v3.3.16 (Previous Release) ✅

fix: traceability skill enforces PO Spec "what" vs architecture "how" boundary

  • Added PO Spec Scope Rule: evaluate business capabilities, not implementation paths
  • Requirement extraction now strips "how" details (technologies, integration paths) from PO Spec — keeps only business capability as traceable requirement
  • Architecture satisfying a requirement via a different path than PO expected is ✅ Covered (not a gap)
  • Only flags gaps when the business capability itself is missing from the architecture

v3.3.15 (Previous Release) ✅

feat: architecture-traceability skill — PO Spec use cases vs architecture coverage report

  • New architecture-traceability skill comparing PO Spec use cases against architecture documentation
  • Generates portable TRACEABILITY_REPORT.md — designed for tickets, emails, and external platforms
  • Per-use-case coverage tables with evidence citations (section + quote)
  • Summary statistics with per-phase breakdown and coverage percentages
  • Gap Report consolidating all Not Covered and Partial items with suggested architecture sections
  • Parses requirements from primary flows, alternative flows, edge cases, preconditions, postconditions, and success metrics

v3.3.14 (Previous Release) ✅

fix: suppress false-positive peer review finding on file prefix vs section number offset

  • Added explicit clarification to PEER_REVIEW_CRITERIA.md checks STRUCT-04, NAMING-02, and NAMING-05
  • Reviewer agents no longer flag the intentional two-number offset between docs/ file prefixes (01–10) and internal section numbers (S1–S12)
  • Offset is by design: S1+S2 share 01-system-overview.md, S5 uses docs/components/ (no numbered file)
  • Updated: PEER_REVIEW_CRITERIA.md (STRUCT-04, NAMING-02, NAMING-05 "What to Look For" columns)

v3.3.13 (Previous Release) ✅

fix: use case count is a complexity indicator, not a hard minimum

  • Reframed use case count across all architecture-readiness scoring and elicitation files
  • Previously enforced "minimum 3 use cases" as a hard constraint; now treated as architecture complexity signal
  • Simple systems may need 1-2 use cases, complex ones may need 5+ — no fixed minimum
  • Updated: PO_SPEC_SCORING_GUIDE.md (evaluation criteria, completeness scoring, gap analysis), REQUIREMENTS_ELICITATION_GUIDE.md (Phase 3 goal, target, phase transition), PRODUCT_OWNER_SPEC_GUIDE.md (scoring prep, self-assessment checklist), SKILL.md (Phase 3 description)

v3.3.12 (Previous Release) ✅

fix: NAMING-04 ADR file naming pattern false positive

  • Fixed peer review NAMING-04 check: pattern was NNN-kebab-case.md but correct ADR convention is ADR-NNN-kebab-case.md
  • Previously flagged valid ADR files (e.g., ADR-001-architecture-type-selection.md) as incorrectly named

v3.3.11 (Previous Release) ✅

perf: persist peer review results as JSON + fast-path playground regeneration

  • Review data now saved to architecture-peer-review-<date>.json after each run (Step 6.1)
  • New Step 0 fast path: "regenerate playground" reads saved JSON and skips agent evaluation entirely
  • Staleness detection: compares source file timestamps to warn if architecture changed since review
  • Enables instant playground regeneration without re-running 13 parallel agents (saves 40s-3min)
  • JSON schema matches the playground reviewData structure exactly — validated with test HTML

v3.3.10 (Previous Release) ✅

fix: clean up old compliance contracts before regeneration

  • Added Step 3.2.1 to compliance skill: deletes existing contracts for selected types before spawning generators, preventing stale dated files from accumulating
  • Previously, regenerating contracts on a different date left old files behind (e.g., both _2026-04-04.md and _2026-04-06.md coexisted)
  • Post-generation pipeline cleanup (Phase 4) retained as a safety net
  • Updated Regeneration Behavior documentation to reflect new pre-generation cleanup

v3.3.9 (Previous Release) ✅

perf: remove document panel from peer review playground

  • Eliminated the left-side document viewer from the peer review playground — findings already carry file + lineRef on each card, making full document embedding redundant
  • Removed doc_files from Step 7 embed list in SKILL.md — playground agent no longer reads and embeds all architecture files
  • Removed renderDocument(), findingForLine(), docContent state field, #doc-panel HTML element, and all associated CSS from PLAYGROUND_TEMPLATE.md
  • Layout simplified to single-column: scorecard → findings → prompt output
  • Runtime token savings: ~50-80K tokens per review (no more reading and embedding ~2,000 lines of architecture files as HTML)
  • Net: ~143 lines removed from PLAYGROUND_TEMPLATE.md

v3.3.8 (Previous Release) ✅

refactor: reduce peer review token usage — eliminate duplicated content across skill files

  • Replaced 13 near-identical Task() examples in SKILL.md with a concise loop instruction referencing the Scoring Weights table (~53 lines removed)
  • Removed Active Categories table and Rating Bands table from SKILL.md — both are now single references to PEER_REVIEW_CRITERIA.md as the source of truth
  • Removed per-finding category, categoryName, depthLevel fields from agent output schema — orchestrator injects them during merge (Step 5.2), eliminating ~3 redundant fields per finding × 30+ findings in HARD depth
  • Collapsed score formula in agent file to a reference to PEER_REVIEW_CRITERIA.md; removed duplicate "no findings" example (one sentence suffices)
  • Removed Pre-Populating section from PLAYGROUND_TEMPLATE.md (duplicated SKILL.md Step 7); collapsed 13-row hardcoded scorecard example to a 2-line comment
  • Net: 1,285 → 1,168 lines (−117 lines, ~11% reduction across the 4 skill files)

v3.3.7 (Previous Release) ✅

perf: eliminate redundant file reads in peer review playground generation

  • Removed orchestrator's Step 7 file-read/concatenation loop — no longer reads all architecture files between agent completion and playground spawn
  • Playground generator now receives doc_files (path list) and reads + concatenates once, replacing the previous triple-read pattern (agents → orchestrator → playground agent)
  • PLAYGROUND_TEMPLATE.md updated with explicit instruction: generator reads doc_files via Read tool and builds docContent itself
  • Eliminates ~100KB of redundant token usage per HARD depth review (~66% reduction in doc-related tokens)

v3.3.6 (Previous Release) ✅

fix: peer review playground syntax error + agent scorecard delegation

  • Fixed Uncaught SyntaxError: missing } in template string in generated playground HTML — root cause was nested template literals in PLAYGROUND_TEMPLATE.md renderDocument() function; extracted to local variables + added warning comment
  • Category agents now compute their own score (start 10.0, deduct per severity, floor 0.0) and return score + weight in CATEGORY_REVIEW_RESULT — orchestrator assembles scorecard directly without recalculation
  • Simplified SKILL.md Step 6: reads score/weight from agent results, applies renormalization, computes weighted average — no per-finding deduction logic in orchestrator

v3.3.5 (Previous Release) ✅

refactor: peer review category agents read files directly instead of receiving inline content

  • Category agents now receive a FILES: list of file paths and read them via the Read tool — no more full document text duplicated 13× in HARD depth prompts
  • SKILL.md Step 4 now resolves doc_files (ordered path list) instead of concatenating content; Step 7 handles concatenation for the playground docContent embed
  • peer-review-category-agent.md Step 2 updated: reads each file in FILES: using the Read tool, tracks per-file line numbers for accurate lineRef values

v3.3.4 (Previous Release) ✅

feat: parallel category agents for architecture peer review

  • New universal agents/peer-review-category-agent.md sub-agent — evaluates one review category's checks against architecture docs and returns a CATEGORY_REVIEW_RESULT JSON block
  • Peer review skill now fans out all active categories in a single parallel message (3 agents for Light, 7 for Medium, 13 for Hard)
  • Dramatic speed improvement: Light ~40s (was ~2 min), Medium ~90s (was ~5 min), Hard ~2-3 min (was ~10 min)
  • Added Step 5.2 (merge + renumber): collects all CATEGORY_REVIEW_RESULT blocks, merges findings, renumbers IDs globally, handles per-agent failures gracefully
  • Added Agent(sa-skills:peer-review-category-agent) to .claude/settings.json.example and CLAUDE.md permissions

v3.3.3 (Previous Release) ✅

fix: peer review playground layout for large finding counts

  • Added structural layout CSS to PLAYGROUND_TEMPLATE.md: viewport constraints, flex containers, panel scroll isolation
  • Document panel and findings panel now scroll independently — no more full-page scroll with 19+ findings
  • Filter bar (All/Pending/Approved/Rejected tabs + dropdowns) is now sticky at top of findings panel
  • Added explicit HTML structure reference (#app, #main, #doc-panel, #findings-filters, #findings-list, etc.) so generated playground uses correct IDs

v3.3.2 (Previous Release) ✅

fix: compliance-docs write permission glob pattern for subdirectories

  • Fixed .claude/settings.json permission glob: Write(compliance-docs/*) → Write(compliance-docs/**) to allow writing to subdirectories
  • Fixed README.md installation verification version (was stuck at v3.2.7)

v3.3.1 (Previous Release) ✅

fix: references file (docs/10-references.md) now included in downstream propagation

  • Added docs/10-references.md to cross-cutting files in Step 5.5 Downstream Documentation Propagation
  • S5 (Components), S8 (Tech Stack), S12 (ADRs) now list docs/10-references.md as downstream in Reverse Dependency Table
  • New propagation rule: ADR changes update ADR index table, technology changes update doc links, new terms update glossary
  • S12 ADR special rule now always syncs references after ADR file creation

v3.3.0 (Previous Release) ✅

feat: IcePanel C4 model sync skill (beta) + Section 12 ADR propagation fix

  • New architecture-icepanel-sync skill (beta): extracts C4 elements from architecture docs, generates IcePanel-compatible import YAML, checks IcePanel API for existing objects, and imports or reports drift
  • Three workflows: Full Sync (online/offline), Drift Report Only, YAML Export Only
  • Online mode uses IcePanel REST API (ICEPANEL_API_KEY + ICEPANEL_LANDSCAPE_ID) for check/import/drift detection
  • Offline mode generates icepanel-sync/c4-model.yaml for manual import via IcePanel UI
  • Includes ICEPANEL_IMPORT_REFERENCE.md with LandscapeImportData schema, type mapping, and tag conventions
  • Fix: Section 12 ADR table updates now trigger ADR file creation via /skill architecture-definition-record delegation
  • Added S12 to Reverse Dependency Table in architecture-docs skill

v3.2.10 (Previous Release) ✅

feat: theme-aware diagram generation — light/dark mode support for all Mermaid diagrams

  • Theme detection: asks user light/dark once, persists as <!-- DIAGRAM_THEME: light|dark --> in docs/03-architecture-layers.md
  • Dark mode C4/sequence diagrams: %%{init: {'theme': 'dark'}}%% init block prepended automatically
  • Dark classDef palettes for all 4 architecture types (META/BIAN, 3-Tier, N-Layer, Microservices) with WCAG AA contrast
  • Generation Workflow step 5.5 added for theme detection before diagram generation
  • Updated across 4 files: DIAGRAM-GENERATION-GUIDE, MERMAID_DIAGRAMS_GUIDE, SKILL.md, ARCHITECTURE_TYPE_SELECTION_WORKFLOW

v3.2.9 (Previous Release) ✅

feat: system-folder-aware component add with L1+L2 structure creation for external systems

  • Step 3a added: detects existing system folders and prompts user to select target system
  • New system creation workflow: asks Internal/External classification and creates L1 descriptor + L2 container folder
  • External system "explode" support: promotes external system references into full C4 L1+L2 hierarchy
  • Change Propagation Report now shows system context (new vs existing, Internal/External)
  • Flow C updated to reflect system selection and L1+L2 creation steps

v3.2.8 ✅

fix: mandatory diagram cascade on component add/remove — replace optional prompt with /skill architecture-docs delegation

  • Step 6e now mandatory: diagrams are regenerated automatically after add/remove operations (no Yes/No prompt)
  • Explicit /skill architecture-docs invocation with structured context block (component name, type, system, connections)
  • Post-generation verification: grep diagrams for component name to confirm it appears in C4 L2 and Detailed View
  • Fallback path if generation fails: PENDING marker + manual instructions (does not block component operation)
  • M8.3 (C4 migration) updated with same mandatory pattern
  • Step 6f Change Propagation Report now includes diagram update status row

v3.2.7 ✅

fix: delegate README.md creation to guardian skill during initial architecture creation

  • Step 4e now invokes architecture-component-guardian with sync instead of creating README.md directly
  • Fixes 6 format inconsistencies: title ("Component Details"), em dash comment, 5.N numbering, intro paragraph, Key Relationships section, Related Documentation section
  • Fallback to manual creation using guardian format spec when skill is unavailable

v3.2.6 ✅

feat: always nest C4 L2 containers in system folders — remove flat single-system exception

  • All architectures now use nested folder structure: docs/components/<system-name>/NN-component.md
  • Removed single-system flat layout exception — system descriptor file and folder always created
  • README.md component index always uses grouped tables with ### System Name headers
  • Updated across 5 files: workflow, guardian, C4 migration reference, restructuring guide, README

v3.2.5 (Previous Release) ✅

feat: ADR Context Block — pre-identify decisions from PO Spec and propagate through creation

  • New Step 0.5 in Workflow 1: derives ADR candidate list from PO Spec analysis (Sections 1, 3, 4, 7) before architecture design begins
  • ADR Context Block maintained through all creation steps — decisions tracked from PENDING to DECIDED with rationale
  • Step 2 (architecture type selection) resolves first ADR candidate automatically
  • Step 5 (section creation) references the block for consistency across principles, tech stack, security, and ADR table
  • Step 6 (ADR generation) passes enriched context with drivers, decisions, and rationale to the ADR skill

v3.2.4 (Previous Release) ✅

feat: pure C4 grouping for Level 2 Container diagram — no architecture-specific layers

  • C4 L2 Container diagram now groups by C4 element type (Container(), ContainerDb(), ContainerQueue()) instead of architecture-specific layers/tiers
  • Architecture Type Adaptation table scoped to Diagrams 1 and 4 only — C4 diagrams use pure C4 conventions
  • All 5 C4 translation files updated (META, BIAN, 3-Tier, N-Layer, Microservices) to enforce pure C4 grouping at L2
  • Layer/tier visual grouping explicitly directed to Logical View (Diagram 1) and Detailed View (Diagram 4)

v3.2.3 (Previous Release) ✅

fix: dynamic principle count in Section 3 header — 9 or 10 based on content

  • Section 3 heading now reflects actual principle count: "(9 Core Principles)" or "(10 Core Principles)" when optional Decouple Through Events is included
  • Document Header Rule added to ARCHITECTURE_DOCUMENTATION_GUIDE.md template
  • Validation checklist updated to verify heading matches principle count
  • Creation workflow enforcement block includes header rule

v3.2.2 (Previous Release) ✅

fix: enforce Section 3 (Architecture Principles) 9-principle template across all paths

  • Creation workflow (Workflow 1) now explicitly enforces the mandatory 9-principle template with exact order, three subsections (Description/Implementation/Trade-offs), and validation checklist reference
  • Migration workflow (Workflow 9) now validates Section 3 against the template during extraction, with update workflow for non-standard source documents
  • Universal enforcement gate added to SKILL.md for any write to docs/02-architecture-principles.md — creation, migration, or edit

v3.2.1 (Previous Release) ✅

fix: recommended VS Code setup — Mermaid Chart extension replaces Office Viewer

  • Removed Office Viewer from recommended extensions
  • Replaced Mermaid Preview with Mermaid Chart (official extension from Mermaid.js creators, v11.4.1)
  • Recommended setup simplified to 2 extensions: Claude Code + Mermaid Chart

v3.2.0 (Previous Release) ✅

feat: Mermaid v11.4.1 target — native C4 diagrams + classic sequenceDiagram

  • All generated Mermaid diagrams now target Mermaid v11.4.1 (Mermaid Chart VS Code extension 2.1.0+)
  • Data flow diagrams reverted from ZenUML to Mermaid sequenceDiagram with full modern syntax (-) async, par/and/end, critical/break)
  • C4 Level 1 uses native C4Context with Person(), System(), System_Ext(), Rel()
  • C4 Level 2 uses native C4Container with Container(), ContainerDb(), ContainerQueue(), Container_Boundary()
  • Diagrams 1 (Logical View) and 4 (Detailed View) remain graph TB with classDef styling
  • DIAGRAM-GENERATION-GUIDE.md updated with complete syntax references, templates, and compatibility rules for v11
  • All secondary files updated: SKILL.md, ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md, MERMAID_DIAGRAMS_GUIDE.md

v3.1.6 (Previous Release) ✅

feat: data flow diagrams migrated to ZenUML syntax

  • Data flow diagrams used Mermaid ZenUML syntax (reverted in v3.2.0)

v3.1.5 ✅

feat: multi-architecture diagram generation guide — 4 standard diagrams for all 5 architecture types

  • New references/DIAGRAM-GENERATION-GUIDE.md defining 4 standard architecture diagrams: Logical View (ASCII), C4 L1 System Context, C4 L2 Container, and Detailed View (Mermaid)
  • Architecture Type Adaptation table maps grouping, naming, and color conventions for META, BIAN, 3-Tier, N-Layer, and Microservices
  • C4 L1 translation table per architecture type (what collapses into Internal System vs External)
  • Diagram 4 color convention tables per architecture type
  • Mermaid 8.x compatibility rules (DO/DON'T) and generation workflow algorithm
  • Workflow 8 now references DIAGRAM-GENERATION-GUIDE (primary) + MERMAID_DIAGRAMS_GUIDE (authoring)
  • Step 7 in Architecture Type Selection generates all 4 diagrams + data flow sequences
  • CLAUDE.md Diagram Enforcement Policy updated to list 4 mandatory standard diagrams

v3.1.4 (Previous Release) ✅

feat: dev handoff enforces C4 L2-only gate — no Level 1 components processed

  • Dev handoff skill now explicitly scoped to C4 Level 2 (Container) components only
  • Two-layer filter in Step 1.3: file naming heuristic + **C4 Level:** metadata check
  • C4 Level Validation Gate in Step 2.1: rejects System (L1) components with clear warning message
  • Missing **C4 Level:** metadata triggers a warning but proceeds (assumes L2)
  • If all selected components are L1, skill stops before Phase 3
  • SECTION_EXTRACTION_GUIDE.md updated with C4 L2 scope note
  • CLAUDE.md dev-handoff description updated to reflect L2-only scope

v3.1.3 (Previous Release) ✅

feat: C4 L1 system descriptor files + cross-skill impact fixes

  • Multi-system architectures now create C4 L1 system descriptor files at docs/components/ root ({system-name}.md) alongside system subfolders
  • System files contain: C4 Level (System L1), Type (Internal/External), Owner, Containers table, System Boundaries, Communication patterns
  • README.md system headers now link to system files: ### [System Name](https://github.com/shadowX4fox/solutions-architect-skills/blob/HEAD/system-name.md)
  • Guardian scan distinguishes NN-*.md (L2 containers) from {name}.md (L1 system descriptors)
  • Migration workflow Phase M4.1b creates system files automatically
  • Dev handoff excludes system descriptor files from handoff targets
  • Peer review NAMING-03 recognizes both L1 (no NN- prefix) and L2 (NN- prefix) naming patterns

v3.1.2 (Previous Release) ✅

feat: guardian loads architecture-type C4 translation on every invocation

  • Component guardian now detects <!-- ARCHITECTURE_TYPE: --> from docs/03-architecture-layers.md on every operation (sync, add, migrate)
  • Loads the matching C4 translation guide ({TYPE}-TO-C4-TRANSLATION.md) to apply type-specific container rules
  • Type-specific validation: flags components that violate the translation guide (e.g., "Service Layer" in 3-Tier = C3, not a valid C2 component)
  • Graceful fallback: if no architecture type detected, uses generic C4 L2 rules only

v3.1.1 (Previous Release) ✅

feat: C4 migration workflow + guardian governance cleanup

  • Added migrate operation to component guardian — 8-phase automated workflow converting flat docs/components/ to C4 multi-system structure (detect → classify → fix metadata → move files → update references → regenerate README → update ARCHITECTURE.md → verify)
  • Supports both git repos (git mv) and non-git folders (Read → Write → delete)
  • C4-MIGRATION-REFERENCE.md — type mapping table (28 entries), ownership heuristics, cross-reference impact map, edge cases from live migration session
  • C4 Model Governance section cleaned — removed redundancies with ICEPANEL-C4-MODEL.md, kept only guardian-specific enforcement rules (canonical types table, ambiguous cases)
  • Removed unsupported triggers frontmatter from component guardian

v3.1.0 (Previous Release) ✅

feat: C4 model integration, architecture reference docs, multi-system components, async intake reorder

  • C4 Model Integration: Components follow C4 L2 (Container diagram) — boundary test, App/Store classification, IcePanel bracket convention for technology
  • 11 architecture reference docs in references/: C4 model + 5 architecture rules + 5 C4 translation guides (Microservices, 3-Tier, N-Layer, META, BIAN)
  • C4 component structure: C4 L1 systems → folders under docs/components/, C4 L2 containers → component files nested in system folders (all architectures)
  • 5-column component index: #, Component, File, Type, Technology with grouped system headers
  • C4 metadata header on all component templates: Type, Technology [in brackets], C4 Level, Deploys as, Communicates via
  • Architecture type selection reordered: Industry Standard (1-3) first, Enterprise (4-5) after, with STANDARD/ENTERPRISE/BANKING tags
  • Reference doc gate: Types without both reference docs are greyed out and cannot be selected
  • Component guardian governed by ICEPANEL-C4-MODEL.md — enforces C4 boundary test and canonical types
  • Async intake reordered to flow #1 in readiness skill with email-ready gap report output
  • Canonical ADR template rule enforced across all write workflows (1, 2, 4) with explicit gate checks
  • Validator personalities moved from generators to validators; validators load domain config at runtime
  • Cross-skill compatibility: handoff, peer review, ADR, docs-export all updated for 5-column index + system subfolders

v3.0.2 (Previous Release) ✅

fix: align validator names, enforce canonical ADR template, async intake isolation + email-ready output

  • Validator spawn descriptions now use full codename + domain format (e.g., Aegis — Business Continuity Validator)
  • Config agent_description fields aligned with validator frontmatter (single source of truth)
  • Removed Glob from validator tools — prevents wildcard permission prompts
  • ADR canonical template rule enforced across all workflows (Workflows 1, 2, 4) with explicit gate checks
  • Async intake reordered to flow #1 in readiness skill, with ⛔ NEVER transitions to elicitation isolation rule
  • PO Spec menu reordered: (1) Elicitation, (2) Async intake, (3) Inline context, (4) Skip
  • Added Ready-to-Send Message template to async intake gap report — email/ticket-ready copyable block

v3.0.1 (Previous Release) ✅

docs: update README Phase 3 with v3.0.0 architecture — two-phase diagram, CC-004 sequence flow

  • Rewrote Phase 3 Compliance Documentation section for the universal generator architecture
  • Added two-phase parallel execution diagram (validators → universal generator ×10)
  • Added CC-004 Development example sequence showing EOL-first WebSearch flow
  • Contract types table now includes Validator codename column
  • Documented key principles: validators own personality, generator is pure template-filler, EOL is blocking

v3.0.0 (Previous Release) ✅

major: universal compliance generator — 10 agents consolidated to 1 + config-driven validators

  • Replaced 10 domain-specific generator agents with a single agents/compliance-generator.md that reads domain config at runtime
  • Personality, key data points, focus areas, and agent notes moved from generators to validators — generators are pure template-fillers
  • Validators read their domain config (agents/base/configs/*.json) at startup for extensibility
  • Removed build system (scripts/build-agents.ts, agents/base/AGENT_BASE.md, agents/base/sections/, agents/base/overrides/) — no longer needed
  • Removed Glob from validator tools (caused wildcard permission prompts)
  • Simplified permissions: 10 generator Agent rules → 1 (compliance-generator)
  • Cleaned redundant validation_agent/validation_agent_name fields from configs
  • Architecture: Orchestrator → 10 validators (parallel, with personality + EOL) → 1 universal generator ×10 (parallel, config-driven)

v2.16.1 (Previous Release) ✅

fix: clean up agent permissions — remove unused Bash commands, align CLAUDE.md with settings.json.example

  • Removed unused Bash permissions (ls, cat, cp, grep, python3) — agents self-constrain via TOOL DISCIPLINE
  • Added 10 validator Agent permissions and WebSearch to CLAUDE.md permissions block
  • Verified all 20 agent references (SKILL.md → agent names → permissions) are in sync

v2.16.0 (Previous Release) ✅

refactor: standardized External Validation Summary across all 10 contracts + generators folder

  • All 10 compliance templates now have a consistent ## External Validation Summary section (table with Status, Validator, Date, Items, Result + Deviations + Recommendations)
  • Step 4.6 (Populate External Validation Summary) moved from development-only override into the base template — all agents now have it
  • Development-specific overrides removed (development-step46.md, development-validation-summary.md) — no longer needed
  • Generated agents moved to agents/generators/ for clean separation from agents/validators/ and agents/base/
  • Validator name parameterized per domain (e.g., Atlas Validator (cloud-validator), Prometheus Validator (sre-validator))

v2.15.1 (Previous Release) ✅

fix: add WebSearch permission to settings.json.example for validator EOL checks

  • Added WebSearch to the permissions allow list in .claude/settings.json.example

v2.15.0 (Previous Release) ✅

refactor: orchestrator-spawned validators — validators run before generators with results passed via prompt

  • Validators are now spawned by the orchestrator (SKILL.md Step 3.3) in parallel, before generators
  • Each validator's VALIDATION_RESULT is collected and passed into its generator's prompt (Step 3.4)
  • Generators no longer attempt nested sub-agent spawning — they parse the pre-provided VALIDATION_RESULT
  • Fixes EOL detection failure: validators now run at orchestrator level with full WebSearch access
  • Architecture: Orchestrator → 10 validators (parallel) → collect results → 10 generators (parallel, with results)

v2.14.4 (Previous Release) ✅

fix: harden EOL enforcement — WebSearch in tools, context7 forbidden for EOL, Spring Boot 3.2 example

  • Added WebSearch to development validator tools frontmatter (was missing — agent couldn't invoke it)
  • Explicitly forbids context7 for EOL checks in 3 locations — context7 provides docs, not lifecycle data
  • Spring Boot 3.2 EOL example in mission section as concrete FAIL reference
  • Phase 1 marked ⛔ DO NOT SKIP with non-negotiable ordering enforcement

v2.14.3 (Previous Release) ✅

fix: EOL-first validation — Phase 1 gathers EOL data before any stack checks

  • Restructured development validator: Phase 1 now builds an EOL lookup table via WebSearch BEFORE Phase 2 evaluates the 26 stack items
  • 6-month safety period: versions within 6 months of EOL are treated as FAIL, not just past-EOL
  • Version-bearing items (1, 2, 7, 8, 13, 19-23) consult the EOL table — approved + EOL = FAIL regardless of catalog status
  • Evidence now includes EOL dates: "Spring Boot 3.2 — approved but EOL since 2024-12-31 — endoflife.date"
  • Glob permission for marketplace directory added to settings.json.example

v2.14.2 (Previous Release) ✅

fix: EOL checks integrated into Phase 1 version items — approved does not mean supported

  • Version-bearing validation items (1, 2, 7, 8, 13, 19, 20, 21, 22, 23) now verify EOL status via WebSearch as part of PASS/FAIL criteria — a technology on the approved list but past end-of-support is marked FAIL
  • Evidence includes both facts: "Spring Boot 3.2 is in approved list but EOL since 2024-12-31 — endoflife.date"
  • Phase 2 simplified to supplementary catch-all for technologies not covered by the 26 standard items
  • Compact VALIDATION_RESULT format maintained across all 10 validators

v2.14.1 (Previous Release) ✅

feat: development validator as sole validation point + EOL checks + compact VALIDATION_RESULT

  • Development validator is now the single source of truth for stack validation — Step 4.6 override no longer duplicates criteria, only maps VALIDATION_RESULT to template placeholders
  • Added Phase 2: EOL Validation to development validator — uses WebSearch to check technology version lifecycle status against endoflife.date and vendor documentation
  • EOL items (DEV-EOL-*) are supplementary: PASS (supported), FAIL (EOL), UNKNOWN (no info); included in deviations/recommendations
  • Compact VALIDATION_RESULT format across all 10 validators — single-line summary + pipe-delimited items table replaces verbose per-item YAML blocks
  • Graceful degradation when WebSearch is unavailable — Phase 2 silently skipped

v2.14.0 (Previous Release) ✅

refactor: compliance contract naming — CC-prefixed kebab-case with numbered types

  • Renamed all compliance contracts to CC-NNN-{type} convention: templates, output files, validation configs, and type identifiers
  • Template files: TEMPLATE_BUSINESS_CONTINUITY.md → cc-001-business-continuity.template.md (10 templates)
  • Output files: BUSINESS_CONTINUITY_Project_Date.md → CC-001-business-continuity_Project_Date.md
  • Fixed numbering: CC-001 (Business Continuity) through CC-010 (SRE Architecture)
  • Updated all TypeScript registries, validation schemas (20 files), utility CLIs, tests (334 pass), and documentation references

v2.13.0 (Previous Release) ✅

refactor: compliance agent build system — base template + domain configs + 10 validation agents

  • Refactored 10 compliance agents (~85% shared boilerplate) into a build-time generation system: agents/base/AGENT_BASE.md + 9 shared sections + 10 domain config JSONs → 10 generated agent .md files via bun run build:agents
  • Added 10 new validation agents (agents/validators/) — one per compliance domain — that perform external standard checks (stack validation, security controls, SRE readiness, etc.)
  • Each compliance agent now invokes its domain validator in Step 3.4 before populating the template
  • Build script (scripts/build-agents.ts) handles {{variable}} substitution, @foreach/@if directives, section injection, and domain-specific overrides
  • Integrated into bun run build pipeline; generated files marked linguist-generated via .gitattributes

v2.12.12 (Previous Release) ✅

feat: dependency-based ordering for batch dev handoff generation

  • Added Step 2.2 to architecture-dev-handoff: when generating multiple handoffs, components are sorted ascending by inter-component dependency count (least → most)
  • Ensures foundational components are generated first so heavily-dependent components can cross-reference upstream handoffs for consistency

v2.12.11 (Previous Release) ✅

docs: add context7 MCP integration guide to README

  • Added context7 to "What's Included" feature list as optional MCP integration
  • New "Optional: Enable context7" section in Quick Start with MCP server JSON config (recommended), CLI setup, and headless alternative
  • Documented which skills use context7 (architecture-dev-handoff, architecture-docs) with usage table
  • Fixed stale installation verification version

v2.12.10 (Previous Release) ✅

docs: merge propagation gates — unified ADR and downstream propagation node in workflow diagram

  • Merged {Propagation} (ADR status change) and {Downstream Propagation} (section edit) diamond nodes into a single {Propagation} gate in the Workflow Integration diagram
  • Both triggers — Status Change from ADRs and Section Edit from ARCHITECTURE.md — now feed into one propagation gate with unified Updates outputs to ARCHITECTURE.md and Dev Handoffs

v2.12.9 (Previous Release) ✅

feat: asset regeneration advisory in downstream propagation workflows

  • Added Phase 5: Asset Regeneration Advisory after Phase 4 Propagation Report in both architecture-docs (Step 5.5) and architecture-definition-record (Workflows 3 & 4)
  • After propagation completes, scans fact-deltas for asset-impact keywords (API, database, Redis, deployment, Kafka, Avro, Protobuf, cron) and cross-references against actual asset files in handoffs/assets/
  • When stale assets are detected, displays advisory listing affected components and asset types, then asks the user whether to re-run /skill architecture-dev-handoff
  • Skips silently when no handoffs were affected or no asset-impact keywords match; also fires on propagation skip to warn that both text and assets may be stale

v2.12.8 (Previous Release) ✅

feat: context7 MCP integration for asset generation and component documentation

  • architecture-dev-handoff: added Step 3.3b (Spec Documentation Lookup) — fetches current spec docs via context7 (resolve-library-id + get-library-docs) for each asset type before generation; caches per session
  • ASSET_GENERATION_GUIDE.md: new "Spec Documentation Integration (context7)" section with asset→library mapping table; per-asset context7 validation callouts for all 8 asset types (OpenAPI, DDL, Kubernetes Deployment, AsyncAPI, CronJob, Avro, Protobuf, Redis)
  • architecture-docs: new "Technology Context Enrichment (context7)" subsection — fetches framework docs during Workflow 1 component creation and presents advisory Technology Context Brief (never auto-fills)
  • All 4 Section 5 templates: HTML comment hint on **Technology**: field directing Claude to use context7 advisory lookup
  • CLAUDE.md: documented context7 as an optional MCP dependency with graceful degradation
  • Syntax/structure only — "no invention" / Asset Fidelity Rule unchanged; all data values still come exclusively from architecture docs

v2.12.7 (Previous Release) ✅

feat: architecture-docs downstream propagation — cascade updates to dependent sections, components, and handoffs after any substantive section edit

  • Added Step 5.5 to the architecture-docs editing workflow: Downstream Documentation Propagation
  • Embedded reverse dependency table mapping each section to its structurally-dependent downstream files
  • 4-phase propagation: fact-delta extraction → user-approval checklist → tier-ordered Context Anchor updates → completion report
  • Cross-cutting scan always covers docs/components/ and handoffs/ regardless of section tier
  • Cosmetic edit heuristic skips propagation silently for formatting/typo changes
  • Anti-recursion rule: propagation edits do not re-trigger propagation
  • Component file edits cascade through S5's full dependency row + always include matching handoff doc

v2.12.6 (Previous Release) ✅

feat: ADR change propagation — downstream documentation impact tracking and execution

When an ADR is updated (status change) or superseded (Workflow 3/4), the architecture-definition-record skill now runs a 4-phase Documentation Impact Propagation step. Phase 1 (Impact Discovery): greps all docs/, docs/components/, and handoffs/ for explicit ADR citations, applies a keyword-to-file topic mapping table to find conceptually-affected files without explicit citations, and extracts concrete fact changes from the ADR content. Phase 2 (Checklist): presents a "Documentation Updates Required" checklist grouped by file type (Architecture Docs / Component Files / Handoff Docs) — each entry states what needs updating and why; user approves all or deselects items for manual handling. Phase 3 (Execute): applies each approved update following the architecture-docs Context Anchor Protocol (load foundation + section-specific parents + changed ADR, update citations and derived facts, run 5-check Post-Write Audit); handoff updates follow the dev-handoff Documentation Fidelity Policy. If user skips, adds <!-- PROPAGATION PENDING --> marker to the ADR file. Phase 4 (Report): completion report with [x] completed / [ ] deselected / ⚠️ failed items. For supersede: also migrates per [ADR-old] citations to per [ADR-new] across all docs and updates ARCHITECTURE.md Section 12 table. Integration table and Success Criteria updated.

v2.12.5 (Previous Release) ✅

feat: focus mode filters sidebar to connected nodes for scoped knowledge cycling and learning prompts

When a node is clicked (focus mode), the sidebar node list now filters to show only the focused node and its direct connections — with a header showing "Exploring: [node name] (N nodes)" and a "Show All" button to exit. The focused node appears bold in accent color. Knowledge cycling (Know/Fuzzy/Unknown) works within this filtered scope, so users can mark what they know about just the connected concepts. The learning prompt also scopes to the focused subset: only edges and nodes touching the focused node are included, and the prompt opens with "I'm currently exploring: [node name] and its N direct connections." Clicking empty canvas or "Show All" restores the full node list and global prompt.

v2.12.4 (Previous Release) ✅

feat: concept map node focus mode — click to highlight connections, dim unrelated nodes

Clicking a node in the onboarding concept map now enters focus mode: the clicked node and all directly connected nodes stay at full opacity while every unrelated node dims to 12% and unrelated edges dim to 6%. Clicking the same node again or clicking empty canvas clears focus and restores full rendering. Implementation: added focusedNode state variable; updated draw() to build a connectedIds set (node + both-direction edge neighbors) and pass it to drawNode()/drawEdge(); updated drawNode() to apply alpha=0.12 for dimmed nodes; updated drawEdge() to apply globalAlpha=0.06 for dimmed edges and 0.04 for their labels; updated mouseup to toggle focus on click-without-drag; updated mousedown to clear focus when clicking empty canvas. Drag behavior is unchanged — focus only triggers on click (mousedown + mouseup with no movement).

v2.12.3 (Previous Release) ✅

fix: enforce lowercase kebab-case naming convention for component files across all skills

Component file names under docs/components/ must follow NN-kebab-case-name.md (e.g., 01-api-gateway.md, 02-payment-service.md) — lowercase, hyphens only, no spaces, no uppercase, no underscores. This was defined in RESTRUCTURING_GUIDE.md but not enforced downstream. Fixed in 4 skills: (1) architecture-component-guardian — added naming validation on scan with auto-rename offer for violations, and kebab-case conversion on add component; (2) architecture-peer-review NAMING-03 check — now explicitly requires NN-kebab-case-name.md with examples (was ambiguous NN-component-name.md); (3) architecture-docs SKILL.md — added component file examples alongside section file examples in naming convention; (4) architecture-dev-handoff — stated that handoff filenames derive from component file names using kebab-case.

v2.12.2 (Previous Release) ✅

fix: ADR generation uses full template with populated body sections, not abbreviated stubs

When ADRs are generated from the ARCHITECTURE.md Section 12 table (Workflow 1 in architecture-definition-record), all 10 template sections are now populated from architecture documentation context — not just the metadata placeholders. Root cause: Step 1.5 only instructed replacing ADR number, title, status, date, and authors, leaving Context, Decision, Rationale, Consequences, and Alternatives empty for the user to fill in later. Fixed by rewriting Step 1.5 with: (1) a keyword-based topic-to-docs mapping table that identifies which docs/ files are relevant per ADR title, (2) a section-by-section population guide mapping every template section to its architecture doc source, (3) an explicit "CRITICAL: use the full canonical template — do NOT produce abbreviated stubs" directive. Comparison tables must use real data (not placeholder rows). Only Implementation Plan and Success Metrics remain as optional stubs. Step 1.6 summary now says "review and refine" instead of "fill in Context, Decision, and Rationale". Step 6 delegation in ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md also updated to explicitly pass the full-template instruction to the ADR skill.

v2.12.1 (Previous Release) ✅

fix: concept map auto-layout — rectangle-aware repulsion, band gravity, and overlap resolution

Rewrote autoLayout() in the architecture-onboarding PLAYGROUND_TEMPLATE.md to eliminate node overlap. Three root causes fixed: (1) Rectangle-aware collision — replaced point-based REPULSION/dist² with bounding-box overlap detection; overlapping nodes are pushed apart along the axis of minimum penetration (push strength 0.55× overlap), while non-overlapping nodes use mild long-range repulsion (3000/dist²). (2) Band gravity — added a Y-axis restoring force (BAND_GRAVITY=0.3) per iteration that pulls each node back toward its group's proportional lane (15%/45%/80% of canvas height), preserving the Use Cases → Sections → Components traceability spine through the simulation. (3) Weaker edge attraction — reduced ATTRACTION from 0.04 → 0.02 and cross-group edges (traces-to, served-by) to 0.01 so band gravity and repulsion win locally. Also shortened REST_LEN 180→120, increased max iterations 200→300, and added early exit when kinetic energy drops below 0.1. initializePositions() band centers updated to proportional values (H×0.15/0.45/0.80) matching the simulation.

v2.12.0 (Previous Release) ✅

feat: new architecture-definition-record skill — single owner of all ADR write operations

Extracted ADR handling from architecture-docs into a dedicated architecture-definition-record skill (9th skill). The new skill owns five workflows: generate ADR files from ARCHITECTURE.md Section 12 table, create individual ADRs interactively (guided interview), update ADR status (Proposed → Accepted / Deprecated / Rejected), supersede an ADR (creates new + marks old as superseded), and list/audit the ADR inventory. All other skills now delegate write operations here while retaining direct read access to adr/*.md. Moved ADR_GUIDE.md and ADR-000-template.md into the new skill directory. Removed ~500-line Step 6 implementation from ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md, replaced with a single delegation instruction. Updated CLAUDE.md, README.md, and 4 other skills with delegation notes.

v2.11.2 (Previous Release) ✅

feat: use case traceability in onboarding concept map; focus on UC → Sections → Components spine

Redesigned the architecture-onboarding concept map around a business-to-technical traceability spine. Adds a Use Cases node group (pink) extracted from PO Spec Section 4 or docs/01-system-overview.md Section 2.3 — placed at the top band, tracing down through Architecture Sections (middle) to Components (bottom). New edge types: traces-to (UC → section, dashed pink) and served-by (UC → component, from handoff docs' Business Context field). Removed lifecycle, compliance, principles, and skill groups entirely — they don't add value to onboarding exploration. Concept map now contains exactly 3 node groups and 3 presets (Use Case Traceability, Section Dependencies, Component Map). Default preset is "Use Case Traceability".

v2.11.1 (Previous Release) ✅

fix: complete concept map rendering — full JS implementation in PLAYGROUND_TEMPLATE.md

Rewrote PLAYGROUND_TEMPLATE.md for the architecture-onboarding skill to include complete, verbatim JavaScript implementations for all canvas rendering functions. Previously, key functions (initializePositions, autoLayout, drawEdge, drag handlers, tooltip) had elided // ... bodies that the playground plugin could not fill in — causing most nodes to render at undefined positions (invisible). All functions are now fully specified: grid-based initial node placement per group band, force-directed auto-layout with pairwise repulsion + edge attraction, full Canvas 2D arrowhead drawing, bounding-box drag, and absolute-positioned tooltips.

v2.11.0 (Previous Release) ✅

feat: new architecture-onboarding skill with interactive concept map playground; rename architecture-doc-export → architecture-docs-export

New architecture-onboarding skill — generates a canvas-based interactive concept map via the playground plugin for onboarding new team members. Draggable nodes represent lifecycle phases (5), architecture sections S1-S12, components, compliance contracts (10 slots), required principles (9), and available skills (9) — connected by dependency, workflow, and validation edges. Users cycle knowledge levels per node (Know/Fuzzy/Unknown) and copy a targeted learning prompt. Includes 6 preset views (Full Map, Lifecycle Flow, Section Dependencies, Component Map, Compliance Coverage, Principles View), ghost nodes for missing artifacts, and force-directed auto-layout. Also renamed architecture-doc-export to architecture-docs-export for consistency across all references.

v2.10.39 (Previous Release) ✅

fix: remove dead instruction blocks from generated compliance contracts — wrap compliance-score-calculation fragment in internal tags; remove duplicate Dynamic Field Instructions from Development template

Two agent-guidance blocks were appearing verbatim in generated contracts: (1) **CRITICAL - Compliance Score Calculation** from shared/fragments/compliance-score-calculation.md — included in all 9 non-SRE templates but not wrapped in <!-- BEGIN_INTERNAL_INSTRUCTIONS --> tags, so --strip-internal never removed it. Fixed by wrapping the fragment content. (2) **Dynamic Field Instructions**: [VALIDATION_SUMMARY]... inline block in TEMPLATE_DEVELOPMENT_ARCHITECTURE.md — a duplicate of the already-properly-wrapped dynamic-field-instructions.md include. Removed the inline duplicate and moved [VALIDATION_SUMMARY] replacement rule into the development agent instead.

v2.10.38 (Previous Release) ✅

fix: add Glob permission for plugin_dir resolution to settings.json.example and CLAUDE.md

Added "Glob(**/skills/architecture-compliance/SKILL.md)" to the permissions allow list in both .claude/settings.json.example and CLAUDE.md. This prevents approval prompts when agents run the Glob to resolve plugin_dir in marketplace installations.

v2.10.37 (Previous Release) ✅

fix: plugin_dir Glob pattern now works for marketplace installations — remove hardcoded repo name from path

The Glob pattern used to resolve plugin_dir was **/solutions-architect-skills/skills/architecture-compliance/SKILL.md, which hardcodes the repo name and only matches the dev directory structure. When running as an installed plugin, the marketplace directory is named shadowx4fox-solution-architect-marketplace/ (not solutions-architect-skills/), so the Glob failed and agents fell back to a wrong path that appended solutions-architect-skills/ as a subdirectory — producing Module not found errors on every compliance contract run. Fixed in skills/architecture-compliance/SKILL.md (orchestrator) and all 10 agent files by changing the pattern to **/skills/architecture-compliance/SKILL.md, which matches both dev and marketplace paths correctly.

v2.10.36 (Previous Release) ✅

fix: Responsible Role always populated — BC/SRE templates now use category-specific roles; all agents forbidden from defaulting to N/A

Business Continuity and SRE compliance contracts were generating N/A in the Responsible Role column because both templates used a generic [Role or N/A] placeholder with no role hint, and all 10 agent instructions permitted defaulting to N/A. Fix: (1) BC template now maps roles by category — BC-GEN → Solution Architect, BC-DR/BC-RTO → Business Continuity Manager, BC-BACKUP → Infrastructure Architect, BC-AUTO → Platform Engineer, BC-CLOUD → Cloud Architect — across all 86 occurrences (summary table + detailed sections). (2) SRE template table rows now use Practice/Observability → SRE Lead, Automation → Platform Engineer; detailed section entries cleaned up from SRE Engineer or N/A to plain SRE Engineer. (3) All 10 agent instructions updated: role placeholders must resolve to the template-specified role name; N/A is only permitted when Status = "Not Applicable".

v2.10.35 (Previous Release) ✅

fix: auto-populate [NEXT_REVIEW_DATE] as generation date +6 months; fix Section 1.6 stack validation placeholders left unreplaced in Development contract

Two fixes in one release: (1) [NEXT_REVIEW_DATE] in the Document Control table was never replaced — added getNextReviewDate() to date-utils.ts and wired it into field-updater.ts so it computes generation date + 6 months with correct month-end clamping. (2) Development contract Section 1.6 "Stack Validation Checklist" had ~30 unreplaced placeholders ([JAVA_ITEM_1]–[JAVA_ITEM_6], [DOTNET_*], [FRONTEND_*], [OTHER_STACKS_*], [EXCEPTIONS_*], [TOTAL_ITEMS], etc.) — removed the dead "Dynamic Field Mapping Instructions" block from the template and added Step 4.6 to the development agent with full 26-item evaluation criteria (Java, .NET, Frontend, Other Stacks, Exceptions). Added 6 new tests for getNextReviewDate and [NEXT_REVIEW_DATE] field-updater replacement.

v2.10.34 (Previous Release) ✅

fix: shorten Compliance Summary table Requirement columns in Business Continuity and SRE templates to use section titles instead of full descriptions; simplify SRE Category column to prefix-only (Practice/Observability/Automation)

Aligns the two remaining outlier templates (Business Continuity: 43 rows, SRE: 57 rows) with the short-title pattern already used by the other 8 compliance templates. BC Requirement column now uses H2 section titles (e.g., "Application or Initiative Name" instead of the full question). SRE Requirement column uses H2 section titles and Category column simplified from "Practice - Log Management" to just "Practice".

v2.10.33 (Previous Release) ✅

feat: standardize Questions & Gaps Register across all 10 compliance contracts; add Word export for compliance contracts; fix TypeScript errors; expand test coverage

Replaces three inconsistent post-appendix gap sections (5-col "Missing Data", 3-col "Not Applicable", 4-col "Unknown Status") with a single unified ## Questions & Gaps Register (8 columns: Code | Requirement | Type | Status | Owner | ARCHITECTURE.md Section | Action Required | Priority) populated automatically by the post-generation pipeline. New questions-register-populator.ts derives priority (Critical/High/Medium/Low) and action text from the domain validation JSON — agents are explicitly forbidden from populating it. Added compliance doc type to generate-doc.js (purple #7B2D8E) with yellow-highlighted editable cells (Owner, Action Required, Priority) and status-conditional coloring in the Compliance Summary table. Added full Workflow C to architecture-docs-export/SKILL.md for exporting compliance contracts to Word. Fixed inline A.2 schema violations in Development and Integration templates (now use shared @include-with-config). Fixed 2 pre-existing TypeScript errors. Added 78 new tests across 4 new test files (questions-register-populator, manifest-generator, resolve-includes, contract-types). Deleted 3 deprecated shared section templates.

v2.10.28 ✅

feat: enforce internal section numbers (S1-S12) across all skills and agents; add supplementary context file intake to architecture creation

Adds explicit S1-S12 section number disambiguation throughout all architecture skills and compliance agents — file prefix numbers (01-10) now never conflate with internal section numbers (S9 = docs/07-security-architecture.md, not docs/09-*). Added canonical S-prefix mapping table and WARNING blocks to ARCHITECTURE_DOCUMENTATION_GUIDE.md, RESTRUCTURING_GUIDE.md, SKILL.md, QUERY_SECTION_MAPPING.md, SECTION_MAPPING_GUIDE.md, and VALIDATIONS.md. Updated all 10 compliance generator agents with a disambiguation note at their Section Mapping. Fixed all legacy Section N.M source references in validation examples, test fixtures, and compliance guides to use file paths. Also added Step 0.5 to the architecture creation workflow: after the PO Spec gate, the user is prompted for supplementary context files (ADRs, HLD PDFs, tech stack specs, OpenAPI/AsyncAPI, data models, NFRs, IaC templates) before architecture type selection — HLD documents are enforced as PDF-only.

v2.10.27 (Previous Release) ✅

feat: add Async Intake mode to architecture-readiness skill

New 4th mode for file-based requirements extraction from tickets, emails, or documents. Reads a context file, maps content to the 8 PO Spec sections using keyword indicators, scores against the weighted rubric, and produces PO_SPEC_GAP_REPORT.md with ready-to-send questions prioritized by section weight. If score ≥7.5, also drafts PRODUCT_OWNER_SPEC.md automatically. No interactive interview — fully async. Added ASYNC_INTAKE_GUIDE.md, updated architecture-docs PO Spec gate with Option 4, and updated CLAUDE.md and README.

See CHANGELOG.md for full version history.

v2.10.26 (Previous Release) ✅

feat: auto-delete superseded compliance contracts in post-generation pipeline

The pipeline now detects when multiple contracts of the same type exist with different dates, keeps only the newest, and deletes the older ones automatically. Each removal is logged. The JSON summary includes a removedContracts field and the SKILL.md orchestrator reporting was updated to relay the cleanup notice to the user.

v2.10.25 (Previous Release) ✅

docs: expand compliance approval paths in Workflow Integration diagram

Updated the Workflow Integration diagram to show both compliance approval paths: auto-approval (score ≥8.0) and manual review (score 7.0–7.9), with both converging on Dev Handoffs before proceeding to Export.

v2.10.24 (Previous Release) ✅

docs: add refinement feedback edge from peer review Quality Gate back to Architecture Team

Added Refine edge from the peer review Quality Gate back to the Architecture Team node in the Workflow Integration diagram, reflecting that failed reviews loop back for architecture refinement before re-submission.

v2.10.23 (Previous Release) ✅

docs: convert Workflow Integration diagram to top-down layout

Changed the Workflow Integration mermaid diagram from left-to-right (graph LR) to top-down (graph TD) for better readability on standard screen widths.

v2.10.22 (Previous Release) ✅

docs: overhaul README to reflect four-phase workflow and migrate version history to CHANGELOG

Rewrote README from ~1048 to ~581 lines: corrected three-phase → four-phase workflow, updated overview diagram, Quick Start, and Features section to include Phase 4 (Dev Handoff + Doc Export); documented architecture-blueprint and quality gate skills (peer review, compliance review); removed stale version markers; replaced the 530-line roadmap/changelog block with a slim current-version summary linked to CHANGELOG.md; migrated all version history (v1.2.0–v2.10.21) to CHANGELOG.md.

v2.10.21 (Previous Release) ✅

feat: add redis-key-schema.md asset type for Redis/Cache components in dev handoff

Future Releases 🚀

  • Improved playground interactivity for compliance review and peer review
  • Additional architecture type templates

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Reporting Issues

If you encounter problems:

  1. Check the Troubleshooting Guide
  2. Search existing issues
  3. Open a new issue with detailed description

Feature Requests

Have an idea for improvement? Open an issue with the enhancement label.

Version History

See CHANGELOG.md for detailed version history.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

shadowx4fox

Acknowledgments

  • Built for Claude Code by Anthropic
  • Follows enterprise architecture best practices
  • Inspired by organizational compliance frameworks

Get Started: Download the latest release and transform your architecture workflow today!

本页内容由上游仓库自动镜像，如有疑问请访问原始仓库。