Keeping track

The words

• A Skill is a named set of instructions an agent loads to do one kind of job, like /to-spec.
• A Flow is a path through the Skills, like the main flow from idea to shipped code.
• A Spec describes one whole feature: the problem and the planned solution.
• A Ticket is one thin slice of a Spec, small enough to build in one fresh session.
• Both are Issues in an Issue tracker: the shared list where work is written down and marked done.

First, setup-matt-pocock-skills asks which tracker your repo uses and records it in docs/agents/issue-tracker.md. to-tickets and to-spec read it to know where to write.

Where Specs and Tickets live

On GitHub. Each Spec and Ticket is an Issue in the repo's GitHub Issues. The Skills reach them with gh, GitHub's command-line tool. Three GitHub features keep the work in order:

• Labels are tags on an Issue. ready-for-agent means the Issue is fully specified, so an agent can pick it up alone.
• Sub-issues hang one Issue under another. When to-tickets splits an existing Spec, each Ticket becomes its sub-issue, so you can see its Spec.
• Blocked-by links say which Tickets must be finished first. GitHub marks a blocked Issue with a "Blocked" icon.

In local files. With the local tracker, Issues are Markdown files under .scratch/. Each feature gets a folder, like .scratch/booking-api/. The Spec is spec.md in that folder. Each Ticket is its own numbered file in issues/, like issues/01-bookings-table.md, and its "Blocked by" line lists the Tickets that come first.

What the other files hold

• docs/agents/ holds the settings the Skills read: where the Issue tracker is (issue-tracker.md), what the labels are called (triage-labels.md), and where the domain docs live (domain.md).
• GLOSSARY.md holds the project's words: each term, what it means, and the words to avoid. Skills write Issue titles in these terms.
• docs/adr/ holds ADRs (architecture decision records): one short, numbered file per decision, saying what was decided and why.

A new repo may lack the last two. They're written as words and decisions get settled.

What's done, and what's next

On GitHub, done means closed. A finished Ticket's Issue is closed.

Next is any open Ticket whose blockers are all closed. Skills call this set the frontier: the Tickets you can start right now.

Say your FastAPI Spec, "Booking API", has two Tickets. #12 adds the bookings table. #13 adds the endpoint that creates a booking, and it's blocked by #12. While #12 is open, only #12 is on the frontier. Close #12, and #13 is next.

• Booking APIIts sub-issues show which Tickets are closed
  • #12 adds the bookings tabledone means closed (closed)
  • #13 adds the endpoint that creates a bookingthe frontier is where to go next (frontier)blocked by #12 adds the bookings table

When you're lost, open the Spec. Its sub-issues show which Tickets are closed, and the frontier is where to go next.