Workflow Tips

A workflow is an ordered set of steps for tasks in one workspace. A workflow can be a plain board, or its step events can start an agent, change agent mode, and move a task after a user or agent turn.

Configure Kanban workflows in Settings → Workspaces → select a workspace → Workflows. You need a workspace first; steps which start agents also need a healthy agent profile and a usable executor profile. Use a template when its prompts fit your process. Use Custom when you only need columns or want to build the automation yourself.

Workflow prompts run with the selected executor's filesystem, credentials, and network access. Do not place tokens in prompt text, and give the agent only the access that workflow needs. Workflow settings use Kandev's current local backend trust boundary; protect any network-exposed installation as described in Run as a Service.

Workflow definitions can be copied between workspaces with Workflow Import / Export, or reconciled from a repository with Workflow Sync.

Quick path

Start with Kanban for ordinary task tracking.
Choose Plan & Build or PR Review when the workflow itself should guide the agent.
Add automatic starts only when the executor, profile, and prompt are ready.
Keep a human Review or Do nothing gate before risky changes ship.

Built-in Kanban templates

The template prompts are product behavior, not merely sample text. Review them before using a template in a repository with strict Git, test, or deployment rules. Kandev currently presents these five Kanban templates.

Kanban

Backlog → In Progress → Review → Done

A normal new task starts in In Progress. Its agent starts automatically.
A user message in Backlog moves the task to In Progress before the message is delivered.
Completion of an agent turn in either Backlog or In Progress moves the task to Review. Backlog also has the user-turn-start transition above, so which route runs depends on how work is started there.
A user message in Review moves the task back to In Progress. A message in Done also reopens it in In Progress.

Choose this for short implementation work with a simple run-and-review loop.

Duplicate a workflow

Use Duplicate to create a new workflow from a saved workflow. The copy starts as a local draft.

Save the source workflow before you select Duplicate.
Select Duplicate on the source workflow card.
Review and edit the copied workflow and its steps.
Select the route-level Save changes action to persist the copy.

Kandev places the draft after the source workflow. The first copy uses <name> (copy). If that name exists, Kandev uses the lowest available number. For example, the next name can be <name> (copy 2).

The copy includes these settings:

workflow description, prompt, and default agent profile
step prompts, colors, positions, transitions, and start-step state
command-panel visibility, manual-move policy, and auto-archive policy
step agent profiles, session start and end policies, completion-signal policy, cancellation policy, WIP limits, and pull-from relationships

The copy does not include tasks, task sessions, execution history, workflow history, template identity, or sync ownership. A copy of a sync-managed workflow becomes an independent manual workflow. The source remains unchanged.

If you remove or discard the draft, or reload before you save it, Kandev does not create a workflow.

Plan & Build

Todo → Plan → Implementation → Done

A normal new task starts in Plan. Kandev enables plan mode and starts the agent with a prompt that asks it to save a task plan and wait for review.
Leaving Plan disables plan mode.
Entering Implementation starts the agent with a prompt that retrieves the saved plan and implements it.
The template does not define automatic transitions between these steps. Move the task to Implementation and Done when ready.

Choose this when a human should approve or edit a plan before implementation.

Architecture

Ideas → Planning → Review → Approved

A normal new task starts in Planning. The agent starts in plan mode and is instructed to produce design, not code.
Review enables plan mode. A user message there moves the task back to Planning for another design turn.
Other transitions are manual; Approved does not launch implementation.

Choose this for designs, RFCs, and technical decisions that will be implemented elsewhere.

Feature Dev

Todo → Spec → Work → Review → QA → PR → CI Fixup → Done

A normal new task starts in Spec, in plan mode.
Entering Work, Review, QA, PR, or CI Fixup starts the step prompt automatically. Review also resets agent context first.
The prompts cover planning, TDD-oriented implementation, diff review, QA, draft-PR creation, and CI repair respectively. Their success depends on repository tools and credentials such as the test runner, Git remote access, gh, and CI access.
The template does not auto-advance between phases. Move the task after checking the current phase's result.

Choose this for a deliberate multi-pass delivery process. It is excessive for small chores.

PR Review

Waiting → Review → Done

A normal new task starts in Waiting. Sending a message moves it to Review.
Entering Review starts an agent. The current prompt expects a GitHub PR number or URL, an authenticated gh CLI, and a usable origin remote. It reviews only added or modified diff lines and reports BLOCKER and SUGGESTION findings.
Moving to Done is manual. The template does not publish review comments by itself.

Choose this for a local first-pass review. For repository-provider watch automation, use the relevant integration instead.

GitHub review watches and WIP limits

