https://github.com/yurihbm/opencode-plan-manager
A simple collection of tools for better plan management by AI agents on OpenCode.
https://github.com/yurihbm/opencode-plan-manager
ai-agent opencode planning plugin
Last synced: about 2 months ago
JSON representation
A simple collection of tools for better plan management by AI agents on OpenCode.
- Host: GitHub
- URL: https://github.com/yurihbm/opencode-plan-manager
- Owner: yurihbm
- License: mit
- Created: 2026-02-06T18:53:32.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-30T00:56:39.000Z (3 months ago)
- Last Synced: 2026-04-03T04:54:48.382Z (2 months ago)
- Topics: ai-agent, opencode, planning, plugin
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/opencode-plan-manager
- Size: 8.14 MB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenCode Plan Manager
[](https://opencode.ai)
[](https://www.typescriptlang.org/)
[](https://bun.sh)
[](https://github.com/yurihbm/opencode-plan-manager/actions/workflows/test.yml)
**AI-native implementation planning for agentic workflows.**
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.
---
## Why Plan Manager?
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:
- **Selective context loading** — agents read only what they need: `summary` (stats), `spec` (requirements), or `plan` (task list).
- **Zero-hallucination schemas** — strict Zod validation prevents malformed plans and invalid state transitions.
- **Filesystem Kanban** — plan state lives in `pending/`, `in_progress/`, and `done/` folders. Atomic, human-readable, no hidden database.
- **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.
Designed for the **Planner → Builder** pattern: a Plan Agent architects the spec, a Build Agent executes it with no ambiguity.
---
## Installation
Add the plugin to your OpenCode configuration (`~/.config/opencode/opencode.json`):
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-plan-manager@1.1.4"],
}
```
> Pinning the version improves OpenCode startup time.
---
## Configuration
Config is loaded with the following precedence (highest → lowest):
1. **Project:** `/.opencode/plan-manager.json`
2. **User:** `~/.config/opencode/plan-manager.json`
3. **Defaults:** built-in fallback
```jsonc
{
// "markdown" (default), "json", or "toon" (https://github.com/toon-format/toon)
"outputFormat": "markdown",
}
```
Permission setup
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.
Example config for the Plan agent:
```jsonc
{
"agent": {
"plan": {
"permission": {
"edit": {
"*": "deny",
".opencode/plans/*": "ask",
},
},
},
},
}
```
See [opencode.ai/docs/permissions](https://opencode.ai/docs/permissions) for details.
---
## Agentic Workflow
Plan Manager is optimized for a two-agent hierarchy, with prompts in `src/prompts/`:
| Agent | Role |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plan Agent** (`plan.txt`) | Architect. Transforms vague requirements into phased, structured plans via a 4-step process: Analysis → Deduplication → Context Decision → Plan Creation. |
| **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. |
> 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.
---
## Filesystem Layout
```text
.opencode/plans/
├── pending/
│ └── feature_auth/
│ ├── metadata.json
│ ├── specifications.md
│ └── implementation.md
├── in_progress/
└── done/
```
Each plan is an isolated folder. Status moves atomically between `pending/`, `in_progress/`, and `done/` — no database, no sync issues.
---
## API
| Tool | Description | Key behavior |
| ------------- | ------------------------- | --------------------------------------------------- |
| `plan_create` | Create a new plan | Validates full structure via Zod |
| `plan_list` | List plans by status/type | Reads only lightweight `metadata.json` files |
| `plan_read` | Read plan content | Supports `summary`, `spec`, `plan`, or `full` views |
| `plan_update` | Update status or tasks | Atomic folder moves, batch task updates |
### `plan_create`
```typescript
plan_create({
metadata: {
title: "JWT Authentication",
type: "feature",
description: "Secure auth flow with refresh tokens",
},
specifications: {
description: "Implement secure JWT-based authentication",
functionals: ["User login", "Token refresh"],
nonFunctionals: ["Passwords hashed with bcrypt"],
acceptanceCriterias: ["Successful login returns a valid JWT"],
outOfScope: ["Social OAuth"],
},
implementation: {
description: "Phased rollout",
phases: [
{
name: "Phase 1: Database",
tasks: [
{ content: "Create users table", status: "pending" },
{ content: "Create sessions table", status: "pending" },
],
},
],
},
});
```
### `plan_read` — selective views
```typescript
plan_read({ id: "feature_auth", view: "summary" }); // metadata + progress stats
plan_read({ id: "feature_auth", view: "spec" }); // requirements only
plan_read({ id: "feature_auth", view: "plan" }); // task list only
plan_read({ id: "feature_auth", view: "full" }); // everything
```
### `plan_update` — batch task updates
```typescript
plan_update({
id: "feature_auth",
status: "in_progress",
taskUpdates: [
{ content: "Create users table", status: "done" },
{ content: "Create sessions table", status: "in_progress" },
],
});
```
---
## Development
```bash
bun install # Install dependencies
bun test # Run test suite
bun build # Build for production
```
---
## License
MIT © 2026 [Yuri Maciel](https://github.com/yurihbm)