ericblue/claude-vibekanban: PRD-to-Tasks Workflow for Claude Code + VibeKanban

A structured, prompt-driven workflow for going from project idea to tracked, executable tasks using VibeKanban and AI coding agents. While this repo ships as Claude Code slash commands, the underlying workflow — PRD generation, planning, task breakdown, execution, and sync — works with any agent that connects to VibeKanban’s MCP API.

This is a lightweight workflow, not a platform. There’s no app to install, no server to run, no database to manage — just markdown-based slash commands that plug into Claude Code. The entire system is a process and methodology with minimal overhead.

Most AI coding tools help you write code faster. This helps you decide what to build, break it down, and coordinate the work — then lets any AI agent do the coding.

• Zero infrastructure — slash commands are markdown files you drop into Claude Code. No build step, no dependencies.
• Structured planning — starts with PRD generation, epic decomposition, and dependency analysis, not a blank editor
• Persistent tracking — task status lives in VibeKanban across sessions, not just within a single conversation
• Safe parallelism — analyzes the dependency graph before spawning agents, so blocked tasks don’t run
• Local and remote execution — run agents locally via git worktrees (Tier 1) or delegate to remote VibeKanban workspace sessions (Tier 2)
• Agent-agnostic — when using VibeKanban for delegation, any supported agent can pick up a task: Claude Code, Cursor, Codex, Gemini, Copilot, or custom agents. You’re not locked to running Claude Code locally.
• Adaptable — the workflow (PRD → plan → tasks → execute → sync) is the real value, not the specific integrations. The slash commands use VibeKanban today, but the patterns could be adapted to any external task management system (Linear, Jira, GitHub Issues) by swapping the MCP layer.

See docs/comparisons.md for detailed comparisons with AutoMaker, Claude Code Agent Teams, Cursor, Aider, and other tools.

VibeKanban is a Kanban-style project board designed for AI-assisted development. It provides an MCP (Model Context Protocol) server that lets AI agents create, update, and track tasks programmatically. Agents like Claude Code, Cursor, Codex, Gemini, and others can connect through the MCP API to:

• Create and manage tasks directly from the agent’s context
• Update task status (todo, inprogress, inreview, done) as work progresses
• Orchestrate multiple agents on the same project board
• Start workspace sessions that pair an agent with a task and repo

VibeKanban acts as the shared coordination layer — the agent does the coding, VK tracks what’s been done and what’s left.

This repo provides 17 slash commands (12 core + 5 experimental) that build a complete development pipeline on top of VibeKanban’s MCP API:

1. PRD (Product Requirements Document) defines what to build
2. Development Plan breaks it down into epics, tasks, dependencies, and acceptance criteria
3. VibeKanban tracks execution and progress across agents
4. Execution commands let agents pick up tasks, implement them, and verify acceptance criteria
5. Sync keeps the plan and board aligned with drift detection

flowchart LR
    Idea[💡 Project Idea] --> GenPRD[📝 /generate-prd]
    GenPRD --> PRD[📄 PRD
docs/prd.md]
    PRD --> Review[🔍 /prd-review]
    Review --> Questions[❓ Clarifying
Questions]
    Questions --> Answers[✅ User
Answers]
    Answers --> Plan[📋 /create-plan]
    Plan --> DevPlan[📝 Development Plan
with Epics]
    DevPlan --> Generate[⚡ /generate-tasks]
    Generate --> VK[📊 VibeKanban
Tasks]
    VK  Sync[🔄 /sync-plan]
    Sync  DevPlan
    DevPlan --> Status[📈 /plan-status]
    DevPlan --> AddEpic[➕ /add-epic]
    DevPlan --> CloseEpic[✅ /close-epic]
    DevPlan --> NextTask[🎯 /next-task]
    NextTask --> WorkNext[🔨 /work-next]
    VK --> WorkTask[🔨 /work-task]
    WorkTask --> VK

Early preview — these commands are experimental and actively evolving. Expect breaking changes over the next few weeks as the execution model is tested and refined. See docs/architecture.md for the full design.

Two execution tiers are supported:

• Tier 1 (Local worktrees): Parallel Claude Code sessions using git worktrees for full file isolation. Each task gets its own branch and working directory.
• Tier 2 (Remote delegation): Spawn separate agent sessions via VibeKanban’s start_workspace_session. Supports Claude Code, Cursor, Codex, Gemini, Copilot, and custom agents.

