krishpunjabi.com ~/skills

← all commands

/planner

/planner agents

Picks the next issue from a repo's board, applies the run's scope exclusions, decides whether to divide, rates its size, recommends a shape and model, and returns a ≤40-line kickoff brief. Read-only. Use when an orchestrator needs the next task briefed.

Install

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

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

Needs: divide, next, the guard-git hook (installed with it).

What it does

Picks the next single unit of work from the board and writes the kickoff brief.

  • Read-only: disallowedTools: Edit, Write, NotebookEdit; never creates issues.
  • maxTurns: 40.

How to invoke

Agent(subagent_type="planner", prompt=…)

You pass: - Repo path + scope contract (exclusions such as gated issues / people tasks / labels, ordering rule, lanes, shape).

  • Issues in flight.
  • Optional decisions (ask|assume).

How it works

  • Runs next.
  • Drops excluded items and wayfinder:* issues.
  • Picks exactly one task (with lanes:, one per lane whose head isn't in flight; swarm: one batch of trivial, file-disjoint items).
  • Uses divide to propose a split if it looks multi-session.
  • If nothing is left, says so and stops.

Design principles

  • Read-only by construction (disallowedTools), so it can only propose, never change the board.
  • Exactly one task per brief.
  • The ≤40-line cap keeps the brief cheap to pass verbatim to the next agent.

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

Use cases

  • Briefing the next issue for a meta-orchestrator loop.
  • Asking on your own "use the planner agent to brief the next issue" before starting work by hand.

Tips

  • Put gated issues, people tasks and labels to skip in the scope contract's exclude, or the planner may pick them.
  • A proposed split is only a proposal; create the issues yourself (or with divide).

Example

One issue through planner, manager and verifier, as an orchestrator (or you) calls them. The manager briefs and spawns its own implementer inside its turn, so only the manager's report comes back. You push and merge in between:

Agent(subagent_type="planner", prompt="~/code/myrepo; exclusions: label needs-design; order: priority label") (+7 lines)
Issue: #31 Add CSV export (checklist: 3 items) Key files: src/export.py, tests/test_export.py Constraints: none Branch: feat/issue-31-csv-export Gotchas: none Size, shape, model: small, pair, sonnet: narrow and well-specified Divide: no
Agent(subagent_type="manager", prompt="working directory: /home/you/code/_worktrees/myrepo-issue-31-csv-export; <the brief, verbatim>; prefix=feat; protected=main; max_rounds=3; never push or merge") (+7 lines)
Branch: feat/issue-31-csv-export, base 1a2b3c4, head 5d6e7f8 Commits: 5d6e7f8 feat: CSV export (#31) Tests: pytest, 118 passed; lint clean (run by me) Findings: none Rounds: 1 of 3 Unfinished: none Manual steps for caller: push, open the PR, merge
Bash(git push -u origin feat/issue-31-csv-export && gh pr create --fill) (+1 line)
https://github.com/you/myrepo/pull/44
Merged PR #44; saved the manager's report to skilleddocs/orchestrator/reports/.
Agent(subagent_type="verifier", prompt="skilleddocs/orchestrator/reports/<#31 report>; interview=park; review-done=yes") (+5 lines)
Verified by: 118 passed · CI run 9876543210 Findings: none Decided for you: none Manual steps for user: none 1. #28 Rework auth flow (unestimated, strong model: needs-design)

Prereqs

  • gh authenticated, plus the project scope for a kanban board (see kanban).
  • The next and divide skills installed.

You get back (≤40 lines)

  • Issue + acceptance checklist.
  • Key files.
  • Decisions/ADRs to respect.
  • Branch name <prefix>/issue-<n>-<kebab-title> (pair §2's rule, used verbatim downstream).
  • Gotchas.
  • Size (a size:* label wins).
  • Recommended shape and model (and why).
  • Divide yes/no + proposed split.
  • Assumptions needed (when decisions=assume).

Sample workflows

  • Run the backlog unattended
    you → lanes → you → meta-orchestrator → planner → manager → implementer → verifier → you → switch → remind → progress-report → you
    Install just this one: ./scripts/install-skills.sh --workflow unattended-backlog or .\scripts\install-skills.ps1 -Workflow unattended-backlog
  • Match each issue to a shape: swarm, pair or flat
    you → meta-orchestrator → planner → implementer → manager → verifier → you
    Install just this one: ./scripts/install-skills.sh --workflow orchestration-shapes or .\scripts\install-skills.ps1 -Workflow orchestration-shapes

Source

Use cases & tips from the community