Stats
Actions
Tags
From git-workflow
Git commit and documentation workflow manager. Analyzes changes, determines commit strategy (direct vs agents), writes conventional commit messages, coordinates documentation updates, and creates pull requests. Use when completing features, making commits, pushing changes, creating PRs, or when the user says "It's time to push commits."
How this skill is triggered — by the user, by Claude, or both
Slash command
/git-workflow:git-workflowThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Intelligent git commit and documentation workflow orchestration. Analyzes changes, writes conventional commit messages, and coordinates documentation updates through parallel agent deployment when needed.
Intelligent git commit and documentation workflow orchestration. Analyzes changes, writes conventional commit messages, and coordinates documentation updates through parallel agent deployment when needed.
Managing git workflow for: $ARGUMENTS
Parse arguments:
If no arguments needed, proceed with analysis.
Run git commands to analyze current state:
git status --porcelain
git diff --stat
git diff --cached --stat
Determine:
Run the analysis script for structured output:
${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/scripts/analyze-changes.sh
This provides:
For each modified file, understand:
Group related changes together for commit organization.
Use this decision tree to determine approach:
Is this a small change?
├─ YES (1-3 files, single feature, minor changes)
│ └─> Use Direct Commit (Phase 3a)
│ - Write commit message yourself
│ - Stage and commit in one operation
│ - Skip agent deployment
│
└─ NO (4+ files, multiple features, substantial changes)
└─> Use Agent Deployment (Phase 3b)
- Deploy parallel docs-git-committer agents
- One agent per feature/significant change
- Each agent handles docs + commit for its scope
Small Change Criteria:
Large Change Criteria:
If --dry-run is present in $ARGUMENTS:
Display the analysis and proposed strategy:
# Dry Run: Git Workflow Analysis
## Changes Detected
**Files Changed**: [count]
**Insertions**: [count]
**Deletions**: [count]
### By Type
- Source files: [count]
- Test files: [count]
- Documentation: [count]
- Configuration: [count]
## Recommended Strategy
**Approach**: [Direct Commit / Agent Deployment]
**Reasoning**: [why this strategy was chosen]
## Proposed Actions
[For Direct Commit]
- Commit message: [proposed message]
- Documentation: [yes/no] - [reasoning]
[For Agent Deployment]
- Agent 1: [feature/scope] - docs + commit
- Agent 2: [feature/scope] - docs + commit
- Total agents: [count]
## Next Steps
Remove --dry-run flag to execute the workflow.
STOP HERE - do not make changes.
Read the documentation decision template:
cat ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/templates/documentation-decision.md
This provides guidance on:
For each changed file or feature, decide:
Feature Documentation (docs/features/):
CLAUDE.md Updates (RARELY NEEDED):
Skip Documentation If:
--no-docs flag is presentRead the conventional commits reference:
cat ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/templates/commit-types.md
Write a conventional commit message:
Format: <type>(<scope>): <subject>
Guidelines:
Example:
feat(auth): implement JWT-based authentication
Add login endpoint with JWT token generation and validation
middleware for protected routes.
BREAKING CHANGE: Session-based auth is no longer supported.
Existing sessions will be invalidated.
Run validation script:
${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/scripts/validate-commit.sh "<commit-message>"
If validation fails, revise the message and re-validate.
Execute the commit:
git add [files...]
git commit -m "$(cat <<'EOF'
<commit-message>
EOF
)"
CRITICAL: Stage and commit in single operation to avoid race conditions.
If --push flag is present:
git push
Skip to Phase 4 (Summary).
Break changes into logical feature scopes:
Example scopes:
Read the docs-git-committer prompt template:
cat ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/templates/agent-prompts.md
CRITICAL: Deploy all agents in a SINGLE message with MULTIPLE Task tool calls.
For each feature scope, deploy a docs-git-committer agent:
| Field | Value |
|---|---|
| subagent_type | docs-git-committer |
| description | "Commit [feature-name] with docs" |
| prompt | Complete instructions including scope, files, documentation needs |
Agent Instructions Template:
You are handling the git commit and documentation for: [FEATURE SCOPE]
## Changed Files in Your Scope
[List of files related to this feature]
## Context
[Brief description of what changed and why]
## Your Tasks
1. Review the changes in your assigned files
2. Determine if documentation updates are needed (see templates)
3. Update or create documentation if appropriate:
- Feature docs: docs/features/[name].doc.md
- CLAUDE.md: Only if critically needed in specific directory
- Architecture docs: docs/architecture/ if system-wide changes
4. Stage all files (source + docs) and commit with conventional message
5. Return summary of what you committed
## Important
- Use conventional commit format
- Combine source + docs in ONE commit
- Use git add + commit in single command
- Do NOT push (main skill handles that)
- Focus ONLY on your assigned scope
Create todos for each agent:
- agent-1: "[Feature 1] - docs-git-committer - status: in_progress"
- agent-2: "[Feature 2] - docs-git-committer - status: in_progress"
Monitor agent execution:
After agents complete:
Gather information about what was committed:
For direct commits:
For agent deployment:
Provide comprehensive completion summary:
# Git Workflow Complete
## Commits Made
### Commit 1: [hash]
**Message**: [subject line]
**Files**: [count] files changed
**Changes**: +[insertions] -[deletions]
[If multiple commits, repeat above]
## Documentation Updates
[If docs were updated]
- Created: docs/features/[name].doc.md
- Updated: [other docs]
[If no docs]
- No documentation updates needed (minor changes)
## Summary
- **Total Commits**: [count]
- **Files Changed**: [count]
- **Documentation**: [yes/no]
- **Pushed**: [yes/no]
## Next Steps
[If not pushed]
1. Review the commits: `git log --oneline -[count]`
2. View changes: `git show HEAD`
3. Push when ready: `git push`
[If pushed]
Changes have been pushed to remote
If --push flag is present and not already pushed:
git push
Display push result.
If --pr flag is present in $ARGUMENTS:
Prerequisites:
gh) must be installed and authenticated--pr but not pushed, automatically push firstRead the PR template:
cat ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/templates/pr-template.md
This provides:
Run the PR creation script to gather information:
${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/scripts/create-pr.sh --analyze
This provides:
Based on commits made, create a PR title:
Single commit: Use the commit subject line
Multiple related commits: Create descriptive title
Format: <type>(<scope>): <description>
Examples:
feat(auth): implement JWT authentication system
fix(api): resolve multiple payment processing issues
docs: update API documentation and examples
refactor(database): migrate to new query builder pattern
Create comprehensive PR description following this structure:
## Summary
[2-4 sentence overview of what this PR does and why]
## Changes
- [Key change 1 with context]
- [Key change 2 with context]
- [Key change 3 with context]
## Documentation
[If docs were created/updated]
- Feature docs: docs/features/[name].doc.md
- API docs: docs/api/[endpoint].md
- Architecture docs: docs/architecture/[topic].md
[If no docs]
- No documentation changes needed
## Testing
[For each feature/change]
### [Feature Name]
**How to test:**
1. Step one
2. Step two
3. Expected result
**Edge cases:**
- Edge case 1 to verify
- Edge case 2 to verify
## Related Issues
[If applicable]
Closes #123
Fixes #456
Related to #789
## Breaking Changes
[If any]
BREAKING CHANGE: [Description]
**Migration steps:**
1. Step one
2. Step two
[If none]
- No breaking changes
## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests passing
- [ ] No new warnings
Decide between regular PR and draft PR:
Use draft PR (--draft flag) when:
Use regular PR when:
Execute PR creation using GitHub CLI:
For regular PR:
gh pr create \
--title "[PR Title]" \
--body "$(cat <<'EOF'
[PR Description from Step 26]
EOF
)" \
--web
For draft PR:
gh pr create \
--title "[PR Title]" \
--body "$(cat <<'EOF'
[PR Description from Step 26]
EOF
)" \
--draft \
--web
The --web flag opens the PR in browser for final review.
After PR creation:
Success:
Failure scenarios:
-u origin [branch]gh auth loginDisplay comprehensive PR creation summary:
# Pull Request Created
## PR Details
**Number**: #[number]
**Title**: [PR title]
**URL**: [GitHub URL]
**Status**: [Draft/Ready for Review]
**Base**: [base-branch] <- [current-branch]
## Commits Included
- [hash]: [commit message]
- [hash]: [commit message]
## Files Changed
**Total**: [count] files
- Source: [count]
- Tests: [count]
- Docs: [count]
## Next Steps
1. PR is ready for review
2. View PR: [URL]
3. Request reviewers in GitHub
4. Monitor CI/CD checks
5. Address review feedback
[If draft]
## Draft PR Status
This PR is marked as draft. To mark ready for review:
gh pr ready [PR number]
Complete these before marking ready:
- [ ] All tests passing
- [ ] Documentation complete
- [ ] Self-review done
If repository has .github/PULL_REQUEST_TEMPLATE.md:
┌─────────────────────────────────────────────────────────┐
│ Phase 0: Analyze Changes │
│ - git status, git diff │
│ - Categorize files │
│ - Run analysis script │
└─────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Phase 1: Determine Strategy │
│ - Apply decision tree │
│ - Small (1-3 files) vs Large (4+ files) │
└─────────────────┬───────────────────────────────────────┘
│
┌─────────┴────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌────────────────────────┐
│ Phase 3a: │ │ Phase 3b: │
│ Direct Commit │ │ Agent Deployment │
│ │ │ │
│ - Write message │ │ - Deploy parallel │
│ - Stage files │ │ docs-git-committer │
│ - Commit │ │ agents │
└────────┬─────────┘ │ - Each commits scope │
│ └──────────┬─────────────┘
│ │
└─────────┬─────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Phase 4: Summary and Push │
│ - Consolidate results │
│ - Display summary │
│ - Optional push (--push flag) │
└─────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Phase 5: Pull Request (Optional, --pr flag) │
│ - Gather PR context │
│ - Generate title and description │
│ - Create PR (draft or ready) │
│ - Display PR URL and next steps │
└─────────────────────────────────────────────────────────┘
--push flag--pr flag to automatically create PR after pushing--draft with --pr for work-in-progress or early feedbackgh CLI tool installed and authenticatedScenario: Fixed a bug in user validation
# Analysis shows: 1 file, 10 lines changed
# Strategy: Direct commit
# Crafted message:
fix(auth): prevent null email validation bypass
# Committed:
git add src/services/auth.ts
git commit -m "fix(auth): prevent null email validation bypass"
Scenario: Implemented user authentication system
# Analysis shows: 8 files, 450 lines changed
# Strategy: Agent deployment
# Deployed 3 agents:
# 1. docs-git-committer: Auth backend (models, services, middleware)
# 2. docs-git-committer: Auth frontend (components, hooks)
# 3. docs-git-committer: Auth tests (unit + integration)
# Result: 3 commits, feature docs created
Scenario: Updated API documentation
# Analysis shows: 2 doc files changed
# Strategy: Direct commit (no feature changes)
# Message:
docs(api): update authentication endpoint examples
# No documentation agents needed (already docs)
Scenario: Implemented new payment feature, commit and create PR
# User runs with PR flag
/git-workflow --pr
# Workflow executes:
# 1. Analyzes changes (12 files)
# 2. Deploys agents (payment backend, frontend, tests)
# 3. Each agent commits with docs
# 4. Pushes to remote
# 5. Creates PR automatically
# Result:
# - 3 commits made
# - Feature docs created
# - PR #123 created and ready for review
# - PR URL displayed for user
Scenario: New feature not fully complete, seeking early feedback
/git-workflow --pr --draft
# Workflow executes:
# 1. Commits current work
# 2. Pushes to remote
# 3. Creates draft PR
# 4. Marks as "not ready for review"
# Result:
# - Draft PR created
# - Reviewers can see progress
# - Can be marked ready later with: gh pr ready [number]
Scenario: Feature complete but not ready to create PR yet
/git-workflow --push
# Workflow executes:
# 1. Commits and documents
# 2. Pushes to remote
# 3. Stops (no PR created)
# User can create PR later:
# /git-workflow --pr (will use existing commits)
Solution: Review commit message format, check type is valid, ensure subject <=50 chars
Solution: Group related changes, combine scopes, or use sequential commits
Solution: Use git diff to review changes, git log for context, ask user for clarification
Solution: This shouldn't happen with proper scope isolation, but if it does, manually resolve and recommit
Solution: When in doubt, skip documentation for minor changes, create it for substantial features
Solution: Install GitHub CLI:
# macOS
brew install gh
# Linux
# See: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
Solution: Authenticate with GitHub:
gh auth login
# Follow prompts to authenticate
Solution: Push with upstream:
git push -u origin [branch-name]
# Then retry with --pr flag
Solution: View existing PR or update it:
# View PR
gh pr view
# Or create new branch for separate PR
git checkout -b [new-branch-name]
Solution: Mark PR as ready for review:
gh pr ready [PR-number]
npx claudepluginhub yandy-r/claude-pluginsManages Git commit workflow using Conventional Commits format with safety protocols. Creates, validates, executes commits; handles hooks, PRs, and safety checks before operations.
Commits changes, pushes to branch, and opens or updates GitHub PR with adaptive value-first description that scales with change complexity. Use for 'commit and PR' or PR description refresh.
Orchestrates multi-agent git workflow from code review and quality checks through testing, Conventional Commits, PR creation, and deployment readiness. Supports trunk-based and feature-branch strategies.