# How to Customize Specialist Prompts for Each Kanban Lane in Routa

> Customize specialist prompts for each Kanban lane in Routa. Bind custom YAML specialist definitions to Kanban columns for tailored AI automation. Learn how to enhance your workflow now.

- Repository: [Fengda Huang/routa](https://github.com/phodal/routa)
- Tags: how-to-guide
- Published: 2026-05-26

---

**Routa enables lane-specific AI automation by binding custom YAML specialist definitions to Kanban columns via the `specialistId` field in the column automation configuration.**

Routa’s open-source workflow engine treats each Kanban column as an automation trigger, allowing you to customize specialist prompts for each Kanban lane to orchestrate context-aware LLM agents. By configuring specialist definitions in the `resources/specialists/workflows/kanban/` directory and mapping them through the board API, you can tailor system prompts, role reminders, and behavior for every stage of your development pipeline. This architecture, defined in [`src/core/models/kanban.ts`](https://github.com/phodal/routa/blob/main/src/core/models/kanban.ts), ensures that moving a card into a specific lane automatically loads the specialized instructions required for that workflow stage.

## Understanding Routa’s Lane Automation Model

Routa drives workflow automation through a **lane-automation** configuration attached to each Kanban column. When a card moves into a column, the system resolves the automation state and can launch a specialist-agent session using the parameters defined in the `KanbanColumnAutomation` interface.

The automation configuration resides in the board model at [`src/core/models/kanban.ts`](https://github.com/phodal/routa/blob/main/src/core/models/kanban.ts) and supports the following specialist-related fields:

- `specialistId`: The unique identifier correlating to a YAML definition file
- `specialistName`: The display name for the specialist agent
- `specialistLocale`: Optional localization identifier for the prompt

## Step 1: Create a Specialist Definition File

Specialist behavior is defined in **specialist definition files** stored under `resources/specialists/workflows/kanban/`. These YAML files contain the `system_prompt`, optional `role_reminder`, and metadata that instruct the LLM how to behave when processing cards in that lane.

For example, to create a custom prompt for a **Dev** lane, create [`resources/specialists/workflows/kanban/dev-executor.yaml`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/dev-executor.yaml):

```yaml
id: "kanban-dev-executor"
name: "Dev Executor"
system_prompt: |
  You are the Dev executor. Implement the story that has just arrived in the Dev lane.
  • Only run code that compiles.
  • Do not push to Git until the GATE review passes.
  …
role_reminder: "Only code, no documentation changes."

```

The `loadSpecialistDefinition` function in [`tools/hook-runtime/src/specialist-review.ts`](https://github.com/phodal/routa/blob/main/tools/hook-runtime/src/specialist-review.ts) discovers and loads these files at runtime, injecting the `system_prompt` into the LLM context when the lane automation triggers.

## Step 2: Bind the Specialist to a Kanban Column

After creating the specialist definition, you must associate it with a specific Kanban column using the board API. The board JSON is persisted in the database (SQLite via Drizzle) and can be updated via `PATCH /api/boards/:boardId`.

Update the column's automation object to reference your specialist:

```bash
curl -X PATCH "https://routa.example.com/api/boards/<board-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {
        "id": "dev",
        "automation": {
          "enabled": true,
          "specialistId": "kanban-dev-executor",
          "specialistName": "Dev Executor"
        }
      }
    ]
  }'

```

Once applied, `resolveCurrentLaneAutomationState` in [`src/core/tools/kanban-tools.ts`](https://github.com/phodal/routa/blob/main/src/core/tools/kanban-tools.ts) reads these values when a card enters the column, ensuring the correct specialist context is initialized for the agent session.

## Step 3: Override UI Prompt Templates (Optional)

To customize how the specialist prompt appears in the task-agent panel UI, modify [`resources/specialists/workflows/kanban/prompts/templates.json`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/prompts/templates.json). This file maps specialist IDs to display templates used by the frontend.

Add an entry keyed by your specialist ID to control the UI representation:

```json
{
  "kanban-dev-executor": {
    "en": [
      "You are the Dev executor. Write the implementation code for the story below.",
      "Ensure all tests pass before submitting."
    ]
  }
}

```

The frontend component at `src/app/workspace/[workspaceId]/kanban/kanban-tab-panels.tsx` reads this template map when rendering the agent interface, allowing you to differentiate the user-facing instructions per lane.

## Key Source Files for Lane Customization

- **[`src/core/models/kanban.ts`](https://github.com/phodal/routa/blob/main/src/core/models/kanban.ts)**: Defines the `KanbanColumnAutomation` interface with `specialistId`, `specialistName`, and `specialistLocale` fields used by the lane engine.
- **[`src/core/tools/kanban-tools.ts`](https://github.com/phodal/routa/blob/main/src/core/tools/kanban-tools.ts)**: Contains `resolveCurrentLaneAutomationState`, which resolves the current lane's automation configuration when cards move between columns.
- **[`tools/hook-runtime/src/specialist-review.ts`](https://github.com/phodal/routa/blob/main/tools/hook-runtime/src/specialist-review.ts)**: Implements `loadSpecialistDefinition` to load YAML specialist files and supply prompts to the LLM runtime.
- **`resources/specialists/workflows/kanban/*.yaml`**: Directory containing per-lane specialist definitions with `system_prompt` and `role_reminder` configurations.
- **[`resources/specialists/workflows/kanban/prompts/templates.json`](https://github.com/phodal/routa/blob/main/resources/specialists/workflows/kanban/prompts/templates.json)**: Stores UI-level prompt overrides for the task-agent panel.
- **`src/app/workspace/[workspaceId]/kanban/kanban-tab-panels.tsx`**: Renders the lane-specific agent UI and consumes the template configurations.

## Summary

- **Specialist definitions** are YAML files in `resources/specialists/workflows/kanban/` that contain lane-specific `system_prompt` and `role_reminder` text.
- **Column automation** binds specialists to lanes via the `specialistId` field in the `KanbanColumnAutomation` interface, persisted through the `PATCH /api/boards/:boardId` endpoint.
- **Runtime loading** is handled by `loadSpecialistDefinition` in [`tools/hook-runtime/src/specialist-review.ts`](https://github.com/phodal/routa/blob/main/tools/hook-runtime/src/specialist-review.ts), which injects prompts when cards enter configured lanes.
- **UI customization** is available through [`templates.json`](https://github.com/phodal/routa/blob/main/templates.json) to modify how prompts appear in the agent panel rendered by [`kanban-tab-panels.tsx`](https://github.com/phodal/routa/blob/main/kanban-tab-panels.tsx).

## Frequently Asked Questions

### Can I use the same specialist definition for multiple Kanban lanes?

Yes. Multiple columns can reference the same `specialistId` in their automation configuration. However, each column can only reference one specialist at a time, so if you need different behaviors for different lanes, you should create separate YAML definition files with unique IDs and bind them accordingly.

### Where does Routa store the active automation configuration for each board?

Routa persists board configurations, including the `KanbanColumnAutomation` settings, in a SQLite database accessed via Drizzle ORM. You modify these settings through the REST API at `PATCH /api/boards/:boardId` rather than editing files directly, ensuring runtime consistency and data integrity.

### What happens if a lane's automation references a specialistId that does not exist?

If `loadSpecialistDefinition` in [`tools/hook-runtime/src/specialist-review.ts`](https://github.com/phodal/routa/blob/main/tools/hook-runtime/src/specialist-review.ts) cannot locate the YAML file corresponding to the `specialistId`, the automation step will typically fail to initialize the agent session or fall back to default behavior. Ensure that files in `resources/specialists/workflows/kanban/` match the ID referenced in your column automation configuration.

### Do I need to restart Routa after adding new specialist YAML files?

No. The `loadSpecialistDefinition` function loads specialist files dynamically at runtime when a card triggers the lane automation. New YAML files placed in `resources/specialists/workflows/kanban/` are discovered automatically, allowing you to add or modify lane prompts without restarting the application.