conventional-commit

Disciplined Git workflow for Claude Code: Conventional Commits, atomic commits, typed branches, and linear history via rebase merge. Provides three skills that guide Claude through a strict commit/push/PR workflow instead of letting it improvise.

Install

Assuming you've already added the marketplace:

/plugin install conventional-commit@claudiomaradonna

Skills

• /commit — local-only: stage and commit on a typed branch off an up-to-date base.
• /push — publish: resolve the remote, confirm, push. Stops after the push; hands off to /pr.
• /pr — open a pull/merge request: detect the provider, refuse to duplicate an existing PR, compose a Conventional-Commits-aligned title and motivation-focused body, and open via gh / glab / tea (or hand back a compare URL).

/commit workflow

1. Pre-flight — resolve the base remote (no hardcoded origin); then in parallel: git status, current branch, recent log, git fetch <base-remote>. If commit signing is enabled, also verify the configured key is usable before staging — try SSH-agent recovery first, then stop and ask the user (stop / fix / authorize unsigned for this single commit) rather than silently bypassing with -c commit.gpgsign=false.
2. Branch setup — never commit on main/master; create a typed branch off an up-to-date base, or confirm the current dedicated branch is the right place.
3. Branch naming — <type>/<short-kebab-description> where <type> is one of: feat, fix, sec, chore, docs, refactor, test, perf, ci, build.
4. Atomic grouping — propose a commit-by-commit split where each commit is a single logical, revertible unit; show the plan before staging.
5. Conventional Commits — <type>(<scope>): <description> with a mandatory body explaining why (unless the change is trivially obvious). Breaking changes use ! plus a BREAKING CHANGE: footer.
6. Stage & commit — explicit staging (no git add -A/git add .); when a single file's changes span multiple commits, split at hunk granularity via a patch-file flow rather than restructuring files.
7. Handoff — list the commits, point the user at /push to publish and then /pr to open a PR/MR. /commit never pushes and never opens a PR.

/push workflow

1. Resolve the remote — upstream of the current branch first; otherwise the single remote, or ask the user when there are several. Never assume origin.
2. Confirm and push — show branch, target remote, commits to publish, and ask before pushing. Push with -u if no upstream is set.
3. Handoff — list the commits just published, print a courtesy compare URL when the host matches a well-known pattern, and point the user at /pr to open a PR/MR. /push never opens a PR.

/pr workflow

1. Pre-flight — branch must have an upstream, exist on the remote, and have commits ahead of the base. If the branch was never pushed (or local is ahead), /pr refuses and points at /push rather than auto-pushing.
2. Detect the provider — parse the remote URL: GitHub → gh, GitLab → glab, Gitea/Forgejo → tea, Bitbucket / unknown → manual. Covers self-hosted via existing CLI logins or env vars (GITEA_SERVER_URL+GITEA_SERVER_TOKEN, GH_HOST+GH_TOKEN, GITLAB_HOST+GITLAB_TOKEN).
3. Check for an existing PR/MR — if one is already open for the branch, surface its URL and stop instead of creating a duplicate.
4. Offer the PR/MR — ask explicitly before opening one. If the user prefers to do it manually, or no CLI is available, hand back a ready-to-click compare URL plus a suggested title and body. PR body always states merge with rebase.

Safety rules built in

• /commit never pushes. /push never pushes without explicit user "yes" and never opens PRs. /pr never opens a PR/MR without explicit user "yes".
• Never --no-verify, never blind --force / --force-with-lease, never git add -A.
• Never silently disable commit signing — if the configured key (SSH/GPG/x509) isn't usable, recover when possible, otherwise stop and let the user choose; -c commit.gpgsign=false is per-commit and only on explicit user authorization.
• Pre-commit / pre-push hook failure → fix and create a new commit, never bypass.
• Base branch behind its remote → rebase, never merge.
• Warn on staged files that look like secrets (.env, credentials.*, private keys).
• Never assume the remote is origin; never assume the provider is GitHub.

Multi-branch changes

Handled interactively: when a change legitimately belongs on more than one branch, Claude asks the user whether to cherry-pick, split, or defer rather than picking a strategy on its own.

Optional: claude-jail companion image

If you run Claude inside claude-jail and want /pr to open PRs/MRs natively (instead of returning a compare URL), this plugin ships a Dockerfile at claude-jail/Dockerfile that layers gh / glab / tea on top of the claude-code image. All three blocks are commented out by default — uncomment only the providers you use, then build and run via --image:

podman build -t claude-code-pr -f claude-jail/Dockerfile .
claude --image claude-code-pr <directory>

If you install multiple plugins that ship their own companion image, you'll need to merge their RUN blocks into a single Dockerfile by hand — there is no automatic composition.

Conventions reference

• Conventional Commits 1.0.0
• Semantic Versioning — driven by commit types (feat → minor, fix → patch, BREAKING CHANGE → major)

License

BSD 3-Clause — see LICENSE.