{"id":44395263,"url":"https://github.com/yurihbm/opencode-plan-manager","last_synced_at":"2026-04-19T20:02:05.324Z","repository":{"id":337293250,"uuid":"1151671762","full_name":"yurihbm/opencode-plan-manager","owner":"yurihbm","description":"A simple collection of tools for better plan management by AI agents on OpenCode.","archived":false,"fork":false,"pushed_at":"2026-03-30T00:56:39.000Z","size":8535,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T04:54:48.382Z","etag":null,"topics":["ai-agent","opencode","planning","plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/opencode-plan-manager","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yurihbm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T18:53:32.000Z","updated_at":"2026-03-30T00:56:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yurihbm/opencode-plan-manager","commit_stats":null,"previous_names":["yurihbm/opencode-plan-manager"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/yurihbm/opencode-plan-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurihbm%2Fopencode-plan-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurihbm%2Fopencode-plan-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurihbm%2Fopencode-plan-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurihbm%2Fopencode-plan-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yurihbm","download_url":"https://codeload.github.com/yurihbm/opencode-plan-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurihbm%2Fopencode-plan-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32020702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","opencode","planning","plugin"],"created_at":"2026-02-12T03:17:45.121Z","updated_at":"2026-04-19T20:02:05.318Z","avatar_url":"https://github.com/yurihbm.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCode Plan Manager\n\n[![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-black)](https://opencode.ai)\n[![TypeScript](https://img.shields.io/badge/TypeScript-blue)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-orange)](https://bun.sh)\n[![Test](https://github.com/yurihbm/opencode-plan-manager/actions/workflows/test.yml/badge.svg)](https://github.com/yurihbm/opencode-plan-manager/actions/workflows/test.yml)\n\n**AI-native implementation planning for agentic workflows.**\n\nStop 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.\n\n![OPM Preview](assets/opm_preview.gif)\n\n---\n\n## Why Plan Manager?\n\nAgentic 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:\n\n- **Selective context loading** — agents read only what they need: `summary` (stats), `spec` (requirements), or `plan` (task list).\n- **Zero-hallucination schemas** — strict Zod validation prevents malformed plans and invalid state transitions.\n- **Filesystem Kanban** — plan state lives in `pending/`, `in_progress/`, and `done/` folders. Atomic, human-readable, no hidden database.\n- **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.\n\nDesigned for the **Planner → Builder** pattern: a Plan Agent architects the spec, a Build Agent executes it with no ambiguity.\n\n---\n\n## Installation\n\nAdd the plugin to your OpenCode configuration (`~/.config/opencode/opencode.json`):\n\n```jsonc\n{\n\t\"$schema\": \"https://opencode.ai/config.json\",\n\t\"plugin\": [\"opencode-plan-manager@1.1.4\"],\n}\n```\n\n\u003e Pinning the version improves OpenCode startup time.\n\n---\n\n## Configuration\n\nConfig is loaded with the following precedence (highest → lowest):\n\n1. **Project:** `\u003cproject-root\u003e/.opencode/plan-manager.json`\n2. **User:** `~/.config/opencode/plan-manager.json`\n3. **Defaults:** built-in fallback\n\n```jsonc\n{\n\t// \"markdown\" (default), \"json\", or \"toon\" (https://github.com/toon-format/toon)\n\t\"outputFormat\": \"markdown\",\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePermission setup\u003c/strong\u003e\u003c/summary\u003e\n\nPlan 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.\n\nExample config for the Plan agent:\n\n```jsonc\n{\n\t\"agent\": {\n\t\t\"plan\": {\n\t\t\t\"permission\": {\n\t\t\t\t\"edit\": {\n\t\t\t\t\t\"*\": \"deny\",\n\t\t\t\t\t\".opencode/plans/*\": \"ask\",\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t},\n}\n```\n\nSee [opencode.ai/docs/permissions](https://opencode.ai/docs/permissions) for details.\n\n\u003c/details\u003e\n\n---\n\n## Agentic Workflow\n\nPlan Manager is optimized for a two-agent hierarchy, with prompts in `src/prompts/`:\n\n| Agent                         | Role                                                                                                                                                          |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Plan Agent** (`plan.txt`)   | Architect. Transforms vague requirements into phased, structured plans via a 4-step process: Analysis → Deduplication → Context Decision → Plan Creation.     |\n| **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. |\n\n\u003e 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.\n\n---\n\n## Filesystem Layout\n\n```text\n.opencode/plans/\n├── pending/\n│   └── feature_auth/\n│       ├── metadata.json\n│       ├── specifications.md\n│       └── implementation.md\n├── in_progress/\n└── done/\n```\n\nEach plan is an isolated folder. Status moves atomically between `pending/`, `in_progress/`, and `done/` — no database, no sync issues.\n\n---\n\n## API\n\n| Tool          | Description               | Key behavior                                        |\n| ------------- | ------------------------- | --------------------------------------------------- |\n| `plan_create` | Create a new plan         | Validates full structure via Zod                    |\n| `plan_list`   | List plans by status/type | Reads only lightweight `metadata.json` files        |\n| `plan_read`   | Read plan content         | Supports `summary`, `spec`, `plan`, or `full` views |\n| `plan_update` | Update status or tasks    | Atomic folder moves, batch task updates             |\n\n### `plan_create`\n\n```typescript\nplan_create({\n\tmetadata: {\n\t\ttitle: \"JWT Authentication\",\n\t\ttype: \"feature\",\n\t\tdescription: \"Secure auth flow with refresh tokens\",\n\t},\n\tspecifications: {\n\t\tdescription: \"Implement secure JWT-based authentication\",\n\t\tfunctionals: [\"User login\", \"Token refresh\"],\n\t\tnonFunctionals: [\"Passwords hashed with bcrypt\"],\n\t\tacceptanceCriterias: [\"Successful login returns a valid JWT\"],\n\t\toutOfScope: [\"Social OAuth\"],\n\t},\n\timplementation: {\n\t\tdescription: \"Phased rollout\",\n\t\tphases: [\n\t\t\t{\n\t\t\t\tname: \"Phase 1: Database\",\n\t\t\t\ttasks: [\n\t\t\t\t\t{ content: \"Create users table\", status: \"pending\" },\n\t\t\t\t\t{ content: \"Create sessions table\", status: \"pending\" },\n\t\t\t\t],\n\t\t\t},\n\t\t],\n\t},\n});\n```\n\n### `plan_read` — selective views\n\n```typescript\nplan_read({ id: \"feature_auth\", view: \"summary\" }); // metadata + progress stats\nplan_read({ id: \"feature_auth\", view: \"spec\" }); // requirements only\nplan_read({ id: \"feature_auth\", view: \"plan\" }); // task list only\nplan_read({ id: \"feature_auth\", view: \"full\" }); // everything\n```\n\n### `plan_update` — batch task updates\n\n```typescript\nplan_update({\n\tid: \"feature_auth\",\n\tstatus: \"in_progress\",\n\ttaskUpdates: [\n\t\t{ content: \"Create users table\", status: \"done\" },\n\t\t{ content: \"Create sessions table\", status: \"in_progress\" },\n\t],\n});\n```\n\n---\n\n## Development\n\n```bash\nbun install # Install dependencies\nbun test    # Run test suite\nbun build   # Build for production\n```\n\n---\n\n## License\n\nMIT © 2026 [Yuri Maciel](https://github.com/yurihbm)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurihbm%2Fopencode-plan-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyurihbm%2Fopencode-plan-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurihbm%2Fopencode-plan-manager/lists"}