planners

Tools for managing plain-text plans with a documented schema, CLI commands, and an installable skillstub. It is designed to automate the mechanical components of generating and updating plain-text plans with standardized frontmatter for a given project. To facilitate tracking and reviewing plans, it also automatically generates and maintains an index table of all existing plans and their statuses.

These tools can be used manually via CLI commands, but they are largely intended to be used in conjunction with a language model. To guide usage by a language model, it ships with built-in skills and rules that offer an opinionated approach to managing the full plan-file lifecycle and automating usage of this package. These skills and rules can be installed on your system via the CLI commands listed in the instructions below. Once installed, the rules will enforce conventions around how plan files are named, filled, and updated, and the skills will facilitate the addition, implementation, and closing out of plans, which includes the use of git branches and worktrees as specified by the user. While its core functionality and plan files are model-agnostic, some aspects of its built-in support (e.g., the skill files, rule files, and pre-commit validation hook) are currently only available for use with Claude Code.

Getting Started

planners is designed to run as a global uv tool, but you can also install it as a per-project dependency.

1. Install the CLI as a uv tool (once per machine), so planners is on your PATH:

   uv tool install planners
   

   Or (re)install from GitHub:

   uv tool install --force git+https://github.com/gitronald/planners.git
   

2. Install the global rules and skills — This installs a global Claude Code rule file and a skills stub: the actual skills are included within this package and are accessible via the CLI; the skills stub just tells the model how to access them and allows you to use the skills via slash commands.

   planners install
   

   This will:

   • (Re)generate the global ~/.claude/skills/planners/SKILL.md holder and ~/.claude/rules/planners.md convention rule, which can change as the package version advances.
   • Wire the planners-validate (pre-commit) and planners-index (post-merge) hooks into the project folder/repo's .pre-commit-config.yaml (registering them when pre-commit is available).
   • Give the generated index its merge semantics: a .planners/README.md merge=union line in the repo's .gitattributes, so a local merge whose two sides both added or closed plans stops conflicting on it. union is built into git, so the one committed line is the whole fix — nothing to configure per clone. GitHub's server-side merge does not apply it, so a PR can still report a conflict on the index; merging the base in locally then resolves it without hand-editing a generated file.

   planners install --check reports each part (the skill stub, the rule, and the .gitattributes line) and exits non-zero unless all are ok, plus a row per hook saying whether it is actually registered in this clone — registration is per-clone state that a fresh clone silently lacks, so it is reported rather than assumed. The hooks only fire once pre-commit is available: in a uv project, run uv add --dev pre-commit once, then re-run planners install.

   The install, check, and print commands (install, skill, rule, permissions) come from pkgskills, which planners declares itself to as a host.

3. Start planning — scaffold your first plan using the add command.

   This can be done within a Claude Code terminal via the installed /planners skill and its add subcommand:

   /planners add my first feature
   

   Or via the CLI directly in your preferred terminal:

   planners add my-first-feature --title "My first feature"
   

   Either case will create a new plan file (.planners/plans/000-my-first-feature/plan.md) and refresh the index (.planners/README.md), though using the skill may produce a slightly different filename.

Usage

planners add <slug> --title "<Title>"    # scaffold a new plan (--defer: stage it unnumbered)
planners finalize                        # number and commit the deferred batch, in one commit
planners activate <NNN>                  # flip a plan to active, fill branch:, log where the work is, and commit
planners set-pr <NNN> <url>              # record a plan's PR, log it, refresh the index, and commit
planners implemented <NNN>               # mark pushed work implemented, log it, and take the PR out of draft
planners finish <NNN>                    # after the merge: remove the worktree, pull, delete the branch, re-point hooks
planners retire <NNN>                    # close a plan as retired (--into <NNN>: where the work went)
planners add <slug> --parent <NNN> --nested   # scaffold a nested subplan under an umbrella
planners subplans <NNN>                  # list nested subplans; fail if the umbrella's table disagrees
planners review                          # report what changed around each open plan (-s all, --json); reads only
planners base                            # print the repo's mainline branch (--all: every one)
planners remote                          # classify origin (github, single-branch, other-forge, bare, none) and what changes
planners index .                         # regenerate .planners/README.md
planners validate                        # validate plan frontmatter (and that the index agrees; --no-index skips the index check; --json prints parsed records)
planners schema                          # show the plan metadata schema
planners skill <name>                    # print a bundled skill body
planners rule <name>                     # print a bundled convention rule body
planners install                         # install holder + rule + repo hook + merge attr (--local: per-repo)
planners permissions --level assist      # print an automation-level permission profile (--apply to write it)

