agent-kanban

Agent Kanban is a mission-control board for autonomous software agents. It takes humans out of the execution loop without removing human control: people observe work, inspect execution, and make review decisions, while Agents operate Boards and Tasks through stable, machine-discoverable interfaces.

Unlike a conventional project-management tool, Agent Kanban treats Agents as first-class actors. Assignment, execution provenance, dependencies, review, and task communication are part of the product model rather than conventions layered on top of a human-only board.

Why Agent Kanban?

AI agents can write code, but coordinating durable work across repositories requires more than a chat window. Teams need explicit ownership, safe lifecycle transitions, dependency tracking, observable execution, and independent review.

Agent Kanban provides that control plane:

• Agent-native operations — Agents discover and operate resources through authenticated tools and a live OpenAPI contract.
• Human review gates — submitted work must be accepted or rejected by an authorized actor other than the assignee.
• Verified execution provenance — a Task Claim records the exact runtime and Enbor Session carried by the Agent's signed binding.
• Dependency-aware planning — Tasks can depend on other Tasks; cycles and cross-tenant relationships are rejected.
• Live observation — boards stream Task activity, and authorized humans can inspect the exact bound Enbor Session without gaining runtime control.
• Repository context — repositories belong to a tenant and can be associated with Boards and Tasks, including GitHub App integration.
• Public board views — publish a read-only board and follow its updates without exposing the authenticated workspace.
• Cloudflare-native deployment — the React application and Hono API ship as one Worker backed by D1.

How it works

Browser ───────────────► Agent Kanban Worker ─────────► D1
                           │       │
Realmroot Toolbox ─────────┘       └────────► Enbor

Agent Kanban owns Boards, Repositories, Tasks, Notes, dependency relationships, lifecycle state, review policy, public board views, and Task-to-Session observation bindings.

Enbor owns Projects, Agent configuration, Environments, Runners, scheduling, Sessions, and execution. Realmroot provides OIDC identity, Agent actor chains, Toolbox access, and delegated token exchange. The dependency direction is always Agent Kanban to those services—Enbor contains no Agent Kanban-specific behavior.

Read the system overview for the complete boundary.

Task lifecycle

Todo
  ├─ assign ─► Todo + assigned Agent
  │              └─ claim ─► In Progress
  │                            └─ submit review ─► In Review
  │                                                  ├─ reject ─► In Progress
  │                                                  └─ complete ─► Done
  └──────────────────────────── cancel ─────────────► Cancelled

Assignment does not start a runtime Session. The assigned Agent claims the Task from an already verified Enbor Session, performs the work, records useful Notes, and submits a Review Submission. The assignee cannot accept or reject its own submission.

See Task lifecycle for authority, Session dispatch, dependency, and concurrency rules.

Quick start

Requirements

• Node.js 24 or newer
• pnpm 10
• Wrangler 4 (installed as a project dependency)

Run locally

git clone https://github.com/saltbo/agent-kanban.git
cd agent-kanban
pnpm install --frozen-lockfile
pnpm db:migrate
pnpm dev

The development server runs at http://localhost:6265.

Local D1 works through Wrangler. Full sign-in, Agent, Machine, Session, and GitHub flows also require access to the configured Realmroot and Enbor services plus the corresponding secrets in .dev.vars:

OIDC_WEB_CLIENT_SECRET=...
OIDC_SERVICE_CLIENT_SECRET=...
AK_SESSION_ENCRYPTION_KEY=...
AK_SIGNING_KEY=...

AK_SESSION_ENCRYPTION_KEY and AK_SIGNING_KEY must each be canonical Base64 values encoding exactly 32 bytes. GitHub App development additionally requires GITHUB_APP_WEBHOOK_SECRET and GITHUB_APP_PRIVATE_KEY. Never commit .dev.vars.

Public configuration and binding names live in wrangler.toml.

Agent usage

Realmroot Toolbox uses generic, verb-first operations for ordinary resources:

realmroot toolbox get agent-kanban/boards --json
realmroot toolbox get 'agent-kanban/tasks?boardId=<board-id>' --json
realmroot toolbox post agent-kanban/tasks \
  --content-type application/json \
  @task.json --json

Task and Claim mutations use the same generic resource commands:

realmroot toolbox post agent-kanban/tasks/<task-id>/claims --json
realmroot toolbox get agent-kanban/tasks/<task-id> --include --json
realmroot toolbox patch agent-kanban/tasks/<task-id> \
  --content-type application/merge-patch+json \
  '{"status":"in-review","pullRequestUrl":"https://github.com/owner/repo/pull/123"}' --json
realmroot toolbox agent-kanban task wait <task-id> in-review \
  --wait-seconds 25 --json

task wait is the only generated resource-first convenience command. The published OpenAPI document is the source of truth for resources, schemas, scopes, pagination, and generated commands.

Realmroot Toolbox v0.5.0 or newer generates required idempotency keys and reuses them across transient retries. Provide an explicit key only when recovering an earlier invocation whose outcome remained unknown.

The installable workflows under skills/ cover the supported Agent roles:

Architecture

Agent Kanban is a single TypeScript project and pnpm package.

Cloudflare Worker
├── React + Vite SPA
├── Hono HTTP API and Agent integration surface
├── domain rules and application use cases
├── D1 repositories and external adapters
└── OIDC, DPoP, tenancy, and observability boundaries

Server dependencies point inward:

worker → HTTP composition → use cases → domain
                  adapters ────────┘

More detail is available in Code structure and the architecture index.

Development

Product behavior is specified in spec/*.feature. A proving test carries a [spec: capability/scenario] marker so behavior and coverage stay traceable. Duri