This skill should be used when starting new feature work, mid-feature when wanting to add unrelated changes, when a branch has grown beyond 20 commits, or when unsure whether to create a new branch. Covers one-feature-one-branch rule, branch size targets, and when to split branches.
Provides disciplined branching guidance to prevent monster branches. Use when starting new work, mid-feature considering unrelated changes, or when a branch exceeds 20 commits. Covers branch creation, size limits, and when to split.
/plugin marketplace add ImproperSubset/hh-agentics/plugin install cc-governance@hh-agenticsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Prevent monster branches by following disciplined branching and merge practices.
Invoke this skill when:
BEFORE writing ANY code, answer these questions:
Non-trivial = ANY of these:
Trivial = ALL of these:
# Ensure main branch is up to date
git checkout main
git pull origin main
# Create feature branch (choose appropriate prefix)
git checkout -b feature/descriptive-name # For new features
git checkout -b refactor/descriptive-name # For refactoring
git checkout -b fix/descriptive-name # For bug fixes
Examples:
feature/user-authentication - New auth implementationrefactor/error-handling - Standardize error handlingfix/login-redirect - Fix login redirect bugWhen in doubt, use a feature branch.
Feature branches provide:
Timeline:
Symptoms:
Consequences:
One feature, one branch, one merge.
If you can't describe the branch in a single sentence without using "and", it's too big.
✅ Good: feat/user-auth - "Add basic user authentication"
✅ Good: feat/smart-fields - "Implement smart field system"
✅ Good: fix/race-condition - "Fix optimistic update race condition"
✅ Good: refactor/scss-modules - "Convert SCSS to module system"
✅ Good: docs/contributing - "Add contributing guidelines"
❌ Bad: feat/improvements - Too vague, likely includes unrelated changes
❌ Bad: fix/various-bugs - Multiple unrelated fixes should be separate branches
❌ Bad: wip/stuff - Not descriptive, suggests unfocused work
Ideal: 5-15 commits, 1-5 files changed significantly Acceptable: Up to 30 commits, up to 10 files Too Large: 50+ commits, 20+ files
Exception: Large refactors that are purely mechanical
5 commits → Normal feature pace
10 commits → Check: Am I still focused on one feature?
20 commits → WARNING: Consider splitting or wrapping up
30 commits → CRITICAL: Finish and merge, or split into multiple branches
50+ commits → MONSTER: This should have been 3-5 separate branches
✅ Acceptable large branches:
❌ Unacceptable large branches:
New change → Related to current feature?
↓ YES (same system, same goal)
→ Continue current branch
↓ NO (different system, different goal)
→ Question 2
Current branch → Ready to merge?
↓ YES (feature complete, tests pass)
→ Merge current, then new branch for new work
↓ NO (feature incomplete)
→ Question 3
New work → Required for current feature to work?
↓ YES (dependency)
→ Continue current branch
↓ NO (nice-to-have, improvement, unrelated)
→ Stash current, new branch, finish new, resume current
<type>/<short-description>
feat/user-auth
feat/smart-fields
feat/dashboard
fix/login-redirect
fix/memory-leak
refactor/scss-modules
refactor/modularization
docs/contributing
docs/api-guide
chore/update-deps
❌ feature/ - Use feat/ (shorter)
❌ bugfix/ - Use fix/ (shorter)
❌ wip/ - Work in progress is implied, use descriptive name
❌ my-branch - Not descriptive
❌ feat/add-feature - Redundant "add"
Before creating branch:
If >30 commits expected: Break into smaller features first.
# From main (or integration branch)
git checkout main
git pull origin main
# Create feature branch
git checkout -b feat/descriptive-name
Commit discipline:
Check progress regularly:
# How many commits?
git log main..HEAD --oneline | wc -l
# How many files changed?
git diff main --stat
# Am I still focused?
git log --oneline -10 # Review recent commits
Warning signs:
// TODO commentsHow to split:
# Option A: Finish current, branch for next
git commit -m "Complete X feature"
# Merge feat/x
git checkout -b feat/y # Start next feature
# Option B: Stash incomplete, branch for urgent work
git stash
git checkout -b fix/urgent-bug
# Fix and merge
git checkout feat/original
git stash pop
Before merging:
# Rebase on latest main
git fetch origin
git rebase origin/main
# Review all changes
git diff origin/main
# Check commit history is clean
git log origin/main..HEAD --oneline
# Run tests if applicable
npm test # or your test command
# Switch to main and merge
git checkout main
git pull origin main
git merge --no-ff feat/descriptive-name
# Push to remote
git push origin main
# Delete local branch
git branch -d feat/descriptive-name
Note: --no-ff creates a merge commit even for fast-forward merges, preserving branch history.
<type>: <short description>
<optional body>
<optional footer>
Same as branch types:
Good commit messages:
feat: Add smart field system with lookups
Implements interactive fields that open selection dialogs
filtered by context. Includes helper and click handler integration.
Closes #42
Bad commit messages:
❌ "Updates"
❌ "Fix stuff"
❌ "WIP"
❌ "More changes"
❌ "Final commit (hopefully)"
You should split if:
Strategy A: Extract Completed Features
# Current branch: feat/massive (50 commits)
# Goal: Extract first feature into separate branch
# 1. Create new branch from main
git checkout main
git checkout -b feat/extracted-feature
# 2. Cherry-pick relevant commits
git log feat/massive --oneline # Find commit SHAs
git cherry-pick abc123 def456 ghi789
# 3. Merge the extracted feature
git checkout main
git merge --no-ff feat/extracted-feature
git push origin main
git branch -d feat/extracted-feature
# 4. Rebase massive branch to remove duplicates
git checkout feat/massive
git rebase main
Strategy B: Start Fresh, Reference Old
# Current branch: feat/massive (too messy to salvage)
# 1. Create new branch from main
git checkout main
git checkout -b feat/feature-1-clean
# 2. Manually apply changes from massive branch
# (Copy files, make clean commits)
# 3. Repeat for each feature
git checkout main
git checkout -b feat/feature-2-clean
# 4. Abandon feat/massive after all features extracted
git branch -D feat/massive
If bug blocks feature X: → Fix in current branch
If bug is unrelated:
→ Stash current work, create fix/bug-y, merge it, resume feature X
If B is required for A: → Continue current branch
If B is independent: → Finish A first, then branch for B
If B is urgent and A is incomplete: → Stash A, branch for B, merge B, resume A
Yes. Options:
Separate them:
# Approach 1: Amend last commit to remove formatting
git reset HEAD~1
git add <feature files only>
git commit -m "feat: add feature"
git add <formatting files>
git commit -m "chore: format code"
# Approach 2: Split into two branches
# - Branch 1: Formatting only (refactor/format-cleanup) - merge first
# - Branch 2: Feature only (feat/my-feature) - merge after
Remember: When in doubt, split it out. Smaller branches are easier to understand, safer to merge, and faster to ship.
Last Updated: 2026-01-05
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.