architecture

Architecture Skill

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

---

Document Sections

Section	Purpose
Purpose	What this skill does
When to Use This Skill	Activation triggers
Available Agents	Agent registry for this skill
Commands	CLI commands and examples
Architectural Principles	Core design principles
Layer Dependency Rules	Import boundary enforcement
Templates	Available templates
Constitutional Compliance	Principle mapping
Integration with Other Skills	Cross-skill workflows
Quick Reference	Common tasks and decision workflows
Routing Disambiguation	When this skill is the wrong choice
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, When to Use, Architectural Principles
L1 (Engineer)	Developers implementing features	Commands, Layer Dependency Rules, References
L2 (Architect)	System designers	Architectural Principles, 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:

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:

# 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 Cockburn

Key Rules:

1. Domain layer has NO external dependencies
2. Dependencies point inward (outer → inner)
3. Ports define contracts (interfaces)
4. Adapters implement contracts

Domain-Driven Design (DDD)

Tactical Patterns Used:

• Aggregates: Consistency boundaries (WorkItem, Project)
• Entities: Objects with identity
• Value Objects: Immutable values (Status, Priority)
• Domain Events: Facts that happened (WorkItemCompleted)
• Repositories: Collection-like interface for aggregates

CQRS (Command Query Responsibility Segregation)

• Commands: Write operations, return None or events
• Queries: Read operations, return DTOs

---

Layer Dependency Rules

┌─────────────────────────────────────────┐
│           Interface Layer               │
│  (CLI, API - may import all layers)     │
├─────────────────────────────────────────┤
│         Infrastructure Layer            │
│  (may import domain, application)       │
├─────────────────────────────────────────┤
│          Application Layer              │
│  (may import domain only)               │
├─────────────────────────────────────────┤
│            Domain Layer                 │
│  (NO external imports - stdlib only)    │
└─────────────────────────────────────────┘

---

Templates

Architecture artifacts should use standardized templates to ensure consistency.

Location: .context/templates/

Template	Use For	Path
adr.md	Architecture Decision Records	docs/knowledge/exemplars/templates/adr.md

Usage: When creating a new ADR, reference the template to ensure consistent structure and sections.

---

Constitutional Compliance

All architecture work adheres to the Jerry Constitution v1.0:

Principle	Requirement	Consequence of Violation
P-003	NEVER spawn recursive subagents -- max 1 level	Agent hierarchy violation; uncontrolled token consumption
P-020	NEVER override user intent -- ask before destructive ops	Unauthorized action; trust erosion
P-022	NEVER deceive about actions, capabilities, or confidence	Governance undermined; quality assessment invalidated
P-002	NEVER leave outputs in transient context only -- persist to files	Context rot vulnerability; artifacts lost on session compaction
P-004	NEVER omit reasoning provenance or source documentation in ADRs	Untraceable decisions; audit trail broken
P-011	NEVER make architecture recommendations without supporting evidence	Unsupported recommendations; confidence inflated without basis
H-07	NEVER violate architecture layer isolation -- domain, application, composition root boundaries enforced	Architecture layer corruption; dependency violations propagate
H-10	NEVER place multiple public classes in a single file	File bloat; class discovery degraded

---

Integration with Other Skills

The architecture skill integrates with other Jerry skills:

Skill	Integration Point	Example
/problem-solving	ps-architect creates ADRs	Architecture decisions documented via ps-architect agent
/nasa-se	nse-architecture formal trade studies	NASA SE process informs architecture decisions
/orchestration	Multi-phase design workflows	Orchestrated architecture review processes

Cross-Skill Handoff:

• ps-architect output → architecture review command for validation
• nse-architecture trade study → architecture decision for ADR creation

---

Quick Reference

Common Tasks

Task	Command / Approach	Output
Verify layer compliance	@architecture analyze src/domain/	Console report with pass/fail
Generate hexagonal diagram	@architecture diagram hexagonal --format mermaid	Mermaid diagram
Review design document	@architecture review docs/design/AUTH_DESIGN.md --checklist hexagonal	Checklist report
Create an ADR	@architecture decision "Use SQLite for persistence"	docs/design/ADR_NNN_*.md
Check import boundaries	@architecture analyze src/ --depth deep	Full dependency analysis

Decision Workflow Summary

Step	Action	Artifact
1. Identify need	Recognize architectural choice required	Problem statement
2. Research options	Use /problem-solving for analysis	Research findings
3. Evaluate trade-offs	Use /nasa-se for formal trade study	Trade study matrix
4. Document decision	@architecture decision "<title>"	ADR in docs/design/
5. Validate compliance	@architecture analyze <path>	Compliance report

---

Routing Disambiguation

When this skill is the wrong choice and what happens if misrouted.

Condition	Use Instead	Consequence of Misrouting
Root cause analysis or debugging needed	/problem-solving (ps-investigator)	Architecture methodology (layer dependency rules, CQRS patterns, hexagonal structure) applied to investigation tasks produces structural design artifacts instead of causal chains; root cause not isolated
Requirements engineering or V&V needed	/nasa-se	Requirements expressed as architectural decisions; V&V traceability lost; compliance gaps not detected
Offensive security testing or penetration testing	/red-team	Architecture compliance checks applied to offensive engagement produce structural diagrams instead of attack narratives; engagement methodology entirely absent
Adversarial quality review or tournament scoring	/adversary	Architecture review checklists applied instead of adversarial strategy templates; S-014 scoring rubric not loaded
Security hardening or threat modeling	/eng-team	Architecture skill lacks STRIDE/DREAD methodology; security-specific governance layers (OWASP, NIST SSDF) not available
Multi-agent workflow coordination	/orchestration	Architecture commands are single-step operations; no state tracking, checkpointing, or sync barrier capability

---

References

• Cockburn, A. (2005). "Hexagonal Architecture"
• Evans, E. (2003). "Domain-Driven Design: Tackling Complexity in the Heart of Software"
• Vernon, V. (2013). "Implementing Domain-Driven Design"
• Martin, R. (2017). "Clean Architecture"
• Jerry Architecture Standards: .context/rules/architecture-standards.md
• Jerry Constitution: docs/governance/JERRY_CONSTITUTION.md

---

Skill Version: 1.0.0 Constitutional Compliance: Jerry Constitution v1.0 Last Updated: 2026-02-16