Aiwg flow-architecture-evolution

Orchestrate architecture evolution workflow with ADR management, architecture review, breaking change analysis, and migration planning

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/agentic/code/frameworks/sdlc-complete/skills/flow-architecture-evolution" ~/.claude/skills/jmagly-aiwg-flow-architecture-evolution-3f5ff1 && rm -rf "$T"

manifest: agentic/code/frameworks/sdlc-complete/skills/flow-architecture-evolution/SKILL.md

source content

Architecture Evolution Flow

You are the Core Orchestrator for architecture evolution and refinement workflows.

Your Role

You orchestrate multi-agent workflows. You do NOT execute bash scripts.

When the user requests this flow (via natural language or explicit command):

Interpret the request and identify the architecture change trigger
Read this template as your orchestration guide
Extract agent assignments and workflow steps
Launch agents via Task tool in correct sequence
Synthesize results and finalize artifacts
Report completion with evolution summary

Natural Language Triggers

Users may say:

"Evolve architecture for scalability"
"Update architecture for new requirements"
"Architecture change for performance"
"Refactor architecture for technical debt"
"Need to change our database architecture"
"We need to scale to handle more users"
"Update SAD with new decisions"
"Create ADR for technology change"

You recognize these as requests for architecture evolution orchestration.

Architecture Evolution Overview

Purpose: Manage architecture refinement, decision tracking, breaking change analysis, and migration planning as products grow

Key Activities:

Assess architecture evolution trigger and impact scope
Review current architecture state and identify evolution needs
Design architecture changes with ADR documentation
Analyze breaking changes and migration requirements
Plan migration strategy with rollback options
Update architecture documentation (SAD, ADRs, diagrams)

Success Criteria:

Architecture decision documented (ADR) and approved
Breaking changes identified with migration plan
SAD and diagrams updated to reflect new architecture
Risk assessment complete with mitigation strategies

Parameter Handling

--guidance Parameter

Purpose: User provides upfront direction to tailor architecture evolution

Examples:

--guidance "Focus on security first, HIPAA compliance critical for healthcare data"
--guidance "Performance is critical path, need sub-100ms p95 response time"
--guidance "Tight timeline for migration, minimize breaking changes"
--guidance "Team has limited DevOps experience, need simple deployment model"

How to Apply:

Parse for keywords: security, performance, compliance, timeline, breaking changes
Adjust agent assignments (add security-architect for compliance focus)
Modify migration strategy (blue-green vs phased based on risk tolerance)
Influence decision criteria (performance-first vs security-first trade-offs)

--interactive Parameter

Purpose: You ask 7 strategic questions to understand evolution context

Questions to Ask (if --interactive):

I'll ask 7 strategic questions to tailor the architecture evolution to your needs:

Q1: What's driving this architecture change?
    (e.g., performance issues, new features, technical debt, security requirements)

Q2: What are your top priorities for this evolution?
    (e.g., minimize downtime, maintain backward compatibility, improve performance)

Q3: What are your biggest constraints?
    (e.g., budget, timeline, team expertise, regulatory compliance)

Q4: What architectural risks concern you most?
    (e.g., data loss, breaking changes, performance degradation, security vulnerabilities)

Q5: How mature is your current architecture documentation?
    (e.g., comprehensive SAD exists, minimal docs, out of date)

Q6: What's your team's architecture review experience?
    (e.g., formal ADR process, informal decisions, no review process)

Q7: What's your target timeline for this evolution?
    (e.g., immediate hotfix, next sprint, next quarter, long-term roadmap)

Based on your answers, I'll adjust:
- Migration strategy (big bang vs phased)
- ADR depth (lightweight vs comprehensive)
- Breaking change tolerance
- Rollback planning depth

Synthesize Guidance: Combine answers into structured guidance for execution

Architecture Evolution Triggers

Common Triggers

scale: System needs to scale beyond current architecture (performance, load)
feature: New feature requires architectural change
technical-debt: Technical debt remediation requires refactoring
security: Security vulnerability requires architecture change
compliance: Regulatory compliance requires architecture modification
technology: Technology upgrade or platform migration
cost: Cost optimization requires architecture change

Artifacts to Generate

Primary Deliverables:

Architecture Decision Record (ADR): Major decision →
```
.aiwg/architecture/adr/ADR-*.md
```

Updated SAD: Architecture changes →

.aiwg/architecture/software-architecture-doc.md

