gh-dhofheinz-open-plugins-plugins-10x-fullstack-engineer/commands/architect

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
• Operations
  • Design
  • Review
  • ADR
  • Assess
• Utility Scripts
• Usage Examples
• Integration
• 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:

/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:

/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:

/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:

/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:

./.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:

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:

./.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

# 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

# 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

# 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

# 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

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

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

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

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

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

/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:

/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:

/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:

/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:

   /architect design requirements:"your project description" scale:"expected scale" constraints:"technical constraints"
   

2. Document Key Decisions:

   /architect adr decision:"decision summary" alternatives:"other options" status:"accepted"
   

3. Establish Baseline:

   /architect assess
   

4. Regular Health Checks:

   /architect assess baseline:"previous"
   /architect review focus:"security"
   

5. Use Utility Scripts:

   ./.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
• OWASP Top 10: https://owasp.org/www-project-top-ten/
• 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)