kanban-tui

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.

<!-- This part is for keeping this SKILL.md up to date with the current tool version via `ktui skill update`--> <!-- Version: KANBAN_TUI_VERSION -->