ticket-flow
Skill4 starsChanged 13 days agoMITView on GitHub
Run a project's work from GitHub Issues and a GitHub Projects board, trunk-based on main. Every change gets a ticket. An orchestrator session picks up to MAX_AGENTS (default 3) Ready tickets, hands each to a Sonnet subagent in its own worktree off main, then validates, fixes, merges and pushes the work itself. The board Status (Backlog → Ready → In progress → In review → Done) is updated at each step. Use when the user asks what's on the backlog, to pick, start or run tickets, to create, update, triage or close a ticket, to move a ticket on the board, or to "run the cycle"; and before making any code change in a project that uses this skill.
- Commits and pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- smg99/ticket-flowtheir own version, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- smg99/ticket-flow★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- security-guardrailsSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
The orchestrator never hands work back: If a subagent's work fails validation, the orchestrator fixes it, tests it and merges it.
- Very specific: line 63
Read its Blocked by #N lines.
- Distinctive: line 67
Run triage again after every merge, because a closed ticket may unblock others.
- Very specific: line 93
If the ticket can't be finished without the user, move it to Backlog with needs-decision, comment the question on the issue, remove the …
- Very specific: line 106
If --ff-only fails, main moved after your rebase: rebase again (step 4.1), re-run the checks, and retry.
- Very specific: line 130
Create a GitHub project board for the repo, then run .claude/skills/ticket-flow/scripts/board.sh init <project-number>.
≈ “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 Flow
GitHub Issues hold the backlog. A GitHub Projects (v2) board shows where each ticket is. Work lands straight on main: no feature branches and no PRs. One orchestrator session (usually Opus) owns the tracker, the git history and the quality bar. Sonnet subagents only write code.
Rules that always apply
- No change without a ticket. Before editing code, find the issue for the change or create one (see "Writing tickets"). This applies to small asks made in chat too. A fix that the orchestrator makes while validating a ticket belongs to that ticket. An unrelated problem gets its own new ticket.
- Only the orchestrator writes to the tracker. Subagents never create, edit, comment on, close or move tickets. With one writer, statuses can't race and nothing is moved twice.
- Never delete a ticket. To drop one, close it with a reason:
gh issue close N --reason "not planned", or close it as a duplicate with a comment naming the original. - Trunk-based. Nothing is ever pushed except
main. Worktrees are detached checkouts ofmain(see "Worktrees on main"). No branch is created, locally or on the remote. - The orchestrator never hands work back. If a subagent's work fails validation, the orchestrator fixes it, tests it and merges it. It does not resume, message or re-brief that subagent.
Board statuses
| Status | Meaning | Set by the orchestrator when |
| Backlog | Not workable yet: blocked by an open ticket, waiting on a decision (needs-decision label), or not triaged | the ticket is created and isn't Ready |
| Ready | Not blocked, no decision pending: can be picked | triage finds it unblocked with no needs-decision label |
| In progress | Picked; a subagent (or the orchestrator itself) is working on it | right before the subagent is launched |
| In review | The work is finished and waiting for the orchestrator to validate and merge it | the subagent returns (the orchestrator moves it at once) |
| Done | Merged to main and pushed; the issue is closed | after the push |
A ticket that turns out to need a decision while in progress goes back to Backlog, gets the needs-decision label and a comment stating the question, and the user is told.
Move statuses with scripts/board.sh (paths in this skill are relative to the skill folder):
S=.claude/skills/ticket-flow/scripts/board.sh
$S list # every ticket on the board with its status
$S list ready # only Ready tickets
$S add 12 ready # put issue #12 on the board in Ready
$S set 12 progress # backlog | ready | progress | review | done
$S init 5 # one-time setup of this repo for project board #5
$S check # verify config, auth and the board's Status options
$S setup # create missing Status options; keeps every card's statusThe cycle (orchestrator)
Run this when the user asks what's on the backlog, says to take tickets, or says to run the cycle. Keep cycling until nothing is Ready or the user says stop. After each cycle, give a short summary: the tickets merged, any new tickets, and anything waiting on the user.
1. Sync and triage
git checkout main && git pull --ff-only origin mainThen triage every open ticket that isn't In progress or In review:
- Read its
Blocked by #Nlines. It is blocked if any of those issues is still open. - It needs a decision if it has the
needs-decisionlabel. - Neither applies → set it to Ready. Otherwise → Backlog.
Run triage again after every merge, because a closed ticket may unblock others.
2. Pick up to MAX_AGENTS
Choose up to MAX_AGENTS Ready tickets (from .claude/ticket-flow.conf; 3 when it isn't set). Never run more subagents at once than that, counting ones still running from an earlier cycle. Take them in the order listed in tasks/plan.md if the project has one, otherwise oldest first. Avoid overlap: two tickets likely to edit the same files go in different cycles, so take fewer rather than set up a merge conflict. If nothing is Ready, say so, list what is blocked and which decisions are pending, and stop.
3. Start each ticket
For each picked ticket, in this order:
$S set N progress
git worktree add --detach .claude/worktrees/N mainThen launch one subagent per ticket with the Agent tool: model: "sonnet", all of them in one message so they run in parallel, in the background. Fill each one's prompt from references/subagent-brief.md, including the full ticket body and the absolute worktree path. Don't use the Agent tool's own isolation: "worktree" option, because it creates a branch. This skill creates the worktree itself.
4. When a subagent returns
Move the ticket at once: $S set N review. Then validate that ticket's worktree yourself. Don't trust the subagent's report on its own.
- Rebase onto the current main (another ticket may have merged first):
git -C .claude/worktrees/N rebase main. Resolve any conflicts yourself. - Review the diff against the ticket's acceptance criteria:
git -C .claude/worktrees/N diff main. Look for missing criteria, unrelated changes, and anything the subagent left unfinished or uncommitted. - Run the project's checks in the worktree: build, lint, typecheck and tests, plus each verification step in the ticket.
- Fix anything wrong yourself in that worktree, commit it with
(#N)in the message, and re-run the checks. Don't report back to the subagent.
If the ticket can't be finished without the user, move it to Backlog with needs-decision, comment the question on the issue, remove the worktree, and carry on with the other tickets.
5. Merge (one ticket at a time)
sha=$(git -C .claude/worktrees/N rev-parse HEAD)
git merge --ff-only "$sha" # in the main checkout
git push origin main
gh issue close N --reason completed --comment "Merged to main in $sha."
$S set N done
git worktree remove .claude/worktrees/NIf --ff-only fails, main moved after your rebase: rebase again (step 4.1), re-run the checks, and retry. Merge the next returned ticket only after this push. Then re-triage, and start the next cycle once every ticket in this one is Done or back in Backlog.
Small changes without subagents
For a quick change that the orchestrator makes itself: create or find the ticket, set it to In progress, work in the main checkout, run the checks, commit with (#N), push, close the issue, and set it to Done. Skip In review, since the session that wrote the code is the one validating it.
Worktrees on main
Git won't let two worktrees check out the same branch, so each ticket's worktree is a detached checkout of main's current commit. The subagent commits there on no branch at all. The orchestrator replays those commits onto the latest main (rebase main) and fast-forwards main to them. History stays linear, everything lands on main, and no branch ever exists. Worktrees live in .claude/worktrees/, which must be in .gitignore.
Writing tickets
Use references/ticket-template.md for every new ticket. One ticket = one change a subagent can finish and verify on its own. After creating it: $S add N backlog (or ready if it already passes triage). Write dependencies as Blocked by #N lines, one per line, because triage parses them. Use sub-issues for an epic's children if the project wants that grouping.
Creating a ticket while planning (e.g. with Addy Osmani's planning-and-task-breakdown) follows the same template. tasks/plan.md then lists only the issue links in order, never a duplicate checklist. Don't use tasks/todo.md or Addy's /build auto in a project that runs this cycle: the cycle replaces them. Their implementation skills (TDD, incremental implementation, code review) still apply inside each ticket.
Environments
- Local session with
gh(the normal case): everything above works. The board needs theprojecttoken scope, which you add withgh auth refresh -s project. - Cloud session (no working
gh, or no Projects access): read and write issues through the GitHub MCP tools instead ofgh issue. The board can't be reached there, so record the status as a label (status:backlog,status:ready,status:progress,status:review,status:done) and say so. The next local session runs$S sync, which moves each labelled ticket to that status on the board and removes the label.
Setup in a new project
- Copy this folder to
.claude/skills/ticket-flow/. The script needsgh(withgh auth refresh -s project) andjq. Create a GitHub project board for the repo, then run
.claude/skills/ticket-flow/scripts/board.sh init <project-number>. Add the owner as a second argument if the board belongs to someone other than the repo owner. It:- writes
.claude/ticket-flow.conf(OWNER, REPO, PROJECT); - creates the
needs-decisionlabel; - adds
.claude/worktrees/to.gitignore; - gives the board's Status field the options Backlog, Ready, In progress, In review, Done, keeping every card's status and removing default options (such as
Todo) that no card uses.
It's safe to run again.
- writes
- Point the project's
CLAUDE.mdat this skill ("Tasks: follow the ticket-flow skill"). - Optional: in the project's settings → Workflows, turn on Auto-add to project for the repo, with new items set to Backlog, so no issue is missed.
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.

