mini-kanban

A local JIRA-like task management system. Uses CLI to manage stories and tasks stored in .tix/ directory under git repo root. All data is human-readable markdown files tracked by git.

First step for any operation: uvx --from shai-tix==0.1.3 shai-tix rebuild_index_db

Command Format

All commands run via uvx (no installation needed):

uvx --from shai-tix==0.1.3 shai-tix <command>

Example:

uvx --from shai-tix==0.1.3 shai-tix create_story "My Feature" --description "Description here"

Core Concepts

Story and Task Hierarchy

Story (Feature/Epic)
└── Task (Atomic work unit)

• Story: High-level feature or requirement
• Task: Specific work item under a Story

Best practice: If a story involves multiple independently testable steps, break it down into tasks. Tasks may have dependencies - describe the order/prerequisites in each task's description.

File System Structure

While you can access files directly, prefer using CLI commands as the primary API for list/search/get/create/update/delete operations on stories and tasks.

.tix/
├── index.sqlite                              # SQLite index (cache, auto-generated)
└── stories/
    └── story-{date}-{id}-{title}/
        ├── metadata.json                     # {"status": "IN_PROGRESS", ...}
        ├── description.md                    # Story description (editable)
        ├── report.md                         # Completion report
        ├── tmp/                              # Temporary scripts and data
        └── tasks/
            └── task-{date}-{id}-{title}/
                ├── metadata.json
                ├── description.md
                ├── report.md
                └── tmp/                      # Task-specific temp files

Key files:

• metadata.json: Contains status and other metadata
• description.md: Detailed description of the story/task
• report.md: Completion report (written when done)
• tmp/: Directory for temporary scripts, data files, or intermediate outputs

Status Values

CLI Commands

Most operations should be done via CLI.

Workflow (MUST FOLLOW)

Step 1: Run rebuild_index_db first to sync the index:

uvx --from shai-tix==0.1.3 shai-tix rebuild_index_db

Step 2: Run -h to see all available subcommands:

uvx --from shai-tix==0.1.3 shai-tix -h

Step 3: Based on SKILL doc scenarios, identify which subcommands you need, then run -h for each to learn the exact arguments:

# Run multiple -h commands in parallel to get usage info
uvx --from shai-tix==0.1.3 shai-tix create_story -h
uvx --from shai-tix==0.1.3 shai-tix create_task -h
uvx --from shai-tix==0.1.3 shai-tix list_stories -h

Step 4: Now execute the actual commands with correct arguments.

Available Subcommands

• Story: create_story, get_story, list_stories, search_stories, update_story, delete_story
• Task: create_task, get_task, list_tasks, list_tasks_by_story, search_tasks, update_task, delete_task
• Index: rebuild_index_db (run this first before any workflow)

Common Scenarios

These examples show typical workflows. Remember:

1. Run rebuild_index_db first
2. Run <subcommand> -h to confirm exact argument format before executing

Creating a New Feature (Story with Tasks)

When user defines a requirement that needs multiple work items:

# 1. Create the story
uvx --from shai-tix==0.1.3 shai-tix create_story "User Authentication" --description "Implement login and logout"

# 2. Break down into tasks
uvx --from shai-tix==0.1.3 shai-tix create_task 1 "Create login form" --description "HTML form with validation"
uvx --from shai-tix==0.1.3 shai-tix create_task 1 "Add session management"
uvx --from shai-tix==0.1.3 shai-tix create_task 1 "Implement logout endpoint"

Viewing Pending Work

When user asks "what's not done?" or "show me pending tickets":

# List recent stories
uvx --from shai-tix==0.1.3 shai-tix list_stories

# Find incomplete work (TODO or IN_PROGRESS)
uvx --from shai-tix==0.1.3 shai-tix search_stories --status "TODO,IN_PROGRESS"
uvx --from shai-tix==0.1.3 shai-tix search_tasks --status "TODO,IN_PROGRESS"

# List tasks under a specific story
uvx --from shai-tix==0.1.3 shai-tix list_tasks_by_story 1

Working on a Specific Ticket

When user references a ticket by [id] or #id (e.g., "work on [3]" or "do #3"):

# 1. Get ticket details to understand the work
uvx --from shai-tix==0.1.3 shai-tix get_story 3    # if story
uvx --from shai-tix==0.1.3 shai-tix get_task 3     # if task

The output includes the Path to the directory. You can:

• Read description.md for detailed requirements
• Read report.md if already completed (to understand what was done)
• Create scripts in tmp/ directory for task execution
• Store intermediate data in tmp/ directory

# 2. Mark as in progress
uvx --from shai-tix==0.1.3 shai-tix update_task 3 --status IN_PROGRESS

# 3. After completing, update with report
uvx --from shai-tix==0.1.3 shai-tix update_task 3 --status COMPLETED --report "Implemented with unit tests"

Direct file access: After getting the path from get_story or get_task, you can directly:

• Read the metadata.json, description.md, report.md files
• Create temp scripts in ${path}/tmp/ to execute work
• Store data or intermediate results in ${path}/tmp/

Searching for Specific Tickets

When user needs to find tickets by criteria:

# Search by title keyword (token matching)
uvx --from shai-tix==0.1.3 shai-tix search_stories --title "login auth"
uvx --from shai-tix==0.1.3 shai-tix search_tasks --title "form"

# Search by status
uvx --from shai-tix==0.1.3 shai-tix search_tasks --status "BLOCKED"

# Search by date range
uvx --from shai-tix==0.1.3 shai-tix search_stories --date_lower 2025-01-01 --date_upper 2025-01-31

# Search by ID range with limit
uvx --from shai-tix==0.1.3 shai-tix search_stories --id_lower 1 --id_upper 10 --limit 5

# Combined filters
uvx --from shai-tix==0.1.3 shai-tix search_tasks --title "api" --status "TODO,IN_PROGRESS"

Updating Ticket Status

# Mark as in progress
uvx --from shai-tix==0.1.3 shai-tix update_task 5 --status IN_PROGRESS

# Mark as blocked
uvx --from shai-tix==0.1.3 shai-tix update_story 2 --status BLOCKED

# Complete with report
uvx --from shai-tix==0.1.3 shai-tix update_task 5 --status COMPLETED --report "Feature implemented and tested"

Batch Operations

For running multiple queries efficiently:

# Rebuild index once, then run multiple queries
uvx --from shai-tix==0.1.3 shai-tix rebuild_index_db
uvx --from shai-tix==0.1.3 shai-tix list_stories
uvx --from shai-tix==0.1.3 shai-tix search_tasks --status TODO

Title Restrictions

Titles must contain only: letters (a-z, A-Z), digits (0-9), and spaces.

Invalid: Feature: Login, Bug Fix #123, Task [urgent] Valid: Feature Login, Bug Fix 123, Task urgent

Project Root

The --root parameter specifies the git repository root directory. The CLI expects a .tix/ directory under this root:

/path/to/git-repo/          <-- --root points here
├── .git/
├── .tix/                   <-- shai-tix data directory
│   ├── index.sqlite
│   └── stories/
├── src/
└── ...

By default, CLI uses current working directory as root. Use --root to specify a different project:

uvx --from shai-tix==0.1.3 shai-tix list_stories --root /path/to/git-repo
uvx --from shai-tix==0.1.3 shai-tix create_story "New Feature" --root /path/to/git-repo