mini-kanban

A local JIRA-like task management system. Uses CLI to manage stories and tasks stored in

.tix/

First step for any operation:

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

Command Format

All commands run via

uvx

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

TODO

IN_PROGRESS

COMPLETED

BLOCKED

CANCELED

CLI Commands

Most operations should be done via CLI.

Workflow (MUST FOLLOW)

Step 1: Run

rebuild_index_db

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

Step 2: Run

-h

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

# 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]

#id

# 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

• 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

get_task

• 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]

Feature Login

Bug Fix 123

Task urgent

Project Root

The

--root

.tix/

/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

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