Plan commits land on the mainline. add, finalize, and activate refuse to commit when HEAD is off it, so a plan is recorded on the mainline even if the feature branch never merges. The accepted set is dev (when that branch exists) plus the repo's default branch — planners base --all prints it. Detection reads git's current refs and goes inert rather than blocking a repo it can't resolve; --allow-branch overrides the refusal where the mainline isn't detectable by name.

Batch creation (--defer + finalize). A plain add numbers a plan as max(existing) + 1, so several adds running at once (e.g. parallel agents each drafting one plan of a split) can read the same max and collide on a number. Instead, have each creator run planners add <slug> --defer, which writes an unnumbered plan to its own directory under .planners/staging/ with no commit and no shared state. Once every creator is done, run planners finalize once: it orders the staged plans by created, assigns sequential numbers, moves them under plans/, refreshes the index, commits the batch (plan [add]: NNN-MMM (N plans)), and self-checks the result. --defer is for top-level plans only; subplans (--parent) are numbered against their umbrella and use a plain add.

Nested subplans. A plan that outgrows one file is split into an umbrella plan.md and one file per step under its own subplans/ directory (subplans/a-<step>.md, b-<step>.md, ...). Each subplan carries a small frontmatter of its own (status and branch, with pr, needs, and moved_to optional), and that frontmatter is the status of record: the umbrella's table is generated from it, between two marker comments. planners subplans <NNN> lists the subplans and exits non-zero when the table disagrees; --write regenerates the table's Status column and leaves the hand-written columns alone; --set <letter>=<status> changes one subplan and the table in the same step; --require-closed is the check an umbrella passes before it closes. Nested subplans stay out of the index and out of validate unless validate --subplans opts in. --parent without --nested still makes a lettered sibling plan (010a-<slug>/), for a step that needs a branch, PR, and lifecycle of its own.

Reviewing plans (review). planners review reports, for each open plan (active, implemented, draft, blocked; -s <status> or -s all for others, or one plan by number), the commits and tags since it was created or last reviewed, the backticked paths and module.function names it mentions and whether they still exist, the plans it names, and for an active, implemented, or blocked plan its branch, worktree, and PR state. A summary table by status opens the report. It never writes: the /planners review skill reads the evidence, gives each plan a verdict (still open, narrowed, accounted for, moot, unclear), and appends a Review: <verdict>. Log entry, which the next review uses as the start of its window. planners review --commit then commits those Log entries alone, on the mainline, and refuses active, implemented, or blocked plans, whose files a review never edits.

Per-repo (local) mode. To pin planners as a project dependency instead of a global tool, add it with uv add --dev planners and run everything as uv run planners …; then planners install --local writes the holder and rule into the repo's own .claude/ rather than ~/.claude/.

Plans

Each plan is a directory under .planners/plans/ ({NNN}-{slug}/plan.md) and can carry scoped sidecar files, and nested subplans under subplans/ once it is split. The generated .planners/README.md is the plans index, which GitHub auto-renders on folder browse.

Convention rule

planners install writes a version-stamped, auto-loaded ~/.claude/rules/planners.md (global) or .claude/rules/planners.md (per-repo). The rule is owned by the package — edit the convention in the package and reinstall; don't hand-edit the installed file. A hand-maintained plan-files.md is superseded by the generated planners.md (install reports it, and never deletes an unstamped one).

See CHANGELOG.md for release notes.