Tasks and Workflows

A task is the work to deliver. A workflow is the sequence of steps it follows. Use a task for the outcome and a workflow for the review process.

Quick path

1. Add a repository to a workspace.
2. Create a task with a clear outcome, a compatible agent, and an executor.
3. Start the agent, review its changes, and move the task through the human gate.

Understand the model

Workflow position and runtime state are different. Moving a card changes its workflow step; it does not prove that an agent ran, code was committed, review passed, or a pull request merged.

Prepare a workspace

A new workspace created from Settings → Workspaces automatically receives a Kanban workflow with the built-in Kanban steps, so it can accept tasks immediately.

1. Open Settings → Workspaces and select Add Workspace.
2. Enter the required workspace name.
3. Open the workspace's Repositories page and add existing local repositories the workspace needs. You can also initialize a new empty repository while creating a task. Remote URLs are not registered on this page; enter them through New Task → Remote. The same page's Repository sets section groups repositories you routinely use together, so one action fills the task form with all of them; see Repository sets.
4. Open its Workflows page to review the default Kanban workflow. Create, import, or synchronize another workflow when the workspace needs a different process.
5. On Workspace Settings, optionally choose a Default Executor and Default Agent Profile. Both default to No default unless configured.

The initial database bootstrap can include a Default Workspace and a Development workflow. Later user-created workspaces receive Kanban instead; they do not inherit other workflows or settings from the default workspace.

Create a task

Use New Task in the sidebar. In an open task, the Task split button also opens task creation.

1. When the title field is shown, enter a concise title of up to 60 characters. Titles prefilled from a remote pull request, issue, or merge request are shortened with an ellipsis when needed; the detailed context belongs in the description. If Settings → General → Task Actions → Agent-generated task titles is enabled, the New Task dialog hides this field, requires a nonempty prompt, and uses the prompt's first six words as a provisional title while the first eligible agent session chooses the final title. The empty-description Plan Mode exception applies only when this setting is disabled.

2. Select the workspace and workflow when Kandev cannot infer them. A regular non-ephemeral task must belong to a workflow.

3. Select a source:

   Source	Use it for	Important behavior
   Repo	A configured, discovered, or new local repository	Select a named branch policy or a raw base branch for each repository row. A policy creates a fresh branch from its saved base and uses its branch template. For a single-row new task, Create new repository initializes an empty main repository with one empty initial commit in a parent folder you choose. Add more rows for a multi-repository task.
   Remote	A remote repository	Search configured GitHub, GitLab, or Azure DevOps repositories, or paste a supported URL. A pasted URL stays editable until you press Enter; then select the branch. Anonymous, credential-free reads include public GitHub repository branches, pull requests, and issues, plus public gitlab.com branch discovery. Private resources and authenticated browse/write features require valid provider credentials.
   None	Planning, research, or work outside Git	Use a scratch workspace or an optional folder on the Kandev host. Git worktree execution and repository-aware Changes, branch, and pull-request features are unavailable.

4. Select a compatible executor profile and agent profile. A workflow default agent profile locks the task-level agent selector. Executor and agent compatibility is validated before launch.

5. Enter the initial description. In the New Task dialog, an empty description changes the primary action to Start Plan Mode; the other dialog actions require a description. Agent-facing task MCP has different empty-description rules. When agent-generated task titles are enabled, every task and subtask action requires a nonempty prompt; the empty-description Plan Mode exception is disabled. A nonempty description exposes the standard split actions.

6. Choose the applicable action:

   • Start Plan Mode is the primary empty-description action and creates the task through the plan-mode path.
   • Start task requires a nonempty description, creates the task, and starts its agent. This path starts in the first positional step whose entry actions include Auto-start agent, falling back to Start step when the workflow automates no step.
   • Start task in plan mode requires a nonempty description and starts the agent with plan mode enabled. This path starts in the first positional workflow step, even if another step is marked Start step.
   • Create without starting agent requires a nonempty description and starts in Start step. A structured ACP profile prepares the session/workspace without starting an agent turn. Passthrough/TUI is an exception: the backend launches it immediately so its native PTY exists.

   On mobile, the two non-primary actions are separate buttons labeled Plan mode and Create only; they have the same plan-mode and create-without-agent behavior.

Branch policies

Manage named branch policies in Settings → Workspaces → workspace → Repositories. A policy stores a base branch, a branch-name template, and a pull-request target for one repository. The task picker shows policies before raw branches. A selected policy starts a fresh branch. A raw branch continues to open the existing branch. Each policy row has an information icon for its saved values. The base branch is the starting point. The pull-request target is the merge destination.

