Stats
Actions
Tags
From workflows
Git worktree patterns, best practices, templates, and quick reference. Use when user asks about "worktree best practices", "worktree patterns", "git worktree help", "worktree template", "worktree mode semantics", "what are worktree modes", "explain worktree metadata", or needs guidance on worktree organization and workflows.
How this skill is triggered — by the user, by Claude, or both
Slash command
/workflows:skills/working-treeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Quick reference and templates for git worktree workflows with AI metadata integration.
Quick reference and templates for git worktree workflows with AI metadata integration.
Quick Overview:
Git worktrees let you checkout multiple branches simultaneously in separate directories. Each worktree has AI metadata (.ai-context.json) that helps tools understand context.
Quick Start:
/working-tree:new <branch-name>/working-tree:list/working-tree:status/working-tree:destroy <path>/working-tree:adoptWhat would you like to know more about?
Based on what you ask for, I can show you:
Mode Semantics → Detailed explanation of each mode Templates → Ready-to-use metadata templates Best Practices → Full reference guide (REFERENCE.md) Examples → Specific workflow examples
Purpose: Stable, production-ready code Restrictions: Minimal changes only, no experimentation Use For: Hotfixes, urgent production changes, stable baseline AI Behavior: Conservative suggestions, focus on safety
Purpose: Active development of new features Restrictions: None, experimentation encouraged Use For: New features, enhancements, active work AI Behavior: Helpful, suggests improvements freely
Purpose: Isolated, surgical bug fixes Restrictions: Minimal scope, no unrelated changes Use For: Specific bug fixes, targeted corrections AI Behavior: Focused on fix only, warns about scope creep
Purpose: Prototypes, spikes, research Restrictions: None, can be messy, expect to discard Use For: POCs, trying new technologies, A/B testing AI Behavior: Aggressive suggestions, OK with rough code
Purpose: Code review, auditing, documentation Restrictions: Read-only mindset, analysis only Use For: PR review, security audits, documentation work AI Behavior: Analytical, suggests improvements, no execution
{
"worktree": "directory-name",
"branch": "branch-name",
"mode": "main|feature|bugfix|experiment|review",
"created": "2025-11-23T12:34:56Z",
"description": "Purpose of this worktree"
}
Fields:
worktree: Directory name (not full path)branch: Git branch namemode: One of the 5 modes abovecreated: ISO 8601 UTC timestampdescription: Freeform text explaining purposeGenerated automatically with worktree details, mode semantics, and paths.
Located in templates/ directory:
ai-context.json.template - Metadata file template with examplesREADME.working-tree.template - README template with placeholdersTo view templates:
/working-tree:new feature/user-auth --mode feature --description "Implement OAuth2"
Work in isolation, merge when ready.
/working-tree:new bugfix/critical-security-fix --mode bugfix
Quick surgical fix, minimizes risk.
/working-tree:new exp/try-new-framework --mode experiment
Prototype freely, discard if needed.
/working-tree:new review/pr-123 --mode review --description "Review user auth PR"
Review without disrupting current work.
/working-tree:new i18n/zh-CN --description "Chinese Simplified translations"
/working-tree:new i18n/42-ja-JP --description "Japanese translations for issue #42"
Isolated i18n work for specific locale.
DO:
feature/user-dashboard--description "User settings page"/working-tree:list regularly to see active workDON'T:
test, temp, newworkflows, src, backend)/working-tree:destroy when doneComprehensive Guide:
Ask to see references/best-practices.md for:
Strategic Consulting:
For complex worktree organization questions, invoke the working-tree-consultant agent:
User: What mode should I use for a prototype?
Skill: For prototypes, use **experiment** mode.
Experiment mode:
- No restrictions, can be messy
- AI will be aggressive with suggestions
- Expect to discard if prototype fails
- Good for POCs and spikes
Command:
/working-tree:new exp/prototype-name --mode experiment --description "Testing new approach"
User: Show me the metadata template
Skill: Here's the .ai-context.json template:
[Shows content of templates/ai-context.json.template]
You can create this manually or use:
- /working-tree:new to auto-generate when creating
- /working-tree:adopt to auto-generate for existing worktree
User: What are worktree best practices?
Skill: **Quick Best Practices:**
1. **Naming**: Use clear, structured names (myapp-feature-user-auth)
2. **Modes**: Choose mode based on work type (see mode semantics above)
3. **Cleanup**: Remove worktrees when done (/working-tree:destroy)
4. **Metadata**: Always add descriptions
5. **Organization**: One feature = one worktree
**Want more detail?**
- See REFERENCE.md for comprehensive guide
- Invoke working-tree-consultant for strategic advice
/working-tree:new, /working-tree:list, /working-tree:status, /working-tree:destroy, /working-tree:adoptworking-tree-consultant for strategic guidancenpx claudepluginhub poindexter12/waypointAutomates Git worktree creation for isolated feature branches, listing, removal, and status checks. Copies env files like .env/.nvmrc and runs npm/yarn/pnpm/bun install.
Creates isolated git worktrees for parallel development without disrupting the main workspace. Includes safety verification to prevent accidental commits of worktree contents.
Manages git worktrees for parallel feature development. Automates creation, switching, and merging of worktrees for multi-feature workflows.