/kanban-setup kanban board

Install

Install just this, from a clone of the repo. Anything it needs comes with it.

./scripts/install-skills.sh --skill kanban-setup   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill kanban-setup   # Windows PowerShell

Needs: next (installed with it).

What it does

Creates a GitHub Projects (v2) board for a repo if it has none, then backfills issues from work already documented in the repo: planned work, already-done work (created and immediately closed, for history), or both.

When to use

• A repo has no board yet (next tells you to run this).
• You want issue history backfilled from docs, TODOs, CHANGELOG or git log.

How to invoke

/kanban-setup [current | retroactive | both]

Default current. Only you can run it (disable-model-invocation: true), because it creates real, visible issues.

How it works

1. Prereq: gh auth status must list the project scope.
   • Otherwise offers gh auth refresh -s project -s read:project (you run it) or label mode.
   • Stops until you pick.
2. Board (read-only until you say yes): looks for <repo> Board as described in next's BOARD.md. If the board exists, it checks its Status field (gh project field-list) for an "In Review" option; the default field only has Todo/In Progress/Done.
   • Nothing is created in this step.
   • Label mode (four status:* labels instead of a board) is used when you ask for it, the project scope isn't granted, or the owner can't create projects.
3. Scan: README "Roadmap"/"TODO" sections, TODO/FIXME comments, CHANGELOG.md, docs/ and plan-like docs; skips skilleddocs/, node_modules, .venv and vendored dirs.
4. Candidates per mode:
   • Both modes drop items that already have an issue (open or closed).
   • current = undone items.
   • retroactive = finished items from CHANGELOG / git log / resolved TODOs.
   • both = both, separated.
5. Preview, then create: shows the board actions and every issue (title, mode, target column), then waits.
   • The board actions are: create the board; gh project link <n> --owner <owner> --repo <owner>/<repo>; add In Review; or, in label mode, create the labels.
   • To add In Review it runs the updateProjectV2Field GraphQL mutation via gh api graphql, replaying every existing option plus the new one (gh can't add an option to an existing field). You can add it by hand in the UI instead.
   • On yes: board actions first.
   • Then current → create + item-add + item-edit to Todo.
   • retroactive → create, close, item-add + item-edit to Done (item-add alone leaves Status empty, so the item-edit step is required, not optional).
   • Label mode: each issue is created with status:todo, or status:done and closed.

Flow

Card status flow: todo → in-progress → in-review → done.

• todo: set explicitly by gh project item-edit when an issue is added — item-add alone leaves Status empty.
• in-progress: set by pair or meta-orchestrator when they create the branch (their guarded agents can only read with gh).
• in-review: set by session-handoff.
• done: set by update-progress, once verified and merged; unmerged stays in-review.
• Label-mode status:* labels are created on first use (gh label create --color <hex> --force, colors in next/BOARD.md), not assumed to exist.

Design principles

• Real issues, so preview first. Issues it creates are public; every one is shown (title, mode, target column) before anything is created.
• Idempotent board, nothing before the yes. It looks for this repo's board, links a new one to the repo, and adds the In Review option only when missing; all of it is previewed and runs after your yes.
• Backfill from what's documented. Candidates come from the repo's own docs, TODOs, CHANGELOG and (retroactive) git log, deduped against existing issues.

Shared context for these principles: Matt Pocock's video.

Use cases

• Starting the kanban loop on a repo with no board, when next says to run this.
• Turning a README roadmap or TODO/FIXME comments into issues.
• Giving a project a clean issue history from its CHANGELOG (retroactive, created and closed in Done).
• Adding the missing In Review column to an existing board.

Tips

• Refresh the project scope before starting; it stops until you have.
• Default mode is current; pass retroactive or both for history.
• Prune the preview before you say yes: anything you leave in becomes a real issue.
• If you'd rather not run the GraphQL mutation for In Review, add the option by hand in the GitHub UI (IN-REVIEW-OPTION.md).

Example

Related

• next reads the board it creates.
• Needs gh with the project scope.

Prereqs

• gh, authenticated, origin on GitHub (otherwise it stops and says so).
• The project OAuth scope is needed for a Projects v2 board: run gh auth refresh -s project -s read:project once (see kanban/README.md).
• It checks for the scope itself and stops if missing.

Sample workflows

• Bootstrap a board from the docs
  you → kanban-setup → you → divide → you → next → find-me-a-skill → you
  Install just this one: ./scripts/install-skills.sh --workflow new-board or .\scripts\install-skills.ps1 -Workflow new-board

Source

• kanban/kanban-setup/SKILL.md
• kanban/kanban-setup/README.md