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

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