Skip to content

Point the roadmap reference at the org template #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rahlk wants to merge 1 commit into
base: main
Choose a base branch
from
+26 −60
Open

Point the roadmap reference at the org template #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "cldk-devtools",
"displayName": "CLDK DevTools",
"description": "The CLDK developer's mode ladder: skills for designing, building, maintaining, and releasing CodeLLM-DevKit — from a language's backend analyzer through the frontend SDKs, plus day-to-day upkeep across the codellm-devkit org.",
"version": "0.4.0",
"version": "0.4.1",
"author": {
"name": "Rahul Krishna",
"email": "i.m.ralk@gmail.com"
Expand Down
10 changes: 10 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,16 @@ All notable changes to the CLDK DevTools plugin are documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.4.1] — 2026-08-06

### 🔧 Changed

- The roadmap skeleton moves to `codellm-devkit/.github` →
`docs/design/roadmap-template.md`, beside the issue forms. It was prose in a fenced
block inside this skill's reference — not copyable, not where the artifact lands,
and carrying editorial voice into every roadmap made from it. The reference now
links the template and keeps only the skill-side rules.

## [0.4.0] — 2026-08-04

### ✨ Added
Expand Down
74 changes: 15 additions & 59 deletions skills/planning-cldk-work/references/roadmap-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,63 +1,19 @@
# Roadmap template
# The roadmap artifact

The artifact `planning-cldk-work` produces. Lives at **`codellm-devkit/.github` →
`docs/design/roadmap.md`**, committed, next to the epics and cross-repo specs it coordinates.
**Template:** `codellm-devkit/.github` → [`docs/design/roadmap-template.md`](https://github.com/codellm-devkit/.github/blob/main/docs/design/roadmap-template.md).
Copy it; do not re-derive the sections here. Same rule as issue bodies — the org repo
owns the shape, this skill owns when and why.

One roadmap per planning pass, amended in place rather than duplicated per quarter — the git
history is the record of how thinking changed, which is exactly what an issue body cannot give you.
**Lands at:** `codellm-devkit/.github` → `docs/design/roadmap.md`, committed, beside the epics and
cross-repo specs it coordinates.

## Template
## Skill-side rules

```markdown
# CLDK roadmap

**Pass:** <date> · **Planned with:** <who>
**Status:** current (supersede by editing, not by adding a second roadmap)

## Candidates

| # | Feature | Moves schema v2? | Collision group | Blocked by |
| - | ------- | ---------------- | --------------- | ---------- |
| 1 | <one line> | yes — <what vocabulary> / no | A | — |
| 2 | <one line> | yes — <same vocabulary> | A | 1 |
| 3 | <one line> | no — SDK surface only | — | 1 |

## Collision groups

Candidates that touch the same schema vocabulary. **Each group is ONE design session for the
shared part**, even where the features ship far apart — the parity clause makes a term coined
twice permanently wrong.

- **Group A — <vocabulary name>**: candidates 1, 2.
<What must be decided once: the kinds/fields, and who emits them.>
Design session: <which candidate carries the decision>.

## Dependency order

<A DAG, not a list. Say what unblocks what and why.>

1 (vocabulary) ──▶ 2 (linking) ──▶ 3 (surface)

## Release trains

| Train | Carries | Notes |
| ----- | ------- | ----- |
| <analyzer x.y.0> | 1 | schema major — SDK pins only once cut |
| <sdk a.b.0> | 3 | after the analyzer release lands |

Candidates sharing a schema major ride **one** migration, not one each.

## Not now

**The list that makes the rest mean something.** What is excluded from this pass, and why.

- <candidate> — <reason: blocked, not worth it yet, superseded, no owner>

## Starting now

<The single feature entering design mode, and its epic link once filed.>
Everything else on this roadmap has no issue yet, by design.
```

Amend in place. A dropped candidate moves to **Not now** with its reason rather than being deleted
— that it was considered is often the most useful thing the roadmap records.
- **One roadmap, amended in place.** Never a second file per quarter — git history is the record of
how thinking changed, which is what makes the doc worth more than an issue.
- **Rows are contract decisions, not themes.** A theme decomposes into several rows before the
collision sweep can compare anything. This is the gate, not a style preference.
- **`Starting now` holds exactly one candidate.** Everything else on the roadmap has no issue yet,
by design — filing ahead is what turns a plan into inventory.
- **Dropped candidates move to `Not now` with a reason**, rather than being deleted. That a thing
was considered and rejected is often the most useful fact the roadmap carries.