kanban-tui

name	kanban-tui
description	Comprehensive kanban board and task management via ktui CLI. Use for project tracking, todo lists, task dependencies, workflow automation, and board management. Activates when user mentions boards, tasks, kanban, or project management. If the `ktui` command is not available, but `uv` is available utilize `uvx kanban-tui` instead.

Kanban-TUI: Terminal-Based Task Management System

You are an expert at using ktui (kanban-tui), a powerful CLI tool for managing kanban boards, tasks, and workflows. This skill enables you to help users organize projects, track tasks, manage dependencies, and automate workflows through a local SQLite-backed system.

Core Concepts

Data Model

• Boards: Workspaces for different projects (e.g., "Frontend", "API Development")
• Columns: Workflow stages within boards (e.g., "Backlog", "In Progress", "Review", "Done")
• Tasks: Work items that move through columns, can have dependencies on other tasks
• Active Board: The currently selected board where operations execute (unless --board specified)
• Special Columns: Each board has reset_column (default start), start_column (in-progress), finish_column (completion)

Key Principles

1. CLI-Interface only: Never run bare ktui, use ktui task/board/column ... commands only
2. ID-Based Operations: All entities use numeric IDs - always list first to get IDs
3. JSON-First: Use --json flag for machine-readable output in automation
4. Active Board Context: Operations apply to active board unless explicitly specified
5. Non-Interactive: Use --no-confirm for automation/scripting

When to Activate This Skill

Automatically activate when the user:

• Mentions "kanban", "board", "task management", "project tracking", or "todo"
• Asks to create, list, update, move, or delete tasks/boards
• Needs workflow automation with task dependencies
• Wants to query actionable items or task status
• Requests project planning or work organization
• Discusses task priorities, due dates, or blockers

Command Categories & Workflows

1. Board Management

List All Boards

ktui board list --json

Output: Array of boards with board_id, name, icon, creation_date, reset_column, start_column, finish_column Note: Active board shown in output header (look for "Active Board: ...")

Create Board

ktui board create "Board Name" --icon "🚀" --set-active -c "Col1" -c "Col2", -c "Col3"

Options:

• --set-active: Immediately activate this board
• -c "Col1" -c "Col2", -c "Col3": Custom columns (default: "Ready, Doing, Done, Archive").
• --icon: Optional emoji icon for visual identification

Update Board

ktui board update BOARD_ID --name "New Name" --icon "🎨"

Note: Only specified fields are updated; others remain unchanged

Switch Active Board

ktui board activate BOARD_ID

Critical: Always verify active board before task operations

Delete Board

ktui board delete BOARD_ID --no-confirm

Warning: Deletes all associated tasks and columns, as an agent always use --no-confirm

2. Category Management

List All Categories

ktui category list --json

Output: Array of categories with category_id, name, color

Create Category

ktui category create "Category Name" "color"

Options:

• color: Optional. If omitted, a color is automatically assigned. Note: Color must be a valid CSS/X11 color name or hex code (e.g., "red", "#FF0000").

Update Category

ktui category update CATEGORY_ID --name "New Name" --color "new-color"

Note: Only specified fields are updated; others remain unchanged

Delete Category

ktui category delete CATEGORY_ID --no-confirm

Impact: Resets the category of all associated tasks to null, as an agent always use --no-confirm

3. Task Management

List Tasks

ktui task list --json

Filters:

• --column COLUMN_ID: Tasks in specific column
• --board BOARD_ID: Tasks on specific board
• --actionable: Only non-blocked tasks (no unfinished dependencies)

Output Fields: task_id, title, description, column_id, board_id, due_date, category_id, depends_on (array), creation_date

Create Task

ktui task create "Task Title" --description "Details" --column COLUMN_ID --category CATEGORY_ID --due-date 2026-01-20 --depends-on TASK_ID

Options:

• --column: Target column ID (omit for leftmost visible column of active board)
• --category: Category ID to assign to the task
• --due-date: Format MUST be YYYY-MM-DD (e.g., "2026-01-20")
• --depends-on: Dependency task ID (use multiple times for multiple dependencies)

Example Multi-Dependency:

ktui task create "Deploy to prod" --depends-on 5 --depends-on 7 --depends-on 9

Note: To create tasks on other boards, only use the --column flag to reference a column on that board

Update Task

ktui task update TASK_ID --title "New Title" --description "New Desc" --category CATEGORY_ID --due-date 2026-01-21 --depends-on TASK_ID --remove-dependency TASK_ID

Options:

• --title: Update task title
• --description: Update task description
• --category: Update category ID
• --due-date: Update due date (format: YYYY-MM-DD)
• --depends-on: Add dependency task ID (use multiple times for multiple dependencies)
• --remove-dependency: Remove dependency task ID (use multiple times for multiple dependencies)

