// Create and refine tickets for the tk ticket system. Use when the user says 'create tickets for X', 'refine ticket X', 'break this into tickets', 'seed tickets from plan', or anything about creating or refining tk tickets.
| name | ticket-creator |
| description | Create and refine tickets for the tk ticket system. Use when the user says 'create tickets for X', 'refine ticket X', 'break this into tickets', 'seed tickets from plan', or anything about creating or refining tk tickets. |
Create well-structured tickets that the ticket-worker skill can consume without ambiguity.
Every ticket must have:
| Field | Required | How |
|---|---|---|
| Title | Yes | Imperative, scoped action: tk create "Add rate limiting to auth endpoints" |
| Description | Yes | What to do, why, and file hints (see src/auth/) |
| Acceptance criteria | Yes | Numbered, each independently verifiable. Prefer criteria that map to a command |
| Type | Yes | bug, feature, task, epic, chore |
| Dependencies | When order matters | tk dep <id> <blocks-id> — the second arg depends on the first |
| Parent | For subtasks | --parent <epic-id> — ticket is a subtask of an epic |
tk create "Fix token refresh returning 401 on expired tokens" \
-d "The /auth/refresh endpoint returns 401 when the refresh token is expired.
Should return 403 with a clear error message instead.
Relevant code in src/auth/refresh.ts and src/auth/middleware.ts." \
--acceptance "1. POST /auth/refresh with expired token returns 403 (not 401)
2. Response body includes 'error' field with descriptive message
3. Existing tests pass
4. New test covers expired token case" \
-t bug
tk create "Fix the bug" -d "There's a bug somewhere in auth"
No acceptance criteria, no file hints, no verification command. The agent will wander.
Use --parent when one ticket is a logical subtask of an epic (e.g., "implement login form" under "add auth system"). Use dep when two tickets are independent work items where one must finish before the other starts. When in doubt, use dep — it's the more common relationship.
Only add dep when there is a real ordering constraint (e.g., ticket B requires code that ticket A will create). If two tickets could be worked on in parallel, do not link them with deps.
Only add --tags ready-for-development when the ticket is fully refined: description, acceptance criteria, and file hints are all present. Vague or wishlist tickets should have no tag — they live in the backlog until refined.
Refining is done via Mode 4 — do not hand-edit YAML frontmatter.
A single ticket should be completable in one agent session (~30 min of agent work). If a task is larger, split it into multiple tickets with dependencies.
User says: "create a ticket for X" or "add a ticket for X"
git add .tickets/ && git commit -m "feat(tickets): add ticket for <short description>"If the request is vague ("add a ticket for that auth thing I mentioned"), create a backlog ticket: brief title, minimal description, no tag. The user or a later refine session will fill in the details.
If the request is specific enough to write proper acceptance criteria and file hints, create a fully-formed ticket with --tags ready-for-development.
User says: "break this goal into tickets" or "create tickets for refactoring X"
lat.md/ exists at project root, run lat search "<goal description>" to discover relevant context from the knowledge graphtk dep <downstream-id> <upstream-id> (downstream depends on upstream)tk dep cycle and tk ready — if there are cycles or no ready tickets, fix before proceedingUser says: "seed tickets from this plan" or provides a plan file path
lat.md/ exists at project root, run lat search "<goal description>" to discover relevant context from the knowledge graphUser says: "refine ticket X" or "refine backlog tickets"
Turn a vague backlog ticket into a workable one. If the ticket is too large, split it first (Mode 2).
tk show <id>ready-for-development tag, tell the user it's already refined and stopready-for-development tag to the frontmattergit add .tickets/ && git commit -m "refactor(tickets): refine ticket <id>"Batch refine: if the user says "refine backlog tickets" or "refine all", repeat for each untagged open ticket. Stop on the first one that needs user clarification — don't guess.
To rewrite a ticket file, use the write tool on the file path shown by tk show. Preserve the existing YAML frontmatter fields (id, created, deps, links, parent) and only update: title, description, acceptance criteria, type, tags.
Modes 2 and 3 create a context file to avoid redundant discovery in each ticket-worker session.
Prerequisite: if a lat.md/ directory exists at the project root, skip context seeding entirely. The lat search command (run in step 2) provides living, queryable context that makes a static context file redundant.
After exploring the codebase (step 2 in both modes), check if plans/.ticket-context.md exists. If it does, skip — the context is already seeded. If not, create it:
mkdir -p plans
Write plans/.ticket-context.md with three sections:
## Verification commands
- Build: <command>
- Test: <command>
- Lint: <command>
## Key directories
- path/ — description
## Conventions
- Description of relevant patterns
Fill in each section from what you discovered during exploration:
devenv.nix (scripts, tasks, git-hooks), package.json (scripts.test, scripts.lint, scripts.build), Makefile (test, lint, check, build targets), flake.nix (checks)The context file is project-local and reusable across all tickets in the batch.
After creating all tickets, run these checks:
tk list — confirm all tickets are opentk show <id> — verify:
tk dep cycle — no cycles allowed. If found, fix.tk ready -T ready-for-development — at least one ticket must be unblockedReport: number of tickets created, any issues found and fixed, whether tickets are ready for work.
tk create with all fields populated. Use real newlines in -d and --acceptance arguments — never pass literal \n characterstk dep <id> <dep-id>git add .tickets/ && git commit -m "feat(tickets): add tickets for <short description>"
.tickets/ is not the tickets dir, find it first with find . -name .tickets -type dplans/.ticket-context.md)Structured workflow for research → plan → tickets → work. Use when starting or continuing a task with /task, /plan, or /tickets commands.
Work on a single tk ticket end-to-end. Use when the user says 'work on ticket X' or when spawned by work-tickets.sh.
REQUIRED when user says 'pickup', '/pickup', 'handoff', '/handoff' — MUST load this skill BEFORE any other work. Compacts conversations into handoff docs or resumes work from a prior handoff document.
Interact with web pages using Chrome DevTools Protocol. Launches a managed browser instance (Helium / Brave Nightly / Chrome) with an isolated profile and exposes nav, eval, screenshot, pick, and emulation helpers. Run scripts/start.js first.
Delegate tasks to other agents - pi sessions or external agents (claude, opencode, aider). Non-blocking with task tracking and completion notifications.
Display code, diffs, images, and other content in a tmux pane or popup, OR render markdown as a single-page interactive HTML and open in the default chromium-family browser. Auto-detects nvim/megaterm for floating popups.