When you create a task, Kandev saves the selected policy values on the task repository. Later edits or deletion of the policy do not change the task. Kandev's pull-request dialog uses the saved target by default. You can change it before creation. Kandev also adds the saved target to the agent's task context. The instruction tells the agent to pass the target explicitly to its provider CLI. Policies are not offered in Quick Chat, Remote, Add Sources, or Add Branch flows.

Kandev remembers draft or recently used repository, branch, executor, and profile choices. Review the restored values before submitting, especially after changing workspace.

When the selected profile is dynamic, the task keeps one logical profile and one session tab while Kandev chooses a concrete candidate in the configured order. Provider errors before a result may move execution to the next configured candidate. Kandev does not switch candidates after an ambiguous started turn. If the route has no eligible candidate, wait for the current turn to settle and use the session's Retry current agent or Try next agent recovery action.

Creating a repository is available only in an unlocked, single-repository New Task form. Kandev rejects an existing target path, creates one empty initial commit but no project files, registers the repository in the workspace, and switches the task to a direct Local executor profile. If no direct Local profile is available, repository creation stays disabled. Add more repository rows only after selecting existing repositories; empty multi-repository worktrees are not supported.

Work with an empty remote repository

An existing local checkout or a repository selected from Remote can point to a remote with no refs. Kandev creates a local empty baseline so a normal Worktree task can start. The baseline contains no README, license, .gitignore, or other project files.

Task launch, resume, and worktree recovery do not write to the remote. When the work is ready, use the existing Changes action to Push or Create pull request. Kandev publishes the selected base branch first, then the task branch, with the task runtime's Git credentials. Read or clone access alone is not enough to publish.

If another person or tool initializes the remote before the first publication, Kandev stops without overwriting that history. Reconcile the remote and local task branch, then retry. If the base branch was published but the task branch failed, the task branch remains local and Push can be retried. On phones, use the same actions from the touch-sized Changes menu.

Local changes: creating a fresh local branch can discard dirty files only after explicit consent. Save or commit important work before approving it.

Repository sets

GET    /api/v1/workspaces/:id/repository-sets
POST   /api/v1/workspaces/:id/repository-sets   {"name","description","repository_ids"}
GET    /api/v1/repository-sets/:id
PATCH  /api/v1/repository-sets/:id              any of name, description, repository_ids
DELETE /api/v1/repository-sets/:id

Add sources to an existing task

Start a task

A task created with Create without starting agent opens in a prepared workbench. Review its repository, branch, executor, profile, and initial prompt, then select Start agent. The run stays in the task conversation, where environment preparation, tool calls, permission requests, and the final response remain inspectable.

If the selected profile is unhealthy or incompatible with the executor, fix that configuration before launch. Starting an agent is separate from moving the task through its workflow; entry actions and turn-complete transitions can move or restart work afterward.

By default, a running session keeps the coarse Generating state and queues another message even if Kandev detects background work. Operators can opt into the high-risk Claude background prompt handoff feature toggle for controlled testing. With that experiment enabled, a Claude Code session shows Working in background after its foreground yields while a recognized async subagent, run_in_background shell, or Monitor remains active. A follow-up is then sent immediately and the child may continue streaming. Other providers and foreground-generating Claude turns retain the coarse queueing behavior.

Prevent auto-start on open

Under Settings → General → Task actions, the Prevent auto-start on open preference is off by default. When enabled, opening a task never launches or resumes its agent on its own; it shows the Start agent button instead. The preference applies in two situations:

• Opening a task in the final step of its workflow. The task opens with a prepared session and the agent stays stopped until you select Start agent. Opening the same task with the preference off keeps the workflow step's normal auto-start behavior.
• Opening a task whose agent was stopped by a Kandev restart. The session is recovered and shown stopped instead of being resumed automatically. Select Start agent to resume it.

The preference only gates opening a task. Choosing Start agent (or a workflow step transition) always starts the agent as usual, and a failed or interrupted session still shows its recovery actions.

Task dependencies

A task can declare that it depends on one or more other tasks. This is a peer relationship and is separate from the parent/child subtask hierarchy: a subtask says "B is part of A", a dependency says "B cannot start until A finishes". The two can be combined freely, including a dependency between a task and its own child.

Dependencies form a graph, not just a line. A task can wait on several predecessors and can itself block several dependents. A link that would close a cycle is rejected when you try to create it, and the offending path is shown so you can see which link to drop.

Declare dependencies

Dependencies are declared in the New Task dialog under Depends on, or by an agent over MCP. There is deliberately no editor in the open task: a dependency records how the work was planned, so the surfaces that display it stay read-only. To change one after the fact, use the MCP tools or delete and recreate the task.

