mcpField
A
adr-roadmap

adr-roadmap

github.com/vladm3105Development1765 installsUpdated 1d ago
Repository

About adr-roadmap

A planning skill for teams coordinating multiple Architecture Decision Records (ADRs). It turns them into phased roadmaps with dependencies, effort, timelines, risks, and testing strategy while preserving the decisions already made.

Key features

  1. 01Inventories ADRs and checks dependency references
  2. 02Maps dependencies and computes the critical path
  3. 03Estimates effort and flags high-risk decisions
  4. 04Groups work into dependency-aware phases
  5. 05Builds timelines with milestones
  6. 06Documents risk, testing, and technical-debt strategy

Use cases

  1. 01Planning coordinated implementation of multiple ADRs
  2. 02Presenting phases and timelines to stakeholders
  3. 03Planning rollback and dual-run for migrations
  4. 04Sequencing delivery based on architecture decisions

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill adr-roadmap

After installing, type/adr-roadmapin Claude Code to confirm it loaded.

Details

From the project README

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

  1. 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.
  2. Build the dependency graph — classify hard / soft / no dependencies, detect cycles (error), compute the critical path, and find clusters that can run in parallel.
  3. 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).
  4. 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.
  5. 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.
  6. 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

Comments

Markdown supported