gitworkflow

GitWorkflow

Smart Git workflow engine with submodule detection, hook-aware commit strategies, repo-aware branch targeting, CI monitoring & auto-merge, issue analysis/routing, deploy-workflow isolation, and changelog awareness.

Optional companion: changelog CLI

If the user has a changelog CLI on PATH, the Commit and Release workflows invoke it for repo awareness:

changelog --auto --dry-run     # Preview unreleased changes (used after every commit)
changelog VERSION --auto       # Generate CHANGELOG.md entry (used in releases)
changelog VERSION --auto --force  # Non-interactive changelog generation

If no changelog binary is found, the workflows continue without it and skip the preview/generation steps. Configure the path or alternative command in .claude/gitworkflow.local.md (see plugin README).

Repository Adaptation Rules

Before running Branch, PullRequest, CIMerge, or Release workflows, detect the repo shape:

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null || git remote show origin | sed -n '/HEAD branch/s/.*: //p')
if git show-ref --verify --quiet refs/heads/develop || git ls-remote --exit-code --heads origin develop >/dev/null 2>&1; then
  INTEGRATION_BRANCH=develop
else
  INTEGRATION_BRANCH="$DEFAULT_BRANCH"
fi

Rules:

• If develop exists, use Git Flow normally.
• If develop does not exist, treat the repo defaultBranch as the integration branch too.
• Feature branches PR into INTEGRATION_BRANCH.
• Release and hotfix branches PR into DEFAULT_BRANCH.
• If the repo has .github/PULL_REQUEST_TEMPLATE.md, use it as the starting shape for the PR body.
• If the repo has an issue-link check or contributing docs that require issue closure keywords, the PR body must contain a real closing reference like Closes #123, Fixes #123, or Resolves #123, or explicitly mark No issue required when the repo allows that path.
• Never leave placeholders like Closes #, #ISSUE_NUM, or a bare #123 in prose and assume GitHub will auto-close the issue.

This matters for repos with strict PR-issue-link metadata checks, which now fail PR checks unless the PR body contains a valid closing keyword or an explicit No issue required marker.

Workflow Routing

When executing a workflow, output this notification directly:

Running the **WorkflowName** workflow from the **GitWorkflow** skill...

Workflow	Trigger	File
Commit	"commit", "commit changes", "make a commit"	workflows/Commit.md
Branch	"create branch", "start feature", "finish branch"	workflows/Branch.md
Release	"create release", "bump version", "tag release"	workflows/Release.md
PullRequest	"create PR", "open pull request", "submit PR"	workflows/PullRequest.md
CIMerge	"merge PR", "check CI", "wait for checks", "is CI passing", "monitor CI", "auto-merge"	workflows/CIMerge.md
Submodule	"add submodule", "add repo as submodule", "submodule add/update/remove"	workflows/Submodule.md
IssueAnalysis	--issue-analysis, "analyze issues", "label issues", "route issues across worktrees", "plan the cut", "who should work on what"	workflows/IssueAnalysis.md
DeployWorkflow	"deploy workflow", "push workflow to main", "merge workflow only", "deploy gh action"	workflows/DeployWorkflow.md

Examples

Example 1: Smart commit with submodule handling

User: "commit my changes"
→ Invokes Commit workflow
→ Detects dirty submodules, commits them first
→ Analyzes hooks to choose strategy (PARALLEL/COORDINATED/HYBRID)
→ Runs pre-commit validation
→ Generates conventional commit message with emoji
→ Executes commit

Example 2: Create and manage a feature branch

User: "create a feature branch for user authentication"
→ Invokes Branch workflow
→ Detects repo default/integration branch
→ Creates feature/user-authentication branch from develop when present, otherwise from the repo default branch
→ Pushes to remote with tracking

Example 3: Create PR, monitor CI, and auto-merge

User: "create a PR and merge it when CI passes"
→ Invokes PullRequest workflow
→ Detects target branch from repo shape + current branch type
→ Reads PR template / issue-link requirements when present
→ Creates PR with a valid closing keyword or marks no-issue-required when allowed
→ Continues to CIMerge workflow
→ Polls CI checks (GitHub Actions, CodeRabbit, GitGuardian, repo-specific metadata checks)
→ Waits 240s for automated reviews to settle (minimum 4 minutes)
→ Checks review decision (changes requested? approved? none?)
→ Auto-merges with squash when all clear

Example 4: Create a release with version bump

User: "create a release for version 2.0.0"
→ Invokes Release workflow
→ Analyzes commits to confirm MAJOR bump is appropriate
→ Creates release/v2.0.0 branch from develop when present, otherwise from the default branch
→ Updates version files
→ Generates changelog from conventional commits
→ Pushes release branch for testing

