Workflows

A workflow is a set of linked tasks that runs through the board on its own. Each task has a route, the columns it visits, and starts when every task it waits for has reached Done. When a task’s agent finishes a turn, the Automation agent judges whether that column’s work is done and moves the task to the next column on its route. What one column does by itself is on Columns and Automations, and Automations and workflows has the order the two act in at a turn end. Before v0.46.0 this address held the column docs that are now on those two pages.

How a workflow runs

A workflow starts as a plan. Its tasks exist only on the Workflows canvas, with no # number, and nothing reaches the board until you press Start. Start creates the tasks in To Do, on their own boards, and from then on the workflow runs in four steps:

A task leaves To Do once every task it waits for is in Done. A task with nothing to wait for starts at once. Starts take agent slots like any other spawn, so past Max concurrent sessions the rest wait in To Do and start in To Do order as slots free up.
In each column on its route, the task’s agent works as it would on any card, and the column’s automations run as they would on any task.
When the agent finishes a turn, the Automation agent reads its final message and answers one question: is this column’s work done, and is the agent not waiting on you? Yes moves the task to the next column on its route, and from the route’s last column to Done. No leaves it where it is, idle, until you answer the agent and it finishes another turn.
When every task is in Done, the workflow is complete, its agent’s session ends, and a Workflow complete notification says so.

A workflow holds at most 100 tasks.

Workflows view

Workflows is the third segment of the view toggle, after Board and Backlog. Ctrl+Shift+L / Cmd+Shift+L opens it, and pressed there it returns to the view you came from. While one of the project’s workflows runs, the segment carries the working mark.

The header picks the workflow and holds Rename, the lifecycle button, Delete, and New workflow. The lifecycle button reads Start on a plan, Running on a running workflow (a click pauses it), and Resume on a paused one. Once a workflow has started, a progress bar beside it counts the tasks in Done (“2 of 9 done”). In the picker’s list, a line under each workflow’s name says when it was paused, what its agent is doing (“Agent idle, last message 10:44”), or, with no agent running, how many of its tasks wait for you (“2 idle”).

The canvas

The canvas in the middle draws each task as its card, with a link from each task to every task that waits for it. With nothing selected, a link is green once the task it comes from is done and grey while that task still holds the other up, and the inspector on the right lists the run order. Select a card and its own links stand out: what it waits for flows into it, what waits for it flows out in the accent color, and every other link fades back. The workflow below has two tasks done, two in progress, and two waiting in To Do.

Drag a card by its body to place it. Drag empty space or scroll to pan, and hold Ctrl or Cmd with the wheel to zoom. Fit view and Auto layout, which puts moved cards back where the automatic layout wants them, sit at the bottom left, and Add task sits at the bottom center. The board’s search and filter apply to the canvas too. Right-click a started task’s card for the board’s own card menu, with Open on board at the top.

The inspector

With a card selected, the inspector shows that task’s Route, the tasks it is Blocked by, the tasks it is Blocking, and Remove, which takes it out of the workflow. Open task at the bottom opens it. For a task on another project’s board, the button reads Open on and that board’s name. A control that would break a rule stays in place, disabled, and its tooltip says why.

Planning a workflow

Click New workflow in the header, or right-click a To Do card on the board and pick New workflow. A workflow made from a card takes the card’s title and description as its brief, and when the workflow starts, that card moves to Done, since the plan carries its work. A new workflow with no tasks shows three steps on its canvas: tell the Workflow agent what to build, review its plan, and press Start.

A plan’s cards have no number yet. Double-click one to open it in the board’s own New Task form, led by the project the task goes on, with its base branch, Worktree or Project placement, and Column Settings or Agent Override, as a task on the board has them. Each of those reads the chosen project: its branches, its Worktrees setting, its default agent, and its board profiles. Choosing another project resets the task’s route to every column of that board.

The plan below has not started. Its middle task is selected, so the inspector shows the columns it will visit, the task it waits for, and the two that wait for it, and Start sits in the header.

Start creates every planned task in To Do with the settings it was given, and the ones with nothing to wait for start at once. A plan can also take in a task already in To Do on the board instead of creating a new one. Delete on a plan removes it and its planned tasks, and touches nothing on the board.

Workflow agent

