opencode-plan-manager 0.2.1 → 0.4.0

package/README.md

@@ -11,6 +11,44 @@ OpenCode Plan Manager is a high-performance, minimalist plugin designed to bridg
 
 ---
 
+<details>
+<summary><strong>⚠️ v0.3.0 Breaking Changes – Read Before Upgrading!</strong></summary>
+
+#### **This release introduces breaking changes that affect file structure, field names, and plan format.**
+
+If you are upgrading from v0.2.x, you MUST migrate all existing plans and metadata for compatibility.
+
+> Tip: AI Agents can still access old plans by reading their files directly (using Bash/list/read tools), then recreate plans in the new format using the latest plugin's API.
+
+**What Changed?**
+
+- **File naming:**
+  - `spec.md` → `specifications.md`
+  - `plan.md` → `implementation.md`
+- **Metadata key:**
+  - `"plan_id"` → `"id"` in `metadata.json`
+- **Markdown structure:**
+  - All `.md` files now require H1 headers:
+    - `# Specifications` at the top of `specifications.md`
+    - `# Implementation Plan` at the top of `implementation.md`
+  - Phases are now indicated using H2 (`##`) headers, not H3.
+  - No more `## Overview/Description` headers—put the summary right after the H1.
+- **Tool arguments:**
+  - All APIs expect updated argument keys (e.g., `id` instead of `plan_id`)
+
+**How to Migrate?**
+
+1. Rename all `spec.md` to `specifications.md` & `plan.md` to `implementation.md` in each plan folder.
+2. Open each `metadata.json` file and rename `plan_id` → `id`.
+3. Update the content of each markdown file to add the correct H1 headers and phase header levels as described above.
+4. Validate your plans by running `plan_list` and `plan_read`.
+
+**Older plans will not load or load with errors until they are migrated to the new format.**
+
+</details>
+
+---
+
 ## 🧠 Why Plan Manager?
 
 In agentic workflows, **Implementation Plans** are the source of truth. However, most implementations suffer from "Token Soup"—where agents are forced to parse massive, unstructured files, leading to hallucinations and lost context.
@@ -28,10 +66,10 @@ Plan Manager solves this by enforcing **Plan-to-Code Determinism**:
 
 Add the plugin to your OpenCode configuration file (~/.config/opencode/opencode.json or similar):
 
-```json
+```jsonc
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-plan-manager@0.2.0"]
+	"$schema": "https://opencode.ai/config.json",
+	"plugin": ["opencode-plan-manager@0.2.0"],
 }
 ```
 
@@ -39,6 +77,62 @@ Add the plugin to your OpenCode configuration file (~/.config/opencode/opencode.
 
 ---
 
+## ⚙️ Configuration
+
+Configuration files are loaded with the following precedence (highest to lowest):
+
+1. **Local Config:** `<project-root>/.opencode/plan-manager.json` (project-specific settings)
+2. **User Config:** `~/.config/opencode/plan-manager.json` (global user settings)
+3. **Default Config:** Built-in defaults (used when no config files exist)
+
+```jsonc
+{
+	"outputFormat": "markdown", // "markdown" (default), "json" or "toon" (see https://github.com/toon-format/toon)
+}
+```
+
+<details>
+<summary>⚠️ Permission Requirement</summary>
+
+> Important:
+> If you deny edit permission in your OpenCode configuration (opencode.json) for the .opencode/plans/\* file pattern, the Plan Manager plugin cannot create or update plans.
+> This is because the plugin uses OpenCode’s built-in ask permission method when modifying plan files. This mechanism shows users a summary of the changes and asks for review (accept/reject) before files are edited, increasing transparency and control.
+
+What does this mean?
+
+- The plan_create and plan_update actions require that AI agents (Plan and Build) have ask or allow permissions for edit on the .opencode/plans/\* pattern.
+- If permission is set to deny, plan creation and modification will fail, and the workflow will not proceed.
+  How to ensure compatibility:
+
+1. Open your opencode.json config file (usually at ~/.config/opencode/opencode.json).
+2. Check the permissions for .opencode/plans/\*.
+3. Make sure edit edit permission is set to "ask" or "allow" for both the Plan Agent and Build Agent.
+
+Here is an example similar to how I configure permissions for the Plan agent:
+
+```jsonc
+{
+	"agent": {
+		"plan": {
+			"permission": {
+				"edit": {
+					"*": "deny", // Deny edits on everything
+					".opencode/plans/*": "ask", // Except for plan files, ask for permission
+				},
+			},
+		},
+	},
+}
+```
+
+References:
+
+- https://opencode.ai/docs/permissions
+
+</details>
+
+---
+
 ## 🤖 The Agentic Workflow
 
 This plugin is optimized for a dual-agent hierarchy, utilizing specialized prompts found in `src/prompts/`:
@@ -76,8 +170,8 @@ Plan Manager organizes work into a structured directory tree that both humans an
 ├── pending/             # New ideas and upcoming features
 │   └── feature_auth/    # Each plan is a dedicated folder
 │       ├── metadata.json
-│       ├── spec.md
-│       └── plan.md
+│       ├── specifications.md
+│       └── implementation.md
 ├── in_progress/         # Currently active development
 └── done/                # Immutable history of completed work
 ```
