| name | kanmer-tickets |
| description | Manage tickets on Kanmer, the file-based kanban shared live with a human's board GUI — orient on the board, create, update, link, order and archive tickets, and keep the board's conventions. Use whenever the user asks to add or update a ticket, manage the backlog, or asks "what's on the board" / "add a ticket for this" — and also proactively when you start a multi-step piece of work in a project that contains a .kanmer folder, so the work is filed before it starts and the human can follow it. DO NOT USE FOR doing the work itself — researching a ticket (kanmer-research), planning it (kanmer-plan), implementing it (kanmer-execute), reviewing it (kanmer-review), post-merge cleanup (kanmer-closeout), or clearing a whole area (kanmer-auto). |
Managing Kanmer tickets
Kanmer stores tickets as folders in the project's .kanmer/ tree — each
ticket owns its markdown file plus a pipeline of documents (research, files,
plan, checklist, proof) that live beside it. The human sees the same data on a
live kanban board (the Kanmer desktop app), so every item you create or move
is instantly visible to them — treat the board as your shared workspace, not
a log.
All access goes through the kanmer MCP tools. Never edit .kanmer/ files
directly; the tools keep ids, timestamps, folders and frontmatter consistent.
This skill covers the tickets themselves. The work inside a ticket is
driven by the phase skills — see the router at the end.
Workflow
- Orient —
get_status, then list_board, then list_items.
- Search before creating —
search_items for anything close.
- Do the one thing asked: create, update, link, order, or archive.
- Pick the profile deliberately when creating — it decides how much
evidence the ticket will owe, and it is the field most often got wrong.
- Hand off, or stop. Filing a ticket is not starting it: if that was the
whole request, say what you filed and stop there.
The ticket enters at Backlog, and this skill leaves it there. Everything
after Backlog belongs to a phase skill — the router at the end says which.
Orient first: get_status, once per session
It tells you whether .kanmer/ exists, the format version, whether the board
is real or the synthesized default, per-stage counts and any file warnings —
before you write anything. Then list_board for the stage/area ids
(they vary per project; writes with unknown ids are rejected, and the error
lists the valid ones) and list_items for current state. search_items
before creating: if something close already exists, update or link it rather
than filing a near-duplicate.
Creating tickets
One ticket per unit of work, created before the work starts (create_item,
body from assets/ticket-template.md). Set area from the board's list —
the area determines the ticket's id prefix (a ticket born in api becomes
API-00X). New tickets belong in the board's first stage (leave status
unset). For several at once use create_items and check its per-entry results.
Link or create a governing doc. The standard board gates leaving Backlog
on a governing PRD/FRD/ADR: give the ticket refs to the doc it implements
(link_doc <id> docs/frd/<slug>.md), or set docs_todo: true when the doc
is still to be written (hand off to kanmer-docs). Without one of the two a
ticket can't leave Backlog. Quick-filed tickets default to docs_todo.
Filing a ticket isn't the same as starting it: if the user only asked you to
file one, create it and stop there.
Linking
Link once, in one direction. Backlinks are derived, so linking A→B is
enough; get_links shows both sides plus typed dependency edges. Use
link_items rel: "blocks" when one ticket must land before another — the
blocked ticket shows it automatically. [[ID]] inside prose works for
inline references.
Archive, don't delete
update_item with archived: true hides an item but keeps it recoverable.
delete_item removes the ticket's whole folder — documents and all —
permanently; reserve it for items the user explicitly wants gone.
Conventions that keep the board useful
- Titles are imperative and specific: "Wire retry logic into upload queue",
not "Fix bug". The board is read at a glance, so the title carries meaning.
- Ticket bodies say why and how to verify; the pipeline documents carry
the depth. Don't duplicate plan.md into the body. The body's Outcome
section stays empty until closeout — in-flight notes go in checklist.md's
Progress notes.
- When rewriting a ticket body or a document late, pass
expected_updated
(the updated you last read) so a concurrent edit surfaces as a conflict
instead of being overwritten.
- Set
due (YYYY-MM-DD) only when the user gives a real deadline. Priority,
roughly: urgent blocks someone now, high is this week, medium normal,
low nice-to-have. Ambiguous wording → ask.
- Use
move_item position ("top" / "bottom" / after another id) when the
user asks for ordering — "top of the todo column" is meaningful now.
- Move tickets through stages by what the stages mean (designing,
implementing, awaiting eyes, verifying, finished), resolved against
list_board — never hardcoded ids. A move crosses at most one gated
boundary, so walk the stages one at a time; a jump is refused even when
every document exists, and update_item status runs the same check. Gates
constrain those two calls and nothing else — creating a ticket in any stage,
including the last, is ungated, which is what makes historical backfill
possible.
- Board changes are shared state:
add_column/update_column/
reorder_columns change what everyone sees, and remove_column needs
migrate_to when items still use the column. Ask before restructuring.
Which skill drives the work
A ticket's life is driven phase by phase; hand off rather than improvising:
kanmer-tickets → -research → -plan → -execute → -review → -verify → -closeout
That is the order. How far a given ticket actually walks it depends on its
profile, and some profiles stop well short of the end — so ask get_doc_gates
rather than assuming every ticket takes every step. Its reachable list is the
per-ticket answer.
| You are about to… | Use |
|---|
| Investigate a ticket, write its research / files documents | kanmer-research |
| Write the plan and checklist | kanmer-plan |
| Implement — worktree, branch, checklist, report, PR | kanmer-execute |
| Review finished work or handle PR feedback | kanmer-review |
| Verify a merged ticket on main → proof | kanmer-verify |
| Clean up after the PR merged | kanmer-closeout |
| Drive a whole area or group autonomously | kanmer-auto |
| Report current state / history | kanmer-report |
| Link/create a governing PRD/FRD/ADR | kanmer-docs |
| Tidy the backlog itself | kanmer-groom |
| Set up or reconcile Kanmer in the repo | kanmer-setup |
For exact tool parameters and what each field means, read
references/tool-reference.md.
Hand off to kanmer-research when the ticket you just filed is one you were
also asked to work — it is the first phase skill, and it takes the ticket out of
Backlog. If the request was only to manage the board, control returns to the
user here: filing is not starting.