sequenceDiagram
    participant U as User
    participant C as Claude Code
    participant P as Plan
    participant VK as VibeKanban

    U->>C: /generate-prd
    C->>U: Interview questions
    U->>C: Answers
    C->>P: Create PRD

    U->>C: /prd-review
    C->>U: Clarifying questions
    U->>C: Answers

    U->>C: /create-plan
    C->>P: Create plan (with complexity & dependencies)

    U->>C: /generate-tasks
    C->>VK: Create tasks
    VK-->>C: Task IDs
    C->>P: Link task IDs

    U->>C: /next-task
    C->>P: Parse priorities & dependencies
    C->>VK: Get task statuses
    C->>U: Top 3 recommendations

    U->>C: /work-next (or /work-task [ID])
    C->>P: Read task details + AC
    C->>VK: Mark task inprogress
    C->>C: Implement task
    C->>U: Verify AC + report changes
    U->>C: Confirm done
    C->>VK: Mark task done

    U->>C: /sync-plan
    C->>VK: Get task statuses
    C->>P: Update plan + drift detection

# Clone the repo
git clone https://github.com/ericblue/claude-vibekanban.git
cd claude-vibekanban

# Run the install script
./install.sh

Copy the commands to your Claude Code global commands directory:

# Create the commands directory if it doesn't exist
mkdir -p ~/.claude/commands

