kanban-tui

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 `--j