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
1---2name: adr-roadmap3description: 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.4---5
6# adr-roadmap
7
8## Purpose
9
10Analyze a project's Architecture Decision Records (ADRs, Layer 5) and produce a
11phased implementation roadmap: dependency mapping, critical path, phase
12decomposition, timeline estimates, per-phase risk assessment, and a testing and
13technical-debt strategy. Engine-agnostic — works for any domain (web, mobile,
14data, ML, infrastructure, embedded).
15
16**Upstream**: ADR. **Downstream**: feeds SPEC → TDD → IPLAN delivery sequencing.
17
18## When to Use
19
20Use `adr-roadmap` when:
21
22- A project has roughly five or more ADRs that need coordinated, phased rollout.
23- You need visibility into architectural dependencies and the critical path.
24- Stakeholders need a timeline, milestones, and an executive summary derived
25 from ADR complexity.
26
27Do **not** use it for a single ADR with a trivial implementation, for
28informational ADRs with no build work, when planning from requirements (use
29`../doc-brd/SKILL.md` / `../doc-prd/SKILL.md` / `../doc-ears/SKILL.md`), or when
30you only need diagrams (use `../charts-flow/SKILL.md`).
31
32## Behavior
33
341. **Inventory ADRs** — read every `ADR-*.md`, extract ID, title, status,
35 complexity (1–5), effort, and dependencies; warn on missing complexity or
36 broken dependency references; error if no ADRs are found.
372. **Build the dependency graph** — classify hard / soft / no dependencies,
38 detect cycles (error), compute the critical path, and find clusters that can
39 run in parallel.
403. **Estimate effort** — map complexity to base effort, sum across ADRs, apply a
41 risk buffer (~20%), and flag high-risk ADRs (complexity 4–5 with many deps).
424. **Form phases** — apply the chosen phase model (`poc-mvp-prod` default,
43 `iterative`, or `waterfall`), respecting dependencies, capping phase length
44 (default 8 weeks), isolating risk, and ending phases on natural milestones.
45 Adapt for greenfield, brownfield/migration (add rollback + dual-run), or
46 refactoring (module-by-module) projects.
475. **Build the timeline** — derive phase durations from effort and team size,
48 add inter-phase buffers, and produce a Gantt chart (via
49 `../charts-flow/SKILL.md`) with milestones.
506. **Write the roadmap** at `{adr_dir}/ADR-00_IMPLEMENTATION-ROADMAP.md`:
51 Document Control, executive summary, per-phase sections (objectives, ADRs,
52 architecture diagram, order, deliverables, success/exit criteria, risk),
53 dependency matrix, technical-debt management, risk assessment, testing
54 strategy, and traceability back to upstream (BRD–BDD) and downstream
55 (SPEC/TDD/IPLAN) artifacts.
56
57**Constraints**: use ADR decisions as-is (make no technology choices); map every
58ADR to exactly one phase; never exceed the phase cap; keep language objective;
59require rollback plans for production phases. Keep each document under 100k
60tokens.
61
62## Related Resources
63
64- ADR layer: `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md` ·
65 `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml`
66- ID & tag standards: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
67- Traceability: `${CLAUDE_PLUGIN_ROOT}/framework/governance/TRACEABILITY.md`
68- Diagrams: `../charts-flow/SKILL.md`
69- Downstream generation: `../doc-spec/SKILL.md` · `../doc-tdd/SKILL.md` ·
70 `../doc-iplan/SKILL.md`
71- Traceability check: `../doc-validator/SKILL.md`
vladm3105