AI Project-Management Playbook

Each label's description on GitHub is the rule it enforces, written out — so the process is visible in the label picker rather than in a document nobody opens. The setup command writes these for you.

Plus GitHub's stock labels (bug, documentation, enhancement, …) and the surface:* labels, if the repo ships more than one thing.

Which labels can coexist

Four rules, enforced on every issue. They're what keep the two axes from blurring into each other, and they're why the roadmap can be computed instead of maintained.

• A milestone is a version — v0.3.0, v1.0.0. Never a theme, never a sprint.
• Putting an issue on one is the only thing that means “scheduled.” Nothing else signals it.
• Keep several open ahead of the current release, so scheduled work always has somewhere to go. 1.0 is a horizon, not a milestone, until its contents are real.
• Closing an issue is not shipping it. The code merges and the issue closes into its milestone; the roadmap keeps saying “pending release” until you cut the tag.

Paste this into every milestone description:

Issues close into this milestone until it is tagged; on the roadmap they read as “pending release” until the vX.Y.Z GitHub Release exists.

Release mechanics

• Conventional commits generate the changelog, and one changelog feeds both surfaces — the GitHub Release body and the website.
• The changelog and roadmap filter out everything that isn't the core product, so only core version work headlines a release.
• If you publish packages, dry-run the publish before you tag. Passing tests inside the repo don't prove an installed user can build.
• Refresh anything that reads “what's next” from the Releases API when the release finishes publishing, not when the tag is pushed — otherwise a just-tagged version shows up as still upcoming.

When green tests aren't enough

This applies to one specific kind of product: one that publishes packages its own output then depends on. A code generator whose emitted code imports your published runtime. A library whose examples install the library. A plugin host and its SDK package. If your project publishes nothing, skip this entirely.

No test suite catches this, because what's broken isn't the code — it's the relationship between your repo and the package registry, and the repo can't see the registry. The only proof is a clean-room run: from an empty directory, using the published tool, do exactly what a user does — install, scaffold, generate, build — and confirm every dependency resolves from the registry. Green tests have never shown this and never will.

Two ways to prevent it — pick one, and write it down

Either one works. Choosing neither doesn't. “We'll remember to publish before we tag” is not a mechanism — it's the exact thing that fails. Whichever you pick, write it into CONTRIBUTING.md so it outlives the person who picked it.

If you keep the gap off your main branch

• main holds released state. After a release it matches the tag, and it is always installable from source.
• develop is where the work integrates. It is allowed to depend on things you haven't published yet — that is its entire job.
• The release order is the whole point: publish the packages, then merge develop into main, then tag. Publishing after the merge puts the window right back.
• Run the clean-room check on main, not on develop. On the integration branch it would be red for an entire cycle, and a check that's always red is a check nobody reads.

So which branch does a docs or website change go to?

Not a question about which part of the product it belongs to. One question:

Does this change describe, use, or demonstrate something that isn't released yet?

Get this backwards and you publish documentation for a feature that doesn't exist yet — which is worse than having no page at all. It generates support load, and it makes your docs a liar at the exact moment someone is trusting them.

release-gate — the rung between closed and released

The ladder ends closed → released. The work that lives in that gap isn't feature work: publishing the packages, reconciling a version number, running the clean-room check, rotating a credential before it expires. Filed as ordinary tech-debt it looks like something you could put off, which is precisely backwards. The release-gate label names it, so “are we ready to ship?” is a search instead of a memory and the tag workflow has something mechanical to check. File one the moment you knowingly defer a release obligation — that's exactly when it's most likely to be forgotten, because everything still works on your machine.

And it carries a ledger of every versioned thing you ship

A release-gate issue that lists only the obligations somebody happened to notice is a checklist of remembered work — and the ones you miss are, by construction, the ones nobody wrote down. So the gate issue carries a table of every independently versioned thing in the project: every published package, every crate, every extension, every separately released binary. Not the ones you touched — all of them, each starting at “no change.” The table gets written when the milestone opens, before any work lands.

As work lands, its row gets updated in the same pass that lands it. That's the whole mechanism. Deciding “does this need a bump?” with the change in front of you is reliable; reconstructing it at tag time from a diff is not.

Which makes the whole gate issue four headings:

One integration branch, never one per version

Once you have an integration branch, the obvious next thought is a second one — v0.5-develop sitting alongside v0.4-develop, so next-cycle work has somewhere to go. Don't. There is exactly one integration branch, and its name never contains a version.

Keep the name version-free and the branch advances itself. develop just means “the cycle in flight,” so the moment you tag a release it becomes the next cycle — no rename, no new branch, no workflow to edit.

Keeping next-cycle work off that branch

The check reads the milestone rather than the branch name — the schedule already lives on the issue, so there's no reason to write it down again:

A pull request targeting the integration branch may not close an issue milestoned later than the cycle in flight.