The pane on the left of the view is the workflow’s own agent. It reads the code and the board, and changes only this workflow’s plan, through the workflow tools. It runs in the project’s own checkout, with no worktree, on the agent, model, and effort chosen under Setting up the agents, not on the project’s default agent. Until one is chosen, the pane says so in place of the terminal, with an Open Settings button, and starts the agent by itself once you choose and close Settings.

Claude Code launches read-only there, with no tools that edit a file or run a command. Every other agent runs in its own default mode, and its first message tells it to plan and leave the files alone. It is asked, not prevented.

A new workflow’s agent starts with the first message from Settings, reads the brief, plans the tasks, and saves them. Made from nothing, it first asks what you want to build. Talk to it in its terminal to reshape the plan. While its turn runs, the canvas says so, and the controls that would change its plan (Start, Add task, links, routes, Remove) wait until the turn ends. Moving cards does not wait.

The pane’s header pauses and resumes the agent, opens its conversation in the transcript viewer, and folds the pane to a strip. Its conversation is kept across a restart, and its usage counts in Usage Stats. If the conversation cannot be resumed, the agent starts a new one from the saved plan, and the pane says it started over. It keeps running when you leave the view.

Any agent can plan a workflow, too: ask it to “plan the usage budgets work as a workflow” and it saves the plan with kangentic_save_workflow. The plan still waits for Start, which an agent outside the workflow calls only when you ask it to.

Routes and links

A task’s Route in the inspector starts at To Do and ends at Done, both locked on, and its switches turn each column between them on or off for that task. A small task can skip a column it does not need. A task still in To Do can take any route. Once it has started, only the columns after the one it is in can change.

A link makes one task wait for another to reach Done. Drag from a card’s right-hand dot onto the card that should wait, and the card under the pointer says what letting go would do, or why it cannot. Add blocker in the inspector does the same from a list. Links cannot go in a circle, and only a task still in To Do can be given a new task to wait for. The X on a link row removes the link.

If a task a link points at is deleted, or its project is removed, the link goes on the engine’s next pass, and the task that waited stops waiting for it. A link whose board cannot be read at the moment, because its database is locked or damaged, still holds, and the waiting card says it is blocked by “a task”.

Moving on

A column’s work is judged by what the agent’s last turn ended with, never by the column’s name, so a workflow runs on any board. The Automation agent is told the task’s route, and the column’s description if it has one, and judges only this column’s step. At the route’s last column it asks only whether the agent reports the work as finished and is not waiting on you. Every answer, yes or no, is recorded with the task’s automation runs, which kangentic_get_automation_runs reads.

A task that finishes a plan in a plan-mode column moves on when you approve the plan, to the next column on its route rather than the column’s own plan-exit target.

A workflow needs no automations to move its tasks. At a turn end the column’s own On agent turn end automations run first, and the workflow’s step runs after them, so a move one of them makes wins. Automations and workflows has the order and what each kind of row does to the step.

Columns a person moves on

Some columns have no agent to judge: no agent starts there, the column’s agent cannot report when it finishes a turn, or no Automation agent is set up. A task in one of those columns waits for you, and you drag the card on to the next column of its route yourself. Of the agents Kangentic runs, Claude Code, Gemini, GitHub Copilot, Grok Build, Antigravity, OpenCode, Qwen Code, and Kimi Code report a turn end. Codex, Cursor, Goose, Aider, Factory Droid, Warp, and Ollama do not.

On the board

