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:
-
Clear Acceptance Criteria — Specific, testable "done" conditions
- ✅ "User can login with email/password and receives JWT"
- ❌ "Login works"
-
Clear Requirements — What exactly to build
- ✅ "POST /api/login accepts {email, password}, returns {token, expiresAt}"
- ❌ "Add login endpoint"
-
Design/UI Info (if applicable) — Visual specs, layouts
- ✅ "Login form: email input, password input, submit button. Error in red below form."
-
Atomic + Actionable — One focused task, can start immediately
- ✅ "Implement password reset email"
- ❌ "Improve auth system"
-
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