Ticket Management with tk

Installation

go install github.com/wedow/ticket/cmd/tk@latest

Tickets stored as markdown in .tickets/. Works from any subdirectory.

What Makes a Complete Ticket

A ticket MUST have ALL of:

1. Clear Acceptance Criteria — Specific, testable "done" conditions

   • ✅ "User can login with email/password and receives JWT"
   • ❌ "Login works"

2. Clear Requirements — What exactly to build

   • ✅ "POST /api/login accepts {email, password}, returns {token, expiresAt}"
   • ❌ "Add login endpoint"

3. Design/UI Info (if applicable) — Visual specs, layouts

   • ✅ "Login form: email input, password input, submit button. Error in red below form."

4. Atomic + Actionable — One focused task, can start immediately

   • ✅ "Implement password reset email"
   • ❌ "Improve auth system"

5. Testing Requirements — What to test

   • ✅ "Test: valid login→200+token, invalid→401, missing fields→400"

Ask yourself: Can someone implement this without clarifying questions?

Quick Reference

Command	Purpose
tk create "title"	Create ticket
tk ls	List all
tk ready	Ready to work (deps resolved)
tk blocked	Waiting on deps
tk show <id>	View details
tk edit <id>	Open in $EDITOR
tk start/close/reopen <id>	Change status
tk dep <id> <dep-id>	Add dependency
tk dep tree <id>	Show dep tree
tk undep <id> <dep-id>	Remove dep
tk link <id> <id>...	Link related
tk add-note <id> "text"	Append note

Supports partial ID matching: tk show 5c4 matches nw-5c46.

Creating Complete Tickets

tk create "Implement JWT login" -t feature -p 1 \
  --description "POST /api/login validates creds, returns JWT with 24h expiry" \
  --acceptance "- Valid creds → 200 + {token, expiresAt}
- Invalid password → 401
- Missing fields → 400
- Token expires in 24h" \
  --tags backend,auth

Options: -t type (bug/feature/task/epic/chore), -p priority (0-4), -d description, --acceptance, --design, -a assignee, --parent, --tags

Dependencies

tk dep ticket-a ticket-b      # a depends on b
tk dep tree ticket-a          # view tree
tk undep ticket-a ticket-b    # remove
tk dep cycle                  # find cycles

Workflow

tk create "Auth system" -t epic                    # auth-7f3a
tk create "Design schema" --parent auth-7f3a       # sch-2b1c
tk create "Login endpoint" --parent auth-7f3a \
  --acceptance "POST /login returns JWT"           # log-9d4e

tk dep log-9d4e sch-2b1c   # login depends on schema
tk ready                   # shows sch-2b1c
tk close sch-2b1c
tk ready                   # now shows log-9d4e