adr-roadmap

Purpose

Analyze Architecture Decision Records (ADRs) and generate phased implementation roadmaps with timelines, dependencies, resource allocation, and risk assessment for any project type.

Key Capabilities

:

Universal ADR analysis across any domain (web, mobile, data, ML, infrastructure, embedded)

Automatic dependency mapping and critical path identification

Phase decomposition based on complexity, dependencies, and milestones

Timeline estimation with effort calculation and risk buffers

Mermaid diagram generation (dependency graphs, Gantt charts)

Risk assessment per phase

Testing strategy definition

Technical debt tracking

When to Use This Skill

Use adr-roadmap when:

Project has ≥5 ADRs requiring coordinated implementation

Need visibility into architectural dependencies and critical path

Planning multi-phase rollout of architectural decisions

Require timeline estimation from ADR complexity assessments

Stakeholders need executive summary of implementation plan

Managing technical debt and need phased remediation plan

Team needs clear milestone definitions and acceptance criteria

Do NOT use adr-roadmap when:

Single ADR with straightforward implementation (direct implementation)

ADRs are informational only with no implementation needed

Planning from requirements (BRD/PRD) not ADRs → use

project-mngt

skill instead

Need to generate documentation artifacts (SYS/REQ/SPEC) → use

doc-flow

skill instead

Only need architecture diagrams → use

charts-flow

skill instead

Skill Inputs

Required Inputs

Input

Description

Example

adr_directory

Absolute path to ADR markdown files

{project_root}/docs/ADR/

project_context

Project type, team size, timeline constraints

"Trading platform, 5 FTE, 6-month timeline"

Optional Inputs

Input

Description

Default

output_file

Roadmap destination path

{adr_directory}/ADR-00_IMPLEMENTATION-ROADMAP.md

max_phase_duration

Maximum weeks per phase

8 weeks

prioritize_adr

Force specific ADR ID first (e.g., "ADR-02")

None

phase_model

Phasing approach:

poc-mvp-prod

,

iterative

,

waterfall

poc-mvp-prod

team_size

Number of FTE engineers

3

target_phases

Desired number of phases

Auto-calculate

Skill Workflow

Step 1: Analyze ADR Directory

Actions

:

Read all

ADR-*.md

files from specified directory

Extract metadata from each ADR:

ADR ID and title

Status (Proposed, Accepted, Deprecated)

Complexity rating (1-5 scale from Implementation Assessment section)

Effort estimate (from Implementation Assessment section)

Dependencies (from Related Decisions section)

Count total ADRs and validate structure

Identify ADR index file (

ADR-00_index.md

) if present

Identify traceability matrix if present

Validation

:

Warn if any ADR missing complexity rating

