overview

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From markwharton/plankit, MIT.

More from markwharton/plankit