Kanban

Persistent task board for multi-agent coordination

Kanban enables agents to coordinate through persistent tasks, creating a shared workspace where work is tracked and distributed across multiple agents.

from praisonaiagents import Agent

coordinator = Agent(name="Coordinator", instructions="Break work into kanban tasks")
coordinator.start("Plan the auth feature and assign workers")

The user asks for a feature; the coordinator creates tasks workers pick up from the shared board.

Quick Start

1. Create Agent with Kanban Tools

   from praisonaiagents import Agent
   from praisonaiagents.kanban import KanbanStoreProtocol
   
   # Agent with kanban protocols (implementation needed from wrapper)
   agent = Agent(name="Coordinator", instructions="Break tasks down")
   result = agent.start("Create user auth system")

2. Add Worker Agent

   from praisonaiagents import Agent
   from praisonaiagents.kanban import VALID_KANBAN_STATUSES
   
   worker = Agent(name="Worker", instructions="Claim and complete tasks")
   result = worker.start("Find ready tasks")

How It Works

Task coordination happens through a SQLite-backed persistent store that all agents and the UI share.

Concepts

Task Statuses

Tasks flow through 8 defined states from creation to completion:

Boards

Boards provide workspace isolation for different projects or contexts:

DAG Links

Tasks form directed acyclic graphs through parent-child dependencies:

Claim/Release

Workers coordinate through atomic claim and release operations:

Agent Tools

Kanban tools are available through the SDK protocols. The wrapper implementation provides these agent tools:

Task Management

Status Changes

Coordination

Boards & Storage

Single Board (Default)

~/.praisonai/kanban.db

Multi-Board Layout

~/.praisonai/kanban/boards/
├── project-a/kanban.db
├── project-b/kanban.db
└── team-x/kanban.db

Environment Configuration

Attempt History & Retry

Each kanban task records every attempt, auto-blocks after repeated failures, and hands off a structured summary on completion.

1. Idempotent create with retry limit

   from praisonaiagents import Agent
   from praisonai.tools.kanban_tools import kanban_create
   
   agent = Agent(name="Coordinator", instructions="Break work into tasks")
   
   task = kanban_create(
       "Replace bcrypt with argon2",
       body="Migrate auth module to argon2",
       assignee="coder",
       max_retries=3,                       # per-task circuit-breaker
       idempotency_key="auth-refactor-q3",  # safe to repeat
   )

2. Structured completion handoff

   from praisonai.tools.kanban_tools import kanban_complete
   
   kanban_complete(
       task["id"],
       summary="argon2 migration; 14 tests pass; CHANGELOG updated",
       metadata={
           "changed_files": ["auth.py", "tests/test_auth.py"],
           "tests_run": 14,
           "residual_risk": "rotate old hashes on next login",
       },
   )

3. Read attempt history on retry

   from praisonai.tools.kanban_tools import kanban_runs
   
   history = kanban_runs(task["id"])
   for run in history["runs"]:
       print(run["outcome"], run["error"] or run["summary"])
   # crashed: ModuleNotFoundError: argon2
   # completed: argon2 migration; 14 tests pass; CHANGELOG updated

What the dispatcher does automatically

When a worker claims a task, the dispatcher opens a run with the claim — anything the worker writes via kanban_complete closes it as completed, anything that crashes closes it as crashed/failed. Below the max_retries limit, failed attempts release the claim and put the task back on ready for re-dispatch. At the limit, the task auto-blocks with gave_up so a human can step in. A successful completion resets the failure counter — the limit is consecutive, not cumulative.

Non-blocking git. With per-task worktree isolation (workspace_kind="worktree" or repo_path), every git command the dispatcher runs — fork, merge, cleanup — happens off the gateway event loop, so chat and WebSocket traffic stay responsive during a slow merge. Integrations into the shared repo are serialised, so two tasks never run git merge at the same time. If the dispatcher stops mid-dispatch, a half-prepared worktree and its branch are removed so a retry can recreate them.

New params on kanban_create

New params on kanban_complete

New tool: kanban_runs

Each row matches the KanbanRunProtocol shape:

New Task fields

Common Patterns

Automation-safe creation — pass idempotency_key derived from the trigger (f"github-issue-{n}", f"webhook-{uuid}"). Re-firing the webhook is a no-op instead of spawning duplicates. Idempotency is per-board, per-tenant — two tenants on the same board never collide on the same key.

