kandev/docs/public/workflow-tips.md

---
title: "Workflow Tips"
description: "Choose, configure, and troubleshoot Kandev task workflows."
---

# Workflows

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](run-as-a-service.md).

> Workflow definitions can be copied between workspaces with [Workflow Import / Export](workflow-import-export.md), or reconciled from a repository with [Workflow Sync](workflow-sync.md).

## Quick path

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

## One-time move options

The workflow stepper and next-step controls keep a fast **Move here** path for ordinary transitions. Choose **Move with options** when one hand-off needs fresh context, extra one-time instructions, or should skip the destination step's saved prompt. These options are consumed by that transition only; the destination step's saved prompt and reset policy remain unchanged for later entries.

Instructions are appended after the normal destination prompt, or replace it when you skip the step prompt. A move from an active agent is deferred until the current turn settles, so the reset, skip-prompt, and instructions stay together. On touch devices, the options form opens in a bottom Drawer. Pull-request draft/readiness remains a PR automation concern rather than a generic workflow move option.

## 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.

1. Save the source workflow before you select **Duplicate**.
2. Select **Duplicate** on the source workflow card.
3. Review and edit the copied workflow and its steps.
4. 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, including in plan mode. Thus, 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. |
| Complete task on entry | On the final step only, marks the task complete when it enters that step. The setting is saved per step, so moving a step changes which saved value is active. A value on a non-final step is retained but inactive. Default is off. |
| 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. |

### Recover from a context reset failure

When **Reset agent context** starts a fresh ACP session, Kandev restores the
selected model, permission mode, and provider options before the next automatic
prompt. If the provider rejects a setting, reset fails, or the request times
out, Kandev leaves the session waiting for input and does not send that prompt.
The conversation shows a previous-agent-error notice with the reset cause.

To recover, delete the affected conversation from its session actions, then
create a new session. The task workspace and files remain available. See
[Sessions and Review](sessions-and-review.md) for the session actions and mobile
session picker.

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 park on end. An explicitly selected completion policy is
preserved.

### Continue a completed conversation

Opening or reloading a completed task does not start its agent. If the task has a completed conversation, select **Resume** to continue that same conversation. The previous messages and provider context remain available, and the task keeps its completed state and workflow step. Select **New Agent** when you want a separate conversation. A follow-up does not run the completed step's workflow actions again.

### Open a completed workspace

Kandev restores a retained workspace when you open a completed task. This action restores Files, Changes, and supported workspace terminals. It does not resume the agent. It does not send a prompt.

If workspace restoration fails, the affected panel shows **Workspace unavailable**. Select **Retry** to restore workspace access. Select **Technical details** to view bounded diagnostic information. The chat remains available while the workspace is unavailable.

Select **Resume** in the completed conversation when you want the agent to continue. Workspace restoration and **Resume** are separate actions.

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

<details>
<summary>Events and action details</summary>

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, including the first non-empty prompt when a task is created with an explicit workflow step. The transition happens before that message is delivered. Prompts started automatically when a task enters a step do not run this event. | 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](workflow-import-export.md).

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.

</details>

## 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.

<details>
<summary>Safe authoring details</summary>

1. Start with manual transitions and verify prompts in a disposable task.
2. Add `auto_start_agent` only to steps that always have an effective agent profile.
3. Add turn-complete transitions after the prompt has an unambiguous stop condition.
4. 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.
5. 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.
6. Add WIP limits before pull rules, then test a full target and a vacated slot.
7. 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.

</details>

## Saved prompt references in step prompts

<details>
<summary>Saved prompt reference details</summary>

A step's Prompt field accepts `@name` references to [saved prompts](developer-tools.md#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.
- Workflow entries keep that hidden context when they start a new profile session, reset the agent context, or recover with a fresh runtime. The saved message and agent prompt retain the same definition once for that entry.
- `{{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](integrations.md#configure-and-use-the-workspace).

</details>

## Repository instructions and multiple repositories

<details>
<summary>Repository instruction details</summary>

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](git-operations.md).

</details>

## 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.
- **Moving tasks on a phone:** open the task card menu and choose **Move to**. Swiping a card scrolls the column; phone cards do not support drag-to-move or drag reordering.
- **Task cannot be dragged on desktop or tablet:** 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-import-export.md), [Workflow Sync](workflow-sync.md), [Git Operations](git-operations.md), and [Executors](executors.md).