Owner's guide

GitHub issue process

Every piece of work is a GitHub issue, and the board of issues is the single record of what's happening, what's next, and what's waiting on you. This is how that board works.

IssuesWork becomes an issue the moment it's worth doing

An issue is one unit of tracked work. The moment something is worth doing, it becomes one, so it outlasts the chat that raised it and the session that forgets it. A task exists as an issue, not as a line in a conversation.

The rule underneath everything here: if it matters, it's an issue. A plan in a chat is not tracked. A plan on the board is.

UmbrellasAn umbrella issue states the idea, and its sub-issues are the pieces

A feature or a project starts as an umbrella issue that states the idea in your words. Its work items are sub-issues underneath it. A large effort gets one place on the board instead of scattering across it.

Parking an umbrella parks the whole subtree. Its children get unassigned, and any question they were waiting on you for is suspended, until you reactivate it. The first thing on reactivation is re-checking those children against whatever changed while it was parked.

The boardThe assignee is the state

You read the board by who each issue is assigned to. That one field is the state, so you read it at a glance.

You Blocked on you. Your Claude needs an answer, a decision, or an account action only you can give, and work stops until you reply. Everything with your name on it is your queue.
Your Claude Being worked right now. It claimed the issue, with a comment, before touching the code.
Unassigned Queued and ready, or deliberately parked. It has no owner yet.

The app draws the same board for you on its Development page, one lane per state: Building now, Waiting on you, Queued. Each row names the issue and how long it has stood.

LabelsTwo labels cover what the assignee can't show

The assignee shows most of the state, so labels stay rare. Two exist, each for a state the assignee can't express.

soft-block

Your Claude is proceeding, and your input would steer or redirect it. Safe to ignore, better if you weigh in. The issue stays with your Claude while a decision is still open, and the assignee can't show that. The label is the only place the fact fits.

deferred

You parked it. A parked issue and a ready one are both unassigned, so the label is what tells them apart.

A hard block never gets a label. Your name as assignee already says it, and a label that only repeats the assignee is noise.

DependenciesA prerequisite is a link, not a sentence

When one issue must finish before another can start, record it as a blocked-by link between them. The link shows on both issues and answers "what's ready to begin" when you plan. A note in the body is for a reader. The link is what a planning pass can query.

Two modesYou drive the board two ways: plan, or execute

The two have different authority. One reorders the work. The other does it.

Review the board and tell me the plan.Your Claude rereads every open issue for currency, answers your comments, assigns you anything only you can unblock, and hands you the order it means to work in. It changes the board, not the code.
Work through everything you can.Your Claude works that queue in order: claim an issue, build it, ship it, close it with a plain-language comment, take the next. It keeps going until every remaining issue is blocked on you, soft-blocked with the question posted, or deferred.

CommentsYour comments outrank everything

Before any new work, a session sweeps your recent replies and answers them. A question you left on an issue is the first thing it handles, ahead of the queue. Your word on the board redirects the work, the same as a rule change.

An issue reads on its own months later. It leads with what you asked and why, in your words, then the context a stranger would need, then the mechanical detail. An issue that only makes sense next to the chat that created it is written wrong.