agentleFS
hanjiang-215hanjiang-215/ticket-index-skills/skills/ticket-index/SKILL.md

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".

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
  1. Distinctive:

    After creating, closing, reassigning, re-linking, or re-prioritising tickets.

    line 28
  2. Distinctive:

    Before a PR, or when someone asks for a project-wide status review.

    line 29
  3. Distinctive:

    When a ticket's module ownership changes.

    line 30
  4. Distinctive:

    When you need to know what can start now (the frontier) or what is blocked.

    line 31
  5. Very specific:

    Create ticket-index.toml at the repository root.

    line 41
  6. Distinctive:

    Make sure ticket files follow the contract below.

    line 43
  7. Very specific:

    Run check; fix every error before relying on the index.

    line 44
  8. Distinctive:

    Every ticket has exactly one entry.

    line 81
  9. Distinctive:

    Use a new module instead of forcing a ticket into the closest existing one.

    line 87
  10. Very specific:

    Only the first # heading counts as the title.

    line 117
  11. Very specific:

    Use facts when you need a compact table for a human decision:

    line 133
  12. Very specific:

    Commit ticket-index.toml together with every generated file.

    line 179
  13. Very specific:

    Before opening a PR, update the branch from its target branch and re-render the index.

    line 192
  14. Very specific:

    If a rebase stops with conflicts, resolve .tickets/*.md and ticket-index.toml first.

    line 193
  15. Very specific:

    If parent is in another module, the child becomes a root in its own module and is annotated with its parent.

    line 206
  16. Distinctive:

    Never copy one ticket into several modules to make a page look complete.

    line 220

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 copy

Readers 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

  1. 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's scripts/install.py performs this copy.
  2. Create ticket-index.toml at the repository root. /setup-ticket-workflow writes it, including the ticket contract and module list.
  3. Make sure ticket files follow the contract below.
  4. 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.
  • module is 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".
  • summary is 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 check

check 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 facts

2. 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 module array;
  • 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-id

3. Review only the delta

python .cursor/skills/ticket-index/scripts/ticket_index.py diff

diff 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 check

Commit 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 parent is 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

SituationConfiguration
A ticket serves several domainsmodule = ["primary", "secondary", ...]
Parent lives in another moduleKeep the child in its own module; no special config
Dependency or link crosses modulesKeep 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: check reports them as stale and render overwrites them.
  • Treating a team name (Team, TBD) as an owner: the overview lists such active tickets under "Missing owners".
  • Using links to express hierarchy: hierarchy comes only from parent.
  • Adding a ticket without a config entry: check fails and render refuses to write.
  • Re-reading the whole index after a small change: run diff and review the hunks.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.