@chriskealley/openroad 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Chris Kealley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# OpenRoad
+
+A companion CLI that connects a project-level roadmap to [OpenSpec](https://openspec.dev/) without forking OpenSpec or modifying its generated skills.
+
+## Requirements
+
+- Node.js 22 or later, with npm and `npx` available.
+- An existing project initialized with OpenSpec. The project must contain `openspec/config.yaml`, `openspec/specs/`, and `openspec/changes/`.
+- At least one supported agent/tool if you want skills installed automatically: Codex, Pi, Claude, or Cursor.
+- Write access to the target project. A global installation may also require permission to write to npm's global package directory.
+
+Initialize OpenSpec in the target project before installing this integration:
+
+```sh
+cd path/to/your-project
+openspec init
+```
+
+## Run with npx
+
+You can run the CLI without installing it globally:
+
+```sh
+npx @chriskealley/openroad init --tools codex,pi,claude,cursor
+```
+
+To install only for Codex, for example:
+
+```sh
+npx @chriskealley/openroad init --tools codex
+```
+
+## Install globally
+
+Install the CLI globally if you plan to use it across several OpenSpec projects:
+
+```sh
+npm install --global @chriskealley/openroad
+```
+
+Then run it from the root of an initialized OpenSpec project:
+
+```sh
+openroad init --tools codex,pi,claude,cursor
+```
+
+If npm reports a permissions error during global installation, configure an npm-managed user-level global directory or use the `npx` option above; avoid running npm with `sudo`.
+
+## What installation changes
+
+If `--tools` is omitted, the CLI detects existing `.codex`, `.pi`, `.claude`, and `.cursor` directories. It then:
+
+- Creates `openspec/roadmap.md` if it does not already exist.
+- Installs the `openroad` and `openroad-next` skills for each selected tool.
+- Adds narrowly scoped context, rules, and archive guidance to `openspec/config.yaml`.
+- Records managed files in `.openroad.json` so updates and removal are safe.
+
+Existing roadmap content is preserved during updates. Removal preserves `openspec/roadmap.md` and removes only this package's exact configuration guidance and managed skill files.
+
+## Commands
+
+```sh
+openroad init
+openroad update
+openroad doctor
+openroad remove
+```
+
+All commands accept `--root <path>`; the default is the current directory. `init` and `update` accept `--tools <comma-separated-list>` using any combination of `codex`, `pi`, `claude`, and `cursor`.
+
+## Roadmap semantics
+
+Lifecycle statuses are `planned`, `ready`, `active`, `done`, and `cancelled`. Only active items have a work state: `available`, `blocked`, or `paused`. Multiple items may be active simultaneously. `openroad-next` selects the eligible ready item with the lowest numeric priority, after checking dependencies, regardless of other blocked or paused active work.
+
+## Development
+
+The CLI is TypeScript compiled to ES modules. Node.js 22 or later is required to build and test; the repository has one runtime dependency (`yaml`) and no build tooling beyond `tsc`.
+
+```sh
+git clone https://github.com/chriskealley/openroad.git
+cd openroad
+npm install
+npm test
+```
+
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | Compile `src/` and `test/` to `dist/` |
+| `npm test` | Build, then run the suite with the Node test runner |
+| `npm run typecheck` | Type-check without emitting output |
+
+Sources live in [src/](src/); `cli.ts` handles argument parsing, `installer.ts` manages the managed-file lifecycle and `.openroad.json` manifest, `config.ts` merges and removes the OpenSpec `config.yaml` guidance, and `roadmap.ts` parses and validates `roadmap.md`. The roadmap template shipped to new projects is [templates/roadmap.md](templates/roadmap.md), and the agent skills are in [skills/](skills/).
+
+Two behaviours are worth preserving when changing the installer or parser, and both are covered by tests: installing and removing must leave an existing `openspec/config.yaml` byte-identical, and the shipped roadmap template must validate cleanly under `openroad doctor`.
+
+To try a change against a real project, pack the tarball and install it rather than linking, so you exercise the same layout users get:
+
+```sh
+npm pack
+npm install --global ./chriskealley-openroad-*.tgz
+```

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { resolve, join } from "node:path";
+import { install, readManifest, remove } from "./installer.js";
+import { validateRoadmap } from "./roadmap.js";
+const VALID_TOOLS = new Set(["codex", "pi", "claude", "cursor"]);
+function usage() {
+    console.log(`openroad <command> [options]\n\nCommands:\n  init      Install roadmap integration\n  update    Refresh managed integration files\n  doctor    Validate installation and roadmap\n  remove    Remove integration (preserves roadmap.md)\n\nOptions:\n  --root <path>       Project root (default: current directory)\n  --tools <list>      Comma-separated: codex,pi,claude,cursor`);
+}
+function option(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+async function main() {
+    const command = process.argv[2];
+    if (!command || command === "--help" || command === "-h")
+        return usage();
+    const root = resolve(option("--root") ?? process.cwd());
+    const toolsText = option("--tools");
+    const tools = toolsText?.split(",").map(value => value.trim());
+    if (tools?.some(tool => !VALID_TOOLS.has(tool)))
+        throw new Error("Unknown tool in --tools; use codex, pi, claude, or cursor");
+    if (command === "init" || command === "update") {
+        if (command === "update" && !await readManifest(root))
+            throw new Error("Not installed; run `openroad init` first");
+        const manifest = await install(root, tools);
+        console.log(`${command === "init" ? "Installed" : "Updated"} OpenRoad for ${manifest.consumers.join(", ") || "no detected skill consumers"}.`);
+    }
+    else if (command === "doctor") {
+        const manifest = await readManifest(root);
+        if (!manifest)
+            throw new Error("Manifest is missing; run `openroad init`");
+        const result = await validateRoadmap(join(root, "openspec/roadmap.md"));
+        if (result.errors.length)
+            throw new Error(`Roadmap validation failed:\n- ${result.errors.join("\n- ")}`);
+        console.log(`Healthy: ${result.items.length} roadmap item(s), ${manifest.consumers.length} skill consumer(s).`);
+    }
+    else if (command === "remove") {
+        await remove(root);
+        console.log("Removed OpenRoad integration. openspec/roadmap.md was preserved.");
+    }
+    else
+        throw new Error(`Unknown command: ${command}`);
+}
+main().catch(error => { console.error(`Error: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; });

package/dist/src/config.d.ts

@@ -0,0 +1,6 @@
+export declare const CONTEXT_LINE = "Roadmap coordination: read openspec/roadmap.md before proposing, applying, or archiving changes. Multiple changes may be active concurrently; lifecycle Status and active Work state are separate.";
+export declare const PROPOSAL_RULE = "Link the proposal to exactly one roadmap item and record the OpenSpec change name on that item when work becomes active.";
+export declare const TASKS_RULE = "Respect roadmap dependencies and blocked or paused work states; do not treat another active change as preventing concurrent work.";
+export declare const ARCHIVE_GUIDANCE = "After a successful archive, mark the linked roadmap item done and clear its active Work state; do not change unrelated roadmap items.";
+export declare function mergeConfig(path: string): Promise<void>;
+export declare function removeConfig(path: string): Promise<void>;

package/dist/src/config.js

@@ -0,0 +1,74 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { parseDocument, YAMLMap, YAMLSeq, Scalar } from "yaml";
+export const CONTEXT_LINE = "Roadmap coordination: read openspec/roadmap.md before proposing, applying, or archiving changes. Multiple changes may be active concurrently; lifecycle Status and active Work state are separate.";
+export const PROPOSAL_RULE = "Link the proposal to exactly one roadmap item and record the OpenSpec change name on that item when work becomes active.";
+export const TASKS_RULE = "Respect roadmap dependencies and blocked or paused work states; do not treat another active change as preventing concurrent work.";
+export const ARCHIVE_GUIDANCE = "After a successful archive, mark the linked roadmap item done and clear its active Work state; do not change unrelated roadmap items.";
+function sequence(doc, values) {
+    const seq = new YAMLSeq();
+    seq.items = values.map(value => new Scalar(value));
+    return seq;
+}
+function addUnique(doc, path, value) {
+    const current = doc.getIn(path, true);
+    if (current instanceof YAMLSeq) {
+        if (!current.items.some(item => String(item.value) === value))
+            current.add(value);
+    }
+    else if (current == null)
+        doc.setIn(path, sequence(doc, [value]));
+    else
+        throw new Error(`Cannot merge config: ${path.join(".")} must be a sequence`);
+}
+export async function mergeConfig(path) {
+    const source = await readFile(path, "utf8");
+    const doc = parseDocument(source);
+    if (doc.errors.length)
+        throw new Error(`Invalid YAML in ${path}: ${doc.errors[0].message}`);
+    if (!(doc.contents instanceof YAMLMap))
+        throw new Error(`Invalid YAML in ${path}: root must be a mapping`);
+    const context = doc.get("context");
+    if (context == null)
+        doc.set("context", CONTEXT_LINE);
+    else if (typeof context === "string" && !context.includes(CONTEXT_LINE))
+        doc.set("context", `${context.trimEnd()}\n${CONTEXT_LINE}${context.endsWith("\n") ? "\n" : ""}`);
+    else if (typeof context !== "string")
+        throw new Error("Cannot merge config: context must be a string");
+    addUnique(doc, ["rules", "proposal"], PROPOSAL_RULE);
+    addUnique(doc, ["rules", "tasks"], TASKS_RULE);
+    addUnique(doc, ["operations", "archive", "guidance"], ARCHIVE_GUIDANCE);
+    await writeFile(path, doc.toString({ lineWidth: 0 }), "utf8");
+}
+function removeFromSequence(doc, path, value) {
+    const current = doc.getIn(path, true);
+    if (current instanceof YAMLSeq)
+        current.items = current.items.filter(item => String(item.value) !== value);
+}
+function pruneEmpty(doc, path) {
+    const node = doc.getIn(path, true);
+    if ((node instanceof YAMLSeq || node instanceof YAMLMap) && node.items.length === 0)
+        doc.deleteIn(path);
+}
+export async function removeConfig(path) {
+    const doc = parseDocument(await readFile(path, "utf8"));
+    const context = doc.get("context");
+    if (typeof context === "string") {
+        const kept = context.split("\n").filter(line => line.trim() !== CONTEXT_LINE).join("\n").trimEnd();
+        // Restore the block scalar exactly as install found it, trailing newline included.
+        if (kept)
+            doc.set("context", context.endsWith("\n") ? `${kept}\n` : kept);
+        else
+            doc.delete("context");
+    }
+    removeFromSequence(doc, ["rules", "proposal"], PROPOSAL_RULE);
+    removeFromSequence(doc, ["rules", "tasks"], TASKS_RULE);
+    removeFromSequence(doc, ["operations", "archive", "guidance"], ARCHIVE_GUIDANCE);
+    // Drop containers left empty so removal restores the config install found, deepest first.
+    pruneEmpty(doc, ["rules", "proposal"]);
+    pruneEmpty(doc, ["rules", "tasks"]);
+    pruneEmpty(doc, ["rules"]);
+    pruneEmpty(doc, ["operations", "archive", "guidance"]);
+    pruneEmpty(doc, ["operations", "archive"]);
+    pruneEmpty(doc, ["operations"]);
+    await writeFile(path, doc.toString({ lineWidth: 0 }), "utf8");
+}

package/dist/src/installer.d.ts

@@ -0,0 +1,6 @@
+import { type Consumer, type Manifest } from "./types.js";
+export declare function isRoadmapEntry(file: string): boolean;
+export declare function detectConsumers(root: string): Promise<Consumer[]>;
+export declare function install(root: string, requested?: Consumer[]): Promise<Manifest>;
+export declare function readManifest(root: string): Promise<Manifest | undefined>;
+export declare function remove(root: string): Promise<void>;

package/dist/src/installer.js

@@ -0,0 +1,93 @@
+import { access, copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mergeConfig, removeConfig } from "./config.js";
+import { MANIFEST_NAME } from "./types.js";
+const CONSUMER_DIRS = {
+    codex: ".codex/skills",
+    pi: ".pi/skills",
+    claude: ".claude/skills",
+    cursor: ".cursor/skills"
+};
+async function exists(path) { try {
+    await access(path);
+    return true;
+}
+catch {
+    return false;
+} }
+const ROADMAP_FILE = "openspec/roadmap.md";
+// Manifests are recorded with POSIX separators so they stay portable and so the
+// roadmap guard in remove() matches on Windows, where relative() yields backslashes.
+function manifestPath(root, target) {
+    return relative(root, target).split(sep).join("/");
+}
+// Exported for tests: the guard that keeps remove() from deleting the roadmap.
+export function isRoadmapEntry(file) {
+    return file.split("\\").join("/") === ROADMAP_FILE;
+}
+function assetRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const built = basename(here) === "src" && basename(dirname(here)) === "dist";
+    return built ? resolve(here, "../..") : resolve(here, "..");
+}
+async function packageVersion() {
+    const packageJson = JSON.parse(await readFile(join(assetRoot(), "package.json"), "utf8"));
+    if (typeof packageJson.version !== "string")
+        throw new Error("Package version is missing from package.json");
+    return packageJson.version;
+}
+export async function detectConsumers(root) {
+    const found = [];
+    for (const [consumer, dir] of Object.entries(CONSUMER_DIRS)) {
+        if (await exists(join(root, dir.split("/")[0])))
+            found.push(consumer);
+    }
+    return found;
+}
+export async function install(root, requested) {
+    const openspec = join(root, "openspec");
+    const config = join(openspec, "config.yaml");
+    if (!await exists(config) || !await exists(join(openspec, "changes")) || !await exists(join(openspec, "specs"))) {
+        throw new Error("OpenSpec is not initialized (expected openspec/config.yaml, specs/, and changes/). Run `openspec init` first.");
+    }
+    const prior = await readManifest(root);
+    const detected = requested ?? await detectConsumers(root);
+    const consumers = [...new Set([...(prior?.consumers ?? []), ...detected])];
+    const files = new Set(prior?.files ?? []);
+    const roadmap = join(openspec, "roadmap.md");
+    if (!await exists(roadmap)) {
+        await copyFile(join(assetRoot(), "templates/roadmap.md"), roadmap);
+    }
+    files.add(manifestPath(root, roadmap));
+    for (const consumer of consumers)
+        for (const skill of ["openroad", "openroad-next"]) {
+            const destination = join(root, CONSUMER_DIRS[consumer], skill, "SKILL.md");
+            await mkdir(dirname(destination), { recursive: true });
+            await copyFile(join(assetRoot(), "skills", skill, "SKILL.md"), destination);
+            files.add(manifestPath(root, destination));
+        }
+    await mergeConfig(config);
+    const manifest = { schemaVersion: 1, packageVersion: await packageVersion(), installedAt: prior?.installedAt ?? new Date().toISOString(), consumers, files: [...files].sort() };
+    await writeFile(join(root, MANIFEST_NAME), JSON.stringify(manifest, null, 2) + "\n");
+    return manifest;
+}
+export async function readManifest(root) {
+    try {
+        return JSON.parse(await readFile(join(root, MANIFEST_NAME), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function remove(root) {
+    const manifest = await readManifest(root);
+    if (!manifest)
+        throw new Error("OpenRoad is not installed (manifest not found)");
+    // toPosix also normalises manifests written by earlier versions on Windows.
+    for (const file of manifest.files)
+        if (!isRoadmapEntry(file))
+            await rm(join(root, file), { force: true });
+    await removeConfig(join(root, "openspec/config.yaml"));
+    await rm(join(root, MANIFEST_NAME), { force: true });
+}

package/dist/src/roadmap.d.ts

@@ -0,0 +1,10 @@
+import type { RoadmapItem } from "./types.js";
+export declare function parseRoadmap(source: string): {
+    items: RoadmapItem[];
+    errors: string[];
+};
+export declare function validateRoadmap(path: string): Promise<{
+    items: RoadmapItem[];
+    errors: string[];
+}>;
+export declare function eligibleReadyItems(items: RoadmapItem[]): RoadmapItem[];

package/dist/src/roadmap.js

@@ -0,0 +1,70 @@
+import { readFile } from "node:fs/promises";
+const STATUSES = new Set(["planned", "ready", "active", "done", "cancelled"]);
+const WORK_STATES = new Set(["available", "blocked", "paused"]);
+export function parseRoadmap(source) {
+    const errors = [];
+    const items = [];
+    const markdown = source.replace(/<!--[\s\S]*?-->/g, "");
+    const headings = [...markdown.matchAll(/^###\s+([A-Za-z][A-Za-z0-9_-]*-\d+)\s+[—-]\s+(.+)$/gm)];
+    const seen = new Set();
+    for (let index = 0; index < headings.length; index++) {
+        const match = headings[index];
+        const id = match[1];
+        const bodyStart = (match.index ?? 0) + match[0].length;
+        const bodyEnd = headings[index + 1]?.index ?? markdown.length;
+        const body = markdown.slice(bodyStart, bodyEnd);
+        const fields = new Map();
+        for (const field of body.matchAll(/^\*\*([^*]+):\*\*[ \t]*(.*?)[ \t]*$/gm)) {
+            fields.set(field[1].trim().toLowerCase(), field[2].trim());
+        }
+        if (seen.has(id))
+            errors.push(`${id}: duplicate roadmap id`);
+        seen.add(id);
+        const status = fields.get("status") ?? "";
+        const workState = fields.get("work state") || undefined;
+        const priorityText = fields.get("priority") ?? "";
+        const priority = Number(priorityText);
+        if (!STATUSES.has(status))
+            errors.push(`${id}: invalid or missing Status`);
+        if (!Number.isInteger(priority) || priority < 0)
+            errors.push(`${id}: Priority must be a non-negative integer`);
+        if (status === "active" && !WORK_STATES.has(workState ?? "")) {
+            errors.push(`${id}: active items require Work state: available, blocked, or paused`);
+        }
+        if (status !== "active" && workState)
+            errors.push(`${id}: Work state is only valid for active items`);
+        if (status === "active" && !fields.get("change"))
+            errors.push(`${id}: active items require Change`);
+        items.push({
+            id,
+            title: match[2].trim(),
+            status: (STATUSES.has(status) ? status : "planned"),
+            workState: WORK_STATES.has(workState ?? "") ? workState : undefined,
+            priority: Number.isInteger(priority) ? priority : 0,
+            change: fields.get("change") || undefined,
+            dependsOn: (fields.get("depends on") ?? "").split(",").map(v => v.trim()).filter(Boolean),
+            blockedBy: fields.get("blocked by") || undefined
+        });
+    }
+    if (headings.length === 0)
+        errors.push("No roadmap items found (expected headings like `### RM-001 — Title`)");
+    const ids = new Set(items.map(item => item.id));
+    for (const item of items)
+        for (const dependency of item.dependsOn) {
+            if (!ids.has(dependency))
+                errors.push(`${item.id}: unknown dependency ${dependency}`);
+            if (dependency === item.id)
+                errors.push(`${item.id}: item cannot depend on itself`);
+        }
+    return { items, errors };
+}
+export async function validateRoadmap(path) {
+    return parseRoadmap(await readFile(path, "utf8"));
+}
+export function eligibleReadyItems(items) {
+    const byId = new Map(items.map(item => [item.id, item]));
+    return items
+        .filter(item => item.status === "ready")
+        .filter(item => item.dependsOn.every(id => byId.get(id)?.status === "done"))
+        .sort((a, b) => a.priority - b.priority || a.id.localeCompare(b.id));
+}

package/dist/src/types.d.ts

@@ -0,0 +1,19 @@
+export declare const MANIFEST_NAME = ".openroad.json";
+export type Consumer = "codex" | "pi" | "claude" | "cursor";
+export interface Manifest {
+    schemaVersion: 1;
+    packageVersion: string;
+    installedAt: string;
+    consumers: Consumer[];
+    files: string[];
+}
+export interface RoadmapItem {
+    id: string;
+    title: string;
+    status: "planned" | "ready" | "active" | "done" | "cancelled";
+    workState?: "available" | "blocked" | "paused";
+    priority: number;
+    change?: string;
+    dependsOn: string[];
+    blockedBy?: string;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export const MANIFEST_NAME = ".openroad.json";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@chriskealley/openroad",
+  "version": "0.1.0",
+  "description": "A roadmap companion for OpenSpec projects",
+  "author": "Chris Kealley",
+  "type": "module",
+  "bin": { "openroad": "dist/src/cli.js" },
+  "files": ["dist/src", "templates", "skills", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test \"dist/test/**/*.test.js\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": ["openspec", "roadmap", "codex", "cli"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chriskealley/openroad.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chriskealley/openroad/issues"
+  },
+  "homepage": "https://github.com/chriskealley/openroad#readme",
+  "engines": { "node": ">=22" },
+  "dependencies": { "yaml": "^2.8.1" },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  },
+  "license": "MIT",
+  "publishConfig": { "access": "public" }
+}

package/skills/openroad/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: openroad
+description: Maintain the project OpenSpec roadmap and keep it synchronized with OpenSpec change lifecycle.
+---
+
+# OpenRoad
+
+Use this skill when the user asks to create, edit, review, or synchronize `openspec/roadmap.md`.
+
+1. Read `openspec/roadmap.md`, `openspec/config.yaml`, and the relevant directories under `openspec/changes/`.
+2. Treat `Status` as lifecycle: `planned`, `ready`, `active`, `done`, or `cancelled`.
+3. Only active items have `Work state`: `available`, `blocked`, or `paused`.
+4. Allow multiple active items. A blocked or paused active item does not prevent work on another eligible item.
+5. Each active item must name its OpenSpec change in `Change`. Never reuse that change for another item.
+6. Preserve stable roadmap IDs and explicit dependencies. Lower numeric `Priority` values rank first.
+7. When an OpenSpec change is successfully archived, mark its linked item `done` and remove `Work state`. Do not infer successful archival merely from intent.
+8. Run `openroad doctor` after edits and fix validation errors.
+
+Do not edit OpenSpec-generated skills or fork an OpenSpec schema for roadmap coordination.

package/skills/openroad-next/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: openroad-next
+description: Select and start the highest-priority eligible ready roadmap item without disrupting concurrent active work.
+---
+
+# OpenRoad next
+
+Use this skill when the user asks what to work on next or asks to start the next roadmap change.
+
+1. Read `openspec/roadmap.md`, validate it with `openroad doctor`, and inspect active OpenSpec changes.
+2. Consider every item whose `Status` is `ready` and whose `Depends on` items are all `done`.
+3. Exclude items already linked to a change and never duplicate an active change.
+4. Select the eligible item with the lowest numeric `Priority`; break ties by roadmap ID.
+5. Existing active items do not prevent selection. In particular, continue past active items whose `Work state` is `blocked` or `paused`.
+6. If no item is eligible, report why and do not manufacture work.
+7. Confirm the selected outcome and derive a short kebab-case change name. Use the installed OpenSpec CLI to create/propose the change according to the project's workflow.
+8. Only after creation succeeds, update the roadmap item to `Status: active`, `Work state: available`, and set `Change` to the created name.
+9. Preserve all unrelated roadmap content and run `openroad doctor`.
+
+Never assume there can be only one active OpenSpec change. Do not patch OpenSpec-generated skills.

package/templates/roadmap.md

@@ -0,0 +1,34 @@
+# OpenRoad
+
+This file coordinates planned work with OpenSpec changes. `Status` is lifecycle; `Work state` only describes whether an active item can proceed. More than one item may be active.
+
+## Status model
+
+- `planned` — captured but not ready to start
+- `ready` — eligible once dependencies are done
+- `active` — has an OpenSpec change; requires `Work state`
+- `done` — shipped and archived
+- `cancelled` — intentionally abandoned
+
+Active work states are `available`, `blocked`, or `paused`. Lower priority numbers run first.
+
+## Items
+
+### RM-001 — Replace with the first roadmap outcome
+
+**Status:** planned
+**Priority:** 100
+**Depends on:**
+
+Describe the outcome, scope, and acceptance signal here.
+
+<!-- Active example:
+### RM-002 — Example active outcome
+
+**Status:** active
+**Work state:** available
+**Priority:** 200
+**Change:** add-example-outcome
+**Depends on:** RM-001
+**Blocked by:**
+-->