A workflow task’s card carries a strip with its workflow’s name and a step track: one mark per stop, from To Do through each column on its route to Done, so the track keeps one length for the task’s whole life. Stops it has passed are grey, the stop it is at is wider and in its column’s color, and stops ahead are bars in their columns’ colors. A card waiting in To Do says what it waits for (“Blocked by #413…”, or “Blocked by 2 tasks…”), or Paused while its workflow is paused. Below, two cards of a running workflow are mid-route, and the two in To Do say what they wait for.

Rest the pointer on a workflow card for a moment and lines fade in from what it waits for and to what waits for it, drawn as the canvas draws a selected card’s links. A refused move shows them too, and keeps them until Escape or a click on empty board space. Open workflow in the card’s right-click menu shows every link on the canvas.

The task detail window has a workflow panel, opened from a pill in its header, with the same route, links, and guards as the inspector. If the task’s workflow was deleted, the panel says so.

Locked while it runs

A running workflow’s cards move only by the workflow, a plan approval, their columns’ automations, and the task’s own agent, whose kangentic_move_task is how a column’s work can report itself done. Drags, the phone, and other agents are refused. A drag stays in the card’s own column, where you can still reorder it, and the refusal says why with an Open workflow link. The exception is a column a person moves on: from there you drag the card onto the next column of its route.

No workflow task moves back to To Do by any path, because that move ends the session and deletes the worktree and branch. Remove it from the workflow first. The card menu’s Move to follows the same lock as a drag. Its Backlog and Archive stay disabled on any workflow task, running or not, because each would take the task out of its workflow, which only Remove does.

Pausing, changing, and deleting

Running in the header pauses the workflow: every task’s agent is paused at once, and nothing starts or moves until Resume. While it is paused you can move its cards by hand, except into To Do, and agents still cannot. Resume resumes each paused task’s agent in the column it is in. It is also the way to retry a start that keeps failing.

A started workflow still changes. Add task puts a new task in To Do on its own board, where it starts once nothing it waits for is left. Routes and links change within the rules under Routes and links. Remove makes a task an ordinary task again, except a task in Done, which stays with its workflow.

Delete on a started workflow leaves its unfinished tasks where they are, as ordinary tasks, and its tasks in Done stay in Done. The workflow’s agent and its conversation go with it.

Tasks on other boards

A planned task can go on another project’s board when its work is in that project’s repository, and the inspector then names each task’s board. Its route uses that board’s columns, and its settings read that project. The Workflow agent reads every project its workflow’s tasks are on. When it needs another of your projects to plan, it asks with kangentic_request_project_access and gets it with no prompt. An agent whose CLI can read a folder outside its own restarts on the same conversation with that project readable and carries on.

Deleting a project does to its workflows what deleting each of its tasks would. A workflow that lived in it goes, and its tasks on other boards become ordinary tasks. A plan with a task on that board refuses to start until it is saved again without that task.

Setting up the agents

Settings > Workflows holds three cards, and applies to every project.

Workflow agent picks the Agent, Model, and Effort every workflow’s agent plans with. Nothing starts until an agent is chosen, and there is no fallback to the project’s default agent. The list offers only installed agents that reach Kangentic’s MCP server with an address of their own and can resume a conversation: Claude Code, Codex, Cursor, GitHub Copilot, Grok Build, OpenCode, and Kimi Code. Model is required when the agent’s CLI takes one, and an unset Effort runs at the CLI’s own level. A change applies the next time a workflow’s agent starts, a Resume included.
Workflow agent prompt is the first message a new workflow’s agent gets, envelope and all. It takes {{projectName}}, {{projectPath}}, {{baseBranch}}, {{columns}} (each column a task can visit, with what it runs, its automations, and how many recently finished tasks went through it), and {{brief_xml}}, from the Template variable menu under the field. Reset to default brings back the built-in text, and the expand button opens a larger editor. An edit applies to workflows whose agent starts after it.
Automation agent picks the Agent, Model, and Effort of the agent that judges both a workflow’s steps and every automation’s Condition, and names tasks and Command Terminals. The Automation agent has what it reads, what it costs, and what stops without one.

When the chosen agent offers floating aliases, the Model lists on both agent cards lead with the Latest group the other model pickers show, so a run set to an alias follows each new release of that model. A new install has no agent chosen on either card, which is how the tab below shows them.

The keys behind the tab are workflows.* and automation.* in the Configuration reference.

When a workflow finishes

When every task of a workflow reaches Done, a Workflow complete toast says so on the workflow’s project, and a desktop notification titled “Workflow complete:” and the workflow’s name reaches you when you are elsewhere. Each has its own switch under Settings > Notifications. See Notifications.

Workflow tools

Thirteen MCP tools in the Workflows group let an agent list, read, plan, start, pause, resume, change, and delete a workflow. A workflow’s own agent gets only the read-only tools and the ones that shape a plan, pinned to its own workflow: it cannot start, pause, resume, or delete one, or create, move, or delete board work outside its plan. Start is your approval of the plan. See the MCP tool reference for each tool.