Task Planner and Cards

Task Planner and Cards

Planner chats create and steer task cards; task-agent chats execute one card at a time.

What this mode pair is for

Refact's task system splits work into two chat roles:

• Task planner: owns the kanban board, creates and edits cards, asks for agent status, merges work, verifies outcomes, and records task-level memory/docs.
• Task agent: executes the work for one card in its own chat, usually with an isolated worktree.

The planner/agent boundary is enforced in tool code: many planner-facing tools reject non-planner chats, and task-agent tools bind themselves to the task/card context.

Task board model

The board is stored in src/tasks/ and loaded from task workspace state. The code uses a kanban-style board with these columns:

• planned
• doing
• done
• failed
• regressed

Task lifecycle status is tracked separately in task metadata:

• planning
• active
• paused
• completed
• abandoned

src/tasks/storage.rs updates board stats by counting cards in these columns; it also treats failed and regressed as failure states when emitting user activity.

Cards

A task card is a structured unit of work. In src/tasks/types.rs / the board tools, the relevant fields include:

• id
• title
• instructions
• depends_on
• target_files
• priority

The board tool code also surfaces common operational fields such as column, assignee, agent_chat_id, agent_branch, agent_worktree_name, status_updates, and optional A/B variant metadata.

Core planner tools

The task toolset is implemented in src/tools/ and wired into tools_list.rs. The key planner-facing tools are:

• task_start — initializes task context / task workspace flow
• board_get — read board state, with summary/tree/mermaid render modes
• board_create — create a card
• board_update — edit a card
• board_move — move a card between columns
• board_delete — delete a card
• ready_cards — enumerate cards ready to work from dependencies/board state
• spawn_agent — create one task-agent chat for a card
• spawn_agents_batch — spawn multiple task agents in one call
• check_agents — inspect active agents and their status
• wait_agents — stop the planner turn and wait for agent completion messages
• agent_diff — inspect agent worktree diffs
• agent_pulse — inspect an agent's current heartbeat/state
• agent_chat_summary — summarize agent chat transcripts
• agent_steer — send steering info back into a live agent chat
• planner_reply — answer planner Q&A from task-agent workflows
• task_verify_card — rerun a verifier for a completed card and store verifier_report
• merge_agent — merge one agent's branch back to the target branch
• merge_ready_in_order — merge ready cards in sequence
• mark_done — manually mark a card done
• mark_failed — manually mark a card failed
• card_comment_* — add/list comments on cards
• task_mem_* — task memory tools (save, pin, archive, inbox, triage_done, etc.)
• doc_* — task document tools (doc_list, doc_get, doc_create, doc_update, doc_append, doc_delete, doc_pin, doc_history)

A/B variants

The task system supports A/B exploration:

• spawn_ab spawns two variants for the same card.
• pick_ab_winner selects the winning variant and cleans up the loser.

The A/B flow stores variant metadata on the card and is integrated with the worktree lifecycle.

Verifier reports

task_verify_card exists to rerun verification for a completed card and persist a verifier_report on the card. Merge behavior can consult the verifier report:

• a failing report can block merge unless forced
• merge code can proceed with force
• merge paths are designed to surface verifier output in the result message

That makes verification part of the planner's final decision loop instead of a separate manual step.

Planner-to-agent loop

flowchart TD
  A[Planner chat] --> B[board_create / board_update / board_move]
  B --> C[ready_cards]
  C --> D[spawn_agent or spawn_agents_batch]
  D --> E[Task-agent chat in isolated worktree]
  E --> F[check_agents / wait_agents]
  F --> G[agent_diff / agent_pulse / agent_chat_summary / agent_steer]
  G --> H[merge_agent or merge_ready_in_order]
  H --> I[task_verify_card]
  I --> J{pass?}
  J -- yes --> K[mark_done]
  J -- no --> L[mark_failed or regressed]
  L --> A
  K --> A

Loading

Notes grounded in code

• Planner-only enforcement appears in tool descriptions and runtime checks.
• board_get can render a mermaid graph.
• wait_agents uses the same status view as check_agents and then pauses the planner turn until agents report back.
• mark_done / mark_failed directly update the card column and completion metadata.
• task_mem_* and doc_* are separate task-scoped knowledge/document tools, not generic repo editors.

See also

• Worktrees
• Subagents