@howaboua/opencode-roadmap-plugin 0.1.9 → 0.2.0

package/README.md

@@ -30,14 +30,14 @@ OpenCode installs it automatically on next launch.
 
 ### `createroadmap`
 
-Create or extend a project roadmap.
+Create or extend a project roadmap. Requires a feature list and a short spec for each feature.
 
 ```
-"Create a roadmap for building user auth with login, signup, and password reset"
+"Create a roadmap with features: 1) Auth, 2) Profiles. Specs: Auth uses OAuth and must support password reset; Profiles needs avatar uploads and privacy settings"
 ```
 
-- Features group related work (`"1"`, `"2"`, `"3"`)
-- Actions are concrete tasks (`"1.01"`, `"1.02"`) within features
+- Features group related work (`"1"`, `"2"`, `"3"`) and include a brief spec
+- Actions are markdown task list items (`- [ ] 1.01 ...`) within features
 - New actions always start as `pending`
 - Append-only: existing IDs never change
 
@@ -54,11 +54,11 @@ Before delegating work to Task tool subagents, instruct them to read the roadmap
 
 ### `updateroadmap`
 
-Change action status or description.
+Change action status or description. Each update includes a brief note appended to the updates section.
 
 ```
-"Mark action 1.01 as in_progress"
-"Action 2.03 is completed"
+"Mark action 1.01 as in_progress — Drafted schema notes"
+"Action 2.03 is completed — Added tests for edge cases"
 ```
 
 **Statuses:** `pending` → `in_progress` → `completed` | `cancelled`
@@ -92,8 +92,8 @@ AI: Reads roadmap → sees Feature 1 has 4 actions → uses todowrite for immedi
 
 ## Storage
 
-- **Active:** `roadmap.json` in project root
-- **Archived:** `roadmap.archive.<timestamp>.json` when complete
+- **Active:** Stored as a markdown roadmap alongside the project
+- **Archived:** Snapshot archived when complete
 
 ## License
 

package/dist/src/descriptions/createroadmap.txt

@@ -12,8 +12,8 @@ Structure: Features contain Actions. IDs are immutable once created.
 
 Inputs:
 - feature: short label for the overall roadmap
