/divide kanban board

Install

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

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

Needs: next (installed with it).

What it does

Splits an issue (or a described task) that's too big for one session into two or more session-sized issues (each fits the ~75K-token smart zone and one PR).

• Links them from the parent.
• Puts them on the board.

When to use

• A task is clearly multi-session.
• Context is running low mid-task and the rest must be split off (the smartzone.py hook suggests this).
• The planner agent uses it to propose splits (it never creates them).

How to invoke

/divide <issue number or task description>. Claude can also run it itself.

How it works

1. Reads the target (gh issue view <n> or your description).
2. Target already fits one session? Says so and stops.
   • Otherwise proposes 2+ pieces (or uses your split) and shows it before creating anything.
   • If you revise the split, it shows it again.
3. On confirmation: gh issue create per piece ("Part of #n").
   • Adds a task-list checkbox per child to the parent's body. If the parent already uses sub-issues, it attaches each child as one instead.
   • Work an existing child covers is never re-split.
   • A free-text target has no parent issue, so "Part of", the checkboxes and the roadmap link are skipped.
4. Adds each child to the board.
   • Projects v2 → gh project item-add then gh project item-edit to set Status=Todo (item-add alone leaves Status empty).
   • Label fallback → status:todo (created first if missing).
5. If a roadmap doc links the parent, adds #n → #a, #b inline and commits only the roadmap file as docs: divide #n into #a/#b/#c… on the current branch.
   • On the default branch it branches first, reports the branch and SHA, asks whether to push and open a PR (never without your yes), then switches back.
6. If the parent is now only a tracker, says so and offers to close it once children land.

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

• Session-sized pieces. Each child gets a "done when", so one session can finish it and session-handoff can call it complete.
• Propose first, create on yes. The split is shown before any issue exists; the planner agent only ever proposes.
• Keep the trail. Children say "Part of #n", the parent gets a checkbox per child, and a roadmap that links the parent links the children too.

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

Use cases

• An issue that is clearly several sessions of work.
• Context running low mid-task: split off what's left as its own issue.
• The planner agent flagging an oversized issue during a meta-orchestrator run (proposal only; you create).

Tips

• Bring your own split ("divide 28 into the token model and the migration") if you already know the seams.
• Push back on the proposal before saying yes; nothing exists until you do.
• Once the parent only tracks children, accept the offer to close it after they land rather than leaving it in Todo.
• In a repo whose roadmap doc links the parent, it commits the roadmap edit (docs: divide #n into #a/#b/#c…, on a branch, not pushed).

Example

1. Auth token model: done when tokens are issued and validated, with tests.
2. Migrate sessions: done when live sessions convert to tokens on next request.
3. Remove old middleware: done when the session middleware is deleted and CI is green.
Create these 3 issues?

Related

• Preloaded by the planner agent (proposal only).
• consult-plan adds its new issues to the board the same way.

Prereqs

• gh, authenticated, origin on GitHub (otherwise it stops and says so).
• On a fork it asks which repo to write to. If the fork has issues turned off (GitHub's default), it reads issues from the parent.
• Projects v2 boards need the project OAuth scope: run gh auth refresh -s project -s read:project once (see kanban/README.md).

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
• Turn a gap scan into planned work
  gap-scan → you → grill-docs → you → divide → you
  Install just this one: ./scripts/install-skills.sh --workflow gaps-to-issues or .\scripts\install-skills.ps1 -Workflow gaps-to-issues
• Plan an effort too big for one session
  you → wayfinder → grill-docs → you → divide → you → meta-orchestrator
  Install just this one: ./scripts/install-skills.sh --workflow big-effort or .\scripts\install-skills.ps1 -Workflow big-effort
• Wrap up a long session
  smartzone → divide → you → session-handoff → you
  Install just this one: ./scripts/install-skills.sh --workflow wrap-up-long-session or .\scripts\install-skills.ps1 -Workflow wrap-up-long-session

Source

• kanban/divide/SKILL.md
• kanban/divide/README.md