@@ -92,25 +186,25 @@ Instead of loose markdown, agents use structured objects to ensure every plan ha
 
 ```typescript
 plan_create({
-  title: "JWT Authentication",
-  type: "feature",
-  description: "Secure auth flow with refresh tokens",
-  spec: {
-    overview: "Implement secure JWT-based authentication",
-    functionals: ["User login", "Token refresh"],
-    nonFunctionals: ["Passwords hashed with bcrypt"],
-    acceptanceCriterias: ["Successful login returns valid JWT"],
-    outOfScope: ["Social OAuth"],
-  },
-  implementation: {
-    description: "Phased rollout",
-    phases: [
-      {
-        phase: "Phase 1: Database",
-        tasks: ["Create users table", "Create sessions table"],
-      },
-    ],
-  },
+	title: "JWT Authentication",
+	type: "feature",
+	description: "Secure auth flow with refresh tokens",
+	spec: {
+		description: "Implement secure JWT-based authentication",
+		functionals: ["User login", "Token refresh"],
+		nonFunctionals: ["Passwords hashed with bcrypt"],
+		acceptanceCriterias: ["Successful login returns valid JWT"],
+		outOfScope: ["Social OAuth"],
+	},
+	implementation: {
+		description: "Phased rollout",
+		phases: [
+			{
+				phase: "Phase 1: Database",
+				tasks: ["Create users table", "Create sessions table"],
+			},
+		],
+	},
 });
 ```
 
@@ -120,13 +214,13 @@ Agents can request only the information they need, significantly reducing token
 
 ```typescript
 // Summary View: Just the metadata and progress stats
-plan_read({ plan_id: "feature_auth", view: "summary" });
+plan_read({ id: "feature_auth", view: "summary" });
 
 // Spec View: Just the requirements (useful for the Planner)
-plan_read({ plan_id: "feature_auth", view: "spec" });
+plan_read({ id: "feature_auth", view: "spec" });
 
 // Plan View: Just the task list (useful for the Builder)
-plan_read({ plan_id: "feature_auth", view: "plan" });
+plan_read({ id: "feature_auth", view: "plan" });
 ```
 
 ### 3. Batch Task Updates (`plan_update`)
@@ -135,12 +229,12 @@ Update multiple tasks or move a plan through the lifecycle with validation.
 
 ```typescript
 plan_update({
-  plan_id: "feature_auth",
-  status: "in_progress",
-  taskUpdates: [
-    { content: "Create users table", status: "done" },
-    { content: "Create sessions table", status: "in_progress" },
-  ],
+	id: "feature_auth",
+	status: "in_progress",
+	taskUpdates: [
+		{ content: "Create users table", status: "done" },
+		{ content: "Create sessions table", status: "in_progress" },
+	],
 });
 ```