A structured development workflow plugin for OpenCode. Guides developers through a repeatable task lifecycle: task → research → plan → execute → commit → review → readme.
Inspired by agentic.
Add to your project's opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-workflow"]
}OpenCode installs it automatically on startup.
Works behind corporate proxies or air-gapped environments — no package manager needed.
# Clone once, anywhere on your machine
git clone https://github.com/chethann/opencode-tasks.git
# From your project directory, run the setup script
cd /path/to/your-project
/path/to/opencode-tasks/setup.shOr pass the target project as an argument:
/path/to/opencode-tasks/setup.sh /path/to/your-projectThis creates symlinks in .opencode/ pointing to the cloned repo. Updates to the clone are picked up automatically (command changes instantly, plugin changes on OpenCode restart).
curl -fsSL https://raw.githubusercontent.com/chethann/opencode-tasks/main/install.sh | bashThis copies the plugin and commands into your project's .opencode/ directory.
/task → /research → /plan → /execute → /commit → /review → /readme
Each step reads context from the previous step via .wip/ — a hidden directory of per-task workflow files in your project root.
| Command | Description |
|---|---|
/task |
Interactively create a new task (name, description, requirements, success criteria) |
/switch [id] |
Switch the active task |
/load-task [id] |
Load a task's full context into the current session |
/dashboard |
Open the workflow dashboard in your browser |
/research |
Analyze the codebase in context of the active task |
/plan |
Generate a phased implementation plan from the research |
/execute |
Implement the plan (runs in primary session, makes real changes) |
/commit |
Draft a conventional commit message (does NOT run git) |
/review |
Validate implementation against the plan and requirements |
/readme |
Generate or update the project README |
All commands are routed to the task-orchestrator agent — a workflow-aware subagent with a system prompt that understands the .wip/ file structure, status gates, and naming conventions. This means commands don't need to repeat workflow context in every prompt.
The agent definition lives at agents/task-orchestrator.md and is installed to .opencode/agents/.
Each command enforces that the prior step is complete before proceeding. If the prerequisite isn't met, the command stops and asks you to complete the prior step first (or override).
/task → (no prerequisite)
/research → task description exists
/plan → at least one research entry
/execute → at least one plan entry
/commit → execution started
/review → execution completed
/readme → at least one approved review
Research, plans, and reviews support multiple iterations per task. Each new run appends with an incrementing index (_0, _1, _2). Commands always read the latest entry.
Every task gets its own self-contained directory under .wip/tasks/:
.wip/
├── .active # Current active task ID
├── tasks/
│ ├── my-task/
│ │ ├── task.json # Metadata + file pointers (central tracking)
│ │ ├── task.md # Human-readable description
│ │ ├── research_2026-04-22_0.md # Codebase analysis (iteration 0)
│ │ ├── plan_0.md # Implementation plan (iteration 0)
│ │ └── review_2026-04-22_0.md # Post-implementation review (iteration 0)
│ └── another-task/
│ ├── task.json
│ ├── task.md
│ └── ...
└── archive/ # Outdated/completed task dirs
Central metadata file per task. Tracks status, timestamps, and pointers to all generated files:
{
"id": "my-task",
"title": "Add OAuth Google login",
"type": "feat",
"status": "planning",
"created_at": "2026-04-21T10:00:00Z",
"updated_at": "2026-04-21T14:30:00Z",
"task": { "file": ".wip/tasks/my-task/task.md", "created_at": "..." },
"research": [{ "index": 0, "file": ".wip/tasks/my-task/research_2026-04-21_0.md", "created_at": "..." }],
"plans": [{ "index": 0, "file": ".wip/tasks/my-task/plan_0.md", "created_at": "..." }],
"execute": { "started_at": null, "completed_at": null },
"commit": { "drafts": [], "committed": false },
"reviews": [{ "index": 0, "file": ".wip/tasks/my-task/review_2026-04-21_0.md", "outcome": "approved" }],
"readme": { "updated_at": null }
}Run /dashboard in OpenCode to launch a local web UI at http://localhost:3456.
Features:
- Task list — all tasks sorted by activity, active task highlighted
- Progress bar — visual step-by-step status (drafting → done)
- Metadata cards — type, status, timestamps, iteration counts
- File browser — click any workflow file to view its contents in a modal
- Action buttons — copy the next workflow command to clipboard, paste into OpenCode
- Auto-refresh — updates every 5 seconds
Zero dependencies — runs on Bun's built-in HTTP server.
The plugin registers these tools for use by commands:
| Tool | Purpose |
|---|---|
workflow-context |
Read active task JSON (file pointers, status, history) |
workflow-update |
Update task JSON (status, add file entries, timestamps) |
workflow-task-init |
Create a new task (directory + JSON + markdown + set active) |
workflow-switch |
Switch the active task |
workflow-gate-check |
Check if prerequisites for a step are met |
To iterate on this plugin locally, symlink it into your target project:
# In your target project
mkdir -p .opencode/plugins .opencode/commands .opencode/agents
# Symlink plugin
ln -s /path/to/opencode-workflow/index.ts .opencode/plugins/opencode-workflow.ts
# Symlink dashboard server
ln -s /path/to/opencode-workflow/dashboard.ts .opencode/plugins/opencode-workflow-dashboard.ts
# Symlink agent
ln -s /path/to/opencode-workflow/agents/task-orchestrator.md .opencode/agents/task-orchestrator.md
# Symlink commands
for cmd in task switch load-task dashboard research plan execute commit review readme; do
ln -s /path/to/opencode-workflow/commands/${cmd}.md .opencode/commands/${cmd}.md
doneThen add the @opencode-ai/plugin dependency:
cat > .opencode/package.json <<EOF
{
"dependencies": {
"@opencode-ai/plugin": "latest"
}
}
EOF- Command file changes (
*.md) take effect on next command run — no restart needed. - Plugin file changes (
index.ts) require quitting and reopening OpenCode.
- Add
.wip/to.gitignoreif you don't want workflow files in version control, or commit them for shared team context. - Run
/load-taskto reload full task context after starting a new session or after compaction. - Run
/switchto jump between tasks without losing context. - Each task is fully self-contained in its own directory — easy to archive, share, or delete.
- Compaction-safe: The plugin injects active task metadata into the compaction summary, so the agent retains awareness of the current task even after context trimming.
MIT