A GitHub Review Watch creates each matching pull request in its configured workflow step. If that step has a WIP limit, admission is atomic and overflow is still visible: queued tasks remain on the board without starting an agent or consuming an admitted slot. With a configured feeder, overflow is placed there and tagged for the review step; without one, it remains queued in the review step. If the feeder is also full, creation is deferred for a later poll and its temporary watch reservation is released.

If the target step has auto_start_agent on entry and move_to_next on turn completion, the task remains in the target step during agent startup and active review. agent.boot_ready only makes the session ready; the first real turn completion performs the configured move once. Use a human-gate transition when reviews must wait for approval instead of advancing automatically.

Build a custom workflow

Choose Add Workflow, give it a name, select Custom, and save it. Expand each step to edit its behavior. Reorder steps by dragging them; transition actions that say “next” or “previous” follow the saved position order.

Workflow-level settings include the name and default agent profile. Each step can override that profile and configure two independent session settings when the effective profile changes: whether the step reuses an available session or starts a new conversation, and whether the session from the step being left is completed or parked. Steps with the same effective profile keep the current session. A step also has these controls:

Control	Behavior
Name and color	Board label and presentation. Color is stored as a CSS utility class.
Prompt	Step-specific agent prompt. `{{task_prompt}}` inserts the task description. Type `@` to reference a saved prompt by name.
Start step	Where a task is created when no agent starts with it. The editor keeps at most one. If none is set, task creation falls back to the first step by position. Creating a task that starts an agent immediately uses the first Auto-start agent step instead, so a Start step with no entry actions is a genuine parking column.
Auto-start agent	Adds `auto_start_agent` to `on_enter`. It still needs a valid agent and executor configuration.
Plan mode	Adds `enable_plan_mode` on entry. Add the matching disable behavior on completion or exit when later steps should edit files.
Reset agent context	Starts the step with fresh conversation context. It is disabled when the step changes agent profile because the destination step's session start setting controls whether that switch reuses or creates a conversation.
Allow manual move	Allows board drag/drop into the step. It is a product-UI rule, not a security boundary for API clients.
Show in command panel	Includes tasks in this step in the command panel.
Auto-archive	Archives eligible tasks after the configured number of hours. `0` disables it; the background sweep runs every five minutes and uses task `updated_at`, so timing is approximate.
Wait for agent completion signal	With an `on_turn_complete` transition, waits for the agent to call `step_complete_kandev`. A halt without the signal leaves the task on the current step; retry or reconnect the agent, or move the task through the normal workflow UI. Without this setting, a normal turn end counts as completion. Default is off.
Run completion actions when a turn is cancelled	Also runs the step's `on_turn_complete` actions after an explicit user cancellation settles. A pending clarification, silent interruption, parent/task stop, provider failure, crash, or runtime teardown does not qualify. If the destination has `on_enter: auto_start_agent`, another agent turn can begin immediately. Default is off for custom steps; the built-in Kanban workflow enables it on Backlog and In Progress for newly created workflows; existing workflows are not backfilled.
WIP limit	Maximum admitted active, non-archived, non-ephemeral tasks in the step. `0` means unlimited; visible overflow is queued. A manual move into a full target succeeds and queues in that target.
Pull from	Optional one-hop feeder step. When capacity opens, Kandev promotes queued destination work first, then feeder work. Direct moves and automatic transitions queue in the destination without using the feeder. A full feeder rejects new overflow creation.

The Kanban column shows the admitted count and limit, followed by a Queued section when overflow exists. The task sidebar shows a queue icon for each queued task; hover or focus gives its position in the destination queue. Queued tasks do not start destination entry actions or consume WIP until promotion.

For a profile change, the destination step's Reuse an available session setting continues the newest eligible conversation for that profile, or starts a new session when none is available. Start a new session always creates a fresh conversation. The source step's Complete the session setting closes the conversation, while Park the session stops the agent and keeps the conversation available for reuse or manual follow-up. These settings default to reuse on start and complete on end.

Pull candidates are selected by board position, then priority, queue time, creation time, and ID. A candidate that cannot be moved is skipped. Pulling runs for every limited step; a feeder is only needed for overflow created outside the destination step.

Complete prompts while editing