Note the shape: it forbids future milestones rather than requiring the current one. That's what makes it usable without exceptions — untracked chores, CI fixes, and typo pull requests all pass, and they should, because work with no issue can't be next-cycle work. Next-cycle work is defined by carrying that milestone, so the milestone is the only thing the rule can fire on.

Never configure which cycle is in flight — derive it. It's the lowest open milestone by version order, so there's no constant to keep updated and nothing that can drift from the actual schedule. That has one prerequisite worth stating because it's easy to skip: closing the milestone has to be part of the release ritual, right next to publishing and tagging. Leave one open after its tag and the check freezes there and starts blocking legitimate next-cycle work — loudly, which is the right way for it to fail.

So where does next-cycle work live in the meantime? On its own branch off the integration branch, unmerged, carrying its real milestone. Rebase after the release merge and it lands normally. That's cheaper than a second integration branch, where you'd pay to forward-port every fix continuously instead of merging once at the end.

The two long-lived branches that are fine

Neither of these is a second release line, which is why they don't break the rule.

A release ships features, fixes, and performance work — things that turn into a binary somebody installs. An experiment is a spike to measure something, and what it delivers is a decision. So it runs alongside the release schedule, never inside it.

• An experiment never goes on a version milestone. Experiments run as an unscheduled research track, alongside the release work rather than inside it.
• What the experiment concludes may commit you to new feature work — and that feature, not the experiment, is what gets scheduled.
• Never build a release around what you hope an experiment will find. You can't schedule a feature the experiment hasn't yet decided should exist.
• The comparison has to be fair and like-for-like. A verdict from a rigged measurement is worse than no verdict, because you'll act on it.

A surfaceis one independently shippable face of the product — the core library, the editor extension, the marketing site — each with its own release cadence and its own tags. They're labels, and you only need them if the repo ships more than one thing. A single-artifact repo has one implicit surface and needs no labels at all.

Why “surface” and not “channel”: a release channel already means a stability stream — stable, beta, nightly. You can ship a beta of the extension, so the two ideas have to stay separable. And CI isn't a surface, because it ships nothing to anyone. The test is whether a user touches the thing.

An epicis an umbrella issue, and it's allowed to span several releases — don't force it to be small. Its children ship one at a time, each carrying its own milestone, and they're linked as real GitHub sub-issues so the progress bar rolls up on its own. Not checkboxes in the description, which drift. Not a custom field, which would be a third way of organizing work.

The roadmap is computed

A /roadmap page is generated from the two axes plus the sub-issue structure, never maintained by hand. Because of the label rules, every bucket is a single filter:

Nothing gets coded until two things exist, in this order: a design note, then an implementation plan. Both live as issues, never as files committed to the repo.

Designing and planning are separate jobs. Doing them one after the other, before any code, is what surfaces the problems while they're still cheap to fix.

Each step feeds the next, so nothing gets worked out twice. The design catches the conceptual problems, the plan catches the execution problems, and the failing tests pin down what you meant before any code exists to disagree with it.

Where the writing lives

The design note is the rfc issue, never a proposal file committed to the repo. The only design docs in the tree are durable architecture references for features that already shipped. When something ships, fold its lasting design into ARCHITECTURE.md and close the rfc.

Redoing a gate you already accepted

Gates get reopened. New information lands, a constraint turns out to be an artifact of an assumption, building the thing reveals the design was solving the wrong problem. Redoing a gate is healthy. What isn't healthy is what the issue body says while you redo it — so the moment you decide to redo an accepted gate, you purge the body, before any new thinking happens. What's left is a placeholder and nothing else.

> **Gate 1 is being redone (reopened YYYY-MM-DD).** The previously accepted
> design has been withdrawn and this body intentionally holds no design content.
> Do not plan against anything here. The live discussion is in the comments.

Stashing the old body to a scratch file while you work is fine, and often useful. Delete the stash once the new gate is accepted and the new body is written — a lingering copy of a withdrawn design is the same hazard, one directory over.

The body stays a placeholder for the whole redo. It gets repopulated only at acceptance, from the accepted outcome — never patched incrementally as the thinking evolves, which just recreates the half-superseded state the purge exists to prevent.

Reconcile the sources on both sides of every gate

Gates are exactly where a stale claim does the most damage, because each gate's output is the next gate's input — so a bad input doesn't get caught downstream, it gets built on. Which means a reconciliation pass on both sides of every gate, not just around work somebody judged non-trivial, and not just around implementation.

This is deliberately expensive, and it's still worth it: a reconciliation pass costs a bounded amount, once. Planning against a stale claim costs an unbounded amount, and you find out late.

These are the rules that keep the issues worth trusting.

The board is just saved searches

Its entire job is to give you the views below. Because of the label rules, each one is a trivial filter rather than a query you have to think about.

GitHub's Status field (Todo / In Progress / Done) stays as a light in-flight indicator. It is not a third way of organizing work.

