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
```bash
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
```bash
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
```bash
ktui board update BOARD_ID --name "New Name" --icon "🎨"
```
**Note**: Only specified fields are updated; others remain unchanged

#### Switch Active Board
```bash
ktui board activate BOARD_ID
```
**Critical**: Always verify active board before task operations

#### Delete Board
```bash
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
```bash
ktui category list --json
```
**Output**: Array of categories with `category_id`, `name`, `color`

#### Create Category
```bash
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
```bash
ktui category update CATEGORY_ID --name "New Name" --color "new-color"
```
**Note**: Only specified fields are updated; others remain unchanged

#### Delete Category
```bash
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
```bash
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
```bash
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**:
```bash
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
```bash
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**:
```bash
# 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
```bash
ktui task move TASK_ID TARGET_COLUMN_ID
```
**Dependency Blocking**: Tasks with unfinished dependencies cannot move to start/f