Help us improve
Share bugs, ideas, or general feedback.
From popkit-dev
Manages git workflow: smart commit (default), push with protections, PRs, code review, CI runs, releases, publish, prune branches, finish. Supports subcommands via <subcommand> [options].
npx claudepluginhub jrc1883/popkit-ai --plugin popkit-devHow this command is triggered — by the user, by Claude, or both
Slash command
/popkit-dev:git <subcommand> [options]The summary Claude sees in its command listing — used to decide when to auto-load this command
# /popkit-dev:git - Git Workflow Management Git operations with smart commits, PRs, code review, CI/CD, releases, publishing, and branch cleanup. ## Subcommands | Subcommand | Description | | ---------------- | ------------------------------------------------------- | | commit | Smart commit with auto-generated message (default) | | push | Push current branch to remote | | pr | Pull request management (create, list, view, merge) | | review | Code review with ...
/gitExecutes Git operations (status, add, commit, push, pull, branch, merge) with intelligent commit messages, branch management, workflow optimization, and status recommendations.
Share bugs, ideas, or general feedback.
Git operations with smart commits, PRs, code review, CI/CD, releases, publishing, and branch cleanup.
| Subcommand | Description |
|---|---|
| commit | Smart commit with auto-generated message (default) |
| push | Push current branch to remote |
| pr | Pull request management (create, list, view, merge) |
| review | Code review with confidence-based filtering |
| ci | GitHub Actions workflow runs (list, view, rerun, watch) |
| release | GitHub releases (create, list, view, changelog) |
| publish | Publish plugin to public repo (monorepo → open source) |
| prune | Remove stale local branches after PR merge |
| finish | Complete development with 4-option flow |
| analyze-strategy | Analyze repository branching strategy |
Generate commit message from staged changes following conventional commits.
Invokes git commit with: Status check → Analyze changes → Generate message → Commit with attribution.
Output: Conventional commit with Claude Code attribution and Co-Authored-By header.
Options: --amend
Push current branch to remote with branch protection safety checks.
Branch Protection (Issue #141, #142):
Before pushing, MUST check current branch:
current_branch=$(git branch --show-current 2>/dev/null)
Protected Branches: main, master, develop, production
If on protected branch:
❌ BLOCK the push operation (do not just warn)
Explain why: "Cannot push directly to protected branch '[branch]' due to branch protection policy"
Recommend feature branch workflow:
# Create feature branch from current state
git checkout -b feat/descriptive-name
git push -u origin feat/descriptive-name
# Create pull request
gh pr create --title "..." --body "..."
# Clean up local protected branch
git checkout [protected-branch]
git reset --hard origin/[protected-branch]
Reference: See CLAUDE.md "Git Workflow Principles" section
If on feature branch:
--force-with-lease if --force requestedOptions: --force-with-lease, -u
Pull request management via gh CLI.
| Subcommand | Description |
|---|---|
| create (default) | Create PR from current branch |
| list | List open/all/draft PRs |
| view | View PR details, comments, files, checks |
| merge | Merge with squash/rebase options |
| checkout | Check out PR locally |
| diff | View PR diff |
| ready | Mark draft as ready |
| update | Update PR branch with base |
Process (create): Verify clean state → Create/switch branch → Stage → Commit → Push → Validate labels (Issue #96) → Create PR with template.
Options: --draft, --base , --title , --label , --squash, --rebase, --delete-branch
Before marking a draft PR as ready, use the executable outside-voice-aware ready helper:
python packages/popkit-ops/skills/pop-cross-model-review/scripts/pr_ready.py --pr <number>
By default, it refuses to mark the PR ready unless the current head already has an advisory outside-voice review.
If no outside-voice review exists for the current head:
Run advisory review automatically and publish/update the PR comment:
python packages/popkit-ops/skills/pop-cross-model-review/scripts/pr_ready.py --pr <number> --run-review-if-missing --publish comment
Or explicitly record a skip:
python packages/popkit-ops/skills/pop-cross-model-review/scripts/pr_ready.py --pr <number> --skip-outside-voice
The helper then calls gh pr ready <number> for you.
CRITICAL: Always validate labels BEFORE calling gh pr create to prevent errors.
Implementation:
from popkit_shared.utils.github_validator import validate_labels
from popkit_shared.utils.github_cache import GitHubCache
# 1. Determine labels (from flags or branch prefix)
if user_labels:
requested_labels = user_labels # e.g., ["enhancement", "needs-review"]
else:
# Infer from branch name
branch_name = get_current_branch()
requested_labels = infer_labels_from_branch(branch_name)
# feat/* → ["enhancement"]
# fix/* → ["bug"]
# docs/* → ["documentation"]
# 2. Validate using cache
cache = GitHubCache()
valid, invalid, suggestions = validate_labels(requested_labels, cache)
# 3. Handle invalid labels
if invalid:
print(f"⚠️ Invalid labels: {', '.join(invalid)}")
# Auto-fix with suggestions
fixed_labels = valid.copy()
for s in suggestions:
if s['suggestions']:
best_match = s['suggestions'][0]
fixed_labels.append(best_match)
print(f" Auto-corrected: {s['invalid']} → {best_match}")
labels_to_use = fixed_labels
else:
labels_to_use = valid
# 4. Create PR with validated labels
if labels_to_use:
gh pr create --title "..." --body "..." --label {','.join(labels_to_use)}
else:
gh pr create --title "..." --body "..."
Example Output:
Creating PR from branch: feat/user-auth
Inferred labels from branch: enhancement
⚠️ Invalid labels: enhancement
Auto-corrected: enhancement → feature
✓ Using labels: feature
✓ PR #45 created successfully
Code review with confidence-based issue filtering (80+ threshold).
Invokes code-reviewer agent: Gather changes → Analyze (Simplicity/Bugs/Conventions) → Score → Report critical/important issues only.
Output: Categorized issues with confidence scores, file locations, and fix suggestions.
Options: --staged, --branch , --pr , --file , --focus , --threshold , --verbose, --outside-voice, --target-provider <auto|claude-code|codex>, --publish <none|comment>
Use --outside-voice to run an advisory review through the opposite model family:
claude-code sessions default to codexcodex sessions default to claude-code--target-provider overrides the automatic choice--publish comment creates or updates a PR comment keyed to the current head SHAImplementation path: pop-cross-model-review
Examples:
/popkit-dev:git review --outside-voice
/popkit-dev:git review --outside-voice --staged
/popkit-dev:git review --outside-voice --pr 123 --publish comment
/popkit-dev:git review --outside-voice --target-provider codex
Monitor and manage GitHub Actions workflows via gh run CLI.
| Subcommand | Description |
|---|---|
| list (default) | Recent workflow runs |
| view | View run details, logs |
| rerun | Rerun all/failed jobs |
| watch | Watch running workflow |
| cancel | Cancel running workflow |
| download | Download artifacts |
| logs | View logs |
Status icons: [ok] success, [x] failure, [...] in_progress, [ ] queued, [~] cancelled, [!] skipped
Options: --workflow , --branch , --status , --limit , --failed, --job
Create and manage GitHub releases with auto-generated changelogs via gh release CLI.
| Subcommand | Description |
|---|---|
| list (default) | All releases |
| create | Create release with auto-changelog |
| view | View release details |
| edit | Edit release notes/status |
| delete | Delete release/tag |
| changelog | Preview changelog |
Process (create): Parse commits → Generate changelog → Update CLAUDE.md (if --update-docs) → Create tag → Create GitHub release.
Changelog: Parses conventional commits (feat, fix, docs, perf, refactor, test, chore) and groups by type.
Version detection: package.json, Cargo.toml, latest tag + increment.
Options: --draft, --prerelease, --title , --update-docs, --changelog-only
Publish plugin from private monorepo to public jrc1883/popkit-plugin repo via git subtree split.
Architecture: Split-repo model - private monorepo (full dev) → public plugin repo (open source).
Process: Verify clean state → IP leak scan → Subtree split → Push to public main branch → Optional tag.
IP Leak Scanner: Blocks publish on critical/high severity findings. Use --skip-ip-scan only for false positives.
Options: --dry-run, --branch , --tag , --force, --changelog, --skip-ip-scan
Remote setup: git remote add plugin-public https://github.com/jrc1883/popkit-plugin.git
Remove stale local branches after PRs are merged.
Process: Fetch --prune → Find gone branches → Preview → Delete (if confirmed).
Safety: Uses -d (safe delete), won't delete unmerged branches, never deletes main/master/develop.
Options: --dry-run, --force
Guide completion of development work with structured options.
Invokes pop-finish-branch: Verify tests → Present 4 options (merge locally, create PR, keep as-is, discard).
Options:
Analyze repository branching strategy and provide recommendations.
Phase 1 Implementation (Issue #151):
Detects current branching strategy by analyzing:
Supported Strategies:
Output:
# Git Branch Strategy Analysis
**Detected Strategy**: Trunk-based Development
**Confidence**: 80%
## Evidence
- main as primary branch
- 32 feature branches
- short-lived branches (avg 3 days)
## Branch Statistics
- Total branches: 35
- Feature branches: 32
- Bugfix branches: 3
- Average branch lifetime: 3 days
## Recommendations
✅ Good for: Small teams (2-5 developers), rapid iteration
✅ Benefits: Fast merges, simple workflow, continuous integration
💡 Consider Git Flow if: Need release coordination or multiple version support
Technical Implementation:
popkit_shared.utils.git_strategy.GitStrategyDetectorgh CLI)Options: --json (output JSON format), --verbose (detailed branch info)
Related Commands:
/popkit-dev:git recommend-strategy (interactive questionnaire)/popkit-dev:git migrate-to <strategy> (automated migration)| Rule | Action |
|---|---|
| Config | NEVER update git config |
| Destructive | NEVER run without explicit request |
| Hooks | NEVER skip (--no-verify) unless requested |
| Force push | NEVER to main/master |
| Amend | AVOID unless requested, check authorship first |
| Preview | ALWAYS before bulk operations |
| Component | Integration |
|---|---|
| Commit | Conventional commits, attribution |
| PR Templates | output-styles/pr-description.md |
| Code Review | skills/pop-code-review/, agent code-reviewer |
| Finish Flow | skills/pop-finish-branch/ |
| GitHub CLI | gh pr/run/release commands |
| Changelog | hooks/utils/changelog_generator.py |
| Version | package.json, Cargo.toml, git tags |
| Publishing | git subtree split, IP scanner |
| IP Scanner | hooks/utils/ip_protection.py |
Related: /popkit-dev:worktree, /popkit-dev:dev execute, /popkit:morning
See examples/git/ for: commit-examples.md, pr-examples.md, review-examples.md, ci-examples.md, release-examples.md, publish-examples.md.