@howaboua/opencode-roadmap-plugin 0.1.5 → 0.1.7

package/README.md

@@ -1,29 +1,100 @@
-# @howaboua/opencode-roadmap-plugin
+# Opencode Roadmap Plugin
 
-Strategic roadmap planning and multi-agent coordination for OpenCode.
+Persistent project roadmaps for OpenCode. Coordinates work across sessions and parallel Task tool subagents.
+
+## Why Use This?
+
+OpenCode's built-in todo is session-scoped—it disappears when you restart. Task tool subagents are stateless—they can't see each other's work.
+
+This plugin solves both:
+
+- **Persists to disk** — survives restarts, available across sessions
+- **Shared context** — subagents read the same roadmap to understand the bigger picture
+- **Concurrent awareness** — agents see what's `in_progress` and avoid conflicts
+
+![opencode-roadmap](https://github.com/user-attachments/assets/e2479a72-ec65-457f-9503-bf2d01580c70)
 
 ## Installation
 
-Add to your repository `opencode.json` or user-level `~/.config/opencode/opencode.json`:
+Add to your `opencode.json`:
 
 ```json
 {
-  "plugin": ["@howaboua/opencode-roadmap-plugin"]
+  "plugin": ["@howaboua/opencode-roadmap-plugin@latest"]
 }
 ```
 
-## How It Works
+OpenCode installs it automatically on next launch.
+
+## Tools
+
+### `createroadmap`
+
+Create or extend a project roadmap.
+
+```
+"Create a roadmap for building user auth with login, signup, and password reset"
+```
+
+- Features group related work (`"1"`, `"2"`, `"3"`)
+- Actions are concrete tasks (`"1.01"`, `"1.02"`) within features
+- New actions always start as `pending`
+- Append-only: existing IDs never change
+
+### `readroadmap`
+
+View current state and progress.
+
+```
+"Show me the roadmap"
+"What's the status of feature 2?"
+```
+
+Before delegating work to Task tool subagents, instruct them to read the roadmap first so they understand their assigned action within the broader plan.
 
-- `createroadmap`: create or append features/actions while keeping IDs immutable.
-- `updateroadmap`: advance action status forward only (`pending` → `in_progress` → `completed`), optional description update.
-- `readroadmap`: summarize roadmap, optionally filtered by feature/action.
-- Storage: JSON on disk with auto-archive when all actions complete.
-- Validation: Zod schemas enforce shape; errors surface readable templates.
+### `updateroadmap`
 
-## Development
+Change action status or description.
 
-```bash
-npm run build   # Emit dist/ (ESM + d.ts)
 ```
+"Mark action 1.01 as in_progress"
+"Action 2.03 is completed"
+```
+
+**Statuses:** `pending` → `in_progress` → `completed` | `cancelled`
+
+Transitions are flexible—you can revert if plans change. Only `cancelled` is terminal.
+
+Auto-archives the roadmap when all actions reach `completed`.
+
+## Coordinating Parallel Work
+
+When multiple subagents work simultaneously:
+
+1. Each reads the roadmap to see what's `in_progress`
+2. Agents stay focused on their assigned action only
+3. They avoid modifying files that belong to another `in_progress` action
+4. Errors outside their scope get noted, not fixed
+
+This prevents conflicts when subagents run in parallel.
+
+## Workflow Example
+
+```
+You: "Plan out building a REST API with auth, users, and posts endpoints"
+
+AI: Creates roadmap with 3 features, ~12 actions
+
+You: "Implement feature 1"
+
+AI: Reads roadmap → sees Feature 1 has 4 actions → uses todowrite for immediate steps → delegates to subagents → each subagent reads roadmap first → updates status when done
+```
+
+## Storage
+
+- **Active:** `roadmap.json` in project root
+- **Archived:** `roadmap.archive.<timestamp>.json` when complete
+
+## License
 
-See `AGENTS.md` for coding standards.
+MIT

package/dist/src/descriptions/createroadmap.txt

@@ -1,20 +1,24 @@
-Initialize or append to project roadmap. Supports adding new features and actions.
+Establish a durable project roadmap saved to disk. Provides shared context across sessions and Task tool subagents.
 
-Constraints:
-1. Descriptions: MUST be detailed, clear, and actionable (unlike the minimal example below).
-2. Append-only: New IDs must follow sequence (Feature 1->2, Action 1.01->1.02).
-3. ID Format: Feature "1", Action "1.01".
-4. Validation: Action prefix MUST match Feature (Action "1.01" belongs to Feature "1").
-5. Status: Must be "pending".
+Use when:
+- User says "roadmap", "plan the project", "phases", or "milestones"  
+- Work will be delegated to Task tool subagents that need shared context
+- 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.
+
+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"
 
 Example:
 {
-  "features": [
-    {
-      "number": "1", "title": "Auth", "description": "User authentication system setup",
-      "actions": [
-        { "number": "1.01", "description": "Initialize PostgreSQL database schema with users table and indexes", "status": "pending" }
-      ]
-    }
-  ]
-}
+  "features": [{
+    "number": "1", "title": "Auth", "description": "User authentication system",
+    "actions": [
+      { "number": "1.01", "description": "Design JWT token flow and refresh strategy", "status": "pending" }
+    ]
+  }]
+}

package/dist/src/descriptions/loader.js

@@ -1,7 +1,13 @@
+/**
+ * Loads tool description text files from the descriptions directory.
+ * ESM-compatible using import.meta.url for path resolution.
+ */
 import { promises as fs } from "fs";
-import { join } from "path";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 export async function loadDescription(filename) {
-    // Assets are colocated with the compiled loader (copied into dist/src/descriptions).
     const filePath = join(__dirname, filename);
     try {
         return await fs.readFile(filePath, "utf-8");

package/dist/src/descriptions/readroadmap.txt

@@ -1,2 +1,19 @@
-Retrieve current roadmap state, progress, and details.
-Filter: Provide 'featureNumber' or 'actionNumber' for specific details, or omit to read entire roadmap.
+Load the persisted roadmap from disk 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
+3. To check overall progress across features
+
+Concurrent work awareness:
+- Actions marked "in_progress" may have another agent actively working on them
+- Stay focused on YOUR assigned action only - do not fix unrelated codebase errors
+- Avoid modifying files that belong to another in_progress action
+- If you encounter errors in code outside your scope, note them but do not fix
+
+Returns: feature list, action statuses, completion percentages.
+
+Filter options:
+- featureNumber: show one feature and its actions
+- actionNumber: show one action's details
+- (omit both): full roadmap overview

package/dist/src/descriptions/updateroadmap.txt

@@ -1,8 +1,10 @@
-Update action status or description.
+Advance action state within the persisted roadmap.
 
-Constraints:
-1. Forward-only status: pending → in_progress → completed.
-2. Immutable IDs: Cannot change action numbers or move actions.
-3. Side Effect: Automatically archives roadmap file when ALL actions are completed.
+Statuses: pending, in_progress, completed, cancelled
+Transitions: Flexible (can revert if needed), except cancelled is terminal.
 
-Input: actionNumber (required), status (optional), description (optional).
+Update after completing work on an action. When delegating to Task tool subagents, instruct them to call updateroadmap when they finish their assigned action.
+
+Archives roadmap automatically when all actions reach completed.
+
+Input: actionNumber (required), status (optional), description (optional).

package/dist/src/errors/loader.js

@@ -1,5 +1,12 @@
+/**
+ * Loads error message templates from the errors directory.
+ * Supports template variable substitution for dynamic error messages.
+ */
 import { promises as fs } from "fs";
-import { join } from "path";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 const ERROR_CACHE = {};
 export async function loadErrorTemplate(filename) {
     if (ERROR_CACHE[filename])

package/dist/src/storage.d.ts

@@ -1,10 +1,21 @@
 import type { Roadmap, RoadmapStorage, ValidationError } from "./types.js";
+type UpdateResult<T> = {
+    roadmap: Roadmap;
+    buildResult: (archiveName: string | null) => T;
+    archive?: boolean;
+};
 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>;
     archive(): Promise<string>;
 }
 export declare class RoadmapValidator {
@@ -23,3 +34,4 @@ export declare class RoadmapValidator {
     static validateDescription(description: string, fieldType: "feature" | "action"): ValidationError | null;
     static validateStatusProgression(currentStatus: string, newStatus: string): ValidationError | null;
 }
+export {};

package/dist/src/storage.js

@@ -1,7 +1,16 @@
+/**
+ * File-based storage for roadmap data with atomic writes and validation.
+ * Handles concurrent access via file locking and provides safe read/write operations.
+ */
 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;
 export class FileStorage {
     directory;
     constructor(directory) {
@@ -17,6 +26,9 @@ 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");
@@ -31,6 +43,10 @@ export class FileStorage {
             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;
             }
@@ -40,35 +56,108 @@ export class FileStorage {
             throw new Error("Unknown error while reading roadmap");
         }
     }
-    async write(roadmap) {
-        const filePath = join(this.directory, ROADMAP_FILE);
-        const tempPath = join(this.directory, `${ROADMAP_FILE}.tmp.${Date.now()}`);
-        try {
-            const data = JSON.stringify(roadmap, null, 2);
-            await fs.writeFile(tempPath, data, "utf-8");
-            await fs.rename(tempPath, filePath);
-        }
-        catch (error) {
+    async acquireLock() {
+        const lockPath = join(this.directory, LOCK_FILE);
+        const start = Date.now();
+        while (Date.now() - start < LOCK_TIMEOUT_MS) {
             try {
-                await fs.unlink(tempPath);
+                await fs.writeFile(lockPath, String(process.pid), { flag: "wx" });
+                return async () => {
+                    await fs.unlink(lockPath).catch(() => { });
+                };
             }
             catch {
-                // Ignore cleanup errors
+                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 archive() {
+    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();
+        try {
+            const data = JSON.stringify(roadmap, null, 2);
+            const filePath = join(this.directory, ROADMAP_FILE);
+            await this.writeAtomic(filePath, data);
+        }
+        finally {
+            await unlock();
+        }
+    }
+    async update(fn) {
+        await fs.mkdir(this.directory, { recursive: true }).catch(() => { });
+        const unlock = await this.acquireLock();
+        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;
+            return outcome.buildResult(archiveName);
+        }
+        finally {
+            await unlock();
+        }
+    }
+    async archive() {
+        if (!(await this.exists())) {
+            throw new Error("Cannot archive: roadmap file does not exist");
+        }
+        const unlock = await this.acquireLock();
+        try {
+            return await this.archiveUnlocked();
+        }
+        finally {
+            await unlock();
+        }
+    }
 }
 export class RoadmapValidator {
     static validateFeatureNumber(number) {
@@ -112,7 +201,7 @@ export class RoadmapValidator {
             }
             // Check action-feature mismatch
             if (featureNumber) {
-                const actionFeaturePrefix = action.number.split('.')[0];
+                const actionFeaturePrefix = action.number.split(".")[0];
                 if (actionFeaturePrefix !== featureNumber) {
                     errors.push({
                         code: "ACTION_FEATURE_MISMATCH",
@@ -192,16 +281,18 @@ export class RoadmapValidator {
         return null;
     }
     static validateStatusProgression(currentStatus, newStatus) {
-        const statusFlow = {
-            pending: ["in_progress", "completed"],
-            in_progress: ["completed"],
-            completed: [],
-        };
-        const allowedTransitions = statusFlow[currentStatus] || [];
-        if (!allowedTransitions.includes(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: `Invalid transition from "${currentStatus}" to "${newStatus}". Allowed: ${allowedTransitions.length > 0 ? allowedTransitions.join(", ") : "None (terminal state)"}`,
+                message: "Cannot change status of cancelled action. Create a new action instead.",
             };
         }
         return null;

package/dist/src/tools/createroadmap.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Tool for creating and appending to project roadmaps.
+ * Supports merge logic for adding new features/actions to existing roadmaps.
+ */
 import { type ToolDefinition } from "@opencode-ai/plugin";
 export declare function createCreateRoadmapTool(directory: string): Promise<ToolDefinition>;