Note: Only specified fields are updated; others remain unchanged

Dependency Management Examples:

# Add single dependency
ktui task update 42 --depends-on 15

# Add multiple dependencies
ktui task update 42 --depends-on 15 --depends-on 20 --depends-on 25

# Remove dependency
ktui task update 42 --remove-dependency 15

# Update title and add dependencies
ktui task update 42 --title "Updated Task" --depends-on 15 --depends-on 20

Validation: The system validates dependencies when updating:

• Checks if dependency tasks exist and prevents duplicate and circular dependencies

Move Task Between Columns

ktui task move TASK_ID TARGET_COLUMN_ID

Dependency Blocking: Tasks with unfinished dependencies cannot move to start/finish columns

Delete Task

ktui task delete TASK_ID --no-confirm

Impact: Removes task and all its dependency relationships, as an agent always use --no-confirm

4. Column Operations

List Columns

ktui column list --json

Filters: --board BOARD_ID to show columns for specific board Output: column_id, name, board_id, position, visible

CLI Capabilities:

• ✅ Available: ktui column list (read-only query)
• ❌ TUI Only: Column creation, deletion, reordering, and renaming requires human in interactive mode (ktui)

Task Dependencies System

Dependency Behavior

• Blocking: Tasks with unfinished dependencies cannot move to start column

Dependency Patterns

Sequential Workflow:

# Create tasks with chain dependencies
ktui task create "Design API" --column 1
ktui task create "Implement API" --column 1 --depends-on 1
ktui task create "Write Tests" --column 1 --depends-on 2
ktui task create "Deploy" --column 1 --depends-on 3

Parallel Dependencies:

# Multiple tasks must complete before final task
ktui task create "Frontend" --column 1
ktui task create "Backend" --column 1
ktui task create "Database" --column 1
ktui task create "Integration" --column 1 --depends-on 1 --depends-on 2 --depends-on 3

Query Actionable Tasks

ktui task list --json --actionable

Use Case: Find tasks ready to work on (no blocking dependencies)

Standard Operational Procedure

Follow this sequence for all operations:

Step 1: Discover IDs

# Get board IDs and identify active board
ktui board list --json

# Get column IDs for current board
ktui column list --json

# Get task IDs
ktui task list --json

Step 2: Verify Context

• Check active board from output header
• Activate correct board if needed: ktui board activate BOARD_ID
• Note column IDs for task placement

Step 3: Execute Operation

• Use retrieved IDs in commands
• Always use --json for automation
• Use --no-confirm for non-interactive execution

Step 4: Validate Result

• Re-list entities to confirm changes
• Check task status after moves
• Verify dependency relationships if relevant

Practical Scenarios

Scenario 1: New Project Setup

User Request: "Set up a new project board for our API development"

Actions:

# Create board with workflow columns Always prefer default columns, i.e. no -c options, if not told otherwise, to ensure already working status columns

ktui board create "API Development" --icon "⚙️" --set-active

# Get column IDs
ktui column list --json

# Create initial tasks with dependencies
ktui task create "Define API spec" --column 1 --due-date 2026-01-25
ktui task create "Implement endpoints" --column 1 --depends-on 1 --due-date 2026-02-01
ktui task create "Write unit tests" --column 1 --depends-on 2 --due-date 2026-02-05
ktui task create "Integration testing" --column 1 --depends-on 3 --due-date 2026-02-08

Scenario 2: Daily Workflow Check

User Request: "What tasks can I work on today?"

Actions:

# List actionable tasks (no blockers)
ktui task list --json --actionable

# Check for overdue tasks (compare due_date to today's date)
ktui task list --json

# Review specific column (e.g., "In Progress")
ktui task list --json --column 2

Scenario 3: Task Lifecycle Management

User Request: "Move task 42 to the next stage"

Actions:

# Get current task status
ktui task list --json | grep -A 10 '"task_id": 42'

# Get column IDs
ktui column list --json

# Move task (if no blockers)
ktui task move 42 3

# Update task details if needed
ktui task update 42 --description "Completed code review feedback"

Scenario 4: Multi-Board Project Tracking

User Request: "Show me all boards and their urgent tasks"

Actions:

# List all boards
ktui board list --json

# For each board, check actionable tasks
ktui task list --json --board 1 --actionable
ktui task list --json --board 2 --actionable

JSON Response Structures

Board Object

{
  "board_id": 1,
  "name": "Project X",
  "icon": "🚀",
  "creation_date": "2026-01-19T01:36:33",
  "reset_column": 1,
  "start_column": 2,
  "finish_column": 3
}

Task Object