Long-running flaky network tasks — set max_retries=5 per task to absorb transient flakes without giving up too early. Watch consecutive_failures in kanban_show to spot stuck tasks.

Retrying workers use prior failures — call kanban_runs(task_id) at the start of a retry attempt to read prior outcomes and errors. Use summary and metadata from the most recent failed run as context: “previous attempt crashed at line X; avoid path Y.”

Common Patterns

Coordinator-Worker Pattern

# Coordinator breaks down requests
from praisonaiagents import Agent
from praisonaiagents.kanban import VALID_KANBAN_STATUSES

coordinator = Agent(
    name="Coordinator", 
    instructions="Break user requests into kanban tasks"
)

# Worker with heartbeat reporting
worker = Agent(
    name="Worker",
    instructions="Claim ready tasks, report progress via heartbeat"
)

Background Processing

# Background processing requires wrapper implementation
# The praisonaiagents.kanban protocols support:
# - Task claiming and status updates
# - Heartbeat reporting for long-running tasks
# - Multi-board coordination

Worker with Heartbeat

from praisonaiagents import Agent
from praisonaiagents.kanban import VALID_KANBAN_STATUSES

worker = Agent(
    name="Worker",
    instructions="""Claim ready tasks and report liveness via heartbeat. 
    Use kanban_heartbeat every 30 seconds during long-running work."""
)

# Worker claims task and reports progress
result = worker.start("Find ready tasks, claim one, and report progress")

Human-Agent Collaboration

# Human-agent collaboration pattern
# Requires wrapper implementation of:
# - CLI commands for task management
# - UI board visualization
# - Agent-to-store protocol bindings

Runs, Retries, and Structured Handoff

Kanban now tracks every execution attempt for each task via the task_runs table, supports per-task retry limits, and allows agents to pass structured data when completing a task.

kanban_complete — structured handoff

kanban_complete(
    task_id="task-123",
    summary="Implemented OAuth2 flow with PKCE",
    metadata={"pr_url": "https://github.com/org/repo/pull/42", "test_coverage": 0.91},
)

kanban_create — idempotency and retries

kanban_create(
    title="Write unit tests for auth module",
    body="Cover all edge cases in JWT validation",
    idempotency_key="auth-tests-v1",
    max_retries=3,
)

kanban_runs — per-task run history

List all execution attempts for a task:

runs = kanban_runs(task_id="task-123")
for run in runs:
    print(run["outcome"], run["summary"], run["created_at"])

Each run record contains:

Auto-block after max retries

When max_retries > 0 and the task accumulates that many "failure" run outcomes, the dispatcher automatically moves the task from running to blocked. The task must be manually unblocked (kanban_move(task_id, "ready")) after the root cause is resolved.

Per-Task Worktree Isolation

Give every kanban worker its own git worktree so parallel tasks never overwrite each other’s files.

from praisonaiagents import Agent
from praisonai.tools.kanban_tools import kanban_create

# Opt this task into per-task worktree isolation
task = kanban_create(
    "Refactor auth module",
    workspace_kind="worktree",   # <-- the whole feature
)

One keyword moves a task onto its own branch and working directory. Everything else — creation, merge-back, and cleanup — happens automatically.

Auto-upgrade for repo-linked tasks

Link a task to a git repo and the dispatcher gives it a worktree automatically — no keyword needed.

from praisonai_bot.kanban.sqlite_store import SQLiteKanbanStore

store = SQLiteKanbanStore()

# repo_path alone opts the task into isolation — workspace_kind is set for you
task = store.create_task({
    "title": "Refactor auth module",
    "repo_path": "/repos/service-a",
})

assert task.workspace_kind == "worktree"
assert task.branch == f"kanban/{task.id}"
assert task.metadata["repo_path"] == "/repos/service-a"

The upgrade is triggered by linkage, not by task content — the task body is never inspected.

Disable the upgrade per task (or per board via metadata) with auto_worktree=False:

from praisonai_bot.kanban.sqlite_store import SQLiteKanbanStore

store = SQLiteKanbanStore()

# repo-linked, but isolation explicitly disabled
task = store.create_task({
    "title": "Read-only audit",
    "repo_path": "/repos/service-a",
    "auto_worktree": False,
})

assert task.workspace_kind == "default"

How It Works

The dispatcher forks a worktree from the base branch, runs the worker inside it, then merges the branch back on success.

