Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cad0p/pi-steering-hooks/llms.txt

Use this file to discover all available pages before exploring further.

Plugins are the primary composition unit in pi-steering. Each plugin is a named bundle of predicates, rules, observers, and trackers that ships as a versioned npm package. When a user adds a plugin to their plugins: [...] array, they get every surface the plugin registers — new when.<key> slots for rules, built-in rules that run immediately, observer hooks that track session history, and walker-level tracker state that follows bash chains command-by-command.

Git Plugin

Branch-aware predicates (branch, upstream, commitsAhead, hasStagedChanges, isClean, remote) plus the no-main-commit and no-main-commit-github rules. Default-on in every config.

Flags Plugin

requiresFlag and allowlistedFlagsOnly predicates for enforcing CLI flag discipline — require a flag be present, or restrict which flags may appear at all.

Commit Format Plugin

commitFormat predicate that validates git commit -m messages against Conventional Commits 1.0.0 or JIRA-style bracket references.

Authoring Plugins

Write and publish your own plugin. Covers the canonical file layout, typed predicate handlers, observer encapsulation, and ecosystem conventions.

​
Registering plugins

Import each plugin and pass it to defineConfig under the plugins key. The explicit import is what gives defineConfig’s generics the rule and plugin name unions for typo-checking — DEFAULT_PLUGINS gives runtime registration but doesn’t extend inference. 
import { defineConfig } from "pi-steering";
import gitPlugin from "pi-steering/plugins/git";
import flagsPlugin from "pi-steering-flags";

export default defineConfig({
  plugins: [gitPlugin, flagsPlugin],
  rules: [ /* your rules */ ],
});
Once a plugin is registered, its predicate keys become available in the when: clause of any rule in the same config. A typo on a predicate name, rule name, or plugin name is a compile-time error caught by tsc --noEmit.

​
Ecosystem discovery

Tag your plugin’s package.json with both ecosystem keywords so it surfaces in pi’s extension directory and in pi-steering’s plugin listings: 
{
  "keywords": [
    "pi-package",
    "pi-steering-package"
  ]
}
pi-package is pi’s ecosystem-wide convention — it surfaces your package alongside every other pi extension. pi-steering-package is the pi-steering-specific tag that will surface your plugin in the steering plugin directory (once one exists) without needing a manual registry entry.

​
Naming convention

Unscoped plugin packages follow the pi-steering-<domain> pattern, mirroring the core package name. The two built-in external plugins — pi-steering-flags and pi-steering-commit-format — establish this precedent. Scoped names (@org/pi-steering-<x>) are fine for internal or proprietary packages.

​
Peer range during v0.x

During the v0.x release window, pin tightly to the current release train: 
{
  "peerDependencies": {
    "pi-steering": "^0.1.0"
  }
}
Once pi-steering reaches v1, switch to a major-only range ("^1"). The tight v0.x pin is intentional — the plugin API shape can change between minor versions during the pre-stable window and a loose range risks loading an incompatible engine.

Build docs developers (and LLMs) love

Get started for freeTalk to us