# Architecture Skill

**Comprehensive system architecture design, review, and documentation with ADR creation**

The Architecture skill provides expert-level architectural guidance through four specialized operations: design new architectures, review existing systems, document architectural decisions, and assess architecture health. All operations leverage the **10x-fullstack-engineer** agent for 15+ years of architectural expertise.

---

## Table of Contents

- [Overview](#overview)
- [Operations](#operations)
  - [Design](#design---design-new-architecture)
  - [Review](#review---review-existing-architecture)
  - [ADR](#adr---create-architectural-decision-records)
  - [Assess](#assess---architecture-health-assessment)
- [Utility Scripts](#utility-scripts)
- [Usage Examples](#usage-examples)
- [Integration](#integration)
- [Best Practices](#best-practices)

---

## Overview

The Architecture skill operates through a router pattern where the main skill file (`skill.md`) parses arguments and routes to specialized operation files. This modular approach enables:

- **Focused Operations**: Each architectural task has dedicated logic and workflows
- **Agent Integration**: All operations invoke the 10x-fullstack-engineer agent for expert guidance
- **Utility Scripts**: Automated analysis tools for dependencies, complexity, and diagrams
- **Structured Output**: Consistent, comprehensive documentation for all architectural artifacts

**Base Directory**: `.claude/commands/architect/` (or plugin equivalent)

**Agent**: All operations require and invoke the **10x-fullstack-engineer** agent

---

## Operations

### Design - Design New Architecture

Create comprehensive system architecture for new features, projects, or major changes.

**Use When**:
- Starting new projects or features
- Major architectural refactoring
- Greenfield development
- Architecture modernization

**Parameters**:
```
requirements:"description"    (required) Feature or system description
scope:"area"                  (optional) Specific focus area (backend, frontend, full-stack)
constraints:"limitations"     (optional) Technical constraints, existing systems, team expertise
scale:"expected-load"         (optional) Expected load, user count, data volume, growth
```

**What It Does**:

1. **Requirements Analysis** - Parses requirements, identifies stakeholders, extracts non-functional requirements
2. **Context Gathering** - Examines existing codebase, technology stack, infrastructure, documentation
3. **Architecture Design** - Creates comprehensive design across all layers:
   - **Database Layer**: Schema design, query optimization, migration strategy, data consistency
   - **Backend Layer**: API design, service architecture, business logic, auth/authz, caching, message queuing
   - **Frontend Layer**: Component architecture, state management, routing, data fetching, performance
   - **Infrastructure Layer**: Deployment architecture, scaling strategy, CI/CD, monitoring, security, disaster recovery
4. **Trade-off Analysis** - Documents decisions with pros/cons/alternatives for major choices
5. **Deliverables** - Produces architecture diagrams, component breakdown, data flow, technology stack, implementation phases, risk assessment, success metrics
6. **ADR Creation** - Documents significant decisions as ADRs

**Output**: Comprehensive architecture design document with executive summary, detailed layer designs, technology justifications, implementation roadmap, and risk mitigation strategies.

**Example**:
```bash
/10x-fullstack-engineer:architect design requirements:"real-time notification system with WebSockets, push notifications, and email delivery" scale:"10,000 concurrent users" constraints:"must integrate with existing REST API, AWS infrastructure"
```

---

### Review - Review Existing Architecture

Analyze existing architecture for quality, security, performance, scalability, and maintainability issues.

**Use When**:
- Architecture health checks
- Pre-production reviews
- Security audits
- Refactoring planning
- Technical debt assessment

**Parameters**:
```
path:"directory"              (optional) Specific directory or component to review (default: entire codebase)
focus:"dimension"             (optional) Primary concern area - security, performance, scalability, maintainability, or "all"
depth:"shallow|deep"          (optional) Review depth - "shallow" for quick assessment, "deep" for comprehensive analysis (default: "deep")
```

**What It Does**:

1. **Context Discovery** - Analyzes directory structure, technology stack, configuration, documentation, testing infrastructure
2. **Layer-by-Layer Analysis**:
   - **Database Layer**: Schema quality, performance, scalability, security
   - **Backend Layer**: API design, code organization, business logic, auth/authz, performance, security, maintainability
   - **Frontend Layer**: Component architecture, state management, performance, UX, security, build/deployment
   - **Infrastructure Layer**: Deployment architecture, scalability, monitoring, CI/CD, security, disaster recovery
3. **Cross-Cutting Concerns**: Security audit (OWASP Top 10), performance analysis, scalability assessment, maintainability review
4. **Issue Identification** - Categorizes issues by severity (Critical/High/Medium/Low) with location, impact, recommendation, effort
5. **Scoring** - Provides 0-10 scores for each dimension with status and trend indicators
6. **Recommendations** - Prioritized roadmap of quick wins, important improvements, strategic initiatives, technical debt

**Output**: Comprehensive architecture review report with health scores, detailed findings by dimension, comparison to industry standards, dependency analysis, and prioritized recommendations roadmap.

**Example**:
```bash
/10x-fullstack-engineer:architect review focus:"security" depth:"deep"
```

---

### ADR - Create Architectural Decision Records

Document significant architectural decisions with context, alternatives, and rationale in standard ADR format.

**Use When**:
- After major design decisions
- Technology selections
- Pattern adoptions
- Architectural pivots
- Documenting trade-offs

**Parameters**:
```
decision:"what-was-decided"   (required) Brief summary of the architectural decision
context:"background"          (optional) Background, problem being solved, forces at play
alternatives:"other-options"  (optional) Other options that were considered
status:"status"               (optional) Decision status - "proposed", "accepted", "deprecated", "superseded" (default: "proposed")
```

**What It Does**:

1. **Context Gathering** - Understands decision scope, problem context, decision drivers, researches current state
2. **Alternative Analysis** - Identifies 3-5 alternatives, analyzes pros/cons/trade-offs for each, creates comparison matrix
3. **Decision Rationale** - Documents primary justification, supporting reasons, risk acceptance, decision criteria
4. **Consequences Analysis** - Identifies positive, negative, and neutral consequences, impact assessment (immediate/short-term/long-term), dependencies
5. **ADR Creation** - Generates standard ADR format with proper numbering, saves to `docs/adr/`, updates ADR index
6. **Documentation** - Links related ADRs, provides implementation guidance

**Output**: Complete ADR document saved to `docs/adr/ADR-NNNN-slug.md` with status, date, deciders, context, considered options, decision outcome, consequences, pros/cons analysis, and references.

**ADR Templates Available**:
- Technology Selection
- Architecture Pattern
- Migration Decision

**Example**:
```bash
/10x-fullstack-engineer:architect adr decision:"use PostgreSQL with JSONB for flexible schema" context:"need relational integrity plus document flexibility" alternatives:"MongoDB, DynamoDB, MySQL" status:"accepted"
```

---

### Assess - Architecture Health Assessment

Comprehensive assessment across technical debt, security, performance, scalability, maintainability, and cost dimensions with scoring and trend analysis.

**Use When**:
- Quarterly reviews
- Baseline establishment
- Improvement tracking
- Executive reporting
- Planning refactoring initiatives

**Parameters**:
```
scope:"level"                 (optional) Assessment scope - "system" (entire architecture), "service", "component" (default: "system")
focus:"dimension"             (optional) Specific dimension - "tech-debt", "security", "performance", "scalability", "maintainability", "cost", or "all" (default: "all")
baseline:"reference"          (optional) Baseline for comparison - ADR number, date (YYYY-MM-DD), or "previous" for last assessment
```

**What It Does**:

1. **Baseline Discovery** - Finds previous assessments, extracts baseline metrics, tracks issue resolution
2. **Dimensional Assessment** - Scores 0-10 across six dimensions:
   - **Technical Debt**: Code quality, outdated dependencies, deprecated patterns, documentation
   - **Security**: Authentication, data protection, vulnerability scanning, OWASP Top 10 compliance
   - **Performance**: API response times, database queries, frontend load times, resource utilization
   - **Scalability**: Horizontal scaling capability, database scaling, auto-scaling, capacity limits
   - **Maintainability**: Code organization, test coverage, documentation, deployment frequency
   - **Cost Efficiency**: Infrastructure costs, resource utilization, optimization opportunities
3. **Comparative Analysis** - Compares to baseline, tracks resolved/new/persistent issues, analyzes trends, projects future state
4. **Recommendations** - Prioritized roadmap:
   - **Immediate Actions** (This Sprint): Critical fixes
   - **Quick Wins** (2-4 weeks): High impact, low effort
   - **Important Improvements** (1-3 months): Significant value, moderate effort
   - **Strategic Initiatives** (3-6 months): Long-term value, high effort
5. **Implementation Roadmap** - Sprint planning, milestone timeline, success metrics, risk assessment

**Output**: Architecture health assessment report with overall health score, dimension-specific scores with trends, detailed findings by category, comparison to baseline, trend analysis, issue tracking, and prioritized recommendations with implementation roadmap.

**Scoring Guide**:
- **9-10 (Excellent)**: Best practices, minimal improvements needed
- **7-8 (Good)**: Solid foundation, minor enhancements possible
- **5-6 (Fair)**: Acceptable but improvements needed
- **3-4 (Poor)**: Significant issues, action required
- **0-2 (Critical)**: Severe problems, urgent action needed

**Example**:
```bash
/10x-fullstack-engineer:architect assess baseline:"previous"
```

---

## Utility Scripts

The Architecture skill includes three utility scripts in the `.scripts/` directory:

### 1. analyze-dependencies.sh

**Purpose**: Analyze project dependencies for security, versioning, and usage

**Usage**:
```bash
./.scripts/analyze-dependencies.sh [path] [json|text]
```

**Features**:
- Detects package manager (npm, pip, pipenv, poetry, bundler, go, cargo, composer)
- Counts direct and development dependencies
- Checks for outdated packages
- Scans for security vulnerabilities (critical/high/medium/low)
- Analyzes dependency tree depth
- Finds unused dependencies
- Detects duplicate dependencies
- Calculates health score (0-10)
- Generates prioritized recommendations

**Output**: JSON or text report with dependency analysis, vulnerability summary, health score, and recommendations

**Exit Codes**:
- 0: Success
- 1: Error during analysis
- 2: Invalid input

---

### 2. complexity-metrics.py

**Purpose**: Calculate code complexity metrics for architecture assessment

**Usage**:
```bash
python3 ./.scripts/complexity-metrics.py [path] [--format json|text]
```

**Features**:
- Analyzes cyclomatic complexity (uses `radon` library if available, falls back to simplified metrics)
- Calculates maintainability index
- Classifies functions: simple (1-5), moderate (6-10), complex (11-20), very complex (>20)
- Tracks average and maximum complexity
- Analyzes maintainability distribution (high/medium/low)
- Calculates overall health score (0-10)
- Generates recommendations for refactoring

**Supported Languages**: Python, JavaScript, TypeScript, Java, Go, Ruby, PHP, C, C++, C#

**Output**: JSON or text report with complexity metrics, maintainability scores, health score, and refactoring recommendations

**Dependencies**: Optional `radon` library (install with `pip install radon`) for enhanced metrics

**Exit Codes**:
- 0: Success
- 1: Error during analysis
- 2: Invalid input

---

### 3. diagram-generator.sh

**Purpose**: Generate ASCII architecture diagrams from system descriptions

**Usage**:
```bash
./.scripts/diagram-generator.sh <type> [--title "Title"] [--color]
```

**Diagram Types**:
- `layered`: Layered architecture diagram (Presentation → Business → Persistence → Database)
- `microservices`: Microservices architecture with API gateway, services, databases, message queue
- `database`: Database architecture with read/write pools, replicas, caching
- `network`: Network topology with CDN, WAF, load balancers, availability zones
- `component`: Component interaction diagram showing client → frontend → backend → data storage
- `dataflow`: Data flow diagram showing step-by-step data movement

**Features**:
- Unicode box drawing characters for clean diagrams
- Optional colored output
- Customizable titles
- Pre-built templates for common architecture patterns

**Output**: ASCII diagram suitable for markdown documentation or terminal display

**Exit Codes**:
- 0: Success
- 1: Error during execution
- 2: Invalid input

---

## Usage Examples

### Complete Architecture Design Workflow

```bash
# 1. Design architecture for new feature
/10x-fullstack-engineer:architectdesign requirements:"multi-tenant SaaS platform with real-time collaboration, file storage, and analytics" scale:"enterprise-level, 100k+ users" constraints:"TypeScript, Node.js, PostgreSQL, horizontal scaling"

# 2. Document key architectural decisions
/10x-fullstack-engineer:architectadr decision:"use PostgreSQL with row-level security for multi-tenancy" alternatives:"separate databases per tenant, schema-based isolation" status:"accepted"

/10x-fullstack-engineer:architectadr decision:"implement CQRS pattern for read-heavy analytics" alternatives:"standard CRUD, event sourcing, materialized views" status:"accepted"

# 3. Assess baseline architecture health
/10x-fullstack-engineer:architectassess

# 4. Review specific component security
/10x-fullstack-engineer:architectreview path:"src/services/auth" focus:"security" depth:"deep"
```

### Quarterly Architecture Review

```bash
# Run comprehensive assessment against last quarter
/10x-fullstack-engineer:architectassess baseline:"2024-01-15"

# Focus on areas that degraded
/10x-fullstack-engineer:architectreview focus:"performance" depth:"deep"

# Document improvement initiatives
/10x-fullstack-engineer:architectadr decision:"implement Redis caching layer to improve performance" context:"assessment showed performance degradation, response times increased 40%" status:"accepted"
```

### Pre-Production Architecture Validation

```bash
# Comprehensive review before launch
/10x-fullstack-engineer:architectreview focus:"all" depth:"deep"

# Security audit
/10x-fullstack-engineer:architectreview focus:"security" depth:"deep"

# Performance validation
/10x-fullstack-engineer:architectreview focus:"performance" depth:"deep"

# Document production readiness decisions
/10x-fullstack-engineer:architectadr decision:"deploy with blue-green strategy for zero-downtime releases" alternatives:"rolling deployment, canary releases" status:"accepted"
```

### Technical Debt Assessment

```bash
# Assess technical debt
/10x-fullstack-engineer:architectassess focus:"tech-debt"

# Review code quality
/10x-fullstack-engineer:architectreview focus:"maintainability" depth:"deep"

# Run complexity analysis
python3 .scripts/complexity-metrics.py . --format json

# Analyze dependencies
./.scripts/analyze-dependencies.sh . json
```

### Architecture Documentation Sprint

```bash
# Document existing system design
/10x-fullstack-engineer:architectdesign requirements:"document existing order processing system" scope:"backend" constraints:"Node.js, PostgreSQL, AWS, existing production system"

# Create ADRs for historical decisions
/10x-fullstack-engineer:architectadr decision:"chose microservices architecture for order processing" context:"monolith scalability limitations" alternatives:"modular monolith, serverless" status:"accepted"

# Generate architecture diagrams
./.scripts/diagram-generator.sh microservices --title "Order Processing Architecture"
./.scripts/diagram-generator.sh database --title "Order Database Architecture"

# Baseline current health
/10x-fullstack-engineer:architectassess
```

---

## Integration

### With Other Skills/Commands

The Architecture skill integrates seamlessly with other development workflows:

**Design Phase**:
- `/10x-fullstack-engineer:architect design` → Design system architecture
- Document decisions with `/architect adr`
- Generate diagrams with `diagram-generator.sh`

**Development Phase**:
- Run `/architect review` on new components
- Check complexity with `complexity-metrics.py`
- Validate dependencies with `analyze-dependencies.sh`

**Testing Phase**:
- `/10x-fullstack-engineer:architect review focus:"performance"` for performance validation
- `/10x-fullstack-engineer:architect assess` for quality gates

**Deployment Phase**:
- `/10x-fullstack-engineer:architect review focus:"security"` before production
- Document deployment decisions with `/architect adr`

**Maintenance Phase**:
- Quarterly `/architect assess` against baseline
- `/10x-fullstack-engineer:architect review focus:"tech-debt"` for refactoring planning
- Update ADRs when superseding decisions

### With Agent System

All operations invoke the **10x-fullstack-engineer** agent, which provides:
- 15+ years of architectural expertise
- Pattern recognition and best practices
- Trade-off analysis and decision guidance
- Production system experience
- Technology stack recommendations
- Scalability and performance insights
- Security and reliability patterns

The agent receives comprehensive context including operation parameters, codebase information, existing architecture, constraints, and scale requirements.

### Continuous Architecture Governance

Integrate architecture operations into your development lifecycle:

**Sprint Planning**:
```bash
# Review technical debt before planning
/10x-fullstack-engineer:architectassess focus:"tech-debt"

# Design new features architecturally
/10x-fullstack-engineer:architectdesign requirements:"sprint feature description"
```

**Code Review**:
```bash
# Review new components
/10x-fullstack-engineer:architectreview path:"src/new-component" depth:"shallow"

# Check complexity
python3 .scripts/complexity-metrics.py src/new-component
```

**Release Process**:
```bash
# Pre-release validation
/10x-fullstack-engineer:architectreview focus:"security" depth:"deep"
/10x-fullstack-engineer:architectreview focus:"performance" depth:"shallow"

# Document release decisions
/10x-fullstack-engineer:architectadr decision:"release decision"
```

**Quarterly Reviews**:
```bash
# Comprehensive health assessment
/10x-fullstack-engineer:architectassess baseline:"previous"

# Trend analysis and planning
/10x-fullstack-engineer:architectreview focus:"all" depth:"deep"
```

---

## Best Practices

### When to Use Each Operation

**Use Design When**:
- Starting new projects or major features
- Need comprehensive architecture documentation
- Evaluating technology stack options
- Planning multi-phase implementation
- Establishing architectural patterns

**Use Review When**:
- Conducting architecture health checks
- Pre-production validation
- Security audits
- Identifying refactoring opportunities
- Onboarding new team members to architecture

**Use ADR When**:
- Making significant architectural decisions
- Choosing technologies or patterns
- Resolving architectural trade-offs
- Documenting rationale for future reference
- Creating decision audit trail

**Use Assess When**:
- Quarterly architecture reviews
- Establishing baseline metrics
- Tracking improvement progress
- Executive reporting on tech health
- Planning major refactoring initiatives

### Architecture Documentation Workflow

1. **Design First**: Start with `/architect design` for new systems
2. **Document Decisions**: Create ADRs for significant choices
3. **Establish Baseline**: Run initial `/architect assess`
4. **Regular Reviews**: Schedule quarterly `/architect assess baseline:"previous"`
5. **Component Reviews**: Review new components with `/architect review`
6. **Update ADRs**: Supersede decisions when architecture evolves
7. **Track Trends**: Monitor health scores over time

### Optimization Tips

**For Design Operations**:
- Provide detailed requirements and constraints upfront
- Specify scale expectations explicitly
- Leverage existing ADRs for consistency
- Use utility scripts for current state analysis
- Review generated architecture with team before implementation

**For Review Operations**:
- Start with shallow reviews for quick feedback
- Use focused reviews (security, performance) for specific concerns
- Run deep reviews before major releases
- Combine with utility scripts for comprehensive analysis
- Address critical issues before continuing to lower priority

**For ADR Creation**:
- Create ADRs immediately after decisions, not retrospectively
- Include alternatives considered, not just chosen option
- Document trade-offs explicitly
- Link related ADRs for context
- Update status as decisions evolve

**For Assessment Operations**:
- Establish baseline early in project lifecycle
- Run assessments consistently (e.g., quarterly)
- Compare to baselines to track trends
- Focus on dimensions with declining scores
- Use assessment output for sprint planning

### Common Workflows

**New Project Setup**:
```bash
/10x-fullstack-engineer:architectdesign requirements:"project description" constraints:"tech stack"
/10x-fullstack-engineer:architectadr decision:"technology choices"
./.scripts/diagram-generator.sh layered --title "Project Architecture"
/10x-fullstack-engineer:architectassess  # Establish baseline
```

**Pre-Production Checklist**:
```bash
/10x-fullstack-engineer:architectreview focus:"security" depth:"deep"
/10x-fullstack-engineer:architectreview focus:"performance" depth:"deep"
/10x-fullstack-engineer:architectassess
./.scripts/analyze-dependencies.sh . json
```

**Technical Debt Paydown**:
```bash
/10x-fullstack-engineer:architectassess focus:"tech-debt"
python3 .scripts/complexity-metrics.py . --format json
/10x-fullstack-engineer:architectreview focus:"maintainability" depth:"deep"
# Address top recommendations
/10x-fullstack-engineer:architectassess baseline:"previous"  # Verify improvement
```

**Architecture Modernization**:
```bash
/10x-fullstack-engineer:architectreview focus:"all" depth:"deep"  # Understand current state
/10x-fullstack-engineer:architectdesign requirements:"modernization goals" constraints:"existing system"
/10x-fullstack-engineer:architectadr decision:"modernization approach"
# Implement incrementally
/10x-fullstack-engineer:architectassess baseline:"pre-modernization"  # Track progress
```

---

## File Structure

```
architect/
├── skill.md                           # Router (invokable via /architect)
├── design.md                          # Design operation (not directly invokable)
├── review.md                          # Review operation (not directly invokable)
├── adr.md                             # ADR operation (not directly invokable)
├── assess.md                          # Assess operation (not directly invokable)
├── .scripts/
│   ├── analyze-dependencies.sh        # Dependency analysis utility
│   ├── complexity-metrics.py          # Code complexity analysis utility
│   └── diagram-generator.sh           # ASCII diagram generation utility
└── README.md                          # This file
```

**Note**: Only `skill.md` is directly invokable via `/10x-fullstack-engineer:architect`. Sub-operations are instruction modules read and executed by the router.

---

## Error Handling

All operations include comprehensive error handling:

- **Unknown Operation**: Lists available operations with examples
- **Missing Required Parameters**: Provides parameter format guidance
- **Invalid Parameters**: Suggests correct parameter values
- **File/Directory Not Found**: Lists available paths or creates directories as needed
- **Insufficient Context**: Documents assumptions and requests clarification

Operations gracefully handle missing metrics, incomplete information, and edge cases by providing clear guidance to the user.

---

## Output Locations

**Architecture Designs**: Generated as markdown in operation response, can be saved manually or integrated with documentation system

**ADRs**: Automatically saved to `docs/adr/ADR-NNNN-slug.md` with index updates

**Assessments**: Generated as markdown in operation response, recommended to save to `docs/assessments/architecture-assessment-YYYY-MM-DD.md`

**Reviews**: Generated as markdown in operation response, can be saved for historical reference

**Utility Script Outputs**: JSON or text format, typically piped or redirected as needed

---

## Getting Started

1. **Initial Architecture Design**:
   ```bash
   /architect design requirements:"your project description" scale:"expected scale" constraints:"technical constraints"
   ```

2. **Document Key Decisions**:
   ```bash
   /architect adr decision:"decision summary" alternatives:"other options" status:"accepted"
   ```

3. **Establish Baseline**:
   ```bash
   /architect assess
   ```

4. **Regular Health Checks**:
   ```bash
   /architect assess baseline:"previous"
   /architect review focus:"security"
   ```

5. **Use Utility Scripts**:
   ```bash
   ./.scripts/analyze-dependencies.sh . json
   python3 .scripts/complexity-metrics.py . --format json
   ./.scripts/diagram-generator.sh microservices --title "System Architecture"
   ```

---

## Additional Resources

- **ADR Format**: Based on [Michael Nygard's ADR template](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- **OWASP Top 10**: [https://owasp.org/www-project-top-ten/](https://owasp.org/www-project-top-ten/)
- **Cyclomatic Complexity**: [https://en.wikipedia.org/wiki/Cyclomatic_complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)
- **Architecture Assessment**: Based on industry best practices for architecture health metrics

---

## Support and Contribution

This skill is part of the **10x-fullstack-engineer** plugin. For issues, improvements, or questions:

1. Review the operation documentation in individual `.md` files
2. Examine utility script comments for detailed usage
3. Refer to the 10x-fullstack-engineer agent capabilities
4. Check ADR templates in `adr.md` for decision documentation patterns

---

**Version**: 1.0.0
**Last Updated**: 2025-10-14
**Agent Integration**: 10x-fullstack-engineer (required)