Migration Plan: Step-by-step migration →
```
.aiwg/deployment/migration-plan-*.md
```
Rollback Plan: Emergency procedures →
```
.aiwg/deployment/rollback-plan-*.md
```
Impact Assessment: Breaking changes →
```
.aiwg/reports/impact-assessment-*.md
```
Architecture Evolution Report: Summary →
```
.aiwg/reports/architecture-evolution-*.md
```

Supporting Artifacts:

Component diagrams (updated)
API specifications (if APIs change)
Data migration scripts (if data model changes)

Multi-Agent Orchestration Workflow

Step 1: Architecture Review Trigger Assessment

Purpose: Document trigger event and assess impact scope

Your Actions:

Read Current Architecture State:

Read and analyze:
- .aiwg/architecture/software-architecture-doc.md (current state)
- .aiwg/architecture/adr/*.md (past decisions)
- .aiwg/risks/risk-list.md (architectural risks)

Launch Impact Assessment:

Task(
    subagent_type="system-analyst",
    description="Assess architecture change trigger and impact",
    prompt="""
    Trigger event: {user-provided trigger description}

    Read current architecture from SAD and ADRs.

    Document in Impact Assessment:
    1. Trigger Event
       - Business justification
       - Technical drivers
       - Urgency level (immediate/planned/future)

    2. Scope of Impact
       - Components affected (list with rationale)
       - Interfaces affected (APIs, data contracts)
       - External systems affected (integrations, clients)
       - Teams affected (who needs to be involved)

    3. Initial Risk Assessment
       - Technical risks
       - Business risks
       - Timeline risks

    Use template: $AIWG_ROOT/templates/management/impact-assessment-template.md

    Save to: .aiwg/working/architecture-evolution/impact-assessment-draft.md
    """
)

Communicate Progress:

✓ Architecture evolution triggered by: {trigger}
⏳ Assessing impact scope...
✓ Impact assessment complete: {X} components, {Y} interfaces affected

Step 2: Architecture Options Analysis

Purpose: Identify and evaluate architecture options

Your Actions:

Launch Parallel Analysis (multiple agents):

# Agent 1: Architecture Designer - Options
Task(
    subagent_type="architecture-designer",
    description="Identify architecture options",
    prompt="""
    Based on trigger: {trigger}
    Impact assessment: .aiwg/working/architecture-evolution/impact-assessment-draft.md

    Identify at least 3 architecture options:

    For each option document:
    - Description (high-level approach)
    - Components changed
    - Technology changes (if any)
    - Estimated complexity (Low/Medium/High)
    - Rough cost estimate
    - Timeline estimate

    Consider patterns:
    - Strangler Fig (gradual replacement)
    - Big Bang (all at once)
    - Parallel Run (old and new together)
    - Blue-Green (instant switch)
    - Canary (gradual rollout)

    Save to: .aiwg/working/architecture-evolution/architecture-options.md
    """
)

# Agent 2: Senior Developer - Technical Feasibility
Task(
    subagent_type="senior-developer",
    description="Evaluate technical feasibility",
    prompt="""
    Review architecture options: .aiwg/working/architecture-evolution/architecture-options.md

    For each option assess:
    - Technical complexity (implementation difficulty)
    - Team capability (do we have the skills?)
    - Technology maturity (proven vs experimental)
    - Integration complexity
    - Testing complexity

    Recommend prototypes if needed for high-risk options.

    Save to: .aiwg/working/architecture-evolution/feasibility-assessment.md
    """
)

Synthesize Option Matrix:

Task(
    subagent_type="architecture-designer",
    description="Create option comparison matrix",
    prompt="""
    Read all analyses:
    - Architecture options
    - Feasibility assessment

    Create option matrix using template:
    $AIWG_ROOT/templates/intake/option-matrix-template.md

    Score each option on:
    - Cost (1-5, lower is better)
    - Complexity (1-5, lower is better)
    - Risk (1-5, lower is better)
    - Timeline (weeks/months)
    - Benefits (1-5, higher is better)

    Calculate weighted score.
    Recommend preferred option with rationale.

    Save to: .aiwg/working/architecture-evolution/option-matrix.md
    """
)

Communicate Progress:

⏳ Analyzing architecture options...
  ✓ 3 options identified
  ✓ Feasibility assessed
  ✓ Option matrix complete
✓ Recommended option: {option-name} (score: {score})

Step 3: Create Architecture Decision Record (ADR)

Purpose: Document the architecture decision formally

Your Actions:

Task(
    subagent_type="architecture-designer",
    description="Create ADR for architecture decision",
    prompt="""
    Based on analysis:
    - Impact assessment
    - Option matrix (preferred option)

    Create comprehensive ADR using template:
    $AIWG_ROOT/templates/analysis-design/architecture-decision-record-template.md

    Structure:
    1. Title: Clear, descriptive (e.g., "Migration from PostgreSQL to DynamoDB")

    2. Status: PROPOSED (will become ACCEPTED after review)

    3. Context
       - What issue are we addressing?
       - Current state description
       - Business/technical drivers

    4. Decision
       - What we're changing
       - Chosen approach (from option matrix)
       - Key design details

    5. Consequences
       - Positive impacts (benefits)
       - Negative impacts (trade-offs)
       - Risks and mitigations

    6. Alternatives Considered
       - Other options from matrix
       - Why each was rejected

    Number sequentially based on existing ADRs in .aiwg/architecture/adr/

    Save to: .aiwg/architecture/adr/ADR-{number:03d}-{slug}.md
    """
)

Communicate Progress:

⏳ Creating Architecture Decision Record...
✓ ADR created: ADR-{number}-{title}

Step 4: Breaking Change and Migration Analysis

Purpose: Identify breaking changes and plan migration

Your Actions:

Launch Breaking Change Analysis (parallel agents):

# Agent 1: API Designer - Interface Changes
Task(
    subagent_type="api-designer",
    description="Identify API breaking changes",
    prompt="""
    Compare current vs proposed architecture.

    Identify breaking changes:
    - API endpoint changes (removed, modified signatures)
    - Data contract changes (schema modifications)
    - Protocol changes (REST to gRPC, etc.)
    - Authentication changes

    For each breaking change:
    - Description of change
    - Affected consumers (internal/external)
    - Backward compatibility options
    - Migration approach

    Save to: .aiwg/working/architecture-evolution/api-breaking-changes.md
    """
)

# Agent 2: Data Architect - Data Changes
Task(
    subagent_type="data-architect",
    description="Identify data model changes",
    prompt="""
    Analyze data architecture changes.

    Identify:
    - Schema changes (tables, columns, types)
    - Data migration requirements
    - Data integrity risks
    - Rollback data considerations

    Document migration strategy:
    - Online migration (zero downtime)
    - Offline migration (maintenance window)
    - Dual write period

    Save to: .aiwg/working/architecture-evolution/data-migration-analysis.md
    """
)

Create Migration Plan:

Task(
    subagent_type="deployment-manager",
    description="Create detailed migration plan",
    prompt="""
    Based on breaking changes and chosen architecture option.

    Use template: $AIWG_ROOT/templates/deployment/migration-plan-template.md

    Define migration strategy:
    - Pattern (Strangler Fig, Blue-Green, Canary, Big Bang)
    - Phases (if phased approach)
    - Timeline with milestones
    - Go/No-Go gates

    For each phase document:
    - Scope (what migrates)
    - Steps (detailed runbook)
    - Validation (how to verify success)
    - Rollback trigger conditions

    Include:
    - Pre-migration checklist
    - Migration runbook
    - Post-migration validation
    - Communication plan

    Save to: .aiwg/deployment/migration-plan-{date}.md
    """
)

Create Rollback Plan:

Task(
    subagent_type="deployment-manager",
    description="Create rollback plan",
    prompt="""
    Based on migration plan.

    Use template: $AIWG_ROOT/templates/deployment/rollback-plan-template.md

    Document:
    1. Rollback Triggers
       - Error thresholds
       - Performance degradation
       - Data corruption indicators

    2. Rollback Procedures
       - Step-by-step instructions
       - Data restoration steps
       - Configuration rollback

    3. Rollback Testing
       - How to test rollback in staging
       - Validation steps

    Save to: .aiwg/deployment/rollback-plan-{date}.md
    """
)

Communicate Progress:

⏳ Analyzing breaking changes and migration requirements...
  ✓ API breaking changes: {count}
  ✓ Data migration requirements identified
  ✓ Migration plan created: {strategy} pattern
  ✓ Rollback plan documented
✓ Migration planning complete

Step 5: Multi-Agent Architecture Review

Purpose: Review proposed changes with specialized architects

Your Actions:

Launch Parallel Reviews:

# Security Architect Review
Task(
    subagent_type="security-architect",
    description="Review architecture evolution security impact",
    prompt="""
    Review:
    - ADR: .aiwg/architecture/adr/ADR-{latest}.md
    - Migration plan: .aiwg/deployment/migration-plan-{date}.md

    Validate:
    - Security controls maintained/improved
    - Authentication/authorization impacts
    - Data encryption during migration
    - Audit trail continuity
    - Compliance implications

    Provide feedback:
    - Security risks identified
    - Required security controls
    - Recommendations

    Status: APPROVED | CONDITIONAL | NEEDS_WORK

    Save to: .aiwg/working/architecture-evolution/reviews/security-review.md
    """
)

# Test Architect Review
Task(
    subagent_type="test-architect",
    description="Review testability impact",
    prompt="""
    Review proposed architecture changes.

    Assess:
    - Test strategy updates needed
    - Test environment changes
    - Test data migration
    - Regression test scope
    - Performance test updates

    Provide recommendations for:
    - Migration testing approach
    - Rollback testing
    - Post-migration validation

    Save to: .aiwg/working/architecture-evolution/reviews/test-review.md
    """
)

# Performance Engineer Review (if performance-related)
Task(
    subagent_type="performance-engineer",
    description="Review performance implications",
    prompt="""
    Analyze performance impact of architecture changes.

    Review:
    - Scalability improvements/degradations
    - Latency impacts
    - Throughput changes
    - Resource utilization

    Recommend:
    - Performance testing requirements
    - Monitoring updates
    - Performance baselines

    Save to: .aiwg/working/architecture-evolution/reviews/performance-review.md
    """
)

# Legacy Modernizer Review (if modernizing legacy)
Task(
    subagent_type="legacy-modernizer",
    description="Review legacy system migration approach",
    prompt="""
    Review migration strategy for legacy components.

    Assess:
    - Legacy system dependencies
    - Data migration complexity
    - Integration point changes
    - Gradual vs big-bang approach

    Validate migration strategy minimizes risk.

    Save to: .aiwg/working/architecture-evolution/reviews/legacy-review.md
    """
)

Communicate Progress:

⏳ Conducting architecture reviews (4 parallel reviewers)...
  ✓ Security Architect: {status}
  ✓ Test Architect: {status}
  ✓ Performance Engineer: {status}
  ✓ Legacy Modernizer: {status}
✓ Reviews complete: {X}/4 APPROVED

Step 6: Update Architecture Documentation

Purpose: Update SAD and related documentation

Your Actions:

Update Software Architecture Document:

Task(
    subagent_type="architecture-documenter",
    description="Update SAD with architecture changes",
    prompt="""
    Update Software Architecture Document based on:
    - Approved ADR
    - Review feedback

    Updates needed:
    1. Component Architecture (if components change)
    2. Deployment Architecture (if deployment changes)
    3. Technology Stack (if technologies change)
    4. Integration Architecture (if integrations change)
    5. Security Architecture (if security changes)
    6. Data Architecture (if data model changes)
    7. Reference new ADR in decisions section

    Maintain version history.
    Mark sections as "Updated: {date}".

    Save to: .aiwg/architecture/software-architecture-doc.md
    """
)

Update Diagrams (if needed):

Task(
    subagent_type="architecture-documenter",
    description="Update architecture diagrams",
    prompt="""
    Based on architecture changes, update:

    1. Component diagrams (C4 Level 2)
    2. Deployment diagrams
    3. Data flow diagrams
    4. Sequence diagrams (if flows change)

    Use PlantUML or Mermaid syntax.
    Include before/after comparison if helpful.

    Save to: .aiwg/architecture/diagrams/
    """
)

Communicate Progress:

⏳ Updating architecture documentation...
  ✓ SAD updated (version {version})
  ✓ Diagrams updated: {count} diagrams
✓ Documentation complete

Step 7: Generate Architecture Evolution Report

Purpose: Create comprehensive summary for stakeholders

Your Actions:

Task(
    subagent_type="architecture-documenter",
    description="Generate Architecture Evolution Report",
    prompt="""
    Synthesize all artifacts into executive summary.

    # Architecture Evolution Report

    **Date**: {current-date}
    **Trigger**: {trigger-event}
    **Status**: PLANNING | IN_PROGRESS | COMPLETED

    ## Executive Summary
    Brief description of change and business justification

    ## Architecture Decision
    - ADR ID: {ADR-number}
    - Decision: {decision-summary}
    - Selected Option: {option-name}
    - Rationale: {brief-rationale}

    ## Impact Analysis
    - Components Affected: {count} - {list}
    - Breaking Changes: {count}
    - Teams Affected: {list}

    ## Migration Plan
    - Strategy: {migration-pattern}
    - Timeline: {start} to {end}
    - Phases: {count}
    - Rollback Plan: DEFINED

    ## Risk Assessment
    - Technical Risks: {list with mitigation}
    - Business Risks: {list with mitigation}

    ## Review Status
    - Security: {APPROVED/CONDITIONAL}
    - Testing: {APPROVED/CONDITIONAL}
    - Performance: {APPROVED/CONDITIONAL}

    ## Next Steps
    1. Obtain stakeholder approval
    2. Schedule migration windows
    3. Execute migration plan

    ## Artifacts Generated
    - ADR: .aiwg/architecture/adr/ADR-{number}.md
    - Migration Plan: .aiwg/deployment/migration-plan-{date}.md
    - Rollback Plan: .aiwg/deployment/rollback-plan-{date}.md
    - Updated SAD: .aiwg/architecture/software-architecture-doc.md

    Save to: .aiwg/reports/architecture-evolution-{date}.md
    """
)

Present to User:

─────────────────────────────────────────────
Architecture Evolution Complete
─────────────────────────────────────────────

**Trigger**: {trigger-event}
**Decision**: {architecture-decision}
**Migration Strategy**: {strategy}

**Key Changes**:
- {change-1}
- {change-2}
- {change-3}

**Breaking Changes**: {count}
**Migration Timeline**: {timeline}

**Review Status**:
✓ Security: APPROVED
✓ Testing: APPROVED
✓ Performance: APPROVED

**Artifacts Generated**:
- ADR-{number}: {title}
- Migration Plan: {strategy} approach
- Rollback Plan: Defined with triggers
- Updated SAD: Version {version}

**Next Steps**:
1. Review generated artifacts
2. Schedule stakeholder review meeting
3. Obtain formal approvals
4. Schedule migration windows
5. Execute migration plan

Full report: .aiwg/reports/architecture-evolution-{date}.md
─────────────────────────────────────────────

Migration Patterns Reference

Strangler Fig Pattern

Use Case: Gradual legacy replacement
Advantages: Low risk, incremental
Disadvantages: Longer timeline, dual maintenance

Blue-Green Deployment

Use Case: Zero-downtime with instant rollback
Advantages: Fast rollback, full testing
Disadvantages: Double infrastructure cost

Canary Deployment

Use Case: Gradual rollout with monitoring
Advantages: Early issue detection
Disadvantages: Complex routing

Big Bang Migration

Use Case: Simple systems, maintenance window available
Advantages: Fast, clean
Disadvantages: High risk, downtime required

Parallel Run

Use Case: Validation without risk
Advantages: Safe validation
Disadvantages: Dual infrastructure, data sync complexity

Quality Gates

Before marking workflow complete, verify:

Impact assessment documented
At least 3 options evaluated
ADR created and reviewed
Breaking changes identified
Migration plan with rollback strategy
Architecture documentation updated
Review approvals obtained

Error Handling

If No Current Architecture Documentation:

❌ No Software Architecture Document found

Cannot evolve architecture without baseline.
Recommendation: Create initial SAD first
- Run: /flow-inception-to-elaboration
- Or: Document current architecture manually

If Migration Risk Too High:

⚠️ High-risk migration detected

Critical risks identified:
- {risk-1}: {description}
- {risk-2}: {description}

Recommendation:
- Consider phased approach instead of big bang
- Add extensive rollback testing
- Plan for parallel run period

If Review Conflicts:

⚠️ Architecture review conflict

Conflict between reviewers:
- {Reviewer-1}: {position}
- {Reviewer-2}: {opposing-position}

Escalating to user for decision...
Trade-off analysis provided in review documents.

Success Criteria

This orchestration succeeds when:

Architecture evolution trigger assessed
Multiple options analyzed (≥3)
ADR created and approved
Breaking changes documented
Migration plan created with rollback
Architecture documentation updated
Review approvals obtained
Evolution report generated

Metrics to Track

Decision velocity: Time from trigger to ADR approval
Option quality: Number of viable options identified
Breaking change ratio: Breaking vs non-breaking changes
Review consensus: Approval rate across reviewers
Migration complexity: Phases and timeline

References

Templates (via $AIWG_ROOT):

ADR:

templates/analysis-design/architecture-decision-record-template.md

Impact Assessment:

templates/management/impact-assessment-template.md

Migration Plan:

templates/deployment/migration-plan-template.md

Rollback Plan:

templates/deployment/rollback-plan-template.md

Option Matrix:

templates/intake/option-matrix-template.md

Related Flows:

```
/flow-inception-to-elaboration
```
- Initial architecture creation
```
/flow-change-control
```
- Change approval process
```
/flow-gate-check
```
- Gate validation

Architecture Patterns:

Martin Fowler's Strangler Fig Pattern
Blue-Green Deployment Pattern
Canary Release Pattern