Warn if dependency references broken (ADR ID doesn't exist)

Error if no ADRs found in directory

Output

ADR inventory with metadata

Step 2: Build Dependency Graph

Actions

:

Parse "Related Decisions" section from each ADR:

Upstream dependencies (must implement first)

Downstream impacts (will be affected)

Parallel decisions (can implement concurrently)

Create adjacency matrix of ADR dependencies

Detect circular dependencies (error condition)

Calculate critical path (longest dependency chain)

Identify independent ADR clusters (can parallelize)

Dependency Classification

:

Hard dependency

ADR-B requires ADR-A implementation complete

Soft dependency

ADR-B references ADR-A decision but can proceed in parallel

No dependency

ADRs completely independent

Output

:

Dependency matrix (table format)

Mermaid flowchart showing ADR relationships

Critical path highlighted

Step 3: Calculate Complexity Scores

Actions

:

Aggregate complexity ratings per ADR:

Complexity 1-2: Simple (1-2 days effort)

Complexity 3: Moderate (3-5 days effort)

Complexity 4: Complex (1-2 weeks effort)

Complexity 5: Architectural change (3-4 weeks effort)

Sum total effort across all ADRs

Identify high-risk ADRs (complexity 4-5 with many dependencies)

Calculate risk buffer (add 20-30% contingency)

Effort Estimation Formula

:

Total Effort = Σ(ADR Complexity × Base Effort) × Risk Buffer

Base Effort (1=1d, 2=2d, 3=4d, 4=10d, 5=20d)

Risk Buffer = 1.2 (20% contingency)

Output

:

Total effort estimate in person-days

High-risk ADR list

Effort distribution per complexity level

Step 4: Create Phase Structure

Phasing Algorithm

:

Apply selected phase model:

A. POC-MVP-Prod Model (Default)

Phase 1: POC (Proof of Concept)

- Minimal ADRs to validate technical feasibility

- Target: 2-3 weeks

- Criteria: Core integration working end-to-end

Phase 2: MVP (Minimum Viable Product)

- Add multi-user, persistence, basic security

- Target: 4-6 weeks

- Criteria: Production-ready for limited users

Phase 3: Production

- Cloud deployment, full security, monitoring

- Target: 6-8 weeks

- Criteria: Enterprise-grade reliability

Phase 4: Scale & Optimize

- Performance tuning, advanced patterns

- Target: 4-6 weeks

- Criteria: Performance targets met

Phase 5: Advanced Features

- Extended capabilities, continuous improvement

- Target: Ongoing

- Criteria: Feature backlog prioritized

B. Iterative Model

Each iteration (2-4 weeks):

- Select ADR cluster (low dependency)

- Implement and validate

- Integrate with existing system

- Deploy incrementally

C. Waterfall Model

Phase by ADR category:

- Infrastructure ADRs

- Core business logic ADRs

- Integration ADRs

- Optimization ADRs

Phase Assignment Rules

:

Respect dependencies

Upstream ADRs in earlier phases

Balance phase size

Target max_phase_duration (default 8 weeks)

Isolate risk

High-risk ADRs in separate phase or early POC

Enable parallelization

Independent ADRs can be in same phase
Milestone alignment: Phases end at natural milestones (POC, MVP, Beta, GA) Output : Phase definitions (1-N phases) ADR assignments per phase Phase duration estimates Parallel implementation opportunities identified Step 5: Generate Timeline Actions : Calculate phase durations from ADR effort estimates: Phase Duration = (Σ ADR Effort in Phase) / (Team Size × Efficiency Factor) Efficiency Factor = 0.7 (account for meetings, context switching) Add inter-phase buffers: Integration testing: 1 week between major phases Security review: 1-2 weeks before production Stakeholder review: Gates between phases Create Gantt chart (Mermaid format): gantt title ADR Implementation Timeline dateFormat YYYY-MM-DD section Phase 1 POC : p1, 2025-01-15, 3w section Phase 2 MVP : p2, after p1, 6w Identify critical milestones: Go/no-go decision points External dependency dates Release windows Output : Timeline table (phase, start, end, duration) Mermaid Gantt chart Milestone list with dates Step 6: Create Roadmap Document Generate comprehensive roadmap at {output_file} : Document Structure :

ADR Implementation Roadmap

Document Control | Item | Details | |

|

|

Executive Summary

Project overview

Total ADRs: N

Total phases: M

Timeline: X weeks

Team size: Y FTE

Key milestones

Phase 1: [Phase Name]

Objectives

Duration

ADRs to Implement

ADR-XXX: Title

Complexity: N/5

Effort: X hours

Scope: What to implement

Deferred: What to skip

Acceptance Criteria

System Architecture

Mermaid diagram

Implementation Order

Week-by-week breakdown

Deliverables

Success Criteria

Risk Assessment

Exit Criteria

Phase 2: [Phase Name] [Same structure] ...

ADR Dependency Matrix

Mermaid flowchart

Critical path highlighted

Parallel opportunities

Technical Debt Management

POC shortcuts (acceptable)

MVP shortcuts (acceptable)

Production standards (zero tolerance)

Debt remediation timeline

Risk Assessment

Phase 1 risks

Phase 2 risks

Go/no-go thresholds

Testing Strategy

Phase 1: Manual testing only

Phase 2: Automated unit/integration

Phase 3: Security, performance, compliance

Phase 4: Load testing, chaos engineering

Acceptance Criteria

Phase 1 acceptance

Phase 2 acceptance

[Per phase]

Traceability

ADR to Phase mapping table

Phase to Timeline mapping

Upstream sources (BRD, PRD)

Downstream artifacts (SYS, REQ, SPEC)

Document Formatting

:

Use objective, factual language (per CLAUDE.md guidelines)

Include Mermaid diagrams for visualizations

Provide measurable acceptance criteria

Specify complexity ratings (1-5 scale)

Document failure modes and risks

No subjective qualifiers (amazing, easy, powerful)

Token limit: <100,000 tokens per file

Output

Complete roadmap markdown file

Adaptation Guidelines

For Greenfield Projects

Characteristics

:

No existing codebase

Clean slate architecture

Can choose optimal tech stack

Phasing Strategy

:

Front-load infrastructure

Cloud, database, auth decisions first

Establish baseline

Technology stack (ADR-000) in Phase 1

Enable parallelization

Independent modules early

Defer optimization

Performance tuning to later phases

Example Phase Structure

:

Phase 1: Foundation (Tech stack, cloud, database)

Phase 2: Core Features (Business logic ADRs)

Phase 3: Integration (External services, APIs)

Phase 4: Polish (Performance, UX, advanced features)

For Brownfield/Legacy Migration Projects

Characteristics

:

Existing production system

Must maintain backward compatibility

Gradual migration required

Phasing Strategy

:

Phase by risk level

Low-risk changes first for confidence

Maintain compatibility

Each phase independently deployable

Include rollback plans

Every phase has back-out procedure

Dual-run periods

Run old and new systems in parallel

Example Phase Structure

:

Phase 1: Infrastructure Prep (Observability, feature flags)

Phase 2: Low-Risk Migration (Read-only endpoints)

Phase 3: Medium-Risk Migration (Write endpoints with rollback)

Phase 4: High-Risk Migration (Core business logic)

Phase 5: Decommission Legacy (Remove old system)

Migration-Specific Sections to Add

:

Rollback procedures per phase

Data migration strategy

Dual-run validation criteria

Backward compatibility requirements

For Refactoring Projects

Characteristics

:

Improving existing system

No new features

Minimize customer-facing changes

Phasing Strategy

:

Phase by module boundaries

Refactor one component at a time

Continuous deployment

Each phase independently deployable

Minimize disruption

Changes invisible to users

Test extensively

Heavy emphasis on regression testing
Example Phase Structure
:
Phase 1: Test Infrastructure (Add missing tests)
Phase 2: Module A Refactor (Database layer)
Phase 3: Module B Refactor (API layer)
Phase 4: Module C Refactor (Business logic)
Phase 5: Cleanup (Remove deprecated code)
Decision Frameworks
Framework 1: Phase Scope Decisions
When to create a new phase?
Decision tree:
1. Check dependencies:
- New ADRs have no dependencies on current phase? → New phase
- All dependencies in current/prior phases? → Same phase
2. Check complexity threshold:
- Current phase exceeds max_phase_duration (8 weeks)? → New phase
- Under threshold? → Same phase
3. Check risk isolation:
- ADR is high-risk (complexity 4-5)? → Consider separate phase for POC
- Low-medium risk? → Group with similar ADRs
4. Check milestone boundary:
- Natural project milestone (POC, MVP, Beta, GA)? → Phase boundary
- Mid-milestone? → Same phase
Output: Phase boundary decision Framework 2: ADR Sequencing Within Phase Order ADRs by : Priority ranking (highest to lowest): Dependency (hard constraint): Upstream ADRs before downstream Risk (strategic): POC phase: High-risk ADRs first (de-risk early) Production phase: Low-risk ADRs first (build confidence) Complexity (team morale): Mix high and low complexity Business value (stakeholder visibility): High-value features earlier Algorithm : def sequence_adrs ( adrs_in_phase ) :

Step 1: Topological sort by dependencies (must respect)

sorted_by_deps

topological_sort ( adrs_in_phase )

Step 2: Within each dependency level, sort by risk/value

for level in sorted_by_deps : if phase == "POC" : level . sort ( key = lambda adr : adr . risk , reverse = True )

High-risk first

else : level . sort ( key = lambda adr : adr . value , reverse = True )

High-value first

return

flatten

(

sorted_by_deps

)

Output

Ordered ADR sequence per phase

Framework 3: Complexity Scoring

Aggregate ADR complexity

when explicit ratings not available:

Estimation heuristics:

Complexity 1 (Trivial):

- Simple configuration change

- Library upgrade (no breaking changes)

- Documentation update

- Effort: 1 day

Complexity 2 (Simple):

- Add logging/monitoring

- Simple API endpoint

- Basic CRUD operation

- Effort: 2 days

Complexity 3 (Moderate):

- New authentication provider

- Database schema change

- Third-party integration

- Effort: 3-5 days

Complexity 4 (Complex):

- New deployment architecture

- Real-time data processing

- Multi-service integration

- Effort: 1-2 weeks

Complexity 5 (Architectural):

- Cloud provider migration

- Event-driven architecture

- Major technology swap

- Effort: 3-4 weeks

Output

Complexity rating per ADR

Framework 4: Technical Debt Classification

Acceptable shortcuts per phase

:

Phase

Acceptable Shortcuts

Must Have

Remediation Phase

POC

Hardcoded credentials, in-memory data, print logging, no tests, local deployment

Working integration

MVP

Basic error handling, simple caching, minimal monitoring

Multi-user auth, persistence, unit tests

Production

Partial optimization

Full security, monitoring, HA, compliance

Scale

Some manual processes

Performance targets, auto-scaling

Advanced

None (continuous improvement)

All features production-grade

N/A

Output

Technical debt tracking table

Example Usage Scenarios

Example 1: MCP Server Project (27 ADRs)

User Invocation

:

Use the adr-roadmap skill to create implementation roadmap.

Inputs:

- ADR directory: {project_root}/docs/ADR/

- Project context: Interactive Brokers MCP server, 3 developers, POC in 3 weeks

- Phase model: poc-mvp-prod

- Team size: 3

Generate roadmap in {project_root}/docs/ADR/ADR-00_IMPLEMENTATION-ROADMAP.md

Skill Actions

:

Read 27 ADRs from

{project_root}/docs/ADR/

Extract complexity: ADR-02 (4/5), ADR-003 (2/5), etc.

Parse dependencies: ADR-006 depends on ADR-003

Create 5 phases:

Phase 1: POC (ADR-000, 001, 002, 003 partial)

Phase 2: MVP (ADR-006, 010, 012, 004, 013, 020, 007, 023)

Phase 3: Production (ADR-014, 011, 016, 017, 018, 019, 026)

Phase 4: Scale (ADR-009, 008, 005, 021, 025)

Phase 5: Advanced (ADR-015, 022, 024)

Calculate timelines:

POC: 2-3 weeks (80 hours / 3 FTE = 2.7 weeks)

MVP: 4-6 weeks

etc.

Generate Mermaid dependency graph

Create comprehensive roadmap document

Generated Output

:

ADR-00_IMPLEMENTATION-ROADMAP.md

(~1,400 lines)

Example 2: Web App Migration (12 ADRs)

User Invocation

:

Use adr-roadmap skill for microservices migration roadmap.

Inputs:

- ADR directory: {example_project_a}/architecture/decisions/

- Project context: Monolith to microservices migration, 8 developers, 9-month timeline

- Phase model: iterative

- Team size: 8

Generate roadmap in {example_project_a}/architecture/decisions/ADR-00_IMPLEMENTATION-ROADMAP.md

Skill Actions

:

Read 12 migration ADRs

Identify migration ADRs:

ADR-01: Service decomposition strategy

ADR-02: API gateway selection

ADR-003: Service mesh (Istio)

ADR-004: Database-per-service pattern

etc.

Phase by service boundaries (iterative):

Iteration 1: User service (ADR-01, 002, 004)

Iteration 2: Product service (ADR-005, 006)

Iteration 3: Order service (ADR-007, 008)

Iteration 4: Payment service (ADR-009, 010)

Add migration-specific sections:

Dual-run strategy per iteration

Rollback procedures

Data migration plans

Generate roadmap with 4 iterations (2 months each)

Generated Output

Migration roadmap with rollback plans

Example 3: Data Platform (35 ADRs, Large Project)

User Invocation

:

Create 6-month data platform roadmap.

Inputs:

- ADR directory: {example_project_b}/docs/ADR/

- Project context: Real-time analytics platform, 10 engineers, 6-month timeline

- Phase model: waterfall

- Team size: 10

- Target phases: 6

Generate roadmap in {example_project_b}/docs/ADR/ADR-00_IMPLEMENTATION-ROADMAP.md

Skill Actions

:

Read 35 ADRs across data engineering stack

Group ADRs by category:

Ingestion: 8 ADRs (Kafka, Kinesis, CDC)

Storage: 6 ADRs (Data lake, warehouse, lakehouse)

Processing: 10 ADRs (Spark, Flink, DBT)

Serving: 6 ADRs (APIs, caching, query engines)

Orchestration: 5 ADRs (Airflow, monitoring, alerting)

Create 6 monthly phases:

Month 1: Ingestion infrastructure

Month 2: Storage layer

Month 3: Processing pipelines

Month 4: Serving layer

Month 5: Orchestration

Month 6: Optimization & launch

Calculate resource allocation (10 engineers across tracks)

Generate roadmap with parallel work streams

Generated Output

Resource-aware roadmap with 6 phases

Example 4: Embedded Systems (15 ADRs, Hardware Constraints)

User Invocation

:

Create roadmap for IoT device firmware.

Inputs:

- ADR directory: /firmware/docs/adr/

- Project context: IoT sensor firmware, 2 embedded engineers, hardware prototype ready

- Phase model: poc-mvp-prod

- Team size: 2

- Constraints: Hardware prototype available Week 4

Generate roadmap in /firmware/docs/adr/ADR-00_IMPLEMENTATION-ROADMAP.md

Skill Actions

:

Read 15 embedded firmware ADRs

Identify hardware-dependent vs. software-only ADRs

Create phases aligned with hardware milestones:

Phase 1: Software simulation (Weeks 1-3)

Phase 2: Hardware integration (Weeks 4-6, after prototype)

Phase 3: Field testing (Weeks 7-10)

Phase 4: Production firmware (Weeks 11-12)

Add hardware constraint notes

Generate roadmap with hardware dependencies

Generated Output

Hardware-aware roadmap with gated phases

Quality Gates (Definition of Done)

Roadmap document must satisfy:

Completeness

All ADRs from directory included

Every ADR assigned to exactly one phase

All dependencies documented in matrix

Timeline calculated for all phases

Risk assessment completed per phase

Testing strategy defined per phase

Acceptance criteria clear per phase

Traceability section complete

Accuracy

Dependency graph validated (no circular dependencies)

Critical path identified correctly

Effort estimates justified from ADR complexity

Phase durations realistic for team size

Risk ratings aligned with ADR assessments

Quality

Mermaid diagrams render correctly

Language objective and factual (CLAUDE.md compliant)

No subjective claims (amazing, easy, powerful)

Measurable acceptance criteria

Token limit <100,000 per document

Markdown formatting valid

Tables formatted correctly

Usability

Executive summary provides overview

Stakeholders can understand timeline

Engineers can start implementation from roadmap

Clear next actions defined

Go/no-go decision criteria explicit

Skill Constraints

What NOT to Do

Do NOT make technology recommendations

Use ADR decisions as-is

Do NOT skip ADRs

All must be mapped to phases

Do NOT create phases >8 weeks

Break down into smaller phases

Do NOT ignore dependencies

Validate critical path

Do NOT use subjective language

Follow CLAUDE.md guidelines

Do NOT guess complexity

Use ADR ratings or ask for clarification

Do NOT create unrealistic timelines

Account for team size and efficiency

Do NOT skip risk assessment

Every phase requires risk analysis

Do NOT omit rollback plans

Production phases require rollback procedures

Edge Cases to Handle

Missing ADR metadata

:

If complexity rating missing → Estimate from ADR content or default to 3/5

If dependencies missing → Assume independent (warn user)

If effort estimate missing → Calculate from complexity

Circular dependencies

:

Error condition: Roadmap cannot proceed

Action: Report circular dependency chain to user

Resolution: User must update ADRs to break cycle

Zero ADRs found

:

Error condition: No ADRs in directory

Action: Validate directory path, check for different naming convention

Resolution: User provides correct path

Conflicting constraints

:

Example: User wants 3-week POC but ADRs require 6 weeks minimum

Action: Report constraint conflict with calculations

Resolution: User adjusts constraints or reduces POC scope

Output Format Specification

Generated Roadmap Document

File

:

{project}/docs/ADR/ADR-00_IMPLEMENTATION-ROADMAP.md

Size

1,000-2,000 lines (varies by ADR count)
Token Limit: <100,000 tokens Sections (in order): Document Header :

ADR Implementation Roadmap
Document Control
:
Project metadata table (name, version, date, owner, preparer, status)
Document Revision History table (version, date, author, changes, approver)
Table of Contents: Links to all sections Executive Summary : Project overview Total ADRs, phases, timeline Key milestones table Critical success factors Phase Definitions (1 section per phase): Objectives Duration estimate ADRs to implement (with complexity, effort, scope) System architecture diagram (Mermaid) Implementation order (week-by-week) Deliverables Success criteria Risk assessment Exit criteria ADR Dependency Matrix : Mermaid flowchart Critical path highlighted Parallel implementation opportunities Technical Debt Management : Acceptable shortcuts per phase Remediation timeline Debt cost estimation Risk Assessment : Risks per phase (table format) Go/no-go thresholds Testing Strategy : Test approach per phase Coverage goals Test environments Acceptance Criteria : Functional requirements per phase Quality attributes per phase Technical validation Traceability : ADR to Phase mapping table Phase to Timeline mapping Upstream sources Downstream artifacts Related Documentation AI Dev Flow Framework SPEC_DRIVEN_DEVELOPMENT_GUIDE.md - Specification-driven development methodology ID_NAMING_STANDARDS.md - Document ID conventions AI_TOOL_OPTIMIZATION_GUIDE.md - Token limits and optimization

安装

|

|

|

|

|

Executive Summary

Project overview

Total ADRs: N

Total phases: M

Timeline: X weeks

Team size: Y FTE

ADR-XXX: Title

Complexity: N/5

Effort: X hours

Scope: What to implement

Deferred: What to skip

System Architecture

Implementation Order

ADR Dependency Matrix

Mermaid flowchart

Critical path highlighted

Technical Debt Management

POC shortcuts (acceptable)

MVP shortcuts (acceptable)

Production standards (zero tolerance)

Risk Assessment

Phase 1 risks

Phase 2 risks

Testing Strategy

Phase 1: Manual testing only

Phase 2: Automated unit/integration

Phase 3: Security, performance, compliance

Acceptance Criteria

Phase 1 acceptance

Phase 2 acceptance

Traceability

ADR to Phase mapping table

Phase to Timeline mapping

Upstream sources (BRD, PRD)

Step 1: Topological sort by dependencies (must respect)

sorted_by_deps

Step 2: Within each dependency level, sort by risk/value

High-risk first

High-value first