ticket-index
Skill1 starsChanged 27 days agoMITView on GitHub
Maintain a layered index over Markdown tickets (overview, module ownership, one-line summaries, cross-module relations, frontier and blocked lists). Use after adding, closing, reassigning, or re-linking tickets in a large repository; use it to answer "what work exists, who owns it, and what can start now".
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- codebase-designSkill
- code-reviewSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- grillingSkill
- handoffSkill
- implementSkill
- implement-specSkill
- prototypeSkill
- prSkill
- setup-ticket-workflowSkill
- tddSkill
- to-specSkill
- to-ticketsSkill
- wayfinderSkill
- writing-for-agentsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 8 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 28
After creating, closing, reassigning, re-linking, or re-prioritising tickets.
- Distinctive: line 29
Before a PR, or when someone asks for a project-wide status review.
- Distinctive: line 30
When a ticket's module ownership changes.
- Distinctive: line 31
When you need to know what can start now (the frontier) or what is blocked.
- Very specific: line 41
Create ticket-index.toml at the repository root.
- Distinctive: line 43
Make sure ticket files follow the contract below.
- Very specific: line 44
Run check; fix every error before relying on the index.
- Distinctive: line 81
Every ticket has exactly one entry.
- Distinctive: line 87
Use a new module instead of forcing a ticket into the closest existing one.
- Very specific: line 117
Only the first # heading counts as the title.
- Very specific: line 133
Use facts when you need a compact table for a human decision:
- Very specific: line 179
Commit ticket-index.toml together with every generated file.
- Very specific: line 192
Before opening a PR, update the branch from its target branch and re-render the index.
- Very specific: line 193
If a rebase stops with conflicts, resolve .tickets/*.md and ticket-index.toml first.
- Very specific: line 206
If parent is in another module, the child becomes a root in its own module and is annotated with its parent.
- Distinctive: line 220
Never copy one ticket into several modules to make a page look complete.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ticket Index
A repository with dozens or hundreds of tickets is expensive for an agent to navigate: opening every ticket burns context before any work starts. This skill maintains a derived index with three levels:
docs/tickets/INDEX.md overview: stats, modules, frontier, blocked, relations
docs/tickets/modules/<id>.md one file per module, tickets arranged by parent
.tickets/<id>.md the ticket itself: the only full copyReaders locate a candidate through the overview, narrow it through one module, then open exactly one ticket. The index never replaces ticket text.
The index is generated by a script. Humans maintain only two judgements in
ticket-index.toml: which module a ticket belongs to and a one-line summary.
Status, type, owner, dependencies, hierarchy, and counts are projected from
ticket frontmatter, so generated output cannot drift from the tickets.
When to run
- After creating, closing, reassigning, re-linking, or re-prioritising tickets.
- Before a PR, or when someone asks for a project-wide status review.
- When a ticket's module ownership changes.
- When you need to know what can start now (the frontier) or what is blocked.
Reading the index is enough for orientation; run the script only when tickets or the config changed.
Setup
- Install the folder where your agent looks for skills:
.cursor/skills/ticket-index/for Cursor,.claude/skills/ticket-index/for Claude Code, or the equivalent for your agent. The kit'sscripts/install.pyperforms this copy. - Create
ticket-index.tomlat the repository root./setup-ticket-workflowwrites it, including the ticket contract and module list. - Make sure ticket files follow the contract below.
- Run
check; fix every error before relying on the index.
Optional: install the auto-sync hook described at the end.
Paths in the commands below assume .cursor/skills/; substitute the directory you
actually installed to.
Configuration
ticket-index.toml at the repository root:
[settings]
title = "Ticket Index" # heading of INDEX.md
tickets_dir = ".tickets" # directory holding <id>.md
output_dir = "docs/tickets" # where generated files go
id_pattern = "[A-Za-z][A-Za-z0-9]*-[0-9a-z]{4}"
summary_max_chars = 160 # soft warning only
placeholder_assignees = ["", "-", "team", "tbd", "todo", "unassigned"]
[[modules]]
id = "core" # lowercase letters, digits, hyphens
title = "Core Platform"
scope = "Runtime, storage, and deployment boundaries"
[[modules]]
id = "docs"
title = "Documentation"
scope = "Guides, references, and examples"
[tickets]
"app-1a2b" = { module = "core", summary = "Decide how sessions survive a worker restart" }
"app-3c4d" = { module = ["core", "docs"], summary = "Define the public API contract and its reference page" }Rules:
- Every ticket has exactly one entry; every entry points at an existing ticket.
moduleis a string or an array. The first item is the primary module; the ticket is expanded only there, and other modules list it under "cross-module membership".summaryis one line that adds information beyond the title. Do not repeat the title, the status, the owner, or a file path.- Use a new module instead of forcing a ticket into the closest existing one.
- Summaries written in any language are fine; the generated scaffolding is English.
Legacy layout
docs/tickets/index.toml is still accepted when no root config exists. Its
output_dir defaults to docs/tickets; [settings] is optional.
Ticket contract
Each ticket is <tickets_dir>/<id>.md with YAML frontmatter:
---
id: app-1a2b
status: open # open | in_progress | closed
type: task
priority: 2 # 0 highest, 4 lowest
assignee: alice # empty means unclaimed
parent: app-9z8y # optional; hierarchy only
deps: [app-5e6f] # optional; blocking edges
links: [app-7g8h] # optional; symmetric associations
tags: [map, core] # "map" or "wayfinder:map" marks a decision map
created: 2026-01-01T00:00:00Z
---
# Ticket title
Body...Only the first # heading counts as the title. Unknown statuses are reported
as warnings and treated as inactive. Any ticket tool that writes these files
works; fer is the reference implementation used by this kit.
Workflow
1. Check
python .cursor/skills/ticket-index/scripts/ticket_index.py checkcheck reports missing config entries, empty summaries, unknown modules,
broken parent/dependency/link references, stale generated files, and obsolete
module files. Exit code 1 means fix the errors first.
Use facts when you need a compact table for a human decision:
python .cursor/skills/ticket-index/scripts/ticket_index.py facts2. Update ownership and summaries
Edit ticket-index.toml:
- new ticket: mint an id with
new-id, then add one line under[tickets]; - moved ticket: change its
modulearray; - removed ticket: delete its line and any now-empty module.
new-id prints one ticket id that does not collide with the existing store, so
two sessions creating tickets in parallel cannot silently pick the same filename:
python .cursor/skills/ticket-index/scripts/ticket_index.py new-id3. Review only the delta
python .cursor/skills/ticket-index/scripts/ticket_index.py diffdiff prints unified diffs for files that would change and writes nothing.
Review only those hunks; do not re-read the whole index. If it prints
"Generated files are already current", skip the review.
Check that:
- new tickets landed in the right module;
- hierarchy follows
parent, and cross-module parents appear as roots with a parent pointer; - multi-module tickets are expanded only in their primary module;
- the frontier, blocked, and missing-owner lists match expectations.
4. Render and verify
python .cursor/skills/ticket-index/scripts/ticket_index.py render
python .cursor/skills/ticket-index/scripts/ticket_index.py checkCommit ticket-index.toml together with every generated file. Exit code 0
and OK: ... means the index is consistent.
Generated files need special merge handling, because every ticket edit rewrites the
overview and the module pages. install.py adds docs/tickets/** merge=ours to the
repository's .gitattributes and registers the ours merge driver in git config.
During a merge or rebase, git then keeps the branch-local index and only source
conflicts (.tickets/*.md, ticket-index.toml) surface; never hand-merge
docs/tickets/** or choose one side's generated output. On a plain clone, register
the driver once with git config merge.ours.driver true (or re-run the installer).
The integrator resolves the source conflicts, runs render and check once so the
merged index carries both sides' tickets, and commits them together.
Before opening a PR, update the branch from its target branch and re-render the index.
If a rebase stops with conflicts, resolve .tickets/*.md and ticket-index.toml first;
never hand-merge docs/tickets/** or choose one side's generated output. Once the source
conflicts are resolved, run render and check to regenerate the conflicted output,
stage the source and generated files, and continue the rebase. After the rebase finishes,
run render and check again before pushing so the PR contains an index generated from
the latest ticket sources.
Module ownership
A module is the domain where the ticket's conclusion lands, not the person who raised it, the stage of discussion, or the ticket type.
- One primary module per ticket; references elsewhere do not duplicate the row.
- If
parentis in another module, the child becomes a root in its own module and is annotated with its parent. - Cross-module dependencies and links are summarised in the overview; ticket rows only show dependencies that still block.
- Summary/epic branches are hierarchy, not modules.
Cross-module patterns
| Situation | Configuration |
| A ticket serves several domains | module = ["primary", "secondary", ...] |
| Parent lives in another module | Keep the child in its own module; no special config |
| Dependency or link crosses modules | Keep ownership unchanged; the overview shows the edge |
Never copy one ticket into several modules to make a page look complete.
Optional: auto-sync hook
hooks/ticket-index-sync.py re-renders after a ticket mutation (Cursor
afterShellExecution / afterFileEdit), so generated files cannot go stale even
when someone forgets to run render.
install.py --install-git-hooks takes the same job to the git layer: it writes
post-merge and post-checkout hooks that re-render the index after every merge
and branch switch, so other people's ticket changes appear as soon as their work
lands. The hooks never overwrite an existing user hook and never block the git
operation.
Merge hooks/hooks.json.example into <repo>/.cursor/hooks.json and adjust the
path if the skill is installed elsewhere:
{
"version": 1,
"hooks": {
"afterShellExecution": [
{ "command": "python .cursor/skills/ticket-index/hooks/ticket-index-sync.py after-shell" }
],
"afterFileEdit": [
{ "command": "python .cursor/skills/ticket-index/hooks/ticket-index-sync.py after-file-edit" }
]
}
}The hook reacts only to ticket files, the config file, and ticket-CLI mutations
(fer by default; edit FER_MUTATION for another CLI). Cursor loads hooks when
a session starts, so restart it after adding the config and confirm the hook in
the Hooks output panel. The hook is a safety net, not a replacement for
check or the diff review.
Companion skills
This skill is the navigation layer of a larger ticket workflow. The kit ships, among
others, setup-ticket-workflow (configure a repo), to-tickets (break a spec into
tickets with blocking edges), wayfinder (map a large effort as decision tickets),
implement-spec (work the frontier), and code-review. When installed together they all
read the same .tickets/*.md contract.
Common mistakes
- Editing generated files:
checkreports them as stale andrenderoverwrites them. - Treating a team name (
Team,TBD) as an owner: the overview lists such active tickets under "Missing owners". - Using
linksto express hierarchy: hierarchy comes only fromparent. - Adding a ticket without a config entry:
checkfails andrenderrefuses to write. - Re-reading the whole index after a small change: run
diffand review the hunks.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

