RFC: A project board for people and agent sessions

Start with the PRD and draft technical design in docs/features/kanban/ on the feat/kanban branch, then read sessionService.ts, src/utils/git.ts, and the StartSession control request flow. The design still has open questions and needs maintainer review; implementation spans persistence, server permissions, agent tools, notifications, and UI. Done means delivering the agreed board capabilities and resolving the design questions.

Status

Requirements settled, technical design in draft. The PRD was finalized on 2026-11-06; the technical design is waiting for maintainer review. Both live in docs/features/kanban/ on the feat/kanban branch (not pushed yet). No code.

Summary

Sessions can already start each other and exchange messages (#239). Once a long task is spread over several sessions, though, the tasks, owners, dependencies and progress live only in chat transcripts. Nobody can see the state of the project without asking each session, and it is lost when sessions stop or the app restarts.

This RFC adds a persistent project board that people and agent sessions share: a fixed project PM, an optional Task Lead for complex work, plus Workers and Reviewers. The board records what to do, who owns it, how far it got and what came out. Clarifying, planning, implementing and verifying stay inside the sessions; the board is not a workflow engine.

Scope

Four capabilities:

1. A persistent board. Cards can be created, split into sub-cards, linked by "must finish first" dependencies and moved between states. It survives sessions stopping and app restarts. Every branch and worktree of a project sees the same board.
2. Hierarchical delegation. Each project has one fixed PM session, set only by the human. A complex card can get a Lead, who may split it further and delegate to Workers, Reviewers, or a lower Lead (default limit: two levels of Leads). Assignments take effect only after the human confirms them.
3. Scoped access. The PM sees the whole project, a Lead its subtree, a Worker its own cards, a Reviewer the cards it reviews. The server enforces this.
4. Agents drive progress. Agents update progress, report blockers and submit results through tools. The human views, adjusts and accepts.

Each card has three identities:

The owner and the acceptor of a card are never the same session, and a Reviewer is never the owner. Reports go to the supervisor, not to the session's parent.

States: Backlog, Todo, In Progress, Blocked, Review, Done, Cancelled. A light permission table decides who may make each transition; starting a card also requires an effective assignment and all dependencies done. An agent submitting a result never marks a card Done. Agent suggestions for new work are Backlog cards with a "suggestion" flag, accepted or rejected by the supervisor or the human.

Non-goals

• A separate spec or requirements state machine, versioned approvals, or multi-stage review, acceptance and merge.
• Creating card worktrees or branches, integration branches, automatic merges or PRs. Branches and PRs are recorded on a card as links.
• Predicting file overlap, scheduling ready tasks, worker pools, leases, retries.
• Cost per card, a cross-project board, scheduled cards, auto-approved assignments, multiple users, cloud sync.

Proposed design

• Storage: one append-only event log per board, ~/.dreamcoder/boards/<sanitized repo root>/events.jsonl, replayed into memory by a pure reducer on first access. This matches how session metadata is already persisted as transcript entries (sessionService.ts), and the log doubles as the card history. No SQLite: nothing in the repo uses bun:sqlite, and the data fits in memory.
• One board per repository. The board key is the canonical git root from findCanonicalGitRoot (src/utils/git.ts), which resolves any worktree to its main repository. It is the same rule that gives sessions their projectRoot, so the sidebar's project groups and the boards line up.
• The entry point decides the actor. REST calls from the app act as the human. Agent tools send control requests over their own session's SDK connection, as StartSession does, so the server knows which session is acting; the request body cannot claim an identity.
• Four CLI tools: KanbanList, KanbanGet, KanbanCreate, KanbanUpdate, backed by kanban_query and kanban_command control requests. The server checks every command against the permission table and the invariants in one pure function.
• Notifications reuse deliverUserTurn. An effective assignment, a revoked assignment, a human comment, a submitted result and a blocker each become a user message with a new origin.kind = 'kanban'. A stopped session is resumed to receive it; a new session gets it as its first message. Like cross-session messages, it is wrapped and marked as carrying no user authority.
• UI: a board page per project, opened from the project group in the sidebar, with a card detail and a "needs me" list. It polls with since=<version> instead of adding a WebSocket channel. Desktop and H5 share it; drag and drop is desktop only.

Open questions

• Can sub-agents call the write tools? Leaning yes: the actor is still the session.
• Should a session created for an assignment appear under its supervisor in the sidebar (a new parent.kind = 'assigned')? Leaning yes.
• Who may edit a card's title, description and dependencies? The PRD does not say. Leaning owner, supervisor and human.
• What counts as a "blocker that involves the human" and a "pending suggestion" in the "needs me" list.

Related

• #239: sessions start and message each other; the board is built on it.
• #162: agent teams.
• #166: isolated workspaces for team members.