{
  "task_id": 42,
  "title": "Implement feature",
  "description": "Add user authentication",
  "column_id": 2,
  "board_id": 1,
  "due_date": "2026-01-25",
  "depends_on": [12, 15],
  "creation_date": "2026-01-20T10:30:00"
}

Column Object

{
  "column_id": 2,
  "name": "In Progress",
  "board_id": 1,
  "position": 1,
  "visible": true
}

Critical Rules & Constraints

Date Formatting

• ONLY VALID FORMAT: YYYY-MM-DD
• Examples: "2026-01-20", "2026-12-31"
• Invalid: "01/20/2026", "20-01-2026", "Jan 20 2026"

ID Requirements

• All IDs are numeric integers
• IDs are auto-generated and permanent
• Always retrieve IDs via list --json commands
• Never guess or invent IDs

Text Handling

• Quote strings with spaces: "Task Title", "Multi-word description"
• The task description also supports markdown
• Escape special shell characters if present
• Use descriptive task titles (user-facing) and detailed descriptions

Dependency Constraints

• Cannot create circular dependencies
• Cannot move blocked tasks to start/finish columns (without --force)
• Deleting a task removes all its dependency relationships
• A task can have multiple dependencies

Active Board Context

• Default behavior: All operations affect the active board
• Override: Use --board BOARD_ID to target specific board when listing
• Verify before operations: Check active board with ktui board list --json

Error Prevention Checklist

Before executing commands:

• Retrieved all necessary IDs via list commands
• Verified correct board is active
• Validated date format is YYYY-MM-DD
• Checked for dependency blockers before moving tasks
• Quoted strings with spaces or special characters
• Used --no-confirm for non-interactive operations
• Used --json for machine-readable output

System Information

Additional Commands for humans

• ktui: Launch TUI interface (exit with ctrl+q)
• ktui demo: Temporary demo instance with example data
• ktui demo --clean: Empty demo instance
• ktui demo --keep: Don't delete demo data after exit
• ktui --web: Launch web interface (requires textual-serve)
• ktui clear: Delete all data and config
• ktui info: Show file locations
• ktui --version: Display version

Database Schema Overview

• tasks table: Task details with foreign keys to columns and categories
• task_dependencies table: Many-to-many task relationships
• boards table: Board configurations
• columns table: Workflow stages per board
• categories table: Task categorization (TUI only)
• audits table: Change tracking (automatic)

Best Practices for Agent Use

1. Always Start with Discovery

# Standard initialization sequence
ktui board list --json
ktui column list --json
ktui task list --json

2. Communicate Intent

Before executing operations, explain to the user:

• What board/tasks you're working with
• What changes you're about to make
• Any potential impacts (e.g., dependency blocking)

3. Validate Assumptions

• Confirm board names and IDs before operations
• Check task dependencies before moving
• Verify date formats before setting due dates

4. Handle Errors Gracefully

• If a command fails, explain why (e.g., "Task 42 cannot move because task 15 is unfinished")
• Suggest alternatives (e.g., "Use --force to override" or "Complete dependency first")

5. Batch Related Operations

# Instead of multiple separate commands, chain related operations:
ktui task create "Task 1" --column 1 && \
ktui task create "Task 2" --column 1 --depends-on 1 && \
ktui task create "Task 3" --column 1 --depends-on 2

6. Provide Context in Outputs

When showing results to users, parse JSON and present:

• Human-readable summaries
• Relevant IDs for reference
• Action items or next steps

Advanced Patterns

Automated Workflow Progression

# Check for tasks ready to move to next stage
TASKS=$(ktui task list --json --column 2 --actionable)
# Parse JSON, filter by criteria, move qualifying tasks
ktui task move TASK_ID 3

Troubleshooting Common Issues

"Task cannot be moved" Error

• Cause: Task has unfinished dependencies
• Solution: Complete dependencies first, or use --force flag
• Check: ktui task list --json | jq '.[] | select(.task_id == X) | .depends_on'

"Board not found" Error

• Cause: Invalid board ID or board deleted
• Solution: Run ktui board list --json to verify board exists

"Invalid date format" Error

• Cause: Date not in YYYY-MM-DD format
• Solution: Reformat date (e.g., "2026-01-20" not "01/20/2026")

Operations Affecting Wrong Board

• Cause: Wrong board is active
• Solution: ktui board activate CORRECT_BOARD_ID or use --board flag

Summary

You now have complete access to the kanban-tui system. Remember:

• CLI only: Never run the bare ktui command to open the TUI
• Discover first: Always get IDs before operations
• Verify context: Check active board
• Use JSON: Enable automation with --json flag
• Respect dependencies: Understand blocking relationships
• Validate inputs: Especially date formats
• Communicate clearly: Explain actions to users

This skill empowers you to help users organize complex projects, automate workflows, and maintain productive task management systems entirely from the command line.