Workflow and step prompt fields use the inline prompt editor. Type @ after whitespace to select a saved prompt. In a step prompt, type {{ to select {{task_prompt}} and other tokens supported by that step. The completion menu inserts the reference into the draft; it does not save the workflow. Use Save changes when the prompt is ready.

The workflow-level prompt supports saved-prompt references but does not expand step-only variables. {{task_prompt}} is available in a step prompt because it is replaced with the task description when that step runs.

Events and actions

The standard Kanban editor exposes these events:

Event	When it runs	Editor actions
`on_enter`	A task enters a step through normal step-entry processing.	Enable plan mode, auto-start agent, reset context.
`on_turn_start`	A user sends a message. The transition happens before that message is delivered.	Move next, previous, or to a selected step.
`on_turn_complete`	A normal agent turn finishes when its signal requirements are satisfied. An explicit user cancellation qualifies when the step enables its cancellation policy, even if the completion signal is absent. A pending clarification always blocks completion.	Move next, previous, or to a selected step; disable plan mode.
`on_exit`	A task leaves a step.	Disable plan mode.

The portable format also recognizes set_session_mode, clear_decisions, queue_run, and queue_run_for_each_participant in on_enter; these are advanced/runtime-dependent actions and most are not offered by the Kanban editor. The seven Office/Phase-2 event triggers round-trip through Kanban import/export; what does not round-trip is Office step metadata (stage type, participants, decisions, task data, step history). See the exact boundary in Workflow Import / Export.

Keep one transition action per event. A “next” action on the last step or “previous” on the first has nowhere to go and leaves the task in place. A missing target step, a failed agent launch, missing credentials, or a full feeder can prevent the intended progression; inspect the task/session error and backend logs before changing the workflow. A full destination step queues the task instead of rejecting the move.

Cancellation policy is deliberately narrow: it is evaluated only for the visible user Cancel action while a turn is working. It reuses the normal turn-complete pipeline after the runtime settles, but does not reinterpret every way a session can stop as a completion.

Safe authoring pattern

Safety: Requiring step_complete_kandev can leave a step waiting indefinitely if the agent cannot call it. Export before large edits; workflow deletion is permanent and may require task migration or archival.

Start with manual transitions and verify prompts in a disposable task.
Add auto_start_agent only to steps that always have an effective agent profile.
Add turn-complete transitions after the prompt has an unambiguous stop condition.
Enable the explicit completion signal for agents that can discover and call step_complete_kandev; otherwise the step can wait indefinitely. If the tool is not already visible, the agent should search the active tool catalog for its canonical name.
Decide whether an explicit user cancellation should run the same completion actions. Enable Run completion actions when a turn is cancelled only when the destination transition is safe to repeat and any destination on_enter automation is intentional.
Add WIP limits before pull rules, then test a full target and a vacated slot.
Export the workflow before a large edit. Workflow deletion is permanent; when it contains tasks, the UI asks you to migrate them or archive them.

Saved prompt references in step prompts

A step's Prompt field accepts @name references to saved prompts (Settings > Prompts), the same way task chat does. Type @ and select a prompt, or type the name directly.

The reference is resolved when the step prompt runs, not when it is saved. Editing the saved prompt's content later automatically changes what every step referencing it sends next time: there is nothing to update on the step itself.
The @name mention stays visible in the prompt/chat. Kandev attaches the referenced prompt's content as hidden context for the agent; it is not shown as part of the visible conversation.
{{task_prompt}} is only interpolated in the step prompt field itself. If a referenced saved prompt's content contains {{task_prompt}}, it is not expanded; it is sent to the agent as literal text.

The same @name syntax and resolution apply to a GitHub Review Watch's prompt field. See Integrations.

Repository instructions and multiple repositories

Step prompts are combined with the selected agent and the checked-out repository. Keep repository-specific instructions such as AGENTS.md, CLAUDE.md, skills, test commands, and MCP configuration in that repository. Kandev does not make one repository's agent rules automatically authoritative for another.

A task may contain several repositories, but a workflow step is not bound to one repository. The agent session receives the task workspace and its repository set. Prompts should name the intended repository when the phase is repository-specific, and Git operations must be scoped per repository. See Git Operations.

Troubleshooting

Task starts in the wrong column: confirm exactly one Start step, save the workflow, and check whether the creator supplied an explicit workflow_step_id. Remember that a create which starts an agent targets the first Auto-start agent step, not the Start step.
Agent does not start: verify the effective workflow/step agent profile, its health, executor profile, repository access, and the auto_start_agent entry action.
Task stays after a turn: check for an absent transition, a pending clarification, the explicit-completion toggle, a queued WIP card waiting for capacity, or an invalid target left by an older definition.
Task stays after a cancel: check for a pending clarification, the cancelled-turn completion policy, an absent or blocked transition, a queued WIP card, or an invalid target left by an older definition.
Task cannot be dragged: the destination may disallow manual moves, be at its WIP limit, or the task may have a starting/running session.
Auto-archive looks late: the sweep cadence is five minutes and task updates extend the age check.
Synced workflow is read-only: edit its repository definition and run Sync now, or remove the sync configuration to release all synced workflows as editable manual workflows.

Related guides: Workflow Import / Export, Workflow Sync, Git Operations, and Executors.

On this page