Integration Examples

Agentic-kanban works with any agent that can run a CLI. These guides show real setups for Pi, Claude Code, and raw CLI workflows.

Pi subagents (three-coder setup)

Pi discovers the kanban extension at startup, registering 9 typed tools. Each role gets a .md file with YAML frontmatter and a skill reference.

setup
# Init project with pi harness
kanban init --harness pi --plan plan.md

This creates .pi/extensions/kanban.ts (auto-registers at startup) and .pi/agents/ with role definitions. Each agent reads its .md file and uses typed tools instead of raw bash.

Run agents with:

terminal
pi run manager    # dispatches work
pi run worker     # claims and completes
pi run reviewer   # approves or rejects

Registered tools: claim_next_task, dispatch_task, log_progress, block_task, complete_task, approve_task, reject_task, review_backlog, view_task. Tools auto-detect the kanban database path by walking up from the current directory.

See the full guide at examples/pi-subagents.md.

Claude Code subagents

Uses Claude's native subagent/agent delegation. Each agent runs as a separate claude process with its own prompt and skill reference.

setup
kanban init --harness claude --plan plan.md

Manager agent — plans and dispatches work:

manager.md
You are a manager agent. You plan and dispatch work.

1. Create tasks: kanban task dispatch --title "..." --role worker --priority N
2. Check backlog: kanban task search --status TODO
3. Check blockers: kanban task search --status BLOCKED
4. Inspect tasks: kanban task view TASK-N

Read skill files in .claude/agents/manager/skills/ for detailed syntax.

Worker agent — claims and executes:

worker.md
You are a worker agent.

1. Claim: kanban task claim-next --agent worker-1 --role worker
2. If no work ({}), report idle.
3. Log progress: kanban task log-progress TASK-N --agent worker-1 --note "..."
4. When done: kanban task complete TASK-N --agent worker-1
5. If blocked: kanban task block TASK-N --agent worker-1 --reason "..."

Read skill files in .claude/agents/worker/skills/ for exact command syntax.

Reviewer agent — approves or rejects:

reviewer.md
You are a reviewer agent.

1. Find IN_REVIEW: kanban task search --status IN_REVIEW
2. View details: kanban task view TASK-N
3. Approve: kanban task approve TASK-N --agent reviewer-1
4. Reject: kanban task reject TASK-N --agent reviewer-1 --reason "..."

No need to claim IN_REVIEW tasks — approve/reject directly.

Run with:

terminal
claude -p "$(cat manager.md)" -f
claude -p "$(cat worker.md)" -f --allowedTools "bash"
claude -p "$(cat reviewer.md)" -f --allowedTools "bash"

# Or use Claude subagents inside a session:
claude dev --agent worker -p "$(cat worker.md)" --allowedTools "bash"

See the full guide at examples/claude-code-subagents.md.

Raw CLI workflow

No agents, no framework — just the kanban binary. Useful for manual debugging, CI/CD pipelines, or scripting.

terminal
# Initialize
cd my-project
kanban init

# Create tasks
kanban task dispatch --title "Refactor auth" --role worker --priority 10
kanban task dispatch --title "Write tests" --role worker --priority 20 --depends-on TASK-1

# Claim and work
kanban task claim-next --agent my-agent --role worker
kanban task log-progress TASK-1 --agent my-agent --note "Extracted middleware" --type PROGRESS
kanban task complete TASK-1 --agent my-agent --review

# Review
kanban task search --status IN_REVIEW
kanban task view TASK-1
kanban task approve TASK-1 --agent reviewer-1

# Or: complete without review (directly to DONE)
kanban task complete TASK-2 --agent my-agent

# Check board
kanban task search --project default
kanban task stats

Batch workflow

For higher throughput, use batch commands to operate on multiple tasks atomically:

terminal
# Claim 5 tasks at once (higher throughput)
kanban batch claim --agent fast-agent --role worker --count 5

# Batch set priority across tasks
kanban batch set-priority --ids TASK-1,TASK-2,TASK-3 --priority 5

# Reassign to a project
kanban batch set-project --ids TASK-5,TASK-6 --project sprint-2

Crash recovery demo

The lease model means crash recovery is automatic — no monitoring, no daemon, no infrastructure.

scenario
# 1. Alice claims TASK-1, starts working
$ kanban task claim-next --agent alice --role worker
→ TASK-1: IN_PROGRESS, lease_until=now+15m

# 2. Alice crashes mid-flight
#    (no log-progress heartbeat sent)

# 3. 15 minutes later... lease expires
#    Bob calls claim-next, no one told Bob about the crash
$ kanban task claim-next --agent bob --role worker
→ TASK-1: expired lease, reclaiming
→ TASK-1: IN_PROGRESS, assigned=bob, lease_until=now+15m

# Bob picks up where Alice left off (last progress note visible in view)
$ kanban task view TASK-1 | jq '.notes[-1]'
{
  "content": "Implemented core logic, tests remaining",
  "author": "alice",
  "note_type": "PROGRESS"
}