planr

Trunk-based, markdown-formatted backlog CLI for solo and concurrent development. Provides automated backlog management: ticket creation, branch claiming, structural linting, board summaries, review briefs, and merge gating.

Installation

From source

cargo install --git https://github.com/unprofessor/planr-rs.git
# or
git clone https://github.com/unprofessor/planr-rs.git
cargo install --path planr-rs
# or
git clone https://github.com/unprofessor/planr-rs.git
cd planr-rs
cargo build --release
cp target/release/planr ~/.local/bin/

Prebuilt binaries

Available on the GitHub Releases page — download the archive for your platform and extract the planr binary into your $PATH.

Dependencies

• Rust (1.70+, ideally the latest stable) for source builds.
• git (any modern version) — all planr commands shell out to git.
• flock (util-linux) is not required — the Rust binary uses in-process flock via the fs2 crate on <git-common-dir>/planr.lock. During transition, the lock file is shared with the legacy TS/bash planr tooling.

Binary size

A release build with LTO and symbol stripping is approximately 2.8 MB (stripped). Build with:

cargo build --release
ls -lh target/release/planr

Usage

planr new <kind> <slug> <title> [parent]     # Scaffold a ticket file
planr board                                    # Backlog + in-flight board
planr lint [ref]                               # Structural checks (working tree or ref)
planr claim <slug> [worktree]                  # Create worktree, set in_progress
planr review <slug>                            # Brief a reviewer
planr abandon <kind> <slug> --reason <reason>  # Mark OBE/won't-do, skip review
planr close task <slug>                        # Gate check -> done -> merge
planr close story <slug>                       # Gate children -> done -> commit
planr close epic <slug>                        # Gate stories -> done -> commit
planr --version                                # Print build-time git-derived version
planr --help                                   # Full help

Subcommand details

Environment variables

Abandoning a ticket

Use the separate abandon command when a ticket is overtaken by events (OBE) or intentionally will not be done:

planr abandon task obsolete-task --reason obe
planr abandon story postponed-story --reason wont-do

The command writes status: abandoned, reason: obe or reason: wont-do, and a refreshed updated date into the ticket, then commits on trunk. It does not require a worker validation or review verdict. An existing plan/<slug> branch is treated as active work: abandon refuses and leaves the branch and worktree untouched, so cleanup is an explicit human decision.

An abandoned ticket does not satisfy depends_on; only status: done unblocks a dependency. Update the dependency relationship or abandon the dependent ticket separately.

Versioning

planr embeds its version at build time from git describe via the semvertag-shell crate. The version follows SemVer monotonic ordering:

CI runs cargo-semvertag check on every push and PR to validate that the Cargo.toml version is a legal successor to the latest git tag — preventing version regressions and missed bumps.

Compatibility

planr uses in-process flock via the fs2 crate, locking the same file (<git-common-dir>/planr.lock) that the legacy TS/bash planr tooling locks via flock(1). This means Rust and TS planr commands can run concurrently on the same repository during transition — they serialize on the same kernel lock.

All ticket files are standard Markdown with YAML frontmatter. The format is identical to what the TS tooling produces and consumes.

Repository layout

.plan/                 # Backlog tracked as ticket files
  epics/               # Epic tickets
  stories/             # Story tickets
  tasks/               # Task tickets
src/                   # Rust source
  main.rs              # CLI entry point (clap)
  parse.rs             # Frontmatter parsing
  ticket.rs            # Ticket types
  git.rs               # Git porcelain wrappers
  lock.rs              # In-process flock guard
  lint.rs              # Three-pass lint engine
  board.rs             # Board renderer
  review.rs            # Review brief generator
  new_cmd.rs           # Ticket creation
  claim.rs             # Claim workflow
  abandon.rs           # Abandon workflow (OBE/won't-do)
  close_cmd.rs         # Close workflow (task/story/epic)
templates/             # Embedded ticket templates
tests/                 # Integration tests
  planr-e2e.rs         # End-to-end suite

Development

cargo test              # Run all tests (unit + e2e)
cargo build             # Debug build
cargo build --release   # Release build with LTO

All commands run against a repository with a .plan/ directory. See the existing backlog in .plan/ for examples.