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.

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