john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add git commit and branch helper skills (#378)

Browse Source
This commit is contained in:
Trevin Chow
2026-03-25 14:53:39 -07:00
committed by GitHub
parent 8ebc77b8e6
commit fe08af2b41
6 changed files with 392 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
plugins/compound-engineering/README.md
View File

@@ -10,9 +10,93 @@ AI-powered development tools that get smarter with every use. Make each unit of
| Skills | 40+ |
| MCP Servers | 1 |
## Skills
### Core Workflow
The primary entry points for engineering work, invoked as slash commands:
| Skill | Description |
|-------|-------------|
| `/ce:ideate` | Discover high-impact project improvements through divergent ideation and adversarial filtering |
| `/ce:brainstorm` | Explore requirements and approaches before planning |
| `/ce:plan` | Transform features into structured implementation plans grounded in repo patterns |
| `/ce:review` | Structured code review with tiered persona agents, confidence gating, and dedup pipeline |
| `/ce:work` | Execute work items systematically |
| `/ce:compound` | Document solved problems to compound team knowledge |
| `/ce:compound-refresh` | Refresh stale or drifting learnings and decide whether to keep, update, replace, or archive them |
| `/deepen-plan` | Stress-test plans and deepen weak sections with targeted research |
### Git Workflow
| Skill | Description |
|-------|-------------|
| `git-clean-gone-branches` | Clean up local branches whose remote tracking branch is gone |
| `git-commit` | Create a git commit with a value-communicating message |
| `git-commit-push-pr` | Commit, push, and open a PR with an adaptive, value-first description |
| `git-worktree` | Manage Git worktrees for parallel development |
### Workflow Utilities
| Skill | Description |
|-------|-------------|
| `/changelog` | Create engaging changelogs for recent merges |
| `/feature-video` | Record video walkthroughs and add to PR description |
| `/reproduce-bug` | Reproduce bugs using logs and console |
| `/report-bug-ce` | Report a bug in the compound-engineering plugin |
| `/resolve-pr-parallel` | Resolve PR comments in parallel |
| `/sync` | Sync Claude Code config across machines |
| `/test-browser` | Run browser tests on PR-affected pages |
| `/test-xcode` | Build and test iOS apps on simulator |
| `/todo-resolve` | Resolve todos in parallel |
| `/todo-triage` | Triage and prioritize pending todos |
### Development Frameworks
| Skill | Description |
|-------|-------------|
| `agent-native-architecture` | Build AI agents using prompt-native architecture |
| `andrew-kane-gem-writer` | Write Ruby gems following Andrew Kane's patterns |
| `dhh-rails-style` | Write Ruby/Rails code in DHH's 37signals style |
| `dspy-ruby` | Build type-safe LLM applications with DSPy.rb |
| `frontend-design` | Create production-grade frontend interfaces |
### Review & Quality
| Skill | Description |
|-------|-------------|
| `claude-permissions-optimizer` | Optimize Claude Code permissions from session history |
| `document-review` | Review documents using parallel persona agents for role-specific feedback |
| `setup` | Configure which review agents run for your project |
### Content & Collaboration
| Skill | Description |
|-------|-------------|
| `compound-docs` | Capture solved problems as categorized documentation |
| `every-style-editor` | Review copy for Every's style guide compliance |
| `proof` | Create, edit, and share documents via Proof collaborative editor |
| `todo-create` | File-based todo tracking system |
### Automation & Tools
| Skill | Description |
|-------|-------------|
| `agent-browser` | CLI-based browser automation using Vercel's agent-browser |
| `gemini-imagegen` | Generate and edit images using Google's Gemini API |
| `orchestrating-swarms` | Comprehensive guide to multi-agent swarm orchestration |
| `rclone` | Upload files to S3, Cloudflare R2, Backblaze B2, and cloud storage |
### Beta / Experimental
| Skill | Description |
|-------|-------------|
| `/lfg` | Full autonomous engineering workflow |
| `/slfg` | Full autonomous workflow with swarm mode for parallel execution |
## Agents
Agents are organized into categories for easier discovery.
Agents are specialized subagents invoked by skills — you typically don't call these directly.
### Review
@@ -87,107 +171,6 @@ Agents are organized into categories for easier discovery.
|-------|-------------|
| `ankane-readme-writer` | Create READMEs following Ankane-style template for Ruby gems |
## Commands
### Workflow Commands
Core workflow commands use `ce:` prefix to unambiguously identify them as compound-engineering commands:
| Command | Description |
|---------|-------------|
| `/ce:ideate` | Discover high-impact project improvements through divergent ideation and adversarial filtering |
| `/ce:brainstorm` | Explore requirements and approaches before planning |
| `/ce:plan` | Transform features into structured implementation plans grounded in repo patterns |
| `/ce:review` | Structured code review with tiered persona agents, confidence gating, and dedup pipeline |
| `/ce:work` | Execute work items systematically |
| `/ce:compound` | Document solved problems to compound team knowledge |
| `/ce:compound-refresh` | Refresh stale or drifting learnings and decide whether to keep, update, replace, or archive them |
### Utility Commands
| Command | Description |
|---------|-------------|
| `/lfg` | Full autonomous engineering workflow |
| `/slfg` | Full autonomous workflow with swarm mode for parallel execution |
| `/deepen-plan` | Stress-test plans and deepen weak sections with targeted research |
| `/changelog` | Create engaging changelogs for recent merges |
| `/generate_command` | Generate new slash commands |
| `/sync` | Sync Claude Code config across machines |
| `/report-bug-ce` | Report a bug in the compound-engineering plugin |
| `/reproduce-bug` | Reproduce bugs using logs and console |
| `/resolve-pr-parallel` | Resolve PR comments in parallel |
| `/todo-resolve` | Resolve todos in parallel |
| `/todo-triage` | Triage and prioritize pending todos |
| `/test-browser` | Run browser tests on PR-affected pages |
| `/test-xcode` | Build and test iOS apps on simulator |
| `/feature-video` | Record video walkthroughs and add to PR description |
## Skills
### Architecture & Design
| Skill | Description |
|-------|-------------|
| `agent-native-architecture` | Build AI agents using prompt-native architecture |
### Development Tools
| Skill | Description |
|-------|-------------|
| `andrew-kane-gem-writer` | Write Ruby gems following Andrew Kane's patterns |
| `compound-docs` | Capture solved problems as categorized documentation |
| `dhh-rails-style` | Write Ruby/Rails code in DHH's 37signals style |
| `dspy-ruby` | Build type-safe LLM applications with DSPy.rb |
| `frontend-design` | Create production-grade frontend interfaces |
### Content & Workflow
| Skill | Description |
|-------|-------------|
| `document-review` | Review documents using parallel persona agents for role-specific feedback |
| `every-style-editor` | Review copy for Every's style guide compliance |
| `todo-create` | File-based todo tracking system |
| `git-worktree` | Manage Git worktrees for parallel development |
| `proof` | Create, edit, and share documents via Proof collaborative editor |
| `claude-permissions-optimizer` | Optimize Claude Code permissions from session history |
| `resolve-pr-parallel` | Resolve PR review comments in parallel |
| `setup` | Configure which review agents run for your project |
### Multi-Agent Orchestration
| Skill | Description |
|-------|-------------|
| `orchestrating-swarms` | Comprehensive guide to multi-agent swarm orchestration |
### File Transfer
| Skill | Description |
|-------|-------------|
| `rclone` | Upload files to S3, Cloudflare R2, Backblaze B2, and cloud storage |
### Browser Automation
| Skill | Description |
|-------|-------------|
| `agent-browser` | CLI-based browser automation using Vercel's agent-browser |
### Image Generation
| Skill | Description |
|-------|-------------|
| `gemini-imagegen` | Generate and edit images using Google's Gemini API |
**gemini-imagegen features:**
- Text-to-image generation
- Image editing and manipulation
- Multi-turn refinement
- Multiple reference image composition (up to 14 images)
**Requirements:**
- `GEMINI_API_KEY` environment variable
- Python packages: `google-genai`, `pillow`
## MCP Servers
| Server | Description |

163
plugins/compound-engineering/skills/generate_command/SKILL.md
View File

@@ -1,163 +0,0 @@
---
name: generate_command
description: Create a new custom slash command following conventions and best practices
argument-hint: "[command purpose and requirements]"
disable-model-invocation: true
---
# Create a Custom Claude Code Command
Create a new skill in `.claude/skills/` for the requested task.
## Goal
#$ARGUMENTS
## Key Capabilities to Leverage
**File Operations:**
- Read, Edit, Write - modify files precisely
- Glob, Grep - search codebase
- MultiEdit - atomic multi-part changes
**Development:**
- Bash - run commands (git, tests, linters)
- Task - launch specialized agents for complex tasks
- TodoWrite - track progress with todo lists
**Web & APIs:**
- WebFetch, WebSearch - research documentation
- GitHub (gh cli) - PRs, issues, reviews
- Playwright - browser automation, screenshots
**Integrations:**
- AppSignal - logs and monitoring
- Context7 - framework docs
- Stripe, Todoist, Featurebase (if relevant)
## Best Practices
1. **Be specific and clear** - detailed instructions yield better results
2. **Break down complex tasks** - use step-by-step plans
3. **Use examples** - reference existing code patterns
4. **Include success criteria** - tests pass, linting clean, etc.
5. **Think first** - use "think hard" or "plan" keywords for complex problems
6. **Iterate** - guide the process step by step
## Required: YAML Frontmatter
**EVERY command MUST start with YAML frontmatter:**
```yaml
---
name: command-name
description: Brief description of what this command does (max 100 chars)
argument-hint: "[what arguments the command accepts]"
---
```
**Fields:**
- `name`: Lowercase command identifier (used internally)
- `description`: Clear, concise summary of command purpose
- `argument-hint`: Shows user what arguments are expected (e.g., `[file path]`, `[PR number]`, `[optional: format]`)
## Structure Your Command
```markdown
# [Command Name]
[Brief description of what this command does]
## Steps
1. [First step with specific details]
- Include file paths, patterns, or constraints
- Reference existing code if applicable
2. [Second step]
- Use parallel tool calls when possible
- Check/verify results
3. [Final steps]
- Run tests
- Lint code
- Commit changes (if appropriate)
## Success Criteria
- [ ] Tests pass
- [ ] Code follows style guide
- [ ] Documentation updated (if needed)
```
## Tips for Effective Commands
- **Use $ARGUMENTS** placeholder for dynamic inputs
- **Reference AGENTS.md** patterns and conventions
- **Include verification steps** - tests, linting, visual checks
- **Be explicit about constraints** - don't modify X, use pattern Y
- **Use XML tags** for structured prompts: `<task>`, `<requirements>`, `<constraints>`
## Example Pattern
```markdown
Implement #$ARGUMENTS following these steps:
1. Research existing patterns
- Search for similar code using Grep
- Read relevant files to understand approach
2. Plan the implementation
- Think through edge cases and requirements
- Consider test cases needed
3. Implement
- Follow existing code patterns (reference specific files)
- Write tests first if doing TDD
- Ensure code follows AGENTS.md conventions
4. Verify
- Run tests: `bin/rails test`
- Run linter: `bundle exec standardrb`
- Check changes with git diff
5. Commit (optional)
- Stage changes
- Write clear commit message
```
## Creating the Command File
1. **Create the directory** at `.claude/skills/[name]/SKILL.md`
2. **Start with YAML frontmatter** (see section above)
3. **Structure the skill** using the template above
4. **Test the skill** by using it with appropriate arguments
## Command File Template
```markdown
---
name: command-name
description: What this command does
argument-hint: "[expected arguments]"
---
# Command Title
Brief introduction of what the command does and when to use it.
## Workflow
### Step 1: [First Major Step]
Details about what to do.
### Step 2: [Second Major Step]
Details about what to do.
## Success Criteria
- [ ] Expected outcome 1
- [ ] Expected outcome 2
```

67
plugins/compound-engineering/skills/git-clean-gone-branches/SKILL.md Normal file
View File

@@ -0,0 +1,67 @@
---
name: git-clean-gone-branches
description: Clean up local branches whose remote tracking branch is gone. Use when the user says "clean up branches", "delete gone branches", "prune local branches", "clean gone", or wants to remove stale local branches that no longer exist on the remote. Also handles removing associated worktrees for branches that have them.
---
# Clean Gone Branches
Delete local branches whose remote tracking branch has been deleted, including any associated worktrees.
## Workflow
### Step 1: Discover gone branches
Run the discovery script to fetch the latest remote state and identify gone branches:
```bash
bash scripts/clean-gone
```
[scripts/clean-gone](./scripts/clean-gone)
The script runs `git fetch --prune` first, then parses `git branch -vv` for branches marked `: gone]`. It uses `command git` to bypass shell aliases and RTK proxies.
If the script outputs `__NONE__`, report that no stale branches were found and stop.
### Step 2: Present branches and ask for confirmation
Show the user the list of branches that will be deleted. Format as a simple list:
```
These local branches have been deleted from the remote:
- feature/old-thing
- bugfix/resolved-issue
- experiment/abandoned
Delete all of them? (y/n)
```
Wait for the user's answer using the platform's question tool (e.g., `AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the list and wait for the user's reply before proceeding.
This is a yes-or-no decision on the entire list -- do not offer multi-selection or per-branch choices.
### Step 3: Delete confirmed branches
If the user confirms, delete each branch. For each branch:
1. Check if it has an associated worktree (`command git worktree list | grep "\\[$branch\\]"`)
2. If a worktree exists and is not the main repo root, remove it first: `command git worktree remove --force "$worktree_path"`
3. Delete the branch: `command git branch -D "$branch"`
Report results as you go:
```
Removed worktree: .worktrees/feature/old-thing
Deleted branch: feature/old-thing
Deleted branch: bugfix/resolved-issue
Deleted branch: experiment/abandoned
Cleaned up 3 branches.
```
If the user declines, acknowledge and stop without deleting anything.
## Important: Use `command git`
Always invoke git as `command git` in shell commands. This bypasses shell aliases and tools like RTK (Rust Token Killer) that proxy git commands, ensuring consistent behavior and output parsing.

49
plugins/compound-engineering/skills/git-clean-gone-branches/scripts/clean-gone Executable file
View File

@@ -0,0 +1,49 @@
#!/usr/bin/env bash
# clean-gone: List local branches whose remote tracking branch is gone.
# Outputs one branch name per line, or nothing if none found.
# Uses `command git` to bypass aliases and RTK proxies.
set -euo pipefail
# Ensure we have current remote state
command git fetch --prune 2>/dev/null
# Find branches marked [gone] in tracking info.
# `git branch -vv` output format:
# * main abc1234 [origin/main] commit msg
# + feature-x def5678 [origin/feature-x: gone] commit msg
# old-branch 789abcd [origin/old-branch: gone] commit msg
#
# The leading column can be: ' ' (normal), '*' (current), '+' (worktree).
# We match lines containing ": gone]" to find branches whose remote is deleted.
gone_branches=()
while IFS= read -r line; do
# Skip the currently checked-out branch (marked with '*').
# git branch -D cannot delete the active branch, and attempting it
# would halt cleanup before other stale branches are processed.
if [[ "$line" =~ ^\* ]]; then
continue
fi
# Strip the leading marker character(s) and whitespace
# The branch name is the first non-whitespace token after the marker
branch_name=$(echo "$line" | sed 's/^[+* ]*//' | awk '{print $1}')
# Validate: skip empty, skip if it looks like a hash or flag, skip HEAD
if [[ -z "$branch_name" ]] || [[ "$branch_name" =~ ^[0-9a-f]{7,}$ ]] || [[ "$branch_name" == "HEAD" ]]; then
continue
fi
gone_branches+=("$branch_name")
done < <(command git branch -vv 2>/dev/null | grep ': gone]')
if [[ ${#gone_branches[@]} -eq 0 ]]; then
echo "__NONE__"
exit 0
fi
for branch in "${gone_branches[@]}"; do
echo "$branch"
done

123
plugins/compound-engineering/skills/git-commit-push-pr/SKILL.md Normal file
View File

@@ -0,0 +1,123 @@
---
name: git-commit-push-pr
description: Commit, push, and open a PR with an adaptive, value-first description. Use when the user says "commit and PR", "push and open a PR", "ship this", "create a PR", "open a pull request", "commit push PR", or wants to go from working changes to an open pull request in one step. Produces PR descriptions that scale in depth with the complexity of the change, avoiding cookie-cutter templates.
---
# Git Commit, Push, and PR
Go from working tree changes to an open pull request in a single workflow. The key differentiator of this skill is PR descriptions that communicate *value and intent* proportional to the complexity of the change.
## Workflow
### Step 1: Gather context
Run these commands. Use `command git` to bypass aliases and RTK proxies.
```bash
command git status
command git diff HEAD
command git branch --show-current
command git log --oneline -10
```
If there are no changes, report that and stop.
### Step 2: Determine conventions
Follow this priority order for commit messages *and* PR titles:
1. **Repo conventions already in context** -- If project instructions (AGENTS.md, CLAUDE.md, or similar) are loaded and specify conventions, follow those. Do not re-read these files; they are loaded at session start.
2. **Recent commit history** -- If no explicit convention exists, match the pattern visible in the last 10 commits.
3. **Default: conventional commits** -- `type(scope): description` as the fallback.
### Step 3: Branch, stage, and commit
1. If on `main` or the repo's default branch, create a descriptive feature branch first (`command git checkout -b <branch-name>`). Derive the branch name from the change content.
2. Before staging everything together, scan the changed files for naturally distinct concerns. If modified files clearly group into separate logical changes (e.g., a refactor in one set of files and a new feature in another), create separate commits for each group. Keep this lightweight -- group at the **file level only** (no `git add -p`), split only when obvious, and aim for two or three logical commits at most. If it's ambiguous, one commit is fine.
3. Stage relevant files by name. Avoid `git add -A` or `git add .` to prevent accidentally including sensitive files.
4. Commit following the conventions from Step 2. Use a heredoc for the message.
### Step 4: Push
```bash
command git push -u origin HEAD
```
### Step 5: Write the PR description
This is the most important step. The description must be **adaptive** -- its depth should match the complexity of the change. A one-line bugfix does not need a table of performance results. A large architectural change should not be a bullet list.
#### Sizing the change
Assess the PR along two axes before writing:
- **Size**: How many files changed? How large is the diff?
- **Complexity**: Is this a straightforward change (rename, dependency bump, typo fix) or does it involve design decisions, trade-offs, new patterns, or cross-cutting concerns?
Use this to select the right description depth:
| Change profile | Description approach |
|---|---|
| Small + simple (typo, config, dep bump) | 1-2 sentences, no headers. Total body under ~300 characters. |
| Small + non-trivial (targeted bugfix, behavioral change) | Short "Problem / Fix" narrative, ~3-5 sentences. Enough for a reviewer to understand *why* without reading the diff. No headers needed unless there are two distinct concerns. |
| Medium feature or refactor | Summary paragraph, then a section explaining what changed and why. Call out design decisions. |
| Large or architecturally significant | Full narrative: problem context, approach chosen (and why), key decisions, migration notes or rollback considerations if relevant. |
| Performance improvement | Include before/after measurements if available. A markdown table is effective here. |
**Brevity matters for small changes.** A 3-line bugfix with a 20-line PR description signals the author didn't calibrate. Match the weight of the description to the weight of the change. When in doubt, shorter is better -- reviewers can read the diff.
#### Writing principles
- **Lead with value**: The first sentence should tell the reviewer *why this PR exists*, not *what files changed*. "Fixes timeout errors during batch exports" beats "Updated export_handler.py and config.yaml".
- **Explain the non-obvious**: If the diff is self-explanatory, don't narrate it. Spend description space on things the diff *doesn't* show: why this approach, what was considered and rejected, what the reviewer should pay attention to.
- **Use structure when it earns its keep**: Headers, bullet lists, and tables are tools -- use them when they aid comprehension, not as mandatory template sections. An empty "## Breaking Changes" section adds noise.
- **Markdown tables for data**: When there are before/after comparisons, performance numbers, or option trade-offs, a table communicates density well. Example:
```markdown
| Metric | Before | After |
|--------|--------|-------|
| p95 latency | 340ms | 120ms |
| Memory (peak) | 2.1GB | 1.4GB |
```
- **No empty sections**: If a section (like "Breaking Changes" or "Migration Guide") doesn't apply, omit it entirely. Do not include it with "N/A" or "None".
- **Test plan -- only when it adds value**: Include a test plan section when the testing approach is non-obvious: edge cases the reviewer might not think of, verification steps for behavior that's hard to see in the diff, or scenarios that require specific setup. Omit it for straightforward changes where the tests are self-explanatory or where "run the tests" is the only useful guidance. A test plan for "verify the typo is fixed" is noise.
#### Numbering and references
**Never prefix list items with `#`** in PR descriptions. GitHub interprets `#1`, `#2`, etc. as issue/PR references and auto-links them. Instead of:
```markdown
## Changes
#1. Updated the parser
#2. Fixed the validation
```
Write:
```markdown
## Changes
1. Updated the parser
2. Fixed the validation
```
When referencing actual GitHub issues or PRs, use the full format: `org/repo#123` or the full URL. Never use bare `#123` unless you have verified it refers to the correct issue in the current repository.
### Step 6: Create the PR
```bash
command gh pr create --title "the pr title" --body "$(cat <<'EOF'
PR description here
EOF
)"
```
Keep the PR title under 72 characters. The title follows the same convention as commit messages (Step 2).
### Step 7: Report
Output the PR URL so the user can navigate to it directly.
## Important: Use `command git` and `command gh`
Always invoke git as `command git` and gh as `command gh` in shell commands. This bypasses shell aliases and tools like RTK (Rust Token Killer) that proxy commands.

68
plugins/compound-engineering/skills/git-commit/SKILL.md Normal file
View File

@@ -0,0 +1,68 @@
---
name: git-commit
description: Create a git commit with a clear, value-communicating message. Use when the user says "commit", "commit this", "save my changes", "create a commit", or wants to commit staged or unstaged work. Produces well-structured commit messages that follow repo conventions when they exist, and defaults to conventional commit format otherwise.
---
# Git Commit
Create a single, well-crafted git commit from the current working tree changes.
## Workflow
### Step 1: Gather context
Run these commands to understand the current state. Use `command git` to bypass aliases and RTK proxies.
```bash
command git status
command git diff HEAD
command git branch --show-current
command git log --oneline -10
```
If there are no changes (nothing staged, nothing modified), report that and stop.
### Step 2: Determine commit message convention
Follow this priority order:
1. **Repo conventions already in context** -- If project instructions (AGENTS.md, CLAUDE.md, or similar) are already loaded and specify commit message conventions, follow those. Do not re-read these files; they are loaded at session start.
2. **Recent commit history** -- If no explicit convention is documented, examine the 10 most recent commits from Step 1. If a clear pattern emerges (e.g., conventional commits, ticket prefixes, emoji prefixes), match that pattern.
3. **Default: conventional commits** -- If neither source provides a pattern, use conventional commit format: `type(scope): description` where type is one of `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`, `style`, `build`.
### Step 3: Consider logical commits
Before staging everything together, scan the changed files for naturally distinct concerns. If modified files clearly group into separate logical changes (e.g., a refactor in one directory and a new feature in another, or test files for a different change than source files), create separate commits for each group.
Keep this lightweight:
- Group at the **file level only** -- do not use `git add -p` or try to split hunks within a file.
- If the separation is obvious (different features, unrelated fixes), split. If it's ambiguous, one commit is fine.
- Two or three logical commits is the sweet spot. Do not over-slice into many tiny commits.
### Step 4: Stage and commit
Stage the relevant files. Prefer staging specific files by name over `git add -A` or `git add .` to avoid accidentally including sensitive files (.env, credentials) or unrelated changes.
Write the commit message:
- **Subject line**: Concise, imperative mood, focused on *why* not *what*. Follow the convention determined in Step 2.
- **Body** (when needed): Add a body separated by a blank line for non-trivial changes. Explain motivation, trade-offs, or anything a future reader would need. Omit the body for obvious single-purpose changes.
Use a heredoc to preserve formatting:
```bash
command git commit -m "$(cat <<'EOF'
type(scope): subject line here
Optional body explaining why this change was made,
not just what changed.
EOF
)"
```
### Step 5: Confirm
Run `command git status` after the commit to verify success. Report the commit hash(es) and subject line(s).
## Important: Use `command git`
Always invoke git as `command git` in shell commands. This bypasses shell aliases and tools like RTK (Rust Token Killer) that proxy git commands.