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.
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), orplan(task list). - Zero-hallucination schemas — strict Zod validation prevents malformed plans and invalid state transitions.
- Filesystem Kanban — plan state lives in
pending/,in_progress/, anddone/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.
Add the plugin to your OpenCode configuration (~/.config/opencode/opencode.json):
Config is loaded with the following precedence (highest → lowest):
- Project:
<project-root>/.opencode/plan-manager.json - User:
~/.config/opencode/plan-manager.json - Defaults: built-in fallback
{
// "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:
{
"agent": {
"plan": {
"permission": {
"edit": {
"*": "deny",
".opencode/plans/*": "ask",
},
},
},
},
}See opencode.ai/docs/permissions for details.
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
PlanandBuildagents (docs) with injected system prompts. Your own custom prompts always take priority.
The examples/ folder contains complete plan folders generated by agents using this plugin, including metadata.json, specifications.md, and implementation.md:
| Example | Description |
|---|---|
feature_authentication-system-for-nestjs-rest-api_20260317_f6dd | Production-oriented NestJS authentication plan with JWT, refresh token rotation, RBAC, password reset, and test coverage requirements. |
feature_telemetry-and-observability-opentelemetry-grafana-lgtm_20260315 | End-to-end observability plan covering OpenTelemetry instrumentation, provider abstraction, Docker Compose infrastructure, and verification steps. |
These are useful reference outputs for the level of detail and structure the plan tools are designed to produce.
.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.
| 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({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({id: "feature_auth",view: "summary"});// metadata + progress statsplan_read({id: "feature_auth",view: "spec"});// requirements onlyplan_read({id: "feature_auth",view: "plan"});// task list onlyplan_read({id: "feature_auth",view: "full"});// everythingplan_update({id: "feature_auth",status: "in_progress",taskUpdates: [{content: "Create users table",status: "done"},{content: "Create sessions table",status: "in_progress"},],});bun install # Install dependencies
bun test# Run test suite
bun build # Build for productionMIT © 2026 Yuri Maciel
{ "$schema": "https://opencode.ai/config.json", "plugin": ["opencode-plan-manager"], }