An interactive issue/ticket creation agent for the ZenBPM project. ZenPlanner runs inside OpenCode and helps you create well-structured project tickets using defined archetypes (Epic, Story, Task, Bug, Spike, Improvement) with relations, size estimates, and developer hints.
- Node.js (v18+) and npm
- OpenCode (UI recommended, CLI also works)
https://opencode.ai/download
npm install
npm run buildThis produces the dist/ directory containing the built plugin.
Add the plugin to your OpenCode config. Either in your global config (~/.config/opencode/opencode.json) or in a project-level opencode.json:
{
"plugin": [
"file:///absolute/path/to/ai-issues-agent/dist/index.js"
]
}Replace the path with the actual absolute path to your built dist/index.js. For example on macOS:
{
"plugin": [
"file:///Users/yourname/projects/ai-issues-agent/dist/index.js"
]
}That's it — the plugin ships everything inside: the agent definition, prompt, tools, ZenBPM project knowledge, and archetypes.
ZenPlanner has been tested with Claude Opus on Anthropic Max/Pro, but works with any model OpenCode supports (GPT, Copilot, etc.).
- Open the OpenCode app
- Click the Settings icon (or press
/and typelogin) - Click Add Provider and select your provider (e.g. Anthropic)
- For Anthropic Max/Pro: click Login with browser — this opens your browser to authenticate
- For API key: paste your key directly (e.g.
sk-ant-...) - Once connected, select your preferred model (e.g.
claude-opus-4-6)
You can connect multiple providers (OpenAI, Copilot, etc.) and switch between models at any time.
- Open the OpenCode app
- Navigate to any directory where you want to work (use the folder picker or open OpenCode from that directory)
ZenPlanner registers as a primary agent. You need to switch to it before you start:
- Press
Tabto cycle through available agents until you see ZenPlanner - Alternatively, press
@to open the agent list and select ZenPlanner from there
When you start a session, ZenPlanner checks if the ZenBPM source code (zenbpm/ and zenbpm-ui/ directories) is available in your current working directory. If not, it will ask you whether it should download the repositories from GitHub. The repos are public:
You can choose to:
- Download both — full context for backend and frontend issues
- Download only one — if you only need backend or frontend
- Skip — continue without source code (issues will have less specific developer hints)
This was tested on macOS and works out of the box.
Once ZenPlanner is active, just describe what you need:
- "Create a bug report for the process instance detail page crashing when variables are empty"
- "Plan out a feature for adding DMN evaluation history"
- "I need a task for adding pagination to the incidents endpoint"
ZenPlanner will:
- Ask you structured questions using interactive UI (radio buttons, options)
- Walk you through the archetype fields step by step
- Browse the source code for relevant developer hints
- Create the issue as a markdown file in
.zenplanner/issues/
| Type | Purpose |
|---|---|
| Epic | Large initiative with business goals and success criteria |
| Story | User-facing feature with acceptance criteria |
| Task | Technical work item with implementation steps |
| Bug | Defect report with reproduction steps |
| Spike | Research/investigation with time-box and deliverables |
| Improvement | Enhancement to existing functionality |
Each issue includes: size estimate (XS/S/M/L/XL), priority, relations to other issues (blocks, blocked_by, child_of, etc.), and archetype-specific custom attributes.
Archetype definitions are in archetypes/archetypes.json with templates in archetypes/templates/*.txt. After editing these, rebuild the plugin with npm run build.
ai-issues-agent/
├── src/
│ ├── index.ts # Plugin entry point (agent registration, prompt, tools)
│ ├── config/
│ │ ├── archetypes.ts # Archetype loader
│ │ └── project-context.ts # Project context loader
│ └── tools/
│ ├── issue-create.ts # Create issues as markdown files
│ ├── issue-list.ts # List created issues
│ ├── issue-edit.ts # Edit existing issues
│ ├── issue-archetypes.ts # List/inspect archetypes
│ └── issue-context.ts # Load project context + repo availability check
├── archetypes/
│ ├── archetypes.json # Archetype definitions
│ └── templates/ # Markdown templates per archetype
├── package.json
└── tsconfig.json
MIT