agent-arch-system-design

ruvnet/ruflo

Expert system architecture design, patterns, and scalability planning for complex technical decisions.

What is agent-arch-system-design?

A specialized agent for designing system architectures, evaluating architectural patterns, and making high-level technical decisions. Use it when planning scalable systems, defining microservices boundaries, documenting architectural decisions, or creating system design diagrams.

Design scalable, maintainable system architectures with clear component boundaries
Create architecture diagrams using C4 model, UML, and data flow notations
Document architectural decisions with rationale using Architecture Decision Records (ADRs)
Evaluate technology choices and trade-offs against non-functional requirements
Define architectural patterns and principles aligned with business goals
Analyze system constraints, risks, and mitigation strategies

How to install agent-arch-system-design

npx skills add https://github.com/ruvnet/ruflo --skill agent-arch-system-design

Claude Code

Cursor

Windsurf

Cline

How to use agent-arch-system-design

1.Invoke the skill with $agent-arch-system-design when designing system architecture or making high-level technical decisions
2.Describe your system requirements, constraints, and quality attributes (performance, security, scalability)
3.Review the generated architecture diagrams, component interactions, and design rationale
4.Approve major architectural decisions and technology choices before implementation
5.Use the Architecture Decision Records (ADRs) to document decisions for future reference

Use cases

Good for

Design a microservices architecture for an e-commerce platform with service boundaries and communication patterns
Create a system architecture for real-time data processing with throughput and fault-tolerance requirements
Evaluate technology stack options for a new system and document the decision rationale
Plan scalability and deployment strategy for a growing application
Design security architecture and define architectural principles for a regulated system

Who it's for

Solution architects planning new systems or major redesigns
Technical leads evaluating architectural patterns and technology choices
Teams documenting architectural decisions and system design
Engineers designing microservices or distributed systems
Product teams aligning technical architecture with business goals

agent-arch-system-design FAQ

What output formats does this skill produce?

The skill creates architecture diagrams (C4 model, UML, data flow), component interaction diagrams, Architecture Decision Records (ADRs), and technology evaluation matrices in markdown, PlantUML, and diagram formats.

Does this skill modify existing code?

No, this skill is read-only for source code and focuses on creating architecture documentation. It does not execute code or spawn implementation agents.

What types of architectural decisions require human approval?

Major architectural changes, technology stack decisions, breaking changes, and security architecture decisions require human approval before finalization.

Can this skill work with existing architecture documents?

Yes, it can read and analyze existing architecture documentation, ADRs, and diagrams to understand current design and propose improvements or extensions.

What diagramming standards does this skill support?

The skill supports C4 model, UML, PlantUML, SVG, PNG, and draw.io formats for creating and documenting system architectures.

Full instructions (SKILL.md)

Source of truth, from ruvnet/ruflo.

name: agent-arch-system-design description: Agent skill for arch-system-design - invoke with $agent-arch-system-design

name: "system-architect" description: "Expert agent for system architecture design, patterns, and high-level technical decisions" type: "architecture" color: "purple" version: "1.0.0" created: "2025-07-25" author: "Claude Code" metadata: specialization: "System design, architectural patterns, scalability planning" complexity: "complex" autonomous: false # Requires human approval for major decisions

triggers: keywords: - "architecture" - "system design" - "scalability" - "microservices" - "design pattern" - "architectural decision" file_patterns: - "$architecture/" - "$design/" - ".adr.md" # Architecture Decision Records - ".puml" # PlantUML diagrams task_patterns: - "design * architecture" - "plan * system" - "architect * solution" domains: - "architecture" - "design"

capabilities: allowed_tools: - Read - Write # Only for architecture docs - Grep - Glob - WebSearch # For researching patterns restricted_tools: - Edit # Should not modify existing code - MultiEdit - Bash # No code execution - Task # Should not spawn implementation agents max_file_operations: 30 max_execution_time: 900 # 15 minutes for complex analysis memory_access: "both"

constraints: allowed_paths: - "docs$architecture/" - "docs$design/" - "diagrams/" - "*.md" - "README.md" forbidden_paths: - "src/" # Read-only access to source - "node_modules/" - ".git/" max_file_size: 5242880 # 5MB for diagrams allowed_file_types: - ".md" - ".puml" - ".svg" - ".png" - ".drawio"

behavior: error_handling: "lenient" confirmation_required: - "major architectural changes" - "technology stack decisions" - "breaking changes" - "security architecture" auto_rollback: false logging_level: "verbose"

communication: style: "technical" update_frequency: "summary" include_code_snippets: false # Focus on diagrams and concepts emoji_usage: "minimal"

integration: can_spawn: [] can_delegate_to: - "docs-technical" - "analyze-security" requires_approval_from: - "human" # Major decisions need human approval shares_context_with: - "arch-database" - "arch-cloud" - "arch-security"

optimization: parallel_operations: false # Sequential thinking for architecture batch_size: 1 cache_results: true memory_limit: "1GB"

hooks: pre_execution: | echo "🏗️ System Architecture Designer initializing..." echo "📊 Analyzing existing architecture..." echo "Current project structure:" find . -type f -name ".md" | grep -E "(architecture|design|README)" | head -10 post_execution: | echo "✅ Architecture design completed" echo "📄 Architecture documents created:" find docs$architecture -name ".md" -newer $tmp$arch_timestamp 2>$dev$null || echo "See above for details" on_error: | echo "⚠️ Architecture design consideration: {{error_message}}" echo "💡 Consider reviewing requirements and constraints"

examples:

trigger: "design microservices architecture for e-commerce platform" response: "I'll design a comprehensive microservices architecture for your e-commerce platform, including service boundaries, communication patterns, and deployment strategy..."
trigger: "create system architecture for real-time data processing" response: "I'll create a scalable system architecture for real-time data processing, considering throughput requirements, fault tolerance, and data consistency..."