# Copy commands
cp commands/*.md ~/.claude/commands/

After installing, the commands should be available in any Claude Code session:

claude
# Then type: /prd-review

If you make changes to commands in this repo and want to apply them:

# Option 1: Re-run install script (will prompt before overwriting)
./install.sh

# Option 2: Force overwrite without prompts
./install.sh --force

# Option 3: Copy specific command
cp commands/sync-plan.md ~/.claude/commands/

# Option 4: Symlink for live updates (development mode)
./install.sh --link

When files already exist in ~/.claude/commands/, the installer will prompt:

⚠ File already exists: sync-plan.md (file)
Overwrite? [y]es / [n]o / [a]ll / [s]kip all:

• y – Overwrite this file
• n – Skip this file
• a – Overwrite all remaining files without prompting
• s – Skip all remaining files without prompting

Use --force or -f to skip all prompts and overwrite everything.

You need VibeKanban MCP configured. See: VibeKanban MCP Documentation

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "vibekanban": {
      "command": "npx",
      "args": ["-y", "@anthropic/vibekanban-mcp"]
    }
  }
}

Your projects should follow this structure:

your-project/
├── docs/
│   ├── prd.md                  # Your PRD (input)
│   └── development-plan.md     # Generated plan (output)
├── src/
└── ...

The development plan uses an epic-based format that enables hierarchical task tracking with progress percentages, complexity estimates, and dependency management:

# Development Plan: Project Name

> **Generated from:** docs/prd.md
> **Created:** 2024-01-22
> **Last synced:** 2024-01-22
> **Status:** Active Planning Document
> **VibeKanban Project ID:** abc-123-def

## Overview

Brief description of what we're building.

## Tech Stack

- **Backend:** Node.js, Express
- **Frontend:** React, TypeScript
- **Database:** PostgreSQL

---

## Completion Status Summary

| Epic | Status | Progress |
|------|--------|----------|
| 1. Foundation | Complete | 100% |
| 2. Core Features | In Progress | 50% |
| 3. Polish | Not Started | 0% |

---

## Epic 1: Foundation (COMPLETE)

Setting up the project infrastructure and dependencies.

### Acceptance Criteria

- [x] Project builds successfully
- [x] CI/CD pipeline runs on commits

### Tasks

| ID | Title | Description | Priority | Complexity | Depends On | Status |
|----|-------|-------------|----------|------------|------------|--------|
| 1.1 | Set up project structure | Initialize with folder structure | High | S | — |  |
| 1.2 | Configure CI/CD | GitHub Actions for testing | Medium | M | 1.1 |  |

### Task Details

**1.1 - Set up project structure**
- [x] Project builds with no errors
- [x] Folder structure follows convention: src/, tests/, docs/
- [x] README includes setup instructions

**1.2 - Configure CI/CD**
- [x] GitHub Actions workflow runs on push to main
- [x] Tests execute and report results in CI
- [x] Build artifacts are generated

---

## Epic 2: Core Features (IN PROGRESS)

Implementing the main application functionality.

### Acceptance Criteria

- [ ] All API endpoints functional
- [ ] Unit test coverage > 80%

### Tasks

| ID | Title | Description | Priority | Complexity | Depends On | Status |
|----|-------|-------------|----------|------------|------------|--------|
| 2.1 | Implement auth | JWT-based authentication | High | L | 1.1, 1.2 |  |
| 2.2 | Add user API | CRUD operations for users | High | M | 2.1 |  |

### Task Details

**2.1 - Implement auth**
- [ ] POST /auth/login returns JWT for valid credentials
- [ ] POST /auth/register creates user and returns token
- [ ] Invalid credentials return 401
- [ ] Unit tests cover happy path and error cases

**2.2 - Add user API**
- [ ] GET /users/:id returns user profile
- [ ] PUT /users/:id updates user fields
- [ ] Endpoints require valid JWT
- [ ] Input validation rejects malformed data

---

## Changelog

- **2024-01-22**: Initial development plan created from PRD
- **2024-01-23**: Epic 1 marked complete; Epic 2 started

Dependencies are tracked in the “Depends On” column using task IDs:

• — means the task has no dependencies and can be started immediately
• 1.1 means the task depends on task 1.1 being completed first
• 1.1, 1.2 means the task depends on both 1.1 and 1.2
• Dependencies can cross epic boundaries (e.g., task 2.1 depending on 1.2)

The /next-task command uses these dependencies to recommend which task to work on next, and /sync-plan detects dependency violations (tasks started before their dependencies are done).

flowchart TD
    Start["/sync-plan"] --> Parse["Parse plan"]
    Parse --> Loop{"For each task"}
    Loop --> HasID{"Has VK ID?"}

    HasID -->|No| Flag["Flag unlinked"]
    HasID -->|Yes| Fetch["Fetch VK status"]

    Fetch --> Compare{"Statuses match?"}

    Compare -->|"VK done, plan unchecked"| Update1["Check box"]
    Compare -->|"VK open, plan checked"| Update2["Uncheck box"]
    Compare -->|Yes| NoChange["No change"]

    Update1 --> Next
    Update2 --> Next
    NoChange --> Next
    Flag --> Next

    Next["Next task"] --> Loop
    Loop -->|"All done"| Report["Sync report"]

Source of Truth: VibeKanban status always wins during sync. This ensures the plan reflects actual work status.

Edit commands/create-plan.md and commands/sync-plan.md to change from docs/development-plan.md to your preferred location.

The default epics in /create-plan are:

1. Foundation/Setup
2. Core Features
3. Supporting Features
4. Polish & UX
5. Testing & Documentation

Modify commands/create-plan.md to adjust these for your workflow. You can also use /add-epic to add new epics to an existing plan.

If VibeKanban supports additional fields (priority, labels, etc.), you can extend the format:

And update the commands to parse/generate these.

1. Ensure commands are in ~/.claude/commands/
2. Restart Claude Code session
3. Check file permissions: ls -la ~/.claude/commands/

1. Verify MCP server is configured: /mcp in Claude Code
2. Check VibeKanban authentication
3. Ensure project exists in VibeKanban

1. Verify task IDs in plan match VibeKanban:
2. Run /generate-tasks to link unlinked tasks
3. Check VibeKanban project has the tasks

1. Fork this repository
2. Make changes to commands in commands/
3. Test with ./install.sh
4. Submit a pull request

MIT License – See LICENSE for details.

While this repo ships as Claude Code slash commands, VibeKanban’s MCP API supports orchestration with multiple agents:

The slash commands in this repo are markdown prompt files — they can be adapted for other agents by translating the instructions into that agent’s prompt format. The MCP tool calls (list_projects, create_task, update_task, etc.) are the same regardless of which agent makes them.

• Cookbook — Walkthroughs, recipes, tips, FAQ, and troubleshooting
• Architecture — Execution model, two-tier parallel execution design, known limitations, and future direction for multi-agent orchestration

A structured, prompt-driven development workflow that bridges product requirements and AI-powered task execution through VibeKanban’s MCP API. Designed to give AI coding agents the full context they need — from PRD to acceptance criteria — to autonomously implement, verify, and track development tasks.

Created by Eric Blue