@howaboua/opencode-roadmap-plugin 0.1.7 → 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

@@ -1,20 +1,24 @@
-Establish a durable project roadmap saved to disk. Provides shared context across sessions and Task tool subagents.
+Establish a durable project roadmap with a high-level spec and task list. Provides shared context across sessions and Task tool subagents.
 
 Use when:
-- User says "roadmap", "plan the project", "phases", or "milestones"  
-- Work will be delegated to Task tool subagents that need shared context
+- After a heavy planning session to lock in the spec and task list
+- When launching Task tool subagents that need shared context
+- User says "roadmap", "plan the project", "phases", or "milestones"
 - Deliverables group naturally into distinct features
 
-When launching Task tool subagents, instruct them to call readroadmap first to understand their work within the broader plan.
+When launching Task tool subagents, explicitly instruct them to: (1) call readroadmap first, and (2) call updateroadmap to mark their action in_progress at start and completed at finish with a short note.
 
 Structure: Features contain Actions. IDs are immutable once created.
 
-Format:
-- Feature: number "1", "2", title, description
-- Action: number "1.01", "1.02" (prefix matches parent feature), description, status "pending"
+Inputs:
+- feature: short label for the overall roadmap
+- spec: natural-language spec for the overall direction (scope, constraints, success criteria)
+- features/actions: structured tasks with numbered IDs and clear, detailed descriptions
 
 Example:
 {
+  "feature": "Core",
+  "spec": "Build the core workflow and key integrations.",
   "features": [{
     "number": "1", "title": "Auth", "description": "User authentication system",
     "actions": [

package/dist/src/descriptions/readroadmap.txt

@@ -1,8 +1,8 @@
-Load the persisted roadmap from disk to understand project state.
+Load the persisted roadmap to understand project state.
 
 When to use:
-1. Before starting a major feature - read roadmap first, then plan immediate steps with todowrite
-2. When launching Task tool subagents - instruct them to call readroadmap to understand their assigned work
+1. Before starting a major feature - call readroadmap first, then plan immediate steps with todowrite
+2. When launching Task tool subagents - explicitly instruct them to call readroadmap before doing any work, then updateroadmap when they start and finish
 3. To check overall progress across features
 
 Concurrent work awareness:

package/dist/src/descriptions/updateroadmap.txt

@@ -3,8 +3,8 @@ Advance action state within the persisted roadmap.
 Statuses: pending, in_progress, completed, cancelled
 Transitions: Flexible (can revert if needed), except cancelled is terminal.
 
-Update after completing work on an action. When delegating to Task tool subagents, instruct them to call updateroadmap when they finish their assigned action.
+Use after completing work on an action. When delegating to Task tool subagents, explicitly instruct them to call updateroadmap at start (set in_progress) and at finish (set completed with a short note).
 
 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/errors/roadmap_corrupted.txt

@@ -1 +1 @@
-Roadmap file is corrupted or unreadable. Ask user to check roadmap.json file.
+Roadmap data is corrupted or unreadable. Ask user to recreate the roadmap.

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

@@ -0,0 +1,9 @@
+/**
+ * Parses and renders the roadmap markdown document.
+ * Keeps frontmatter simple and the task list machine-readable.
+ * Exposes a narrow API for the storage layer.
+ */
+import type { RoadmapDocument } from "../types.js";
+export declare const parseDocument: (data: string) => RoadmapDocument;
+export declare const buildDocument: (document: RoadmapDocument) => string;
+export declare const ensureDocument: (document: RoadmapDocument) => RoadmapDocument;

package/dist/src/roadmap/document.js

@@ -0,0 +1,199 @@
+import { Roadmap as RoadmapSchema } from "../types.js";
+const FRONTMATTER_START = "---\n";
+const FRONTMATTER_END = "\n---\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 = 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 taskList = buildTaskList(document.roadmap);
+    return [
+        "---",
+        `feature: ${JSON.stringify(document.feature)}`,
+        "spec: |",
+        specBlock,
+        "---",
+        "",
+        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.");
+    }
+    const endIndex = data.indexOf(FRONTMATTER_END, FRONTMATTER_START.length);
+    if (endIndex === -1) {
+        throw new Error("Roadmap format is invalid. Frontmatter is not closed.");
+    }
+    const frontmatter = data.slice(FRONTMATTER_START.length, endIndex);
+    const body = data.slice(endIndex + FRONTMATTER_END.length);
+    return { frontmatter, body };
+};
+const parseFrontmatter = (frontmatter) => {
+    const lines = frontmatter.split("\n");
+    let feature = null;
+    let specStart = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.startsWith("feature:")) {
+            feature = parseScalar(line.slice("feature:".length));
+        }
+        if (line.startsWith("spec:")) {
+            if (line.trim() !== "spec: |") {
+                throw new Error("Roadmap format is invalid. Spec must use a block value.");
+            }
+            specStart = i;
+        }
+    }
+    if (!feature) {
+        throw new Error("Roadmap format is invalid. Missing feature.");
+    }
+    if (specStart === -1) {
+        throw new Error("Roadmap format is invalid. Missing spec.");
+    }
+    const specLines = lines.slice(specStart + 1);
+    const spec = normalizeSpec(specLines);
+    return { feature, spec };
+};
+const parseScalar = (value) => {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1);
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+};
+const normalizeSpec = (lines) => {
+    if (lines.length === 0) {
+        return "";
+    }
+    const nonEmpty = lines.filter((line) => line.trim() !== "");
+    const indent = nonEmpty.length === 0
+        ? 0
+        : nonEmpty.reduce((min, line) => {
+            const match = line.match(/^\s+/);
+            const count = match ? match[0].length : 0;
+            return Math.min(min, count);
+        }, Number.MAX_SAFE_INTEGER);
+    const normalized = lines.map((line) => line.slice(indent));
+    return normalized.join("\n").trimEnd();
+};
+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;
+        }
+    }
+    if (currentFeature) {
+        features.push(currentFeature);
+    }
+    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.`);
+        }
+    }
+    return RoadmapSchema.parse({ features });
+};
+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/roadmap/files.d.ts

@@ -0,0 +1,4 @@
+export declare const ensureRoadmapDir: (base: string) => Promise<void>;
+export declare const readRoadmapFile: (base: string) => Promise<string>;
+export declare const writeRoadmapFile: (base: string, data: string) => Promise<void>;
+export declare const archiveRoadmapFile: (base: string) => Promise<string>;

package/dist/src/roadmap/files.js

@@ -0,0 +1,49 @@
+/**
+ * Handles roadmap file IO with atomic writes.
+ * Keeps filesystem concerns separate from document parsing.
+ */
+import { promises as fs } from "fs";
+import { roadmapDir, roadmapPath, tempPath } from "./paths.js";
+export const ensureRoadmapDir = async (base) => {
+    await fs.mkdir(roadmapDir(base), { recursive: true }).catch(() => { });
+};
+export const readRoadmapFile = async (base) => {
+    return await fs.readFile(roadmapPath(base), "utf-8");
+};
+const fsyncDir = async (dir) => {
+    const handle = await fs.open(dir, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+};
+export const writeRoadmapFile = async (base, data) => {
+    const suffix = `${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    const temp = tempPath(base, suffix);
+    const handle = await fs.open(temp, "w");
+    try {
+        await handle.writeFile(data, "utf-8");
+        await handle.sync();
+        await handle.close();
+        await fs.rename(temp, roadmapPath(base));
+        await fsyncDir(roadmapDir(base));
+    }
+    catch (error) {
+        await handle.close().catch(() => { });
+        await fs.unlink(temp).catch(() => { });
+        if (error instanceof Error) {
+            throw error;
+        }
+        throw new Error("Unknown error while persisting roadmap");
+    }
+};
+export const archiveRoadmapFile = async (base) => {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const archiveFilename = `roadmap.archive.${timestamp}.md`;
+    const archivePath = `${roadmapDir(base)}/${archiveFilename}`;
+    await fs.rename(roadmapPath(base), archivePath);
+    await fsyncDir(roadmapDir(base));
+    return archiveFilename;
+};

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

