# ticket (tk) — LLM Knowledge Base & Documentation Index > Dependency-aware, Git-friendly task queue for humans and coding agents. > Repository: https://github.com/msampathkumar/ticket --- ## 1. System Overview & Philosophy `ticket` (`tk`) is a zero-database, offline-first task tracking system with Directed Acyclic Graph (DAG) dependency intelligence. ### Key Tenets 1. **Zero Database / Pure Plain Text**: State resides in human-readable Markdown files with YAML frontmatter inside `.tickets/*.md`. Versioned directly alongside code in Git. 2. **DAG Dependency Intelligence**: Native support for parent-child hierarchies, blockers, cycle detection, and automatic unblocking of ready tasks. 3. **Unix Speed**: Core CLI is a single portable Bash script (Bash 3.2+) using `awk` and `sed`; no Python or Node. `jq` is optional, only for `tk query `. 4. **Safe Concurrent Claims**: `tk start --claim` lets exactly one agent win a ticket (exit `3` for the others). 5. **Decoupled Extensions**: Web UI (FastAPI + Tailwind Kanban & Mind Map), GitHub import, and SCION agent dispatch operate as optional plugins discovered via `$PATH`. Core scope and non-goals: [SPEC Section 1](SPEC.md#non-goals). --- ## 2. Agent Execution Loop (5-Step Deterministic Workflow) Autonomous AI coding agents operating inside repositories tracked by `tk` must follow this deterministic 5-step operational loop: 1. **Query Actionable Work**: ```bash tk ready ``` Lists open/in-progress tickets whose dependencies have all been satisfied (`closed`). 2. **Claim the Task**: ```bash tk start --claim --assignee ``` Atomically sets `in_progress` and the assignee. Exit `3`: another assignee holds it, pick another ticket from `tk ready`. Exit `4`: lock timeout, retry. 3. **Inspect Requirements & Subtasks**: ```bash tk show ``` Displays description, design notes, acceptance criteria, and subtasks. Decompose complex tasks with: ```bash tk create "" --parent tk dep ``` 4. **Implement, Verify & Record Notes**: Make code changes, execute tests (`make test`), and log review audit notes: ```bash tk add-note "Implemented feature and verified against test suite." ``` 5. **Close the Ticket**: ```bash tk close ``` Marks the ticket complete and automatically unblocks downstream dependent tasks. --- ## 3. Core CLI Command Cheat Sheet ### Ticket Management & Lifecycle - `tk init [path]`: Initialize `.tickets` repository in current or target folder. - `tk create [title] [options]`: Create new ticket, prints generated ID. - `-d, --description `: Detailed description. - `--design `: Architecture or implementation design notes. - `--acceptance `: Acceptance criteria for verification. - `-t, --type `: Type (`bug`|`feature`|`task`|`epic`|`chore`) [default: `task`]. - `-p, --priority <0-4>`: Priority (0=highest/urgent, 4=lowest) [default: 2]. - `-a, --assignee `: Assignee name or handle. - `--tags `: Comma-separated tags. - `--parent `: Parent ticket ID (hierarchy). - `tk start [--claim [--assignee ]]`: Set status to `in_progress`; `--claim` is atomic and fails with exit `3` if another assignee holds it. - `tk close `: Set status to `closed`. - `tk reopen `: Set status to `open`. - `tk status `: Update status (`open`|`in_progress`|`closed`). - `tk update [options]`: Update title, description, priority, tags, design, etc. - `tk show `: Display full ticket details and notes. - `tk edit `: Open ticket Markdown file in `$EDITOR`. - `tk add-note [text]`: Append timestamped review/audit note (or pipe via stdin). ### Dependency & DAG Intelligence - `tk dep `: Add dependency (`id` depends on `dep-id`); rejected with exit `1` if it would create a cycle. - `tk undep `: Remove dependency. - `tk dep tree `: Display recursive dependency tree. - `tk dep cycle`: Detect dependency cycles across open tickets. - `tk ready`: List open/in-progress tickets with all dependencies resolved. - `tk blocked`: List tickets blocked by open dependencies. - `tk closed [--limit=N]`: List recently closed tickets. ### Listing & Querying - `tk ls [options]`: List tickets (hides closed by default, limit 10). - `-s, --status `: Filter status (`open`|`in_progress`|`closed`|`all`). - `-p, --priority <0-4>`: Filter priority. - `-t, --type `: Filter type. - `-T, --tag `: Filter tag. - `-a, --assignee `: Filter assignee. - `-n, --limit `: Limit results (default 10); `--full`: no limit. - `--all`: Show all statuses without limit. - `tk find `: Full-text search across all ticket titles, descriptions, and notes. - `tk query [jq-filter]`: Output tickets as structured JSON, optionally filtered with `jq`. --- ## 4. Web UI & Background Server Management The Web UI (`tk webui` / `tk-webui`) is an optional dashboard running on default port **`8475`** (ASCII `T`=84, `K`=75): - **Foreground**: `tk webui [optional-path]` - **Background Daemon**: - `tk webui server start [path]`: Starts daemon on `http://127.0.0.1:8475`. - `tk webui server status`: Inspects PID, URL, and log file path. - `tk webui server stop`: Stops daemon. - `tk webui server restart`: Restarts daemon. --- ## 5. Plugin Architecture & Extensions `tk` discovers plugins named `tk-` or `ticket-` in system `$PATH` and `plugins//`. When launching a plugin, `tk` exports: - `TICKETS_DIR`: Absolute path to active `.tickets` directory. - `TK_SCRIPT`: Absolute path to root `tk` executable. Plugins can invoke core built-in commands using: `"$TK_SCRIPT" super [args...]` ### Official Plugins - `tk webui`: FastAPI + Tailwind 4-lane Kanban, Table View, and DAG Mind Map. - `tk github`: One-way import of GitHub issues and PRs (`tk github sync`); imported text is untrusted input. - `tk scion-taskforce`: Event-driven SCION worker per opted-in ticket, triggered by a `tk` save hook; local OpenTelemetry logs. --- ## 6. Curated Documentation File Index For complete and in-depth details, refer to the individual Markdown guides: - [Overview](index.md): Introduction, core architecture, and quick installation. - [Installation Guide](getting-started/installation.md): Modular installation flags (`--core`, `--webui`, `--skill`, `--github`, `--scion-taskforce`, `--full`, `--all`). - [Quick Start](getting-started/quick-start.md): 60-second tutorial to initialize and manage tasks. - [Solo CLI Workflow](workflows/cli-solo.md): Terminal-first workflow for solo developers and power users. - [Web UI & Kanban Workflow](workflows/webui-team.md): Visual sprint planning, DAG Mind Map, and code review comments. - [SCION Task Force Workflow](workflows/scion-taskforce.md): Tag a ticket for a SCION worker, review its report, send feedback and close. - [Command Reference](core-cli/commands.md): Complete reference table for all core `tk` commands. - [Dependency Intelligence](core-cli/dependencies.md): DAG task dependencies, blockers, and cycle detection. - [Core CLI Configuration](core-cli/configuration.md): Environment variables, directory discovery logic, and schema. - [Plugin Architecture](plugins/architecture.md): Writing custom Bash or Python plugins with `TICKETS_DIR` and `TK_SCRIPT`. - [Interactive Web UI Plugin](plugins/webui.md): 4-lane Kanban board, DAG Mind Map, daemon management, and configuration. - [GitHub Import Plugin](plugins/github.md): One-way GitHub issue/PR import, untrusted-input warning, prerequisites, and configuration. - [SCION Task Force Plugin](plugins/scion-taskforce.md): Save-hook bridge to SCION workers: setup, lifecycle, commands, configuration and troubleshooting. - [Agent Execution Loop](agents/workflow.md): The deterministic 5-step operational loop for AI coding agents. - [Agent Skill](agents/agent-skill.md): Reusable agent skill definition and `npx` install instructions. - [LLM & Agent Context Guide](agents/llms-txt.md): Machine-readable documentation standards and endpoints. - [System Specification](SPEC.md): Scope and non-goals, data model, DAG semantics, CLI exit codes, locks and claims. - [Agent Integration Guide](AGENTS.md): 10,000-foot architecture and operational guide for agents. - [Plugin Specification](PLUGIN_SPEC.md): Official plugin standard and metadata contract. - [Plugin Catalog](PLUGINS.md): Overview and development guide for plugins.