On success the dispatcher auto-commits any uncommitted worker edits as kanban worker output for kanban/<task_id>, merges the branch into the base with git merge --no-ff, then tears the worktree down. On conflict the merge is aborted, so the base branch is never left half-merged.

Choosing default vs worktree

Pick isolation only when workers actually edit files in a git repo.

New Task fields

Environment configuration

Add these to the Environment Configuration table when the dispatcher runs outside the repo.

The dispatcher branches from the current HEAD of PRAISONAI_KANBAN_REPO_DIR (defaulting to the process working directory). When HEAD cannot be detected, it falls back to PRAISONAI_KANBAN_BASE_BRANCH (default main).

Merge conflict handling

A conflict never touches the base branch — it routes the task to blocked for a human to resolve.

• The merge is aborted; the base branch is left untouched.
• The task moves to blocked with a comment listing the conflicted files — read it via kanban_show(task_id).
• The KANBAN_TASK_BLOCKED hook fires; the conflicted files live on the task comment thread, not the hook payload.
• The worktree is preserved on disk for inspection.

To recover, resolve the conflicts inside the kept worktree, then re-run or discard it:

from praisonai.tools.kanban_tools import kanban_move

# After resolving conflicts inside ~/.praisonai/kanban/worktrees/<task_id>
kanban_move("task_abc123", "ready")   # re-dispatch the task

Or discard the worktree entirely from the base repo:

git worktree remove --force ~/.praisonai/kanban/worktrees/task_abc123

Lossless-only worktree teardown

The dispatcher never destroys work a worker produced but failed to integrate — a worktree with uncommitted changes or unmerged commits is preserved on disk with a worktree_preserved comment on the task.

sequenceDiagram
    participant Dispatcher
    participant Guard as Lossless guard
    participant Git
    participant Store as Kanban Store

    Dispatcher->>Git: git merge --no-ff kanban/<id>
    Dispatcher->>Guard: _remove_worktree(path, branch)
    Guard->>Git: git status --porcelain
    Guard->>Git: git rev-list --count base..branch
    alt Clean tree and 0 commits ahead
        Guard->>Git: git worktree remove --force
        alt remove succeeded
            Git-->>Guard: ok
            Guard-->>Dispatcher: None (removed)
            Dispatcher->>Store: drop tracking entry
        else remove failed (nonzero / exception)
            Git-->>Guard: error
            Guard-->>Dispatcher: "worktree removal failed: …"
            Dispatcher->>Store: add_comment worktree_preserved at <path>: …
            Note over Dispatcher: tracking entry kept — no orphan
        end
    else Dirty or ahead of base
        Guard-->>Dispatcher: reason string
        Dispatcher->>Store: add_comment worktree_preserved at <path>: <reason>
        Note over Dispatcher: worktree left on disk; tracking entry kept
    end

Every preserved worktree records its reason as a task comment, readable via kanban_show(task_id):

commit(s) not in <base> | git rev-list –count <base>..<branch> > 0 (worker committed something that never merged into base) | Merge or cherry-pick the branch into base by hand, then rerun cleanup, or force-remove if the commits are known-throwaway | | could not read worktree status: <err> / could not compute ahead-count: <err> | The git status / git rev-list command itself failed | Investigate the worktree state manually — the guard errs toward preservation, so no data is at risk | | worktree removal failed: <detail> | git worktree remove –force returned nonzero | Read the git error, resolve, then rerun cleanup or force-remove | | worktree removal error: <exc> | git worktree remove` raised (permissions, missing binary, etc.) | Fix the underlying environment issue, then retry |

To recover a preserved worktree, commit anything worth keeping first, then integrate or remove it from the base repo:

# Read the preserved worktree, losslessly commit anything worth keeping
git -C ~/.praisonai/kanban/worktrees/task_abc123 status
git -C ~/.praisonai/kanban/worktrees/task_abc123 add -A
git -C ~/.praisonai/kanban/worktrees/task_abc123 commit -m "recover worker output"

# Then either integrate the branch by hand...
git merge kanban/task_abc123

# ...or, if the edits are known throwaway, remove the worktree manually
git worktree remove --force ~/.praisonai/kanban/worktrees/task_abc123

Inside a dispatcher-owned code path (e.g. a custom KanbanDispatcher subclass), the equivalent destructive teardown is an explicit force=True:

# Explicitly opt into destructive teardown — bypasses the lossless guard
dispatcher._remove_worktree(path, branch, force=True)

Best Practices

Best Practices

Related