Description

What This Does

This feature introduces the/architecture command—a new (optional) workflow phase that enables users to initialize or refine architecture documentation for their projects. It provides a structured, guided process for creating and maintaining the foundational design documents that serve as a single source of truth for system design decisions, technical constraints, and development patterns. Think of this like the steering docs of Kiro AI, or a companion for the simple AGENTS.md.

Rationale

Architecture documentation is critical for both human developers and AI agents to understand project design decisions and implementation patterns. Previously, the Agentic workflow started with the research phase. Adding an architecture setup phase allows teams to establish a documented foundation before diving into implementation, leading to:

• Better coordination: AI agents and developers have explicit architectural constraints to reference
• Faster onboarding: New team members understand the system design upfront
• Clearer decisions: Design trade-offs and technical choices are documented
• Improved planning: The/plan and/execute commands can reference these documents for alignment
• Flexibility: Supports both new projects (create mode) and existing projects (refine mode)

Feature Capabilities

Two Modes of Operation:

1. Create Mode (for new projects)

   • Guides users through setup with minimal, focused questions
   • Determines which documents are necessary based on project type
   • Generates core documents:overview,system-architecture,domain-model,testing-strategy,development-workflow,persistence
   • Conditionally creates optional documents:api-design,cli-design,event-bus
   • Populates documents with user-provided context
   • The documents are in line with the already present Agentic documentation

2. Refine Mode (for existing projects)

   • Detects existing architecture documentation
   • Analyzes codebase to identify current patterns and structure
   • Compares documentation against implementation
   • Identifies discrepancies and suggests updates
   • Preserves user-added content while updating stale information

Subagent Integration:

• Leverages specialized agents (codebase-locator, codebase-pattern-finder, codebase-analyzer, thoughts-analyzer) for comprehensive analysis: it mimics exactly what is done in the/research command for the logic behind it.
• Executes in three phases during refinement: Locate → Find Patterns → Analyze

Main Changes

New Files

• command/architecture.md (217 lines)
  • Complete command definition with detailed execution logic
  • Comprehensive step-by-step process for both create and refine modes
  • Guidelines for document structure, content strategy, and file management

Updated Files

• docs/commands.md

  • Added/architecture command documentation
  • Included in command reference with syntax, purpose, and process overview

• docs/workflow.md

  • Added "Phase 0: Architecture Setup" as the initial workflow phase
  • Updated workflow overview to reflect new architecture phase
  • Positioned architecture as foundation for research, planning, and execution phases

Documentation Improvements

• Workflow documentation now shows complete lifecycle starting with architecture
• Commands reference updated with comprehensive architecture command details
• Clear explanations of create vs. refine modes help users understand when/how to use the feature
• Integration notes explain how architecture docs are referenced by downstream commands

Technical Details

Design Principles:

• Architecture-agnostic: Works with any project type (web apps, CLI tools, libraries, etc.)
• Minimal friction: Create mode starts with just 2 broad questions
• Incremental: Supports partial documentation with TODO placeholders
• Intelligent: Refine mode analyzes codebase before suggesting updates
• Reversible: Never overwrites without explicit confirmation

Document Structure:
Architecture documents follow a consistent template with:

• Clear purpose statements
• Organized sections with guidance
• TODO checklists for pending decisions
• Related documentation links
• Update timestamps (for refined docs)

User Impact

For New Projects:
Users can now establish architecture documentation early, guiding implementation decisions before code is written.

For Existing Projects:
Users can analyze their codebase and update documentation to reflect current reality, ensuring it remains an accurate reference.

For the Workflow:
Architecture serves as a reference point for/research,/plan, and/execute commands, improving coordination and decision-making throughout development.

Files Changed Summary

• 4 files modified
• 2 new sections added to existing docs
• ~80 lines added to documentation
• Complete architecture command specification (~217 lines)