opencode-plan-manager 0.4.4 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +75 -146
- package/dist/index.js +107 -162
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,110 +5,63 @@
|
|
|
5
5
|
[](https://bun.sh)
|
|
6
6
|
[](https://github.com/yurihbm/opencode-plan-manager/actions/workflows/test.yml)
|
|
7
7
|
|
|
8
|
-
**AI-
|
|
8
|
+
**AI-native implementation planning for agentic workflows.**
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Stop losing context mid-feature or with cross-session work. OpenCode Plan Manager gives your AI agents a structured way to plan, track, and execute complex work — from a single idea to a fully shipped feature.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
<details>
|
|
15
|
-
<summary><strong>⚠️ v0.3.0 Breaking Changes – Read Before Upgrading!</strong></summary>
|
|
16
|
-
|
|
17
|
-
#### **This release introduces breaking changes that affect file structure, field names, and plan format.**
|
|
18
|
-
|
|
19
|
-
If you are upgrading from v0.2.x, you MUST migrate all existing plans and metadata for compatibility.
|
|
20
|
-
|
|
21
|
-
> 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.
|
|
22
|
-
|
|
23
|
-
**What Changed?**
|
|
24
|
-
|
|
25
|
-
- **File naming:**
|
|
26
|
-
- `spec.md` → `specifications.md`
|
|
27
|
-
- `plan.md` → `implementation.md`
|
|
28
|
-
- **Metadata key:**
|
|
29
|
-
- `"plan_id"` → `"id"` in `metadata.json`
|
|
30
|
-
- **Markdown structure:**
|
|
31
|
-
- All `.md` files now require H1 headers:
|
|
32
|
-
- `# Specifications` at the top of `specifications.md`
|
|
33
|
-
- `# Implementation Plan` at the top of `implementation.md`
|
|
34
|
-
- Phases are now indicated using H2 (`##`) headers, not H3.
|
|
35
|
-
- No more `## Overview/Description` headers—put the summary right after the H1.
|
|
36
|
-
- **Tool arguments:**
|
|
37
|
-
- All APIs expect updated argument keys (e.g., `id` instead of `plan_id`)
|
|
38
|
-
|
|
39
|
-
**How to Migrate?**
|
|
40
|
-
|
|
41
|
-
1. Rename all `spec.md` to `specifications.md` & `plan.md` to `implementation.md` in each plan folder.
|
|
42
|
-
2. Open each `metadata.json` file and rename `plan_id` → `id`.
|
|
43
|
-
3. Update the content of each markdown file to add the correct H1 headers and phase header levels as described above.
|
|
44
|
-
4. Validate your plans by running `plan_list` and `plan_read`.
|
|
45
|
-
|
|
46
|
-
**Older plans will not load or load with errors until they are migrated to the new format.**
|
|
47
|
-
|
|
48
|
-
</details>
|
|
12
|
+
|
|
49
13
|
|
|
50
14
|
---
|
|
51
15
|
|
|
52
|
-
##
|
|
16
|
+
## Why Plan Manager?
|
|
53
17
|
|
|
54
|
-
|
|
18
|
+
Agentic coding workflows break down when context gets too large. Agents start hallucinating, lose track of tasks, and repeat work. Plan Manager solves this with four principles:
|
|
55
19
|
|
|
56
|
-
|
|
20
|
+
- **Selective context loading** — agents read only what they need: `summary` (stats), `spec` (requirements), or `plan` (task list).
|
|
21
|
+
- **Zero-hallucination schemas** — strict Zod validation prevents malformed plans and invalid state transitions.
|
|
22
|
+
- **Filesystem Kanban** — plan state lives in `pending/`, `in_progress/`, and `done/` folders. Atomic, human-readable, no hidden database.
|
|
23
|
+
- **Cross-session continuity** — plans are plain files committed to your repo. Pick up exactly where you left off in any new session, on any machine, with any agent — the spec and task progress are always there.
|
|
57
24
|
|
|
58
|
-
|
|
59
|
-
- **Zero-Hallucination Schemas:** Built with strict Zod validation. Agents _cannot_ create malformed plans or invalid state transitions.
|
|
60
|
-
- **Visible Filesystem Kanban:** Unlike hidden databases, your state is the filesystem. `pending/`, `in_progress/`, and `done/` folders provide an atomic, human-readable Kanban board.
|
|
61
|
-
- **Multi-Agent Native:** Designed for the **Planner-Builder** pattern. Standardized outputs allow a specialized **Plan Agent** to hand off a deterministic spec to a **Build Agent** with zero ambiguity.
|
|
25
|
+
Designed for the **Planner → Builder** pattern: a Plan Agent architects the spec, a Build Agent executes it with no ambiguity.
|
|
62
26
|
|
|
63
27
|
---
|
|
64
28
|
|
|
65
|
-
##
|
|
29
|
+
## Installation
|
|
66
30
|
|
|
67
|
-
Add the plugin to your OpenCode configuration
|
|
31
|
+
Add the plugin to your OpenCode configuration (`~/.config/opencode/opencode.json`):
|
|
68
32
|
|
|
69
33
|
```jsonc
|
|
70
34
|
{
|
|
71
35
|
"$schema": "https://opencode.ai/config.json",
|
|
72
|
-
"plugin": ["opencode-plan-manager@0.
|
|
36
|
+
"plugin": ["opencode-plan-manager@1.0.0"],
|
|
73
37
|
}
|
|
74
38
|
```
|
|
75
39
|
|
|
76
|
-
>
|
|
40
|
+
> Pinning the version improves OpenCode startup time.
|
|
77
41
|
|
|
78
42
|
---
|
|
79
43
|
|
|
80
|
-
##
|
|
44
|
+
## Configuration
|
|
81
45
|
|
|
82
|
-
|
|
46
|
+
Config is loaded with the following precedence (highest → lowest):
|
|
83
47
|
|
|
84
|
-
1. **
|
|
85
|
-
2. **User
|
|
86
|
-
3. **
|
|
48
|
+
1. **Project:** `<project-root>/.opencode/plan-manager.json`
|
|
49
|
+
2. **User:** `~/.config/opencode/plan-manager.json`
|
|
50
|
+
3. **Defaults:** built-in fallback
|
|
87
51
|
|
|
88
52
|
```jsonc
|
|
89
53
|
{
|
|
90
|
-
|
|
54
|
+
// "markdown" (default), "json", or "toon" (https://github.com/toon-format/toon)
|
|
55
|
+
"outputFormat": "markdown",
|
|
91
56
|
}
|
|
92
57
|
```
|
|
93
58
|
|
|
94
59
|
<details>
|
|
95
|
-
<summary
|
|
96
|
-
|
|
97
|
-
> Important:
|
|
98
|
-
> 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.
|
|
99
|
-
> 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.
|
|
60
|
+
<summary><strong>Permission setup</strong></summary>
|
|
100
61
|
|
|
101
|
-
|
|
62
|
+
Plan Manager writes to `.opencode/plans/*`. For `plan_create` and `plan_update` to work, the agents that call them must have `ask` or `allow` permission on that path.
|
|
102
63
|
|
|
103
|
-
|
|
104
|
-
- If permission is set to deny, plan creation and modification will fail, and the workflow will not proceed.
|
|
105
|
-
How to ensure compatibility:
|
|
106
|
-
|
|
107
|
-
1. Open your opencode.json config file (usually at ~/.config/opencode/opencode.json).
|
|
108
|
-
2. Check the permissions for .opencode/plans/\*.
|
|
109
|
-
3. Make sure edit edit permission is set to "ask" or "allow" for both the Plan Agent and Build Agent.
|
|
110
|
-
|
|
111
|
-
Here is an example similar to how I configure permissions for the Plan agent:
|
|
64
|
+
Example config for the Plan agent:
|
|
112
65
|
|
|
113
66
|
```jsonc
|
|
114
67
|
{
|
|
@@ -116,8 +69,8 @@ Here is an example similar to how I configure permissions for the Plan agent:
|
|
|
116
69
|
"plan": {
|
|
117
70
|
"permission": {
|
|
118
71
|
"edit": {
|
|
119
|
-
"*": "deny",
|
|
120
|
-
".opencode/plans/*": "ask",
|
|
72
|
+
"*": "deny",
|
|
73
|
+
".opencode/plans/*": "ask",
|
|
121
74
|
},
|
|
122
75
|
},
|
|
123
76
|
},
|
|
@@ -125,107 +78,92 @@ Here is an example similar to how I configure permissions for the Plan agent:
|
|
|
125
78
|
}
|
|
126
79
|
```
|
|
127
80
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
- https://opencode.ai/docs/permissions
|
|
81
|
+
See [opencode.ai/docs/permissions](https://opencode.ai/docs/permissions) for details.
|
|
131
82
|
|
|
132
83
|
</details>
|
|
133
84
|
|
|
134
85
|
---
|
|
135
86
|
|
|
136
|
-
##
|
|
137
|
-
|
|
138
|
-
This plugin is optimized for a dual-agent hierarchy, utilizing specialized prompts found in `src/prompts/`:
|
|
87
|
+
## Agentic Workflow
|
|
139
88
|
|
|
140
|
-
|
|
141
|
-
- **Workflow:** Follows a 4-step process: Analysis → Deduplication → Context Decision → Plan Creation.
|
|
142
|
-
2. **Build Agent (`build.txt`):** An implementation specialist that executes plans with high precision.
|
|
143
|
-
- **Logic:** If a plan exists, it _must_ follow it. If a task is too complex, it will suggest calling the Plan Agent first.
|
|
144
|
-
- **Task Management:** Automatically handles task state transitions from `pending` to `in_progress` to `done`.
|
|
89
|
+
Plan Manager is optimized for a two-agent hierarchy, with prompts in `src/prompts/`:
|
|
145
90
|
|
|
146
|
-
|
|
147
|
-
|
|
91
|
+
| Agent | Role |
|
|
92
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| **Plan Agent** (`plan.txt`) | Architect. Transforms vague requirements into phased, structured plans via a 4-step process: Analysis → Deduplication → Context Decision → Plan Creation. |
|
|
94
|
+
| **Build Agent** (`build.txt`) | Executor. Follows the plan precisely, managing task state from `pending` → `in_progress` → `done`. Escalates to the Plan Agent when a task needs more design. |
|
|
148
95
|
|
|
149
|
-
>
|
|
150
|
-
> Your prompts have priority over the plugin's defaults.
|
|
96
|
+
> Uses OpenCode's built-in `Plan` and `Build` agents ([docs](https://opencode.ai/docs/agents/)) with injected system prompts. Your own custom prompts always take priority.
|
|
151
97
|
|
|
152
98
|
---
|
|
153
99
|
|
|
154
|
-
##
|
|
155
|
-
|
|
156
|
-
- 🛠️ **Folder-Per-Plan Architecture:** Isolation of concerns. Each feature has its own metadata, spec, and task list.
|
|
157
|
-
- 📉 **Token Optimization:** Native support for `summary` and `selective` views to keep agent context windows clean and focused.
|
|
158
|
-
- 🔄 **Atomic State Transitions:** Safe folder movements (`rename()`) ensure that plan status is always in sync with the filesystem.
|
|
159
|
-
- ✅ **Deterministic Task Management:** Support for three task states (`[ ]`, `[~]`, `[x]`) with batch update capabilities.
|
|
160
|
-
- 🚀 **High Performance:** Metadata-only listing for fast scanning of plans.
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
## 📁 Architecture: The Filesystem Kanban
|
|
165
|
-
|
|
166
|
-
Plan Manager organizes work into a structured directory tree that both humans and AI can navigate intuitively:
|
|
100
|
+
## Filesystem Layout
|
|
167
101
|
|
|
168
102
|
```text
|
|
169
103
|
.opencode/plans/
|
|
170
|
-
├── pending/
|
|
171
|
-
│ └── feature_auth/
|
|
104
|
+
├── pending/
|
|
105
|
+
│ └── feature_auth/
|
|
172
106
|
│ ├── metadata.json
|
|
173
107
|
│ ├── specifications.md
|
|
174
108
|
│ └── implementation.md
|
|
175
|
-
├── in_progress/
|
|
176
|
-
└── done/
|
|
109
|
+
├── in_progress/
|
|
110
|
+
└── done/
|
|
177
111
|
```
|
|
178
112
|
|
|
113
|
+
Each plan is an isolated folder. Status moves atomically between `pending/`, `in_progress/`, and `done/` — no database, no sync issues.
|
|
114
|
+
|
|
179
115
|
---
|
|
180
116
|
|
|
181
|
-
##
|
|
117
|
+
## API
|
|
182
118
|
|
|
183
|
-
|
|
119
|
+
| Tool | Description | Key behavior |
|
|
120
|
+
| ------------- | ------------------------- | --------------------------------------------------- |
|
|
121
|
+
| `plan_create` | Create a new plan | Validates full structure via Zod |
|
|
122
|
+
| `plan_list` | List plans by status/type | Reads only lightweight `metadata.json` files |
|
|
123
|
+
| `plan_read` | Read plan content | Supports `summary`, `spec`, `plan`, or `full` views |
|
|
124
|
+
| `plan_update` | Update status or tasks | Atomic folder moves, batch task updates |
|
|
184
125
|
|
|
185
|
-
|
|
126
|
+
### `plan_create`
|
|
186
127
|
|
|
187
128
|
```typescript
|
|
188
129
|
plan_create({
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
130
|
+
metadata: {
|
|
131
|
+
title: "JWT Authentication",
|
|
132
|
+
type: "feature",
|
|
133
|
+
description: "Secure auth flow with refresh tokens",
|
|
134
|
+
},
|
|
135
|
+
specifications: {
|
|
193
136
|
description: "Implement secure JWT-based authentication",
|
|
194
137
|
functionals: ["User login", "Token refresh"],
|
|
195
138
|
nonFunctionals: ["Passwords hashed with bcrypt"],
|
|
196
|
-
acceptanceCriterias: ["Successful login returns valid JWT"],
|
|
139
|
+
acceptanceCriterias: ["Successful login returns a valid JWT"],
|
|
197
140
|
outOfScope: ["Social OAuth"],
|
|
198
141
|
},
|
|
199
142
|
implementation: {
|
|
200
143
|
description: "Phased rollout",
|
|
201
144
|
phases: [
|
|
202
145
|
{
|
|
203
|
-
|
|
204
|
-
tasks: [
|
|
146
|
+
name: "Phase 1: Database",
|
|
147
|
+
tasks: [
|
|
148
|
+
{ content: "Create users table", status: "pending" },
|
|
149
|
+
{ content: "Create sessions table", status: "pending" },
|
|
150
|
+
],
|
|
205
151
|
},
|
|
206
152
|
],
|
|
207
153
|
},
|
|
208
154
|
});
|
|
209
155
|
```
|
|
210
156
|
|
|
211
|
-
###
|
|
212
|
-
|
|
213
|
-
Agents can request only the information they need, significantly reducing token costs.
|
|
157
|
+
### `plan_read` — selective views
|
|
214
158
|
|
|
215
159
|
```typescript
|
|
216
|
-
|
|
217
|
-
plan_read({ id: "feature_auth", view: "
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
plan_read({ id: "feature_auth", view: "spec" });
|
|
221
|
-
|
|
222
|
-
// Plan View: Just the task list (useful for the Builder)
|
|
223
|
-
plan_read({ id: "feature_auth", view: "plan" });
|
|
160
|
+
plan_read({ id: "feature_auth", view: "summary" }); // metadata + progress stats
|
|
161
|
+
plan_read({ id: "feature_auth", view: "spec" }); // requirements only
|
|
162
|
+
plan_read({ id: "feature_auth", view: "plan" }); // task list only
|
|
163
|
+
plan_read({ id: "feature_auth", view: "full" }); // everything
|
|
224
164
|
```
|
|
225
165
|
|
|
226
|
-
###
|
|
227
|
-
|
|
228
|
-
Update multiple tasks or move a plan through the lifecycle with validation.
|
|
166
|
+
### `plan_update` — batch task updates
|
|
229
167
|
|
|
230
168
|
```typescript
|
|
231
169
|
plan_update({
|
|
@@ -240,25 +178,16 @@ plan_update({
|
|
|
240
178
|
|
|
241
179
|
---
|
|
242
180
|
|
|
243
|
-
##
|
|
244
|
-
|
|
245
|
-
| Tool | Purpose | Key Optimization |
|
|
246
|
-
| :------------ | :--------------------- | :---------------------------------------- |
|
|
247
|
-
| `plan_create` | Initializes a new plan | Validates structure via Zod |
|
|
248
|
-
| `plan_list` | Scans available plans | Reads only 200B metadata files |
|
|
249
|
-
| `plan_read` | Loads plan content | Supports selective views for token saving |
|
|
250
|
-
| `plan_update` | Updates state/tasks | Atomic folder moves + batch updates |
|
|
251
|
-
|
|
252
|
-
---
|
|
253
|
-
|
|
254
|
-
## 🧪 Development
|
|
181
|
+
## Development
|
|
255
182
|
|
|
256
183
|
```bash
|
|
257
|
-
bun install
|
|
258
|
-
bun test
|
|
259
|
-
bun build
|
|
184
|
+
bun install # Install dependencies
|
|
185
|
+
bun test # Run test suite
|
|
186
|
+
bun build # Build for production
|
|
260
187
|
```
|
|
261
188
|
|
|
262
|
-
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## License
|
|
263
192
|
|
|
264
|
-
MIT © 2026
|
|
193
|
+
MIT © 2026 [Yuri Maciel](https://github.com/yurihbm)
|