What blocked means

A task with at least one unfinished predecessor is blocked. Blocked tasks show a badge on their Kanban card and a dependency chip in the status row above the chat box, next to the pull request chip. The chip reports both directions, the tasks this one waits on and the tasks waiting on it, and each entry links to that task.

While a task is blocked, no automated path starts it. That covers workflow On Enter auto-start, promotion out of a WIP queue, integration watchers, and dependency resolution itself. You can still press Start agent yourself; a manual start is an explicit override, not an error.

Chains that run themselves

A task created with dependencies and an agent start request does not launch immediately. It records the start as an intent, and Kandev launches it once every predecessor has completed successfully. Setting that up along a path produces a chain:

1. Create task A normally.
2. Create task B with Depends on set to A.
3. Create task C with Depends on set to B.

Starting A is the only manual step. When A completes, B starts. When B completes, C starts. A is never restarted.

Auto-start grants eligibility, never a bypass. If a task's dependencies have resolved but the target step is at its WIP limit, the task stays queued and launches when the queue promotes it, exactly as any other queued task would.

When a predecessor does not succeed

Only successful completion resolves a dependency. A predecessor that ends in Failed or Cancelled leaves its dependents blocked, and the blocked reason names the failed task rather than reporting a generic wait. The chain stops there and waits for you. Kandev never retries a failed predecessor on its own and never quietly drops the link.

Three things clear it, all of them deliberate: retry the predecessor until it succeeds, remove the link over MCP, or start the dependent manually.

An archived predecessor is treated as unfinished, not as failed and not as resolved, so archiving a task does not release the work waiting on it. Deleting a task does remove its links in both directions, and any dependent that was waiting only on it becomes unblocked. That dependent is not started: deletion is not success.

Find and organize tasks

On desktop and tablet, the header switches between Kanban, Pipeline, and List. Kanban and Pipeline show the same workflow steps in different layouts. Kandev remembers the last selected view in that browser on the current device. Phones offer Kanban and List only; a saved desktop Pipeline preference is kept but shown as Kanban on the phone.

Under Settings → General → Appearance → Startup Page, choose Task overview (the default) or Last visited task. The latter resumes the most recently opened task in the current workspace on that device when Kandev starts or you open bare Home. It does not change an explicit task or workflow link. Home navigation and a task's Back action always return to the task overview; when there is no matching local recent task, Kandev opens the overview instead.

The TASKS list in the left sidebar has two time-based sort choices. These choices are separate from the sort choices in the task List view.

Choose Last activity when you want to review tasks by the least recent user or agent interaction.

• Search matches tasks without changing their state.
• The display menu filters by Workflow and Repository and can enable Open preview on click. In Kanban/Pipeline, each workflow lane has a Columns menu to hide individual steps. Unticking a step hides its column and tasks on that board, scoped to its own workflow, until you re-tick it. The optional Auto-hide empty columns setting collapses unoccupied steps without changing those manual choices; auto-hidden empty steps return as move destinations while a task is being moved, while manually hidden steps remain unavailable for pointer and bulk moves. On phones, open the menu drawer to change columns for the focused workflow.
• In List, the display menu can enable Show task details to include available repository, description, pull-request, session, parent, review, and archive context in each row. This option is off by default and follows the user across devices.
• List can group by State, Workflow, Repository, or None.
• List can sort by updated time, created time, or title in either direction.
• Show archived reveals archived tasks in List.
• List page sizes are 10, 25, or 50; the default is 25.
• Parent tasks and direct subtasks are indented as a tree.
• A subtask's action menu can detach it into a top-level task. Detaching preserves its workflow position and descendants; an inherited workspace remains shared with the former parent.

On phones, Kanban focuses one workflow and one step at a time. The board navigator always names both; open it to choose either level, or use the previous/next controls and horizontal swipe to move between steps. Choosing a workflow makes it the active workflow for board actions and task creation. Tap a card to open that task directly. Its More options menu opens as a touch-sized bottom surface; Move to changes the task's workflow or step. Edit can still rename a task after work starts, while its original prompt remains locked.

Regular Kanban does not currently expose label editing or label filters. Do not design a supported Kanban process around labels.

Use the task plan

Regular tasks have one shared Markdown plan, not a collection of named documents.

1. In the task workbench, select Add panel (+) → Plan.
2. Write the plan or let an agent write it through task MCP.
3. Edit it directly. The panel autosaves after 1.5 seconds.
4. Use plan history to preview a revision, compare it with the previous or current revision, or restore it. Restore creates a new revision; it does not erase history or coalesce with the preceding revision.
5. Select plan text to leave a comment. Run sends the selected feedback to the agent in plan mode.
6. Choose Implement for the current session or Implement in fresh agent. Kandev saves the current draft first and marks the plan as sent for implementation; the implement control is then disabled for that plan.