@@ -0,0 +1 @@
+export declare const acquireLock: (base: string) => Promise<() => Promise<void>>;

package/dist/src/roadmap/lock.js

@@ -0,0 +1,33 @@
+/**
+ * Provides exclusive access for roadmap operations.
+ * Uses a lock file with stale detection to avoid deadlocks.
+ */
+import { promises as fs } from "fs";
+import { lockPath } from "./paths.js";
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_RETRY_MS = 50;
+const LOCK_STALE_MS = 30000;
+export const acquireLock = async (base) => {
+    const path = lockPath(base);
+    const start = Date.now();
+    while (Date.now() - start < LOCK_TIMEOUT_MS) {
+        try {
+            await fs.writeFile(path, String(process.pid), { flag: "wx" });
+            return async () => {
+                await fs.unlink(path).catch(() => { });
+            };
+        }
+        catch {
+            const isStale = await fs
+                .stat(path)
+                .then((stat) => Date.now() - stat.mtimeMs > LOCK_STALE_MS)
+                .catch(() => false);
+            if (isStale) {
+                await fs.unlink(path).catch(() => { });
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+        }
+    }
+    throw new Error("Could not acquire lock on roadmap data. Another operation may be in progress.");
+};

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

@@ -0,0 +1,7 @@
+export declare const ROADMAP_DIR = "roadmap";
+export declare const ROADMAP_FILE = "roadmap.md";
+export declare const LOCK_FILE = "roadmap.md.lock";
+export declare const roadmapDir: (base: string) => string;
+export declare const roadmapPath: (base: string) => string;
+export declare const lockPath: (base: string) => string;
+export declare const tempPath: (base: string, suffix: string) => string;

package/dist/src/roadmap/paths.js

@@ -0,0 +1,12 @@
+/**
+ * Centralizes file naming for the roadmap document.
+ * Keeps path logic consistent across storage helpers.
+ */
+import { join } from "path";
+export const ROADMAP_DIR = "roadmap";
+export const ROADMAP_FILE = "roadmap.md";
+export const LOCK_FILE = `${ROADMAP_FILE}.lock`;
+export const roadmapDir = (base) => join(base, ROADMAP_DIR);
+export const roadmapPath = (base) => join(roadmapDir(base), ROADMAP_FILE);
+export const lockPath = (base) => join(roadmapDir(base), LOCK_FILE);
+export const tempPath = (base, suffix) => join(roadmapDir(base), `${ROADMAP_FILE}.tmp.${suffix}`);

package/dist/src/storage.d.ts

@@ -1,6 +1,6 @@
-import type { Roadmap, RoadmapStorage, ValidationError } from "./types.js";
+import type { RoadmapDocument, RoadmapStorage } from "./types.js";
 type UpdateResult<T> = {
-    roadmap: Roadmap;
+    document: RoadmapDocument;
     buildResult: (archiveName: string | null) => T;
     archive?: boolean;
 };
@@ -8,30 +8,10 @@ export declare class FileStorage implements RoadmapStorage {
     private readonly directory;
     constructor(directory: string);
     exists(): Promise<boolean>;
-    read(): Promise<Roadmap | null>;
-    private readFromDisk;
-    private acquireLock;
-    private fsyncDir;
-    private writeAtomic;
-    private archiveUnlocked;
-    write(roadmap: Roadmap): Promise<void>;
-    update<T>(fn: (current: Roadmap | null) => Promise<UpdateResult<T>> | UpdateResult<T>): Promise<T>;
+    read(): Promise<RoadmapDocument | null>;
+    write(document: RoadmapDocument): Promise<void>;
+    update<T>(fn: (current: RoadmapDocument | null) => Promise<UpdateResult<T>> | UpdateResult<T>): Promise<T>;
     archive(): Promise<string>;
-}
-export declare class RoadmapValidator {
-    static validateFeatureNumber(number: string): ValidationError | null;
-    static validateActionNumber(number: string): ValidationError | null;
-    static validateActionSequence(actions: {
-        number: string;
-    }[], globalSeenNumbers?: Set<string>, featureNumber?: string): ValidationError[];
-    static validateFeatureSequence(features: {
-        number: string;
-        actions: {
-            number: string;
-        }[];
-    }[]): ValidationError[];
-    static validateTitle(title: string, fieldType: "feature" | "action"): ValidationError | null;
-    static validateDescription(description: string, fieldType: "feature" | "action"): ValidationError | null;
-    static validateStatusProgression(currentStatus: string, newStatus: string): ValidationError | null;
+    private readFromDisk;
 }
 export {};

package/dist/src/storage.js

@@ -1,16 +1,14 @@
 /**
- * File-based storage for roadmap data with atomic writes and validation.
- * Handles concurrent access via file locking and provides safe read/write operations.
+ * Persists the roadmap document with locking and atomic writes.
+ * Delegates parsing and formatting to the document helpers.
+ * Keeps IO logic focused on concurrency and filesystem safety.
  */
 import { promises as fs } from "fs";
-import { join } from "path";
 import { z } from "zod";
-import { Roadmap as RoadmapSchema } from "./types.js";
-const ROADMAP_FILE = "roadmap.json";
-const LOCK_FILE = `${ROADMAP_FILE}.lock`;
-const LOCK_TIMEOUT_MS = 5000;
-const LOCK_RETRY_MS = 50;
-const LOCK_STALE_MS = 30000;
+import { parseDocument, buildDocument, ensureDocument } from "./roadmap/document.js";
+import { acquireLock } from "./roadmap/lock.js";
+import { ensureRoadmapDir, readRoadmapFile, writeRoadmapFile, archiveRoadmapFile } from "./roadmap/files.js";
+import { roadmapPath } from "./roadmap/paths.js";
 export class FileStorage {
     directory;
     constructor(directory) {
@@ -18,7 +16,7 @@ export class FileStorage {
     }
     async exists() {
         try {
-            await fs.access(join(this.directory, ROADMAP_FILE));
+            await fs.access(roadmapPath(this.directory));
             return true;
         }
         catch {
@@ -28,118 +26,26 @@ export class FileStorage {
     async read() {
         return this.readFromDisk();
     }
-    async readFromDisk() {
-        try {
-            const filePath = join(this.directory, ROADMAP_FILE);
-            const data = await fs.readFile(filePath, "utf-8");
-            if (!data.trim()) {
-                return null;
-            }
-            const parsed = JSON.parse(data);
-            const validated = RoadmapSchema.parse(parsed);
-            return validated;
-        }
-        catch (error) {
-            if (error instanceof SyntaxError) {
-                throw new Error("Roadmap file contains invalid JSON. File may be corrupted.");
-            }
-            if (error instanceof z.ZodError) {
-                const issues = error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
-                throw new Error(`Roadmap file has invalid structure: ${issues}`);
-            }
-            if (error instanceof Error && error.message.includes("ENOENT")) {
-                return null;
-            }
-            if (error instanceof Error) {
-                throw error;
-            }
-            throw new Error("Unknown error while reading roadmap");
-        }
-    }
-    async acquireLock() {
-        const lockPath = join(this.directory, LOCK_FILE);
-        const start = Date.now();
-        while (Date.now() - start < LOCK_TIMEOUT_MS) {
-            try {
-                await fs.writeFile(lockPath, String(process.pid), { flag: "wx" });
-                return async () => {
-                    await fs.unlink(lockPath).catch(() => { });
-                };
-            }
-            catch {
-                const isStale = await fs
-                    .stat(lockPath)
-                    .then((stat) => Date.now() - stat.mtimeMs > LOCK_STALE_MS)
-                    .catch(() => false);
-                if (isStale) {
-                    await fs.unlink(lockPath).catch(() => { });
-                    continue;
-                }
-                await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
-            }
-        }
-        throw new Error("Could not acquire lock on roadmap file. Another operation may be in progress.");
-    }
-    async fsyncDir() {
-        const handle = await fs.open(this.directory, "r");
-        try {
-            await handle.sync();
-        }
-        finally {
-            await handle.close().catch(() => { });
-        }
-    }
-    async writeAtomic(filePath, data) {
-        const randomSuffix = Math.random().toString(36).slice(2, 8);
-        const tempPath = join(this.directory, `${ROADMAP_FILE}.tmp.${Date.now()}.${randomSuffix}`);
-        const handle = await fs.open(tempPath, "w");
-        try {
-            await handle.writeFile(data, "utf-8");
-            await handle.sync();
-            await handle.close();
-            await fs.rename(tempPath, filePath);
-            await this.fsyncDir();
-        }
-        catch (error) {
-            await handle.close().catch(() => { });
-            await fs.unlink(tempPath).catch(() => { });
-            if (error instanceof Error) {
-                throw error;
-            }
-            throw new Error("Unknown error while writing roadmap");
-        }
-    }
-    async archiveUnlocked() {
-        const filePath = join(this.directory, ROADMAP_FILE);
-        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const archiveFilename = `roadmap.archive.${timestamp}.json`;
-        const archivePath = join(this.directory, archiveFilename);
-        await fs.rename(filePath, archivePath);
-        await this.fsyncDir();
-        return archiveFilename;
-    }
-    async write(roadmap) {
-        await fs.mkdir(this.directory, { recursive: true }).catch(() => { });
-        const unlock = await this.acquireLock();
+    async write(document) {
+        await ensureRoadmapDir(this.directory);
+        const unlock = await acquireLock(this.directory);
         try {
-            const data = JSON.stringify(roadmap, null, 2);
-            const filePath = join(this.directory, ROADMAP_FILE);
-            await this.writeAtomic(filePath, data);
+            const data = buildDocument(ensureDocument(document));
+            await writeRoadmapFile(this.directory, data);
         }
         finally {
             await unlock();
         }
     }
     async update(fn) {
-        await fs.mkdir(this.directory, { recursive: true }).catch(() => { });
-        const unlock = await this.acquireLock();
+        await ensureRoadmapDir(this.directory);
+        const unlock = await acquireLock(this.directory);
         try {
             const current = await this.readFromDisk();
             const outcome = await fn(current);
-            const data = JSON.stringify(outcome.roadmap, null, 2);
-            const filePath = join(this.directory, ROADMAP_FILE);
-            await this.writeAtomic(filePath, data);
-            const archiveName = outcome.archive ? await this.archiveUnlocked() : null;
+            const data = buildDocument(ensureDocument(outcome.document));
+            await writeRoadmapFile(this.directory, data);
+            const archiveName = outcome.archive ? await archiveRoadmapFile(this.directory) : null;
             return outcome.buildResult(archiveName);
         }
         finally {
@@ -148,153 +54,39 @@ export class FileStorage {
     }
     async archive() {
         if (!(await this.exists())) {
-            throw new Error("Cannot archive: roadmap file does not exist");
+            throw new Error("Roadmap not found.");
         }
-        const unlock = await this.acquireLock();
+        const unlock = await acquireLock(this.directory);
         try {
-            return await this.archiveUnlocked();
+            return await archiveRoadmapFile(this.directory);
         }
         finally {
             await unlock();
         }
     }
-}
-export class RoadmapValidator {
-    static validateFeatureNumber(number) {
-        if (!number || typeof number !== "string") {
-            return {
-                code: "INVALID_FEATURE_NUMBER",
-                message: "Invalid feature ID: must be a string.",
-            };
-        }
-        if (!/^\d+$/.test(number)) {
-            return {
-                code: "INVALID_FEATURE_NUMBER_FORMAT",
-                message: "Invalid feature ID format: must be a simple number.",
-            };
-        }
-        return null;
-    }
-    static validateActionNumber(number) {
-        if (!number || typeof number !== "string") {
-            return {
-                code: "INVALID_ACTION_NUMBER",
-                message: "Invalid action ID: must be a string.",
-            };
-        }
-        if (!/^\d+\.\d{2}$/.test(number)) {
-            return {
-                code: "INVALID_ACTION_NUMBER_FORMAT",
-                message: "Invalid action ID format: must be X.YY (e.g., 1.01).",
-            };
-        }
-        return null;
-    }
-    static validateActionSequence(actions, globalSeenNumbers, featureNumber) {
-        const errors = [];
-        const seenNumbers = new Set();
-        for (const action of actions) {
-            const numberError = this.validateActionNumber(action.number);
-            if (numberError) {
-                errors.push(numberError);
-                continue;
-            }
-            // Check action-feature mismatch
-            if (featureNumber) {
-                const actionFeaturePrefix = action.number.split(".")[0];
-                if (actionFeaturePrefix !== featureNumber) {
-                    errors.push({
-                        code: "ACTION_FEATURE_MISMATCH",
-                        message: `Action "${action.number}" does not belong to feature "${featureNumber}".`,
-                    });
-                }
+    async readFromDisk() {
+        try {
+            const data = await readRoadmapFile(this.directory);
+            if (!data.trim()) {
+                return null;
             }
-            // Check for duplicates within this feature
-            if (seenNumbers.has(action.number)) {
-                errors.push({
-                    code: "DUPLICATE_ACTION_NUMBER",
-                    message: `Duplicate action ID "${action.number}".`,
-                });
+            return ensureDocument(parseDocument(data));
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error("Roadmap data is invalid. Unable to parse tasks.");
             }
-            // Check for global duplicates
-            if (globalSeenNumbers?.has(action.number)) {
-                errors.push({
-                    code: "DUPLICATE_ACTION_NUMBER_GLOBAL",
-                    message: `Duplicate action ID "${action.number}" (exists in another feature).`,
-                });
+            if (error instanceof z.ZodError) {
+                const issues = error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+                throw new Error(`Roadmap data is invalid: ${issues}`);
             }
-            seenNumbers.add(action.number);
-            globalSeenNumbers?.add(action.number);
-        }
-        return errors;
-    }
-    static validateFeatureSequence(features) {
-        const errors = [];
-        const seenNumbers = new Set();
-        const seenActionNumbers = new Set();
-        for (const feature of features) {
-            const numberError = this.validateFeatureNumber(feature.number);
-            if (numberError) {
-                errors.push(numberError);
-                continue;
+            if (error instanceof Error && error.message.includes("ENOENT")) {
+                return null;
             }
-            if (seenNumbers.has(feature.number)) {
-                errors.push({
-                    code: "DUPLICATE_FEATURE_NUMBER",
-                    message: `Duplicate feature ID "${feature.number}".`,
-                });
+            if (error instanceof Error) {
+                throw error;
             }
-            seenNumbers.add(feature.number);
-            const actionErrors = this.validateActionSequence(feature.actions, seenActionNumbers, feature.number);
-            errors.push(...actionErrors);
-        }
-        return errors;
-    }
-    static validateTitle(title, fieldType) {
-        if (!title || typeof title !== "string") {
-            return {
-                code: "INVALID_TITLE",
-                message: `Invalid ${fieldType} title. Must be non-empty string.`,
-            };
-        }
-        if (title.trim() === "") {
-            return {
-                code: "EMPTY_TITLE",
-                message: `${fieldType.charAt(0).toUpperCase() + fieldType.slice(1)} title cannot be empty.`,
-            };
-        }
-        return null;
-    }
-    static validateDescription(description, fieldType) {
-        if (!description || typeof description !== "string") {
-            return {
-                code: "INVALID_DESCRIPTION",
-                message: `Invalid ${fieldType} description. Must be non-empty string.`,
-            };
-        }
-        if (description.trim() === "") {
-            return {
-                code: "EMPTY_DESCRIPTION",
-                message: `${fieldType.charAt(0).toUpperCase() + fieldType.slice(1)} description cannot be empty.`,
-            };
-        }
-        return null;
-    }
-    static validateStatusProgression(currentStatus, newStatus) {
-        const validStatuses = ["pending", "in_progress", "completed", "cancelled"];
-        if (!validStatuses.includes(newStatus)) {
-            return {
-                code: "INVALID_STATUS",
-                message: `Invalid status "${newStatus}". Valid: ${validStatuses.join(", ")}`,
-            };
-        }
-        // Allow any transition except from cancelled (terminal state for abandoned work)
-        if (currentStatus === "cancelled") {
-            return {
-                code: "INVALID_STATUS_TRANSITION",
-                message: "Cannot change status of cancelled action. Create a new action instead.",
-            };
+            throw new Error("Unknown error while loading roadmap");
         }
-        return null;
     }
 }

package/dist/src/tools/createroadmap.js

@@ -3,7 +3,8 @@
  * Supports merge logic for adding new features/actions to existing roadmaps.
  */
 import { tool } from "@opencode-ai/plugin";
-import { FileStorage, RoadmapValidator } from "../storage.js";
+import { FileStorage } from "../storage.js";
+import { RoadmapValidator } from "../validators.js";
 import { loadDescription } from "../descriptions/index.js";
 import { getErrorMessage } from "../errors/loader.js";
 export async function createCreateRoadmapTool(directory) {
@@ -11,6 +12,8 @@ export async function createCreateRoadmapTool(directory) {
     return tool({
         description,
         args: {
+            feature: tool.schema.string().describe("Short feature label for the roadmap"),
+            spec: tool.schema.string().describe("Overall spec and goals in natural language"),
             features: tool.schema
                 .array(tool.schema.object({
                 number: tool.schema.string().describe('Feature number as string ("1", "2", "3...")'),
@@ -30,13 +33,27 @@ export async function createCreateRoadmapTool(directory) {
         },
         async execute(args) {
             const storage = new FileStorage(directory);
+            const featureError = RoadmapValidator.validateTitle(args.feature, "feature");
+            if (featureError) {
+                throw new Error(featureError.message);
+            }
+            const specError = RoadmapValidator.validateDescription(args.spec, "feature");
+            if (specError) {
+                throw new Error(specError.message);
+            }
             if (!args.features || args.features.length === 0) {
-                throw new Error('Roadmap must have at least one feature with at least one action. Example: {"features": [{"number": "1", "title": "Feature 1", "description": "Description", "actions": [{"number": "1.01", "description": "Action 1", "status": "pending"}]}]}');
+                throw new Error('Roadmap must have at least one feature with at least one action. Example: {"feature":"Core","spec":"Project goals...","features": [{"number": "1", "title": "Feature 1", "description": "Description", "actions": [{"number": "1.01", "description": "Action 1", "status": "pending"}]}]}');
             }
             return await storage.update(async (current) => {
-                const roadmap = current ?? { features: [] };
+                const roadmap = current ? current.roadmap : { features: [] };
                 const isUpdate = current !== null;
                 const validationErrors = [];
+                if (current && current.feature !== args.feature) {
+                    throw new Error("Feature label does not match existing roadmap.");
+                }
+                if (current && current.spec !== args.spec) {
+                    throw new Error("Spec does not match existing roadmap.");
+                }
                 // First pass: structural validation of input
                 for (const feature of args.features) {
                     if (!feature.actions || feature.actions.length === 0) {
@@ -130,7 +147,11 @@ export async function createCreateRoadmapTool(directory) {
                         .map((feature) => `  Feature ${feature.number}: ${feature.title} (${feature.actions.length} actions)`)
                         .join("\n");
                 return {
-                    roadmap,
+                    document: {
+                        feature: args.feature,
+                        spec: args.spec,
+                        roadmap,
+                    },
                     buildResult: () => summary,
                 };
             });

package/dist/src/tools/readroadmap.js

@@ -3,7 +3,8 @@
  * Supports filtering by feature or action number.
  */
 import { tool } from "@opencode-ai/plugin";
-import { FileStorage, RoadmapValidator } from "../storage.js";
+import { FileStorage } from "../storage.js";
+import { RoadmapValidator } from "../validators.js";
 import { loadDescription } from "../descriptions/index.js";
 export async function createReadRoadmapTool(directory) {
     const description = await loadDescription("readroadmap.txt");
@@ -24,10 +25,11 @@ export async function createReadRoadmapTool(directory) {
             if (!(await storage.exists())) {
                 throw new Error("Roadmap not found. Use CreateRoadmap to create one.");
             }
-            const roadmap = await storage.read();
-            if (!roadmap) {
-                throw new Error("Roadmap file is corrupted. Please fix manually.");
+            const document = await storage.read();
+            if (!document) {
+                throw new Error("Roadmap data is corrupted. Please fix manually.");
             }
+            const roadmap = document.roadmap;
             if (args.actionNumber && args.featureNumber) {
                 throw new Error("Cannot specify both actionNumber and featureNumber. Use one or the other, or neither for full roadmap.");
             }
@@ -73,6 +75,8 @@ export async function createReadRoadmapTool(directory) {
             const pendingActions = totalActions - completedActions - inProgressActions;
             let output = `Project Roadmap Overview\n` +
                 `========================\n` +
+                `Feature: ${document.feature}\n` +
+                `Spec:\n${document.spec}\n\n` +
                 `Features: ${roadmap.features.length}\n` +
                 `Total Actions: ${totalActions}\n` +
                 `Progress: ${completedActions} completed, ${inProgressActions} in progress, ${pendingActions} pending\n\n`;

package/dist/src/tools/updateroadmap.js

@@ -3,7 +3,8 @@
  * Enforces forward-only status progression and archives when complete.
  */
 import { tool } from "@opencode-ai/plugin";
-import { FileStorage, RoadmapValidator } from "../storage.js";
+import { FileStorage } from "../storage.js";
+import { RoadmapValidator } from "../validators.js";
 import { loadDescription } from "../descriptions/index.js";
 export async function createUpdateRoadmapTool(directory) {
     const description = await loadDescription("updateroadmap.txt");
@@ -19,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);
@@ -26,10 +28,11 @@ export async function createUpdateRoadmapTool(directory) {
             if (actionNumberError) {
                 throw new Error(`${actionNumberError.message} Use ReadRoadmap to see valid action numbers.`);
             }
-            return await storage.update((roadmap) => {
-                if (!roadmap) {
+            return await storage.update((document) => {
+                if (!document) {
                     throw new Error("Roadmap not found. Use CreateRoadmap to create one.");
                 }
+                const roadmap = document.roadmap;
                 let targetAction = null;
                 let targetFeature = null;
                 let actionFound = false;
@@ -52,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
@@ -62,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);
@@ -77,9 +85,16 @@ 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 {
-                        roadmap,
+                        document: {
+                            feature: document.feature,
+                            spec: document.spec,
+                            roadmap,
+                        },
                         buildResult: () => `Action ${args.actionNumber} unchanged. Provided values match current state.`,
                     };
                 }
@@ -105,7 +120,11 @@ export async function createUpdateRoadmapTool(directory) {
                     featureContext += `${action.number} ${statusIcon} ${action.description} [${action.status}]\n`;
                 }
                 return {
-                    roadmap,
+                    document: {
+                        feature: document.feature,
+                        spec: document.spec,
+                        roadmap,
+                    },
                     archive: allCompleted,
                     buildResult: (archiveName) => {
                         const archiveMsg = archiveName ? `\n\nAll actions completed! Roadmap archived to "${archiveName}".` : "";

package/dist/src/types.d.ts

@@ -113,9 +113,14 @@ export declare const Roadmap: z.ZodObject<{
     }[];
 }>;
 export type Roadmap = z.infer<typeof Roadmap>;
+export type RoadmapDocument = {
+    feature: string;
+    spec: string;
+    roadmap: Roadmap;
+};
 export interface RoadmapStorage {
-    read(): Promise<Roadmap | null>;
-    write(roadmap: Roadmap): Promise<void>;
+    read(): Promise<RoadmapDocument | null>;
+    write(document: RoadmapDocument): Promise<void>;
     exists(): Promise<boolean>;
     archive(): Promise<string>;
 }
@@ -129,6 +134,8 @@ export interface ValidationResult {
     errors: ValidationError[];
 }
 export interface CreateRoadmapInput {
+    feature: string;
+    spec: string;
     features: {
         number: string;
         title: string;

package/dist/src/validators.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validates roadmap identifiers and text fields.
+ * Keeps validation concerns separate from storage and tools.
+ */
+import type { ValidationError } from "./types.js";
+export declare class RoadmapValidator {
+    static validateFeatureNumber(number: string): ValidationError | null;
+    static validateActionNumber(number: string): ValidationError | null;
+    static validateActionSequence(actions: {
+        number: string;
+    }[], globalSeenNumbers?: Set<string>, featureNumber?: string): ValidationError[];
+    static validateFeatureSequence(features: {
+        number: string;
+        actions: {
+            number: string;
+        }[];
+    }[]): ValidationError[];
+    static validateTitle(title: string, fieldType: "feature" | "action"): ValidationError | null;
+    static validateDescription(description: string, fieldType: "feature" | "action"): ValidationError | null;
+    static validateStatusProgression(currentStatus: string, newStatus: string): ValidationError | null;
+}

package/dist/src/validators.js

@@ -0,0 +1,135 @@
+export class RoadmapValidator {
+    static validateFeatureNumber(number) {
+        if (!number || typeof number !== "string") {
+            return {
+                code: "INVALID_FEATURE_NUMBER",
+                message: "Invalid feature ID: must be a string.",
+            };
+        }
+        if (!/^\d+$/.test(number)) {
+            return {
+                code: "INVALID_FEATURE_NUMBER_FORMAT",
+                message: "Invalid feature ID format: must be a simple number.",
+            };
+        }
+        return null;
+    }
+    static validateActionNumber(number) {
+        if (!number || typeof number !== "string") {
+            return {
+                code: "INVALID_ACTION_NUMBER",
+                message: "Invalid action ID: must be a string.",
+            };
+        }
+        if (!/^\d+\.\d{2}$/.test(number)) {
+            return {
+                code: "INVALID_ACTION_NUMBER_FORMAT",
+                message: "Invalid action ID format: must be X.YY (e.g., 1.01).",
+            };
+        }
+        return null;
+    }
+    static validateActionSequence(actions, globalSeenNumbers, featureNumber) {
+        const errors = [];
+        const seenNumbers = new Set();
+        for (const action of actions) {
+            const numberError = this.validateActionNumber(action.number);
+            if (numberError) {
+                errors.push(numberError);
+                continue;
+            }
+            if (featureNumber) {
+                const actionFeaturePrefix = action.number.split(".")[0];
+                if (actionFeaturePrefix !== featureNumber) {
+                    errors.push({
+                        code: "ACTION_FEATURE_MISMATCH",
+                        message: `Action "${action.number}" does not belong to feature "${featureNumber}".`,
+                    });
+                }
+            }
+            if (seenNumbers.has(action.number)) {
+                errors.push({
+                    code: "DUPLICATE_ACTION_NUMBER",
+                    message: `Duplicate action ID "${action.number}".`,
+                });
+            }
+            if (globalSeenNumbers?.has(action.number)) {
+                errors.push({
+                    code: "DUPLICATE_ACTION_NUMBER_GLOBAL",
+                    message: `Duplicate action ID "${action.number}" (exists in another feature).`,
+                });
+            }
+            seenNumbers.add(action.number);
+            globalSeenNumbers?.add(action.number);
+        }
+        return errors;
+    }
+    static validateFeatureSequence(features) {
+        const errors = [];
+        const seenNumbers = new Set();
+        const seenActionNumbers = new Set();
+        for (const feature of features) {
+            const numberError = this.validateFeatureNumber(feature.number);
+            if (numberError) {
+                errors.push(numberError);
+                continue;
+            }
+            if (seenNumbers.has(feature.number)) {
+                errors.push({
+                    code: "DUPLICATE_FEATURE_NUMBER",
+                    message: `Duplicate feature ID "${feature.number}".`,
+                });
+            }
+            seenNumbers.add(feature.number);
+            const actionErrors = this.validateActionSequence(feature.actions, seenActionNumbers, feature.number);
+            errors.push(...actionErrors);
+        }
+        return errors;
+    }
+    static validateTitle(title, fieldType) {
+        if (!title || typeof title !== "string") {
+            return {
+                code: "INVALID_TITLE",
+                message: `Invalid ${fieldType} title. Must be non-empty string.`,
+            };
+        }
+        if (title.trim() === "") {
+            return {
+                code: "EMPTY_TITLE",
+                message: `${fieldType.charAt(0).toUpperCase() + fieldType.slice(1)} title cannot be empty.`,
+            };
+        }
+        return null;
+    }
+    static validateDescription(description, fieldType) {
+        if (!description || typeof description !== "string") {
+            return {
+                code: "INVALID_DESCRIPTION",
+                message: `Invalid ${fieldType} description. Must be non-empty string.`,
+            };
+        }
+        if (description.trim() === "") {
+            return {
+                code: "EMPTY_DESCRIPTION",
+                message: `${fieldType.charAt(0).toUpperCase() + fieldType.slice(1)} description cannot be empty.`,
+            };
+        }
+        return null;
+    }
+    static validateStatusProgression(currentStatus, newStatus) {
+        const validStatuses = ["pending", "in_progress", "completed", "cancelled"];
+        if (!validStatuses.includes(newStatus)) {
+            return {
+                code: "INVALID_STATUS",
+                message: `Invalid status "${newStatus}". Valid: ${validStatuses.join(", ")}`,
+            };
+        }
+        if (currentStatus === "cancelled") {
+            return {
+                code: "INVALID_STATUS_TRANSITION",
+                message: "Cannot change status of cancelled action. Create a new action instead.",
+            };
+        }
+        return null;
+    }
+}

package/package.json

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