zhongwei/gh-poindexter12-waypoint-workflows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:47:41 +08:00
commit f9c8c37217
13 changed files with 6174 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1049
skills/working-tree/REFERENCE.md Normal file
View File

File diff suppressed because it is too large Load Diff

224
skills/working-tree/SKILL.md Normal file
View File

@@ -0,0 +1,224 @@
---
name: worktree-guide
description: 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.
---
# Git Worktree Guide
Quick reference and templates for git worktree workflows with AI metadata integration.
## Progressive Disclosure
### Initial Response
**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:**
- Create worktree: `/working-tree:new <branch-name>`
- List worktrees: `/working-tree:list`
- Check status: `/working-tree:status`
- Remove worktree: `/working-tree:destroy <path>`
- Add metadata: `/working-tree:adopt`
**What would you like to know more about?**
1. Mode semantics (main, feature, bugfix, experiment, review)
2. Metadata file structure and templates
3. Comprehensive best practices guide
4. Strategic organization patterns
### On Request
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
## Mode Semantics Quick Reference
### main
**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
### feature
**Purpose:** Active development of new features
**Restrictions:** None, experimentation encouraged
**Use For:** New features, enhancements, active work
**AI Behavior:** Helpful, suggests improvements freely
### bugfix
**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
### experiment
**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
### review
**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
## Metadata File Structure
### .ai-context.json
```json
{
"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 name
- `mode`: One of the 5 modes above
- `created`: ISO 8601 UTC timestamp
- `description`: Freeform text explaining purpose
### README.working-tree.md
Generated automatically with worktree details, mode semantics, and paths.
## Templates
### Available Templates
Located in `templates/` directory:
1. `ai-context.json.template` - Metadata file template with examples
2. `README.working-tree.template` - README template with placeholders
To view templates:
- Ask "show me the metadata template"
- Ask "show me the README template"
## Common Patterns
### Pattern 1: Feature Development
```bash
/working-tree:new feature/user-auth --mode feature --description "Implement OAuth2"
```
Work in isolation, merge when ready.
### Pattern 2: Production Hotfix
```bash
/working-tree:new bugfix/critical-security-fix --mode bugfix
```
Quick surgical fix, minimizes risk.
### Pattern 3: Experimentation
```bash
/working-tree:new exp/try-new-framework --mode experiment
```
Prototype freely, discard if needed.
### Pattern 4: Code Review
```bash
/working-tree:new review/pr-123 --mode review --description "Review user auth PR"
```
Review without disrupting current work.
## Supporting Files
- **REFERENCE.md**: Comprehensive guide with detailed best practices, naming conventions, workflows, and advanced patterns
- **templates/ai-context.json.template**: Copy-paste template for manual metadata creation
- **templates/README.working-tree.template**: Template for worktree README
## Quick Tips
**DO:**
- Use descriptive branch names: `feature/user-dashboard`
- Add descriptions to worktrees: `--description "User settings page"`
- Run `/working-tree:list` regularly to see active work
- Choose appropriate mode for context
**DON'T:**
- Create worktree for same branch twice
- Use generic names: `test`, `temp`, `new`
- Forget to clean up: `/working-tree:destroy` when done
- Ignore uncommitted changes before destroying
## For More Detail
**Comprehensive Guide:**
Ask to see `REFERENCE.md` for:
- Detailed mode usage guidelines
- Naming conventions and patterns
- Multi-worktree organization strategies
- Troubleshooting common issues
- Team collaboration workflows
- CI/CD integration patterns
**Strategic Consulting:**
For complex worktree organization questions, invoke the `working-tree-consultant` agent:
- "Help me organize my worktrees"
- "Review my worktree strategy"
- "Migrate to worktree workflow"
## Examples
### Example 1: Quick Mode Check
```
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"
```
### Example 2: Template Request
```
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
```
### Example 3: Best Practices Request
```
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
```
## Related
- Commands: `/working-tree:new`, `/working-tree:list`, `/working-tree:status`, `/working-tree:destroy`, `/working-tree:adopt`
- Agent: `working-tree-consultant` for strategic guidance
- Documentation: See REFERENCE.md for comprehensive coverage

310
skills/working-tree/templates/README.working-tree.template Normal file
View File

@@ -0,0 +1,310 @@
# Worktree: REPLACE_WITH_WORKTREE_NAME
**Branch:** `REPLACE_WITH_BRANCH_NAME`
**Mode:** `REPLACE_WITH_MODE`
**Created:** REPLACE_WITH_TIMESTAMP
## Purpose
REPLACE_WITH_DESCRIPTION (or "No description provided")
## Mode Semantics
- **main**: Minimal changes, stable work only
- Use for: Production code, critical hotfixes
- Restrictions: No experimentation, minimal scope
- AI Behavior: Conservative, safety-focused
- **feature**: Active development, larger changes allowed
- Use for: New features, enhancements, most development
- Restrictions: None - be creative!
- AI Behavior: Helpful, proactive suggestions
- **bugfix**: Isolated, surgical fixes only
- Use for: Specific bug fixes, targeted corrections
- Restrictions: Minimal scope, no unrelated changes
- AI Behavior: Focused, warns about scope creep
- **experiment**: Prototypes, large swings, unsafe changes allowed
- Use for: POCs, technology spikes, learning
- Restrictions: None - can be messy
- AI Behavior: Aggressive suggestions, OK with rough code
- **review**: Documentation, analysis, audits
- Use for: Code review, security audits, understanding code
- Restrictions: Read-only mindset
- AI Behavior: Analytical, critical feedback
## About This Worktree
This directory is an independent Git worktree attached to the main repository.
- **Main repository:** REPLACE_WITH_MAIN_REPO_PATH
- **Worktree path:** REPLACE_WITH_WORKTREE_PATH
- **Branch:** REPLACE_WITH_BRANCH_NAME
- **Git directory:** Linked to main repository `.git/`
### What is a Git Worktree?
A git worktree allows you to check out multiple branches simultaneously in separate directories. All worktrees share the same repository history but have independent working directories.
**Benefits:**
- No need to `git stash` when switching contexts
- Work on multiple features in parallel
- Isolated dependencies and build artifacts
- Fast context switching (just `cd` to different directory)
### Metadata Files
**`.ai-context.json`** (Machine-Readable)
- JSON format for AI tools
- Contains: worktree, branch, mode, created, description
- Read automatically by Claude and other AI tools
**`README.working-tree.md`** (This File)
- Human-readable documentation
- Explains mode semantics and worktree info
- Generated automatically by `/working-tree:new` or `/working-tree:adopt`
## Quick Commands
### View Status
```bash
/working-tree:status
```
Show metadata for current worktree.
### List All Worktrees
```bash
/working-tree:list
```
See all worktrees in this repository with their metadata.
### Remove This Worktree
```bash
cd REPLACE_WITH_MAIN_REPO_PATH
/working-tree:destroy REPLACE_WITH_WORKTREE_PATH
```
Safely remove this worktree (preserves branch).
### Update Metadata
```bash
/working-tree:adopt --description "New description"
```
Update mode or description for this worktree.
## Workflow Tips
### Switching Between Worktrees
```bash
# From this worktree to another
cd ../other-worktree-name
# Back to this worktree
cd REPLACE_WITH_WORKTREE_PATH
```
### Committing Changes
```bash
# Normal git workflow
git add .
git commit -m "Your commit message"
git push origin REPLACE_WITH_BRANCH_NAME
```
### Creating Pull Request
```bash
# After pushing commits
git push origin REPLACE_WITH_BRANCH_NAME
# Then create PR in GitHub/GitLab
```
### When Done With This Worktree
```bash
# 1. Ensure all changes are committed
git status
# 2. Push to remote
git push origin REPLACE_WITH_BRANCH_NAME
# 3. Create and merge PR
# 4. Remove worktree
cd REPLACE_WITH_MAIN_REPO_PATH
/working-tree:destroy REPLACE_WITH_WORKTREE_PATH
# 5. Optionally delete branch after PR merge
git branch -d REPLACE_WITH_BRANCH_NAME
```
## Related Worktrees
Use `/working-tree:list` to see all active worktrees for this repository.
## Documentation
- **Comprehensive Guide:** See `working-tree/skills/worktree-guide/REFERENCE.md`
- **Templates:** See `working-tree/skills/worktree-guide/templates/`
- **Strategic Guidance:** Invoke `working-tree-consultant` agent
---
**Auto-Generated:** This file was created automatically by the waypoint working-tree module.
**Update:** Run `/working-tree:adopt` to regenerate this file with updated information.
EXAMPLE COMPLETE FILE (Feature Development):
# Worktree: myapp-feature-user-auth
**Branch:** `feature/user-authentication`
**Mode:** `feature`
**Created:** 2025-11-23T10:30:00Z
## Purpose
Implement OAuth2 and JWT authentication with refresh token support
## Mode Semantics
- **main**: Minimal changes, stable work only
- Use for: Production code, critical hotfixes
- Restrictions: No experimentation, minimal scope
- AI Behavior: Conservative, safety-focused
- **feature**: Active development, larger changes allowed
- Use for: New features, enhancements, most development
- Restrictions: None - be creative!
- AI Behavior: Helpful, proactive suggestions
- **bugfix**: Isolated, surgical fixes only
- Use for: Specific bug fixes, targeted corrections
- Restrictions: Minimal scope, no unrelated changes
- AI Behavior: Focused, warns about scope creep
- **experiment**: Prototypes, large swings, unsafe changes allowed
- Use for: POCs, technology spikes, learning
- Restrictions: None - can be messy
- AI Behavior: Aggressive suggestions, OK with rough code
- **review**: Documentation, analysis, audits
- Use for: Code review, security audits, understanding code
- Restrictions: Read-only mindset
- AI Behavior: Analytical, critical feedback
## About This Worktree
This directory is an independent Git worktree attached to the main repository.
- **Main repository:** /Users/joe/Code/myapp
- **Worktree path:** /Users/joe/Code/myapp-feature-user-auth
- **Branch:** feature/user-authentication
- **Git directory:** Linked to main repository `.git/`
### What is a Git Worktree?
A git worktree allows you to check out multiple branches simultaneously in separate directories. All worktrees share the same repository history but have independent working directories.
**Benefits:**
- No need to `git stash` when switching contexts
- Work on multiple features in parallel
- Isolated dependencies and build artifacts
- Fast context switching (just `cd` to different directory)
### Metadata Files
**`.ai-context.json`** (Machine-Readable)
- JSON format for AI tools
- Contains: worktree, branch, mode, created, description
- Read automatically by Claude and other AI tools
**`README.working-tree.md`** (This File)
- Human-readable documentation
- Explains mode semantics and worktree info
- Generated automatically by `/working-tree:new` or `/working-tree:adopt`
## Quick Commands
### View Status
```bash
/working-tree:status
```
Show metadata for current worktree.
### List All Worktrees
```bash
/working-tree:list
```
See all worktrees in this repository with their metadata.
### Remove This Worktree
```bash
cd /Users/joe/Code/myapp
/working-tree:destroy /Users/joe/Code/myapp-feature-user-auth
```
Safely remove this worktree (preserves branch).
### Update Metadata
```bash
/working-tree:adopt --description "New description"
```
Update mode or description for this worktree.
## Workflow Tips
### Switching Between Worktrees
```bash
# From this worktree to another
cd ../myapp-feature-other
# Back to this worktree
cd /Users/joe/Code/myapp-feature-user-auth
```
### Committing Changes
```bash
# Normal git workflow
git add .
git commit -m "feat: add OAuth2 authentication provider"
git push origin feature/user-authentication
```
### Creating Pull Request
```bash
# After pushing commits
git push origin feature/user-authentication
# Then create PR in GitHub/GitLab
```
### When Done With This Worktree
```bash
# 1. Ensure all changes are committed
git status
# 2. Push to remote
git push origin feature/user-authentication
# 3. Create and merge PR
# 4. Remove worktree
cd /Users/joe/Code/myapp
/working-tree:destroy /Users/joe/Code/myapp-feature-user-auth
# 5. Optionally delete branch after PR merge
git branch -d feature/user-authentication
```
## Related Worktrees
Use `/working-tree:list` to see all active worktrees for this repository.
## Documentation
- **Comprehensive Guide:** See `working-tree/skills/worktree-guide/REFERENCE.md`
- **Templates:** See `working-tree/skills/worktree-guide/templates/`
- **Strategic Guidance:** Invoke `working-tree-consultant` agent
---
**Auto-Generated:** This file was created automatically by the waypoint working-tree module.
**Update:** Run `/working-tree:adopt` to regenerate this file with updated information.

121
skills/working-tree/templates/ai-context.json.template Normal file
View File

@@ -0,0 +1,121 @@
{
"worktree": "REPLACE_WITH_DIRECTORY_NAME",
"branch": "REPLACE_WITH_BRANCH_NAME",
"mode": "CHOOSE_ONE: main|feature|bugfix|experiment|review",
"created": "REPLACE_WITH_ISO8601_TIMESTAMP",
"description": "REPLACE_WITH_PURPOSE_DESCRIPTION"
}
EXAMPLES:
Example 1 - Feature Development:
{
"worktree": "myapp-feature-user-auth",
"branch": "feature/user-authentication",
"mode": "feature",
"created": "2025-11-23T10:30:00Z",
"description": "Implement OAuth2 and JWT authentication with refresh tokens"
}
Example 2 - Bug Fix:
{
"worktree": "api-server-bugfix-rate-limit",
"branch": "bugfix/rate-limit-bypass",
"mode": "bugfix",
"created": "2025-11-23T14:15:00Z",
"description": "Fix rate limiting bypass in authentication endpoint (issue #427)"
}
Example 3 - Experiment:
{
"worktree": "myapp-exp-graphql",
"branch": "exp/graphql-migration",
"mode": "experiment",
"created": "2025-11-23T09:00:00Z",
"description": "Evaluate GraphQL migration feasibility and performance impact"
}
Example 4 - Code Review:
{
"worktree": "myapp-review-pr-543",
"branch": "review/pr-543-user-auth",
"mode": "review",
"created": "2025-11-23T16:45:00Z",
"description": "Review PR #543 - User authentication refactor"
}
Example 5 - Main/Production:
{
"worktree": "myapp",
"branch": "main",
"mode": "main",
"created": "2025-11-23T08:00:00Z",
"description": "Production baseline for critical hotfixes only"
}
FIELD REFERENCE:
worktree:
- Directory name only (not full path)
- Should match your worktree directory name
- Example: "myapp-feature-user-auth"
branch:
- Full git branch name
- Must match actual git branch
- Example: "feature/user-authentication"
- Common prefixes: feature/, bugfix/, exp/, review/
mode:
- Must be one of: main, feature, bugfix, experiment, review
- main: Production code, minimal changes only
- feature: Active development, no restrictions
- bugfix: Surgical fixes, focused scope
- experiment: Prototypes, can be messy
- review: Code review and analysis
created:
- ISO 8601 format in UTC
- Format: YYYY-MM-DDTHH:MM:SSZ
- Must end with 'Z' (UTC timezone)
- Example: "2025-11-23T10:30:00Z"
- Generate with: date -u +"%Y-%m-%dT%H:%M:%SZ"
description:
- Freeform text explaining purpose
- Keep to one sentence if possible
- Include issue numbers if applicable
- Can be empty string: ""
- Examples:
- "Implement OAuth2 authentication"
- "Fix session timeout bug (issue #427)"
- "Prototype new GraphQL API"
- ""
AUTOMATED GENERATION:
Instead of creating this file manually, use commands:
/working-tree:new <branch-name> - Creates new worktree with metadata
/working-tree:adopt - Adds metadata to existing worktree
These commands auto-generate this file with correct values.
VALIDATION:
Valid JSON:
- Proper quotes (double quotes only)
- Comma after each field except last
- No trailing commas
- Valid UTF-8
Common Mistakes:
❌ Single quotes: {'worktree': 'name'}
✅ Double quotes: {"worktree": "name"}
❌ Missing comma: {"worktree": "name" "branch": "main"}
✅ Comma present: {"worktree": "name", "branch": "main"}
❌ Trailing comma: {"mode": "feature",}
✅ No trailing comma: {"mode": "feature"}
Validate with: jq . .ai-context.json