Written down, this is prose in a context window — which is to say a suggestion. The rules above are already yes-or-no questions about labels and milestones, so they can be run instead of read. That turns them into a command that exits non-zero, and an agent corrects itself against a failing check far more reliably than against a paragraph it only half-loaded.

Why it isn't a normal dependency

Two payloads, going to two different places by two different routes.

The rules get copied into your repo rather than read out of node_modules, and that's deliberate: cloud agents, CI containers, and review sandboxes routinely have no node_modules at all; a committed file shows up in a pull request diff, so a change to the rules gets reviewed like anything else; and every agent harness can read a file in the repo, while none of them reliably resolve a package path mentioned in prose.

Copying costs you drift, so it's paid for with a manifest — the package version plus a hash of every file. The linter compares them and tells you to re-run setup when they've diverged. It's the lockfile idea applied to prose.

What lands in AGENTS.md is about twenty lines: a pointer to the vendored copy plus the label rules, never the whole doctrine. Always-loaded context is the scarcest thing in a repo, and spending hundreds of lines of it on project management would make the agent worse at everything else. The short stanza buys you the rest on demand. Setup can also write CLAUDE.md, .cursorrules, GEMINI.md, and the rest for whatever harnesses you already use, and re-running is safe — the stanza sits between markers, so your own writing is never touched.

The rules it checks

Everything above the line is one of the label rules from earlier, executed instead of described. The rest checks that the setup itself hasn't rotted.

The commands

Setup deliberately doesn't touch GitHub unless you ask it to. Creating labels changes state your whole team sees, and that should be a decision somebody made, not a side effect of installing a dependency.

The Claude Code plugin

The vendored copy already works in any harness that reads repo files — Claude Code, Cursor, Codex, Copilot, Gemini, Windsurf. The Claude Code plugin is optional, and what it adds is enforcement earlier in the loop.

/plugin marketplace add hoodiecollin/ai-pm-playbook
/plugin install pm-playbook@pm-playbook

The hook reads the command text and nothing else. That's on purpose: it catches what's self-evident in the command instantly and offline, and leaves anything that depends on repo state to the linter. A fast partial check beats a complete one that makes every command wait on the network. It also fails open on anything it can't parse — a hook that breaks your session is worse than no hook — and it never blocks the fix, because it only reads the flags that add things.

Versioning, and what happens when a label changes

The rules are versioned like code, because a change to them can turn issues you already have into violations.

Your labels live in your GitHub, not in the package — so a release that renames one can't fix itself. The setup command writes labels by name and would just add the new one next to the old, leaving every existing issue on the stale taxonomy. That's what the migration command is for, and it previews before it acts, because the three cases aren't equally reversible: if only the old label exists it renames in place and GitHub keeps every assignment; if both exist it has to relabel each issue and then delete the old one; and if only the new one exists it skips, so re-running is safe.

The first command is local — it copies the rules into your repo and wires up your agent instruction files. The second provisions GitHub: the labels with their descriptions, a starter milestone, and the filtered board views. Both are safe to re-run.

npx @hoodiecollin/pm-playbook init
npx @hoodiecollin/pm-playbook bootstrap \
  --repo <owner>/<name> --project <N> \
  --surfaces "core,ide-extension,website"

1. Run init. It copies the rules into your repo, adds the issue templates, and wires your agent instruction files. Commit what it writes — agents read it out of the repo, so it can't be gitignored.
2. Run bootstrap to provision GitHub: the labels with their descriptions, a starter milestone, and the filtered board views. It's safe to re-run.
3. Set the group-by on the release-spine, surface, and execution boards by hand — grouping is the one thing the API won't do.
4. Migrating an existing board? Delete the priority, size, and workstream fields, and every view that filtered or grouped by them.
5. Define your surface labels — but only if the repo ships more than one thing.
6. Seed the two roadmap docs, and write the model into CONTRIBUTING.md.
7. If your project publishes packages its own output depends on, decide now whether you publish as you go or keep the gap off your main branch. Write down the answer and which branch a pull request should target, and make the clean-room check required on the default branch. If you publish nothing, skip this.
8. Backfill: put the existing backlog on the ladder, assign milestones, and enforce the rules. A plan-next sitting next to a milestone is the number one sign of drift — check --all-states finds every violation at once.
9. Convert epic checklists into real sub-issues.
10. Wire the checks into CI, so the rules outlive whoever set them up: lint on pull requests, the release check before a tag, and the scope check on anything targeting the integration branch.

Wiring it into CI

This is the step that makes the rules stick — everything above is a convention until something exits non-zero.

# on pull requests — lint the backlog
- run: npx @hoodiecollin/pm-playbook check --repo ${{ github.repository }}

# before a tag — "can we actually release this?"
- run: npx @hoodiecollin/pm-playbook release-check ${{ github.ref_name }}

# on pull requests into the integration branch — keep next-cycle work out
- run: npx @hoodiecollin/pm-playbook scope-check ${{ github.event.pull_request.number }}

The issue templates