architect

System Architect Command

You are a command wrapper that gathers context and invokes the architect-specialist agent to perform architecture design.

Architecture Context: $ARGUMENTS

Workflow

Phase 1: Parallel Context Gathering

When given an issue number, gather complete context IN PARALLEL:

if [[ "$ARGUMENTS" =~ ^[0-9]+$ ]]; then
  echo "=== Loading Issue #$ARGUMENTS with all context (parallel) ==="
  ISSUE_NUMBER=$ARGUMENTS

  # Run context gathering in parallel for speed
  (
    echo "=== Issue Details ==="
    gh issue view $ARGUMENTS
  ) &

  (
    echo -e "\n=== All Comments (PM requirements, research, etc.) ==="
    gh issue view $ARGUMENTS --comments
  ) &

  (
    echo -e "\n=== Existing Architecture Documentation ==="
    find . -name "*.md" -path "*/docs/*" -o -name "ARCHITECTURE.md" -o -name "CLAUDE.md" 2>/dev/null | head -10
  ) &

  (
    echo -e "\n=== Related PRs ==="
    gh pr list --search "mentions:$ARGUMENTS" --limit 5
  ) &

  # Wait for all parallel context gathering to complete
  wait

else
  # Topic-based architecture (no issue number)
  ISSUE_NUMBER=""
  echo "=== Architecture Topic: $ARGUMENTS ==="
fi

This provides (in parallel):

• Issue details and requirements
• All comments (PM requirements, research, etc.)
• Existing architecture patterns and documentation
• Related PRs for additional context

Codebase Structure Research (Parallel)

Invoke repo-research-analyst in parallel with context gathering to provide codebase structure context before architecture design:

Use the Task tool:

• subagent_type: "psd-coding-system:research:repo-research-analyst"
• description: "Codebase research for architecture #$ISSUE_NUMBER"
• prompt: "Analyze this repository's structure, tech stack, architecture patterns, and conventions. Produce a structured overview to inform architecture design for: $ARGUMENTS. Focus on existing patterns, entry points, dependency graph, and naming conventions."

Feed the codebase research output into Phase 2 architect-specialist invocation as additional context.

Phase 1.5: UX Architecture Guidance (if UI-related)

Check if architecture involves user-facing components and invoke UX specialist for heuristic-based guidance:

# Detect if architecture involves UI components
if [[ "$ARGUMENTS" =~ (component|ui|interface|form|modal|dialog|page|screen|dashboard|menu|navigation|frontend) ]]; then
  echo "=== UI architecture detected - invoking UX specialist for heuristics ==="
  UI_ARCHITECTURE=true
else
  UI_ARCHITECTURE=false
fi

If UI architecture detected, invoke UX specialist BEFORE architect-specialist:

Use the Task tool:

• subagent_type: "psd-coding-system:domain:ux-specialist"
• description: "UX architectural guidance for issue #$ISSUE_NUMBER"
• prompt: "Provide UX architectural guidance for: $ARGUMENTS

Based on 68 usability heuristics, recommend:

1. Component structure that supports user control (H3, H11, H44)
2. State management patterns for feedback and status visibility (H1, H28, H47)
3. Error handling architecture (H5, H9, H66)
4. Accessibility requirements in component design (H40, H61)
5. Navigation and discoverability patterns (H46, H57, H58)
6. Data flow that minimizes cognitive load (H12, H17, H45)

Provide specific architectural patterns and anti-patterns."

Incorporate UX guidance into architecture design.

Phase 2: Invoke Architecture Specialist

Now invoke the architect-specialist agent with all gathered context:

Use the Task tool with:

• subagent_type: "psd-coding-system:domain:architect-specialist"
• description: "Architecture design for issue #$ISSUE_NUMBER" or "Architecture design for: [topic]"
• prompt: Include the full context gathered above plus the original $ARGUMENTS

The agent will return a structured architecture design containing:

1. Executive Summary
2. Design Overview
3. Key Architectural Decisions
4. Component Breakdown
5. API Design (if applicable)
6. Data Model (if applicable)
7. Implementation Steps
8. Testing Strategy
9. Risk Assessment
10. Success Metrics

Phase 3: Post to GitHub Issue

If an issue number was provided, add the architecture design as a comment:

if [ -n "$ISSUE_NUMBER" ]; then
  # Post architecture design to the issue
  gh issue comment $ISSUE_NUMBER --body "## Architecture Design

[Paste the executive summary from architect-specialist]

### Key Decisions
[Paste key decisions]

### Implementation Plan
[Paste implementation steps]

### Full Architecture Design
[Paste complete design from architect-specialist, or link to documentation if very long]

---
*Generated by architect-specialist agent*"

  echo "Architecture design posted to issue #$ISSUE_NUMBER"
else
  # No issue number - just display the design
  echo "Architecture design completed"
fi

Usage Examples

With issue number:

/architect 347
# Loads issue #347, invokes architect-specialist, posts design to issue

With architecture topic:

/architect "Design caching layer for API responses"
# Invokes architect-specialist with topic, displays design

Notes

• This command is a thin wrapper around @agents/architect-specialist
• The agent contains all architecture expertise and patterns
• This command focuses on context gathering and GitHub integration
• For architecture design without GitHub integration, the agent can be invoked directly

Remember: Good architecture enables change. Design for the future, but build for today.