| name | adr-roadmap |
| description | Generate a phased implementation roadmap from a set of Architecture Decision Records, with dependencies, timeline, risk, and testing strategy. Use when coordinating delivery of multiple ADRs. |
| metadata | {"tags":["sdd-workflow","utility"],"custom_fields":{"skill_category":"utility","upstream_artifacts":["ADR"],"downstream_artifacts":["SPEC","TDD","IPLAN"],"version":"0.24.0","framework_spec_version":"0.40.0","last_updated":"2026-05-23"}} |
adr-roadmap
Purpose
Analyze a project's Architecture Decision Records (ADRs, Layer 5) and produce a
phased implementation roadmap: dependency mapping, critical path, phase
decomposition, timeline estimates, per-phase risk assessment, and a testing and
technical-debt strategy. Engine-agnostic — works for any domain (web, mobile,
data, ML, infrastructure, embedded).
Upstream: ADR. Downstream: feeds SPEC → TDD → IPLAN delivery sequencing.
When to Use
Use adr-roadmap when:
- A project has roughly five or more ADRs that need coordinated, phased rollout.
- You need visibility into architectural dependencies and the critical path.
- Stakeholders need a timeline, milestones, and an executive summary derived
from ADR complexity.
Do not use it for a single ADR with a trivial implementation, for
informational ADRs with no build work, when planning from requirements (use
../doc-brd/SKILL.md / ../doc-prd/SKILL.md / ../doc-ears/SKILL.md), or when
you only need diagrams (use ../charts-flow/SKILL.md).
Behavior
- Inventory ADRs — read every
ADR-*.md, extract ID, title, status,
complexity (1–5), effort, and dependencies; warn on missing complexity or
broken dependency references; error if no ADRs are found.
- Build the dependency graph — classify hard / soft / no dependencies,
detect cycles (error), compute the critical path, and find clusters that can
run in parallel.
- Estimate effort — map complexity to base effort, sum across ADRs, apply a
risk buffer (~20%), and flag high-risk ADRs (complexity 4–5 with many deps).
- Form phases — apply the chosen phase model (
poc-mvp-prod default,
iterative, or waterfall), respecting dependencies, capping phase length
(default 8 weeks), isolating risk, and ending phases on natural milestones.
Adapt for greenfield, brownfield/migration (add rollback + dual-run), or
refactoring (module-by-module) projects.
- Build the timeline — derive phase durations from effort and team size,
add inter-phase buffers, and produce a Gantt chart (via
../charts-flow/SKILL.md) with milestones.
- Write the roadmap at
{adr_dir}/ADR-00_IMPLEMENTATION-ROADMAP.md:
Document Control, executive summary, per-phase sections (objectives, ADRs,
architecture diagram, order, deliverables, success/exit criteria, risk),
dependency matrix, technical-debt management, risk assessment, testing
strategy, and traceability back to upstream (BRD–BDD) and downstream
(SPEC/TDD/IPLAN) artifacts.
Constraints: use ADR decisions as-is (make no technology choices); map every
ADR to exactly one phase; never exceed the phase cap; keep language objective;
require rollback plans for production phases. Keep each document under 100k
tokens.
Related Resources
- ADR layer:
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md ·
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
- ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
- Traceability:
${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md
- Diagrams:
../charts-flow/SKILL.md
- Downstream generation:
../doc-spec/SKILL.md · ../doc-tdd/SKILL.md ·
../doc-iplan/SKILL.md
- Traceability check:
../doc-validator/SKILL.md