Agents use create_task_plan_kandev, get_task_plan_kandev, update_task_plan_kandev, and delete_task_plan_kandev. Human edits are therefore visible to the next agent that reads the plan. A plan records intent; verify that code and review still match it.

Revision history is not an immutable record of every autosave. Consecutive writes from the same author name and author kind coalesce into the latest revision for five minutes by default. Operators can set KANDEV_PLAN_COALESCE_WINDOW_MS; 0 disables coalescing, while an invalid or negative value falls back to five minutes.

Office documents, labels, and blockers

Regular Kanban reads and enforces blocker relationships (see Task dependencies) but has no blocker filter and no in-place editor: dependencies are declared when the task is created or over MCP. Office additionally exposes named documents, labels, and its own blocker property editor. Do not treat those Office surfaces as a stable public contract yet.

Archive, unarchive, and delete

Archive records the task as archived and removes it from active views immediately. Runtime stopping and physical cleanup then run in the background with a 60-second timeout. Cleanup is best-effort: a stop or deletion failure is logged and does not undo the archive, and Kandev preserves a runtime or environment when a nonterminal session cannot be stopped. Shared inherited environments and borrowed worktrees are also preserved while another active task still uses them.

The archive confirmation is enabled by default at Settings → General → Task Actions → Archive Confirmation under Confirm before archiving tasks. If a parent has children, Also archive N subtasks is unchecked by default; without it, the children remain active. Task MCP archive/delete operations affect only the selected task and do not offer the cascade checkbox. MCP delete also does not reparent direct children the way the UI's non-cascade delete does; use the UI rather than task MCP to delete a parent that still has children.

To restore a task, open List, enable Show archived, and choose unarchive. If the parent was archived with its children, the cascade-owned children are restored with it. For worktree tasks, archive keeps the environment identity and the local branch. The next session recreates the worktree directory from that branch. Recovery is best-effort and does not rewrite ambiguous multi-row attachments for the same repository. If an external action or an older Kandev version removed the branch, Kandev also checks origin. If no branch exists, the next session starts from the base branch. Removed worktree directories, containers, and sandboxes are materialized again on a later launch rather than resumed in place.

Delete is permanent. If Also delete N subtasks is left unchecked, direct children become root tasks. If selected, descendants are deleted. The operation cannot be undone, and executor cleanup follows the same asynchronous, best-effort rules as archive.

When a task still has a RUNNING agent, the confirmation dialog adds a still-working warning: proceeding discards work that is in progress. Delete always shows this warning; archive shows it only when the archive confirmation is enabled. Best-effort detached-work accounting does not independently keep a settled task in the still-working state.

Troubleshooting

• No workflow is available: open the workspace's Workflows page. Newly added workspaces have none by default.
• No agent starts: the empty-description Start Plan Mode path does not use the normal start-agent submission. To begin an agent immediately, enter a description and use Start task or Start task in plan mode; also confirm the selected profiles are healthy and compatible.
• Task starts in the wrong step: the destination depends on the action. Create without starting agent uses Start step with first-step fallback; Start task uses the first Auto-start agent step and falls back to Start step; Start task in plan mode deliberately uses the first positional step. An explicit workflow_step_id from the creator outranks all three.
• A task moves unexpectedly: inspect On Turn Start, On Turn Complete, child completion, entry actions, and the destination step's entry actions.
• A 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.
• Move rejected: check the target WIP limit and whether the task is already counted there.
• Pull does nothing: configure a nonzero WIP limit, remove cycles, and confirm feeder candidates are not running or starting.
• Child completion does not move the parent: confirm every active direct child is terminal and the parent still has a session in CREATED, STARTING, RUNNING, or WAITING_FOR_INPUT.
• Completion signal appears ignored: it is asynchronous; also check whether a user message canceled it or whether the task already left the step.
• Remote source cannot clone or fetch: verify provider credentials and access to every repository and base branch.
• Attachment is rejected below the picker limit: encoded size is subject to the backend's stricter 10 MB item/batch checks.
• Resources remain after archive or delete: physical cleanup is asynchronous and best-effort. Check for an active task sharing the environment, a failed runtime stop, and server cleanup logs before removing anything manually.
• An unarchived worktree starts fresh: an external action or an older Kandev version removed the branch, and no matching branch exists on origin.
• A synchronized workflow is read-only: edit the workflow file in its GitHub source and let sync apply the change.

Related: Coordinate work, Sessions and review, Agents and profiles, and Automation and MCP.