How to Customize Specialist Prompts for Each Kanban Lane in Routa

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, 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 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:

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 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:

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

{
  "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: Defines the KanbanColumnAutomation interface with specialistId, specialistName, and specialistLocale fields used by the lane engine.
• 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: 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: 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, which injects prompts when cards enter configured lanes.
• UI customization is available through templates.json to modify how prompts appear in the agent panel rendered by 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}