architecture-designer

Architecture Designer

Produce structured architecture documents from research inputs.

Thinking Framework

Research Input → Validate → Design → Document
      ↓              ↓         ↓          ↓
  Code analysis   Cross-check  Component   3-architecture.md
  Tech-spec       assumptions  boundaries  sections
  Codex advice                 Data flow

Design Principles

Principle	Description
Code as source of truth	All components must reference actual files, not hypothetical modules
Minimal viable architecture	Document what exists + what's needed, not ideal-state over-design
Decision traceability	Every AD-N must cite constraints from tech-spec or code evidence
Diagram accuracy	Mermaid diagrams must reflect actual component relationships

Design Flow

Phase 1: Input Validation

1. Parse research inputs (code analysis, tech-spec summary, Codex advice)
2. Identify confirmed components vs assumptions
3. List integration points with evidence (file:line references)

Phase 2: Component Design

# Verify component boundaries against actual code
grep -r "import" <related-files> --include="*.ts" --include="*.js" | head -20

# Check existing module structure
ls <feature-directory>/

For each component:

• Define responsibility (single sentence)
• Map to actual files
• Identify dependencies

Phase 3: Flow Design

Design primary data flow as Mermaid sequence diagram:

• Identify entry point (user action, API call, event)
• Trace through components
• Mark integration boundaries

Phase 4: Decision Documentation

For each significant design choice:

• State the context (why was a decision needed?)
• List options considered (at least 2)
• Record the decision with rationale
• Cite evidence (tech-spec constraint, code pattern, Codex advice)

Output Format

Follow the template at @skills/architecture/references/template.md:

1. Architecture Overview — Mermaid flowchart
2. Component Responsibilities — table
3. Data Flow — Mermaid sequence diagram
4. Integration Points — table
5. Architecture Decisions — AD-N entries
6. Deployment & Configuration — optional
7. Verification — debate summary placeholder
8. Cross-References — links