perk 1.0.1

Plan-oriented engineering workflow for Pi (the CLI exterior / session host).

perk

A Pi-native, plan-oriented engineering workflow — a Python perk CLI (the session exterior) plus a TypeScript Pi extension (the session interior).

Start at docs/user-docs/.

Originally based on prior art erk, by the team at dagster

What perk is

perk implements a plan-oriented engineering workflow (explore read-only → save a plan → implement on a branch → submit → land → learn) to Pi, split across two planes:

• the exterior — a Python perk CLI that scaffolds repos, positions worktrees, mints run ids, and launches primed pi sessions (everything that happens outside a session);
• the interior — a TypeScript Pi extension that drives stage transitions and state inside a running session.

A language-neutral shared/ contract (the stage registry + cross-plane specs) is the single source both planes read, so the two stay in lockstep without a codegen step.

perk is built to bootstrap its own development: each phase leaves perk capable of driving the next, and perk's own repo is the first thing it scaffolds.

Quickstart

perk targets any git repo. From the repo you want to wire:

uv tool install perk        # (or run from source — see Develop)
perk init                   # scaffold/converge Pi wiring (idempotent; safe to re-run)
perk doctor                 # report health; perk doctor --fix repairs drift

perk init requires a git repo + git, gh, node ≥ 22, ast-grep, and pi on PATH. GitHub auth is verified but never required (it is reported, never fatal).

For the guided first run, follow Get started with perk.

Documentation

The operator-facing docs live under docs/user-docs/, organized as the four Divio quadrants:

• Tutorials — learning-oriented lessons; start with Get started with perk.
• How-to guides — goal-oriented recipes (resume a plan, address review feedback, switch to Linear, attach a skill, …).
• Reference — the CLI surface, in-session commands & tools, the objective roadmap model, configuration, and providers & backends.
• Explanation — how perk thinks; headless/remote maturity.

perk's internal research and planning record lives under docs/ and is for perk's own developers.

Layout

• perk/ — the Python CLI (the session exterior).
• extension/ — the TypeScript Pi extension (the session interior).
• shared/ — cross-plane contracts (the stage registry + specs), bundled into both build artifacts.
• docs/ — research inputs, design notes, and durable learnings.

Develop

Two pinned toolchains:

• Python — uv (3.13, pinned in .python-version), ruff (lint/format), ty (types).
• TypeScript — npm (Node ≥ 22, .npmrc), Biome (lint/format), tsc (types).

With just:

just setup        # uv sync + npm install + git hooks + install-cli (the `perk` CLI on PATH)
just install-cli  # just the `perk` CLI on PATH (editable: tracks this clone)
just fmt          # ruff format + biome format
just lint         # ruff check + biome check
just typecheck    # ty + tsc
just test         # pytest + node:test (the regression gate)
just ci           # setup + lint + typecheck + test

After just setup (or just install-cli), call perk directly — no uv run. The install is editable, so a git pull reflects Python changes live; re-run just install-cli after a dependency change. It lands in uv's tool bin (~/.local/bin) — if perk isn't found, that dir is not on your PATH; run uv tool update-shell (then restart your shell). Remove it with uv tool uninstall perk.

Releasing perk → see docs/releasing.md (version SSOT, dual-plane runbook, the validate-release-versions tag gate).

just setup also runs just hooks (prek install), wiring a prek pre-commit hook that runs ruff check on staged Python (config in prek.toml; the ruff env is built by prek from the remote ruff-pre-commit repo, so it never depends on a system/.venv ruff). Re-run just hooks after a fresh clone.

Without just: uv run … for Python (uv run perk init, uv run pytest, uv run ruff check perk tests, uv run ty check) and npm run … for TypeScript (npm run lint, npm run typecheck).