-- spec: natural-language spec for the overall direction
-- features/actions: structured tasks with numbered IDs
+- spec: natural-language spec for the overall direction (scope, constraints, success criteria)
+- features/actions: structured tasks with numbered IDs and clear, detailed descriptions
 
 Example:
 {

package/dist/src/descriptions/updateroadmap.txt

@@ -7,4 +7,4 @@ Use after completing work on an action. When delegating to Task tool subagents,
 
 Archives roadmap automatically when all actions reach completed.
 
-Input: actionNumber (required), status (optional), description (optional).
+Input: actionNumber (required), note (required), status (optional), description (optional).

package/dist/src/roadmap/document.d.ts

@@ -1,6 +1,6 @@
 /**
  * Parses and renders the roadmap markdown document.
- * Keeps frontmatter simple and the task block machine-readable.
+ * Keeps frontmatter simple and the task list machine-readable.
  * Exposes a narrow API for the storage layer.
  */
 import type { RoadmapDocument } from "../types.js";

package/dist/src/roadmap/document.js

@@ -1,19 +1,25 @@
 import { Roadmap as RoadmapSchema } from "../types.js";
 const FRONTMATTER_START = "---\n";
 const FRONTMATTER_END = "\n---\n";
-const TASK_FENCE = "```json";
-const TASK_FENCE_END = "\n```";
+const TASK_LIST_HEADER = "## Task List";
+const STATUS_MAP = {
+    " ": "pending",
+    x: "completed",
+    X: "completed",
+    "~": "in_progress",
+    "-": "cancelled",
+};
 export const parseDocument = (data) => {
     const { frontmatter, body } = splitFrontmatter(data);
     const { feature, spec } = parseFrontmatter(frontmatter);
-    const roadmap = parseRoadmapBody(body);
+    const roadmap = parseTaskList(body);
     return { feature, spec, roadmap };
 };
 export const buildDocument = (document) => {
     const specValue = document.spec.trimEnd();
     const specLines = specValue === "" ? [""] : specValue.split("\n");
     const specBlock = specLines.map((line) => `  ${line}`).join("\n");
-    const tasks = JSON.stringify(document.roadmap, null, 2);
+    const taskList = buildTaskList(document.roadmap);
     return [
         "---",
         `feature: ${JSON.stringify(document.feature)}`,
@@ -21,12 +27,19 @@ export const buildDocument = (document) => {
         specBlock,
         "---",
         "",
-        TASK_FENCE,
-        tasks,
-        "```",
+        TASK_LIST_HEADER,
         "",
+        taskList,
     ].join("\n");
 };
+export const ensureDocument = (document) => {
+    const validated = RoadmapSchema.parse(document.roadmap);
+    return {
+        feature: document.feature,
+        spec: document.spec,
+        roadmap: validated,
+    };
+};
 const splitFrontmatter = (data) => {
     if (!data.startsWith(FRONTMATTER_START)) {
         throw new Error("Roadmap format is invalid. Missing frontmatter.");
@@ -90,28 +103,97 @@ const normalizeSpec = (lines) => {
     const normalized = lines.map((line) => line.slice(indent));
     return normalized.join("\n").trimEnd();
 };
-const parseRoadmapBody = (body) => {
-    const fenceStart = body.indexOf(TASK_FENCE);
-    if (fenceStart === -1) {
-        throw new Error("Roadmap format is invalid. Missing task block.");
+const parseTaskList = (body) => {
+    const lines = body.split("\n");
+    const features = [];
+    let currentFeature = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed === TASK_LIST_HEADER) {
+            continue;
+        }
+        const featureMatch = trimmed.match(/^#+\s*Feature\s+(\d+)\s*:\s*(.+)$/);
+        if (featureMatch) {
+            if (currentFeature) {
+                features.push(currentFeature);
+            }
+            currentFeature = {
+                number: featureMatch[1],
+                title: featureMatch[2].trim(),
+                description: "",
+                actions: [],
+            };
+            continue;
+        }
+        const descriptionMatch = trimmed.match(/^Description:\s*(.+)$/);
+        if (descriptionMatch) {
+            if (!currentFeature) {
+                throw new Error("Roadmap format is invalid. Description must follow a feature header.");
+            }
+            currentFeature.description = descriptionMatch[1].trim();
+            continue;
+        }
+        const actionMatch = trimmed.match(/^-\s*\[([ xX~-])\]\s+(\d+\.\d{2})\s+(.+)$/);
+        if (actionMatch) {
+            if (!currentFeature) {
+                throw new Error("Roadmap format is invalid. Action must follow a feature header.");
+            }
+            const statusToken = actionMatch[1];
+            const status = STATUS_MAP[statusToken];
+            if (!status) {
+                throw new Error("Roadmap format is invalid. Unsupported status marker.");
+            }
+            const number = actionMatch[2];
+            const numberPrefix = number.split(".")[0];
+            if (numberPrefix !== currentFeature.number) {
+                throw new Error(`Action "${number}" does not belong to feature "${currentFeature.number}".`);
+            }
+            currentFeature.actions.push({
+                number,
+                description: actionMatch[3].trim(),
+                status,
+            });
+            continue;
+        }
     }
-    const jsonStart = body.indexOf("\n", fenceStart + TASK_FENCE.length);
-    if (jsonStart === -1) {
-        throw new Error("Roadmap format is invalid. Task block is incomplete.");
+    if (currentFeature) {
+        features.push(currentFeature);
     }
-    const fenceEnd = body.indexOf(TASK_FENCE_END, jsonStart + 1);
-    if (fenceEnd === -1) {
-        throw new Error("Roadmap format is invalid. Task block is not closed.");
+    if (features.length === 0) {
+        throw new Error("Roadmap format is invalid. Missing task list.");
+    }
+    for (const feature of features) {
+        if (!feature.description) {
+            throw new Error(`Feature "${feature.number}" is missing a description.`);
+        }
+        if (feature.actions.length === 0) {
+            throw new Error(`Feature "${feature.number}" must include at least one action.`);
+        }
     }
-    const jsonText = body.slice(jsonStart + 1, fenceEnd).trim();
-    const parsed = JSON.parse(jsonText);
-    return RoadmapSchema.parse(parsed);
+    return RoadmapSchema.parse({ features });
 };
-export const ensureDocument = (document) => {
-    const validated = RoadmapSchema.parse(document.roadmap);
-    return {
-        feature: document.feature,
-        spec: document.spec,
-        roadmap: validated,
-    };
+const buildTaskList = (roadmap) => {
+    const lines = [];
+    for (const feature of roadmap.features) {
+        lines.push(`### Feature ${feature.number}: ${feature.title}`);
+        lines.push(`Description: ${feature.description}`);
+        for (const action of feature.actions) {
+            lines.push(`${renderAction(action.status)} ${action.number} ${action.description}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+};
+const renderAction = (status) => {
+    switch (status) {
+        case "completed":
+            return "- [x]";
+        case "in_progress":
+            return "- [~]";
+        case "cancelled":
+            return "- [-]";
+        case "pending":
+        default:
+            return "- [ ]";
+    }
 };

package/dist/src/tools/updateroadmap.js

@@ -20,6 +20,7 @@ export async function createUpdateRoadmapTool(directory) {
                 .enum(["pending", "in_progress", "completed", "cancelled"])
                 .optional()
                 .describe("New action status. Flexible transitions allowed except from cancelled."),
+            note: tool.schema.string().describe("Required update note to append to the action."),
         },
         async execute(args) {
             const storage = new FileStorage(directory);
@@ -54,6 +55,10 @@ export async function createUpdateRoadmapTool(directory) {
                 if (args.description === undefined && args.status === undefined) {
                     throw new Error("No changes specified. Please provide description and/or status.");
                 }
+                const noteError = RoadmapValidator.validateDescription(args.note, "action");
+                if (noteError) {
+                    throw new Error(`${noteError.message}`);
+                }
                 const oldStatus = targetAction.status;
                 const oldDescription = targetAction.description;
                 // Validate description if provided
@@ -64,6 +69,7 @@ export async function createUpdateRoadmapTool(directory) {
                     }
                     targetAction.description = args.description;
                 }
+                targetAction.description = `${targetAction.description} (note: ${args.note})`;
                 // Validate and update status if provided
                 if (args.status !== undefined) {
                     const statusTransitionError = RoadmapValidator.validateStatusProgression(targetAction.status, args.status);
@@ -79,6 +85,9 @@ export async function createUpdateRoadmapTool(directory) {
                 if (args.status !== undefined && oldStatus !== args.status) {
                     changes.push(`status: "${oldStatus}" → "${args.status}"`);
                 }
+                if (oldDescription !== targetAction.description) {
+                    changes.push("note added");
+                }
                 if (changes.length === 0) {
                     return {
                         document: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howaboua/opencode-roadmap-plugin",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Strategic roadmap planning and multi-agent coordination for OpenCode",
   "type": "module",
   "main": "./dist/index.js",