plankit

overview

plankit preserves approved Claude Code plans, guards protected branches, and derives releases from commit messages. It ships as a Claude Code plugin. These skills are the documentation; pk help renders the same pages in a terminal.

Model

Claude plans the work. On approval, the preserve hook copies the plan, byte for byte, into the plans directory under a dated, sequenced filename. The protect hook denies edits there. The guard hook denies or questions git mutations on protected branches.

Per-repo footprint

A configured repository carries .pk.json, the committed policy: modes, protected branches, changelog sections, release hooks. Those commands run through sh -c, or cmd /c on Windows. Its .claude/settings.json carries the plankit marketplace under extraKnownMarketplaces and plankit@plankit under enabledPlugins, so a teammate who trusts the folder has the marketplace and is one /plugin install from the plugin; pk status spells out any entry that is missing. The plans directory appears when the first plan is preserved. Without .pk.json, every hook exits without acting.

Commit conventions

Work commits follow Conventional Commits: type(scope): subject. ! after the type or a BREAKING CHANGE: footer marks a breaking change. The type table is changelog.types in .pk.json; pk init writes the default table, listed under pk help changelog. pk changelog --dry-run previews how the current commits will land. Never add a breaking marker on your own judgment; see pk help guard, Breaking markers. The commits decide the version; --bump on the release commands is the developer's, see pk help ship, Deciding the version.

Commands

pk help prints the topic index. Each command's page is also a /plankit: shortcut in Claude Code.

Updating

/plugin marketplace update plankit, then /plugin update plankit@plankit, then /reload-plugins. A new release changes the plugin only; no repository changes. A pk installed with go install or Homebrew is updated separately, and the brief says when it is behind the plugin.

Cloud sessions

A cloud session at claude.ai/code starts from a fresh clone and never installs the plugins a repository enables, so plankit's hooks and skills are absent there unless the cloud environment installs the plugin. Give the environment a setup script:

#!/bin/bash
set -x
if command -v claude >/dev/null 2>&1; then
  claude plugin install plankit --marketplace https://plankit.com/marketplace.json --scope user \
    || echo "setup: plankit install failed" >&2
else
  echo "setup: claude CLI not on PATH during setup" >&2
fi

Every line is non-fatal: a non-zero exit stops the session starting. Under Network access, allow plankit.com, github.com and *.githubusercontent.com; the plugin archive is a GitHub release asset and downloads through a redirect to the last of those. The environment is set once per account, in the environment selector under the message box, and serves every repository that enables the plugin.

To confirm it took effect, ask a session in that environment to run pk status: pk is only present when the plugin installed, so the policy block printing is the proof. pk: command not found means the session is in an environment without the script; pick the right environment rather than installing pk by hand, which gives a session pk without the hooks. Tags are not part of the clone; pk changelog fetches them from origin when none are present.

Migrating from pre-plugin plankit (v0.x)

The plugin replaces the files pk setup copied into a repository. In a repository configured by a v0.x release:

  1. Remove the plankit hook entries (guard, protect, preserve, and the install-pk SessionStart entry) from .claude/settings.json. The plugin wires the same hooks, and leftover entries fire twice.
  2. Delete .claude/install-pk.sh, the copied .claude/skills/, and .claude/rules/plankit/.
  3. Keep .pk.json and the plans directory. The config schema is unchanged.

Windows without Git Bash

When Git for Windows is absent, Claude Code's shell tool is PowerShell, and the plugin's bin/ directory is not on its PATH. Invoke pk by its full path:

& "${CLAUDE_PLUGIN_ROOT}\bin\pk.cmd" status

Claude Code substitutes ${CLAUDE_PLUGIN_ROOT} when it loads this page. In a terminal, pk help shows the placeholder verbatim.