@aprimediet/git-workflow

Branching strategy enforcer + safe git commands for the pi coding agent.

This extension enforces a branching strategy (gitflow / github-flow / gitlab-flow / trunk-based) at project init time, persists the choice to ~/.pi/projects/<project-id>/git-workflow.json, and provides 15 slash commands that wrap every common git workflow with explicit user confirmation.

The agent is never allowed to run git commit, git push, git tag -m, gh pr create/merge, or glab mr create/merge without asking first. Suggest /git:commit, /git:push, etc. instead.

Install

pi install @aprimediet/git-workflow

Setup

On first pi startup inside a git repo, you'll be prompted to pick a branching strategy. The choice persists to ~/.pi/projects/<project-id>/git-workflow.json (NOT in the repo) so it survives git clean and cross-machine clones.

To re-pick later:

/git:init

Commands

Core

Command	What it does
/git:init	Pick a branching strategy, create base branches, write config.
/git:commit	Detect changes, suggest a conventional-commit message, commit on approval.
/git:worktree	Suggest a worktree pattern based on current branch + strategy, create it.
/git:push	Push current branch to origin (with -u first time).

Extras

Command	What it does
/git:pr	Open a pull request / merge request via gh or glab.
/git:merge <src>	Merge <src> into current branch with strategy-aware flags.
/git:rebase <base>	Rebase current branch onto <base> (refuses if dirty).
/git:log [filters]	Pretty git log with --since, --author, -- path filters.
/git:stash [name]	Stash changes with a strategy-aware name.
/git:diff [args]	Show diff with optional ref/path filters.
/git:tag vX.Y.Z [-m msg]	Create annotated SemVer tag; ask to push.
/git:reset <mode> <target>	Soft/mixed/hard reset with mandatory backup branch.
/git:branch list|create|delete	Branch management with strategy validation.
/git:status	Compact 4-line status summary.
/git:changelog [ref]	Generate grouped Markdown changelog since <ref>.

Branching strategies

Strategy	Branches
gitflow	master, dev, features/*, release/*, hotfix/*, bugfix/*
github-flow	master, features/*, bugfix/*
gitlab-flow	master, staging, production, features/*, hotfix/*
trunk-based	main, features/*, release/*

Each strategy ships as an agentskills.io-compliant skill that the agent loads when it sees matching work.

Safety gates

The extension wires five lifecycle hooks:

1. G1 — session_start: if the project has git but no config, prompts to initialize.
2. G2 — before_agent_start: injects a "Git Workflow Safety Policy" + active-strategy reminder into the system prompt so the agent knows to suggest slash commands instead of running git directly.
3. G3 — tool_call: blocks git commit, git push, git tag -m, gh pr create/merge, glab mr create/merge unless explicitly confirmed by the user. Slash-command handlers bypass via a sentinel flag.
4. G4 — agent_end: after each turn, if the working tree is dirty, asks "Commit now?" and suggests /git:commit (never auto-executes).
5. G5 — tool_call: detects git checkout -b / git switch -c for branches outside the configured strategy and asks the user to either cancel, create anyway, or update the strategy.

Memory integration

This extension does not depend on @aprimediet/memory. If you have it installed and want git-related events persisted to memory (strategy decisions, commits, pushes, tag, PR), configure your memory extension to capture these events via its own means — e.g. a session-end hook that parses the current branch + last commit and writes a memory entry.

File layout

~/.pi/projects/<project-id>/
└── git-workflow.json          # persisted config (strategy, branches, preferences)

Publishing

This package is published under the @aprimediet npm scope. To publish a new version:

cd extensions/git-workflow
# bump version in package.json
npm run pack:dry
npm publish --access public --userconfig /tmp/npmrc

See ../../prompts/git-workflow.md for the full build prompt and specification.

License

MIT © aprimediet