Custom Workflows & Transitions

Kangentic’s board isn’t just a task tracker — each column can trigger actions when tasks arrive. This lets you build automated pipelines like Plan → Execute → Review without manual intervention.

Default Board Layout

New projects start with seven columns. You can add, remove, rename, and reorder them to match your workflow.

Column	Purpose
Backlog	Holding area. No agent runs. Dragging a task here ends its session.
Planning	Spawns Claude in plan mode. Agent creates a plan, then the task auto-moves to Executing.
Executing	Spawns Claude with the default permission mode. The agent works on the task.
Code Review	Agent keeps running. You can attach a review prompt as an auto-command.
Tests	Agent keeps running.
Ship It	Agent keeps running.
Done	Suspends the session (preserving context) and archives the task.

What Happens When You Drag a Card

When you drag a task from one column to another, Kangentic evaluates these rules in order:

Rule	Behavior
Target is Backlog	Session ends, worktree is preserved.
Target is Done	Session is suspended (resumable), task is archived.
Target has auto-spawn off	Session is suspended.
Task already has a running agent	Agent keeps running. If the target column has an auto-command, it’s injected.
Task has no running agent	A new agent is spawned (or a suspended session is resumed).

The key insight: moving between active columns doesn’t restart the agent. The session stays alive, and only an auto-command is injected if one is configured. This means you can move a task from “Executing” to “Code Review” and the agent seamlessly receives a review prompt.

Auto-Commands

An auto-command is a prompt that gets injected into a running agent when a task arrives in a column. This enables hands-free transitions.

Example: Set a Code Review column’s auto-command to:

Review the code changes you just made. Check for bugs, security issues, and adherence to the project’s coding standards.

When you drag a task from Executing to Code Review, that prompt is automatically sent to the running agent — no manual typing needed.

Auto-commands support template variables (see below) so they can reference the task’s title, description, or worktree path.

Plan Mode Workflow

The default board includes a Planning column configured with:

• Permission mode set to plan
• A plan exit target pointing to the Executing column

Here’s what happens:

1. You drag a task to Planning
2. Kangentic spawns Claude in plan mode (read-only tools only)
3. The agent analyzes the codebase and creates a plan
4. When the agent calls ExitPlanMode, Kangentic detects it
5. The task automatically moves to the column specified by plan_exit_target_id (default: Executing)
6. The agent resumes with full autonomy to implement the plan

This gives you a two-phase workflow: plan first, then execute — with the transition happening automatically.

Configuring Plan Exit Targets

The plan_exit_target_id column setting controls where a task moves when a plan-mode agent calls ExitPlanMode. You can set this in the column settings dialog under Plan Exit Target.

• If plan_exit_target_id is set, the task auto-moves to that column when planning completes
• If not set (null), the task stays in the plan-mode column after planning finishes
• The target column typically has a less restrictive permission mode so the agent can execute the plan

You can chain multiple plan stages — for example, a “High-Level Plan” column that exits to a “Detailed Plan” column, which exits to “Executing.”

Tip

You can create your own plan-mode columns. Set a column’s permission mode to plan and point its plan exit target to any other column.

Action Types

When a task arrives in a column with no running session, Kangentic executes a chain of actions sequentially. For example, the default “move to Planning” transition runs: Kill Session → Spawn Agent.

Available action types:

Action	Description
Spawn Agent	Starts a Claude Code session with a prompt template
Send Command	Injects text into a running session’s terminal
Run Script	Executes a one-off shell command
Kill Session	Suspends the current session (preserving it for later resume)
Create Worktree	Creates a git worktree for the task
Cleanup Worktree	Removes the task’s worktree and optionally its branch
Create PR	Creates a pull request from the task’s worktree branch
Webhook	Sends an HTTP request to an external URL

Action Chaining

When a task arrives in a column with no running session, Kangentic runs the column’s actions sequentially in execution_order. For example, the default “move to Planning” transition runs two actions in order:

1. Kill Session — ends any existing session
2. Spawn Agent — starts a new Claude Code session in plan mode

You can build multi-step workflows by chaining actions. Each action in the chain completes before the next begins.

Run Script Example

Use Run Script to execute setup or validation commands:

• Action type: Run Script
• Config: npm run lint -- --fix — runs a linter before the agent starts, or npm test to validate before shipping.

Run Script executes a one-off shell command in the task’s worktree directory (or project root if worktrees are disabled). The command runs to completion before the next action in the chain.

Webhook Example

Use Webhook to notify external services when tasks change columns:

• Action type: Webhook
• Config: Send an HTTP POST to a Slack incoming webhook URL, a logging endpoint, or any external API. The request body includes the task title, description, column name, and other metadata.

Combine with wildcard transitions to log every column move to an external service.

Template Variables

Prompt templates and auto-commands can use these placeholders:

Variable	Replaced with
{{title}}	Task title
{{description}}	Task description
{{taskId}}	Task UUID
{{worktreePath}}	Git worktree directory path
{{branchName}}	Git branch name
{{attachments}}	List of attached image paths

Example prompt template:

{{title}}{{description}}

Work in {{worktreePath}} on branch {{branchName}}.

Concurrency & Queue Management

Kangentic runs multiple agents in parallel, each as a separate CLI process (Claude Code, Codex, Gemini, Cursor, Copilot, Aider, or Warp). The agent.maxConcurrentSessions setting (default: 8) caps how many sessions can run at once across all agents. When the limit is reached, new sessions enter a FIFO queue.

How Queuing Works

1. You drag a task to an active column.
2. If a session slot is available, the agent starts immediately.
3. If all slots are full, the task enters the queue and its card shows a “Queued” label.
4. When a running session exits or is suspended, the next queued task promotes automatically.
5. Queue promotion is reentrancy-safe — if a promotion triggers another session exit, the queue processes correctly without race conditions.

Overflow Behavior

The agent.queueOverflow setting controls what happens when the limit is reached:

Mode	Behavior
queue (default)	Tasks wait in a FIFO queue until a slot opens
reject	The move is rejected — the task stays in its current column

Tuning Concurrency

• Lower the limit if your machine runs out of memory or CPU with many agents. Each Claude Code process uses significant resources.
• Raise the limit if you have a powerful machine and want more agents running simultaneously.
• The limit is global, not per-project. If you have 3 projects each running agents, they share the same pool.

Configure both settings in Settings under the Agent tab, or in the config file — see Configuration Reference.

Adding Custom Columns

Click the + button at the end of your column row to add a new column. Then configure it:

1. Set a name and optional icon and color
2. Choose a permission mode if you want to override the default
3. Set an auto-command if tasks arriving here should receive a prompt
4. Toggle auto-spawn off if this column shouldn’t run agents

Columns can be reordered by dragging their headers and deleted when empty.

Wildcard Transitions

You can use a wildcard (*) as the source in a transition rule to match any column. This is useful for creating catch-all behaviors — for example, a wildcard transition pointing to a “Logging” webhook ensures every column move triggers a log entry.