From f2457bffd9d18ae3b0e6d65d13dcca2005c6d6b1 Mon Sep 17 00:00:00 2001
From: Rahul Krishna <rkrsn@ibm.com>
Date: Thu, 6 Aug 2026 09:17:35 -0400
Subject: [PATCH] Add roadmap template next to the issue forms

The roadmap skeleton lived as prose inside a fenced block in a cldk-devtools skill
reference -- not copyable, not where the artifact lands, and with editorial voice
baked into the section headings.

Move it here as a real file, sibling to ISSUE_TEMPLATE/ and CONTRIBUTING, on the
same principle issue bodies already follow: the template lives in the org repo, the
skill links it. Roadmaps are committed to this repo anyway.

Skeleton is placeholders plus a one-line HTML-comment hint per section, so the
guidance disappears when the file is filled in rather than shipping in every copy.
---
 docs/design/roadmap-template.md | 51 +++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/design/roadmap-template.md

diff --git a/docs/design/roadmap-template.md b/docs/design/roadmap-template.md
new file mode 100644
index 0000000..0837ca6
--- /dev/null
+++ b/docs/design/roadmap-template.md
@@ -0,0 +1,51 @@
+# <org or area> roadmap
+
+<!-- Copy this file to docs/design/roadmap.md and fill it in. One roadmap, amended in
+     place — do not add a second. Git history is the record of how thinking changed. -->
+
+**Pass:** <date> · **Planned with:** <who>
+
+## Candidates
+
+<!-- One row per contract decision, not per theme. A theme ("microservice analysis")
+     is several rows. -->
+
+| # | Candidate | Moves schema? | Collision group | Blocked by |
+| - | --------- | ------------- | --------------- | ---------- |
+| 1 | <one line> | <yes — what vocabulary / no> | <A / —> | <# / —> |
+| 2 | <one line> | <> | <> | <> |
+
+## Collision groups
+
+<!-- Candidates touching the same schema vocabulary. Each group is one design session
+     for the shared part, however far apart the candidates ship. -->
+
+- **<A — vocabulary name>**: candidates <#, #>
+  - Decide once: <kinds/fields, and who emits them>
+  - Carried by: <which candidate>
+
+## Dependency order
+
+<!-- What unblocks what. A graph, not a list. -->
+
+    <1> ──▶ <2> ──▶ <3>
+
+## Release trains
+
+| Train | Carries | Notes |
+| ----- | ------- | ----- |
+| <repo x.y.0> | <#> | <schema major? lockstep constraint?> |
+
+## Not now
+
+<!-- Excluded this pass, with the reason. Deleting a row loses the fact it was
+     considered. -->
+
+- <candidate> — <blocked / not yet worth it / superseded / no owner>
+
+## Starting now
+
+<!-- The single candidate entering design mode, and its epic link once filed.
+     Everything else here has no issue yet, by design. -->
+
+- <candidate> — <epic link>