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.

The three individual rule packs — force-push-strict, no-amend, and draft-prs-only — each address a distinct failure mode. When combined they encode a coherent team discipline: history is append-only, code review is gated by the human, and the agent can never accidentally publish work before it’s been looked at. The combined-git-discipline pack bundles all three into a single config that works as a drop-in starting point. The pack also preserves pi-steering’s built-in default rules (no-hard-reset, no-rm-rf-slash, no-long-running-commands). Only the default no-force-push is disabled — replaced by the stricter no-force-push-strict variant.

​
Configuration

import { defineConfig } from "pi-steering";

export default defineConfig({
  // Disable the shipped default so its less-strict reason message
  // ("--force-with-lease is fine") doesn't leak alongside the strict
  // variant. The other default rules stay active.
  disabledRules: ["no-force-push"],
  rules: [
    {
      name: "no-force-push-strict",
      tool: "bash",
      field: "command",
      pattern:
        "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+push\\b.*(?:--force\\b|\\s-f(?:\\s|$))",
      reason:
        "No force pushes of any kind, including --force-with-lease.",
    },
    {
      name: "no-amend",
      tool: "bash",
      field: "command",
      pattern:
        "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b.*--amend\\b",
      reason:
        "Don't rewrite history with --amend. Create a new commit instead.",
    },
    {
      name: "pr-create-must-be-draft",
      tool: "bash",
      field: "command",
      pattern: "^gh\\s+pr\\s+create\\b",
      unless: "--draft\\b",
      reason:
        "PRs must be created as drafts. Mark ready for review only after human approval.",
    },
  ],
});

​
What each rule enforces

no-force-push-strict — Blocks every form of git push --force, including --force-with-lease. This is a strict superset of the built-in no-force-push rule, which allows the lease variant. See Force Push Strict for the full pattern breakdown and adversarial matrix. no-amend — Blocks git commit --amend in any invocation form, including those with git pre-subcommand flags (git -C /path commit --amend). Prevents the agent from rewriting commit SHAs, which breaks per-line comment anchors in code review tools. See No Amend for the rationale and the cwd-scoped variant. pr-create-must-be-draft — Blocks gh pr create unless --draft is present. The unless mechanism short-circuits the rule when the safe flag is found, so gh pr create --draft ... is allowed without needing a second exemption pattern. See Draft PRs Only for details on the unless mechanism.

​
Active defaults (not disabled)

The pack leaves pi-steering’s other default rules untouched:
RuleWhat it blocks
no-hard-resetgit reset --hard — prevents silent loss of uncommitted work
no-rm-rf-slashrm -rf / with any flag combination or wrapper — noOverride: true
no-long-running-commandsnpm run dev, tsc --watch, next dev, and similar watchers that block the agent

​
Customising individual rules

The combined config is a starting point, not a final answer. Because all three rules are plain objects in the rules array, you can tune any of them inline: Change a reason message: 
{
  name: "no-amend",
  // ...pattern unchanged...
  reason: "History is append-only in this repo. Open a follow-up commit.",
},
Scope a rule to a specific directory tree: 
{
  name: "no-amend",
  // ...pattern unchanged...
  when: { cwd: "^/home/[^/]+/projects/regulated/" },
  reason: "Regulated subtrees enforce linear history.",
},
Disable one rule from the bundle without touching the others: 
export default defineConfig({
  disabledRules: ["no-force-push", "no-amend"], // drop no-amend too
  rules: [
    // no-force-push-strict and pr-create-must-be-draft only
    { name: "no-force-push-strict", ... },
    { name: "pr-create-must-be-draft", ... },
  ],
});

​
Install

cp examples/combined-git-discipline/steering.ts .pi/steering/index.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us