architecture

What this skill does

# Architecture Skill

> **Version:** 1.0.0
> **Framework:** Jerry Architecture (ARCH)
> **Constitutional Compliance:** Jerry Constitution v1.0

---

## Document Sections

| Section | Purpose |
|---------|---------|
| [Purpose](#purpose) | What this skill does |
| [When to Use This Skill](#when-to-use-this-skill) | Activation triggers |
| [Available Agents](#available-agents) | Agent registry for this skill |
| [Commands](#commands) | CLI commands and examples |
| [Architectural Principles](#architectural-principles) | Core design principles |
| [Layer Dependency Rules](#layer-dependency-rules) | Import boundary enforcement |
| [Templates](#templates) | Available templates |
| [Constitutional Compliance](#constitutional-compliance) | Principle mapping |
| [Integration with Other Skills](#integration-with-other-skills) | Cross-skill workflows |
| [Quick Reference](#quick-reference) | Common tasks and decision workflows |
| [Routing Disambiguation](#routing-disambiguation) | When this skill is the wrong choice |
| [References](#references) | Canonical sources |

---

## Document Audience (Triple-Lens)

This SKILL.md serves multiple audiences:

| Level | Audience | Sections to Focus On |
|-------|----------|---------------------|
| **L0 (ELI5)** | New users, stakeholders | [Purpose](#purpose), [When to Use](#when-to-use-this-skill), [Architectural Principles](#architectural-principles) |
| **L1 (Engineer)** | Developers implementing features | [Commands](#commands), [Layer Dependency Rules](#layer-dependency-rules), [References](#references) |
| **L2 (Architect)** | System designers | [Architectural Principles](#architectural-principles), [Constitutional Compliance](#constitutional-compliance) |

---

## Purpose

The Architecture skill provides guidance for system design, architecture review,
and structural analysis. It helps maintain hexagonal architecture principles
and ensures consistent design decisions.

### Key Capabilities

- **Architectural Analysis** - Verify hexagonal architecture compliance
- **Diagram Generation** - Create architecture visualizations (Mermaid, PlantUML, ASCII)
- **Design Review** - Assess designs against DDD, SOLID, and hexagonal patterns
- **Decision Documentation** - Create and manage Architecture Decision Records (ADRs)
- **Layer Compliance** - Enforce dependency direction rules
- **Pattern Guidance** - Apply tactical DDD patterns (aggregates, entities, value objects)

---

## When to Use This Skill

Activate when:

- Designing a new system or major component
- Creating an Architecture Decision Record (ADR)
- Reviewing existing architecture for compliance
- Analyzing layer dependencies and port/adapter structure
- Generating architecture diagrams
- Validating that domain layer has no external dependencies
- Applying Domain-Driven Design (DDD) tactical patterns
- Documenting trade-offs between architectural approaches

---

## Available Agents

This skill provides command-based analysis rather than agent-based workflows. Commands are invoked via natural language or explicit requests.

| Command | Purpose | Output Location |
|---------|---------|-----------------|
| `analyze` | Verify architectural compliance of a component | Console + optional file |
| `diagram` | Generate architecture visualizations | Console or specified file path |
| `review` | Review design documents against checklists | Console + optional file |
| `decision` | Create an Architecture Decision Record | `docs/design/ADR_NNN_*.md` |

---

## Commands

### Analyze Component

Analyze a component's architectural compliance.

```
@architecture analyze <path> [--depth DEPTH]
```

**Arguments:**
- `path`: Path to component (file or directory)
- `--depth`: Analysis depth (`surface`, `deep`) (default: `surface`)

**Example:**
```
@architecture analyze src/domain/
```

**Output:**
```
Architecture Analysis: src/domain/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Layer: Domain (Innermost)
Compliance: ✓ PASS

Checks:
  ✓ No external package imports
  ✓ No imports from application/
  ✓ No imports from infrastructure/
  ✓ No imports from interface/
  ✓ Entities use dataclasses
  ✓ Value objects are frozen

Components Found:
  - aggregates/work_item.py (Aggregate Root)
  - aggregates/project.py (Aggregate Root)
  - value_objects/status.py (Value Object)
  - ports/repository.py (Secondary Port)

Recommendations:
  - Consider adding domain events for state changes
```

---

### Generate Diagram

Generate architecture diagrams.

```
@architecture diagram <type> [--output PATH] [--format FORMAT]
```

**Arguments:**
- `type`: `hexagonal`, `component`, `sequence`, `data-flow`
- `--output`: Output file path
- `--format`: `mermaid`, `plantuml`, `ascii` (default: `mermaid`)

**Example:**
```
@architecture diagram hexagonal --format mermaid
```

**Output:**
```mermaid
graph TB
    subgraph "Interface Layer"
        CLI[CLI Adapter]
        API[API Adapter]
    end

    subgraph "Application Layer"
        UC[Use Cases]
        CMD[Commands]
        QRY[Queries]
    end

    subgraph "Domain Layer"
        AGG[Aggregates]
        VO[Value Objects]
        EVT[Domain Events]
        PORT[Ports]
    end

    subgraph "Infrastructure Layer"
        REPO[Repository Adapter]
        MSG[Messaging Adapter]
    end

    CLI --> UC
    API --> UC
    UC --> CMD
    UC --> QRY
    CMD --> AGG
    QRY --> AGG
    AGG --> PORT
    PORT -.-> REPO
    EVT -.-> MSG
```

---

### Review Design

Review a design document or proposed change.

```
@architecture review <path> [--checklist CHECKLIST]
```

**Arguments:**
- `path`: Path to design document or code
- `--checklist`: Checklist to apply (`hexagonal`, `ddd`, `solid`, `all`)

**Example:**
```
@architecture review docs/design/AUTH_DESIGN.md --checklist hexagonal
```

**Output:**
```
Architecture Review: AUTH_DESIGN.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Checklist: Hexagonal Architecture

Domain Layer:
  ✓ Business logic isolated from infrastructure
  ✓ Entities enforce invariants
  ⚠ Missing domain events for state changes

Ports:
  ✓ IUserRepository defined as protocol
  ✓ ITokenService defined as protocol
  ✗ INotifier port missing for notifications

Adapters:
  ✓ JWTTokenAdapter implements ITokenService
  ✓ SQLiteUserRepository implements IUserRepository
  ⚠ Consider adding InMemory adapters for testing

Dependency Direction:
  ✓ Domain has no outward dependencies
  ✓ Application depends only on domain
  ✓ Infrastructure implements domain ports

Overall: PASS with recommendations

Recommendations:
1. Add UserRegistered domain event
2. Define INotifier port for email notifications
3. Create InMemoryUserRepository for unit tests
```

---

### Document Decision

Create an Architecture Decision Record (ADR).

```
@architecture decision <title> [--status STATUS]
```

**Arguments:**
- `title`: Decision title
- `--status`: `proposed`, `accepted`, `deprecated`, `superseded`

**Example:**
```
@architecture decision "Use SQLite for persistence"
```

**Creates:** `docs/design/ADR_001_sqlite_persistence.md`

**Template:**
```markdown
# ADR-001: Use SQLite for Persistence

**Status**: Proposed
**Date**: 2026-01-07
**Author**: Claude

## Context

{What is the issue that we're seeing that is motivating this decision?}

## Decision

We will use SQLite for persistence because...

## Consequences

### Positive
- {Benefit 1}
- {Benefit 2}

### Negative
- {Drawback 1}
- {Drawback 2}

### Neutral
- {Observation}

## Alternatives Considered

| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| SQLite | ... | ... | Selected |
| PostgreSQL | ... | ... | Rejected |
| File-based | ... | ... | Rejected |

## References

- {Link to relevant documentation}
```

---

## Architectural Principles

### Hexagonal Architecture (Ports & Adapters)

> "Allow an application to equally be driven by users, programs, automated test
> or batch scripts, and to be developed and tested in isolation from its eventual
> run-time devices and databases."
> — Alistair Cockbu