@endgame-build/claude-workflows/.claude/commands/eg/architect.md

Claude Code workflow system with commands, agents, and templates for AI-native development

---
description: Design technical solution architecture for features or improvements
argument-hint: <instance-name> <@feature-definition.md or description>
---

# /eg:architect

You are tasked with creating a comprehensive technical architecture for a feature or improvement. Your goal is to design a robust, scalable solution that balances immediate needs with long-term maintainability.

Input: `$ARGUMENTS`

## Step 1: Parse Arguments and Setup

Parse the arguments to extract:
- Instance name (first word before space)
- Feature definition or description (everything after first space)

Create the workflow directory:
!mkdir -p .eg/{instance-name}

## Step 2: Analyze Requirements

If a feature definition file is provided (starts with @), read it:
- Look for `.eg/{instance-name}/feature-definition.md`
- Otherwise, work with the provided description

## Step 3: Research Best Practices

Use the Task tool to invoke the architect agent to research and design:

```
Task(
  description="Research and design technical architecture",
  prompt=`
    Create a comprehensive technical architecture for: {requirements}
    
    1. Research industry best practices using firecrawl-mcp for similar features
    2. Use zen-mcp thinkdeep or consensus tools for architectural insights
    3. Consider at least 3 different architectural approaches
    
    Use the provided solution template from .claude/templates/solution.template.md
    
    Fill in all template sections:
    - Overview: Technical approach summary
    - Architecture: Component diagram and descriptions
    - Data Flow: How data moves through the system
    - API Design: Endpoints, contracts, validation
    - State Management: How state is handled
    - Error Handling: Error strategies and recovery
    - Security: Authentication, authorization, data protection
    - Testing Strategy: Unit, integration, E2E approach
    - Performance: Optimization and scaling considerations
    - Migration: From current state to new architecture
    
    Save the architecture document to: .eg/{instance-name}/architecture.md
  `,
  subagent_type="architect"
)
```

## Step 4: Validate Architecture

After the architecture is created, validate it using the architecture-validator:

```
Task(
  description="Validate architecture against quality standards",
  prompt=`
    Validate the architecture document at .eg/{instance-name}/architecture.md
    
    Use the architecture-validator agent to:
    - Check template compliance
    - Validate technical soundness
    - Ensure all components are properly defined
    - Verify integration points
    - Check security considerations
    - Provide structured feedback
    
    The validator will output PASS/NEEDS_IMPROVEMENT/MAJOR_ISSUES
  `,
  subagent_type="architecture-validator"
)
```

## Step 5: Review and Iterate

If validation result is NEEDS_IMPROVEMENT or MAJOR_ISSUES:
1. Use the validator feedback to improve the architecture
2. Re-run the architect with specific improvements
3. Re-validate until PASS is achieved

## Step 6: Review Architecture

Once validation passes, invoke the architecture reviewer for additional insights:

```
Task(
  description="Review architecture for risks and optimizations",
  prompt=`
    Review the architecture at @.eg/{instance-name}/architecture.md
    
    Validate:
    - Scalability assumptions and patterns
    - Security vulnerabilities and risks
    - Maintainability and operational concerns
    - Alignment with system principles
    - Performance bottlenecks
    - Future extensibility
    
    Provide specific feedback on:
    - Critical risks that must be addressed
    - Optimization opportunities
    - Alternative approaches for problematic areas
    - Missing architectural concerns
    
    If changes are needed, update the architecture document.
  `,
  subagent_type="architecture-reviewer"
)
```

## Step 7: Finalize and Phase Gate

Based on all feedback:
1. Make any necessary final updates to the architecture
2. Present the validated architecture to the user
3. Ask for explicit approval: "The architecture has been validated and is ready. Shall we proceed to the planning phase? (yes/no)"
4. Only proceed to planning after receiving "yes"

Once approved, inform the user that the next step would be:
`/eg:plan {instance-name} @.eg/{instance-name}/architecture.md`