Example 5: Route issues across coding-agent worktrees toward a beta cut

User: "/git-workflow --issue-analysis --apply"
→ Invokes IssueAnalysis workflow
→ Detects worktrees (claude / codex / pi) and in-flight PRs
→ Asks for the cut sentence (north-star check)
→ Splits backlog into <cut>-blocker vs post-<cut>
→ Assigns issues to agents by warm context + file boundary
→ Creates labels: agent:<name>, <cut>-blocker, post-<cut>
→ Edits all open issues with appropriate labels
→ Prints routing table + ASCII route map + per-agent gh cheat-line

Example 6: Deploy a GitHub Actions workflow from a feature branch without merging the feature

User: "deploy this workflow to main, but don't merge my feature branch yet"
→ Invokes DeployWorkflow workflow
→ Stashes uncommitted changes on the current feature branch
→ Creates an isolated branch from origin/main
→ Cherry-picks or checks out only the workflow files
→ Commits, pushes, opens PR, merges with squash
→ Returns to the feature branch and restores the stash
→ Workflow is live on main; feature branch remains untouched

---

Quick Reference: Commit Messages

Use Conventional Commits with emoji prefixes:

<emoji> <type>(<scope>): <description>

[optional body]

Co-Authored-By: <Your Name or Team>

Common Types:

• ✨ feat - New feature
• 🐛 fix - Bug fix
• 📝 docs - Documentation
• 💄 style - Formatting/style
• ♻️ refactor - Code refactoring
• ✅ test - Tests
• 🔧 chore - Tooling, configuration

Reference: See <your emoji commit reference> for 50+ emoji mappings

---

Quick Reference: Branch Commands

Detect Base Branches

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null || git remote show origin | sed -n '/HEAD branch/s/.*: //p')
if git show-ref --verify --quiet refs/heads/develop || git ls-remote --exit-code --heads origin develop >/dev/null 2>&1; then
  INTEGRATION_BRANCH=develop
else
  INTEGRATION_BRANCH="$DEFAULT_BRANCH"
fi

Feature Branch

# Start
git checkout "$INTEGRATION_BRANCH" && git pull origin "$INTEGRATION_BRANCH"
git checkout -b feature/descriptive-name
git push -u origin feature/descriptive-name

# Finish (preferred: open a PR into $INTEGRATION_BRANCH)

Release Branch

# Start
git checkout "$INTEGRATION_BRANCH" && git checkout -b release/vX.Y.Z
git commit -am "🔖 release: bump version to X.Y.Z"
git push -u origin release/vX.Y.Z

# Finish (merge to default branch, then back-merge to develop only when develop exists)

Hotfix Branch

# Start (from repo default branch)
git checkout "$DEFAULT_BRANCH" && git checkout -b hotfix/descriptive-name
git push -u origin hotfix/descriptive-name

# Finish (merge to default branch, then back-merge to develop only when develop exists)

---

Commit Strategy Detection

The Commit workflow automatically detects the optimal strategy based on pre-commit hooks:

Hook Configuration	Strategy	Behavior
No formatting hooks	PARALLEL	Stage multiple commits independently
Formatting hooks (non-aggressive)	COORDINATED	Stage and commit sequentially
Aggressive formatting (prettier --write)	HYBRID	Stage all, let hook format, single commit

---

Gotchas

• lefthook install in postinstall crashes on Vercel (not a git repo). Fix: "postinstall": "lefthook install || true".
• Always check postinstall scripts before first Vercel deploy.
• Always verify NEXT_PUBLIC_SITE_URL env var is set to the production URL, not localhost, on first deploy.
• Do not assume every repo has develop. Detect it.
• Do not assume every PR can omit issue metadata. Inspect .github/ and contributing docs first.

Reusable Workflow Templates

Ready-to-copy GitHub Actions workflows stored in templates/:

Template	Purpose	Files
Issue Auto-Labeler	Deterministic keyword-based issue labeling, AI-swap-in ready	templates/issue-labeler.yml + templates/labeler-config.json

Drop both files into a repo's .github/ directory, customize labeler-config.json to match the repo's labels, and the workflow is live on the next push to the default branch.

Supplementary Resources

Detailed per-workflow methodology, conflict resolution, error handling: Read the matching file under workflows/ for the workflow you're running.

Emoji commit reference: The Quick Reference above lists the 7 most-common types. For a fuller emoji palette, point this skill at your own emoji reference file via .claude/gitworkflow.local.md (see plugin README).