firefrost-gaming/claude-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Dev (#249)

Browse Source 
* docs: restructure README.md — 2,539 → 209 lines (#247)

- Cut from 2,539 lines / 73 sections to 209 lines / 18 sections
- Consolidated 4 install methods into one unified section
- Moved all skill details to domain-level READMEs (linked from table)
- Front-loaded value prop and keywords for SEO
- Added POWERFUL tier highlight section
- Added skill-security-auditor showcase section
- Removed stale Q4 2025 roadmap, outdated ROI claims, duplicate content
- Fixed all internal links
- Clean heading hierarchy (H2 for main sections only)

Closes #233

Co-authored-by: Leo <leo@openclaw.ai>

* fix: enhance 5 skills with scripts, references, and Anthropic best practices (#248)

* fix(skill): enhance git-worktree-manager with scripts, references, and Anthropic best practices

* fix(skill): enhance mcp-server-builder with scripts, references, and Anthropic best practices

* fix(skill): enhance changelog-generator with scripts, references, and Anthropic best practices

* fix(skill): enhance ci-cd-pipeline-builder with scripts, references, and Anthropic best practices

* fix(skill): enhance prompt-engineer-toolkit with scripts, references, and Anthropic best practices

* docs: update README, CHANGELOG, and plugin metadata

* fix: correct marketing plugin count, expand thin references

---------

Co-authored-by: Leo <leo@openclaw.ai>

---------

Co-authored-by: Leo <leo@openclaw.ai>
This commit is contained in:
Alireza Rezvani
2026-03-04 08:38:06 +01:00
committed by GitHub
parent 3960661ae5
commit 3d9d1d2d92
39 changed files with 3835 additions and 4711 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
engineering/git-worktree-manager/SKILL.md
View File

@@ -6,152 +6,183 @@
## Overview
The Git Worktree Manager skill provides systematic management of Git worktrees for parallel development workflows. It handles worktree creation with automatic port allocation, environment file management, secret copying, and cleanup — enabling developers to run multiple Claude Code instances on separate features simultaneously without conflicts.
Use this skill to run parallel feature work safely with Git worktrees. It standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app without stepping on another branch.
This skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree.
## Core Capabilities
- **Worktree Lifecycle Management** — create, list, switch, and cleanup worktrees with automated setup
- **Port Allocation & Isolation** — automatic port assignment per worktree to avoid dev server conflicts
- **Environment Synchronization** — copy .env files, secrets, and config between main and worktrees
- **Docker Compose Overrides** — generate per-worktree port override files for multi-service stacks
- **Conflict Prevention** — detect and warn about shared resources, database names, and API endpoints
- **Cleanup & Pruning** — safe removal with stale branch detection and uncommitted work warnings
- Create worktrees from new or existing branches with deterministic naming
- Auto-allocate non-conflicting ports per worktree and persist assignments
- Copy local environment files (`.env*`) from main repo to new worktree
- Optionally install dependencies based on lockfile detection
- Detect stale worktrees and uncommitted changes before cleanup
- Identify merged branches and safely remove outdated worktrees
## When to Use This Skill
## When to Use
- Running multiple Claude Code sessions on different features simultaneously
- Working on a hotfix while a feature branch has uncommitted work
- Reviewing a PR while continuing development on your branch
- Parallel CI/testing against multiple branches
- Monorepo development with isolated package changes
- You need 2+ concurrent branches open locally
- You want isolated dev servers for feature, hotfix, and PR validation
- You are working with multiple agents that must not share a branch
- Your current branch is blocked but you need to ship a quick fix now
- You want repeatable cleanup instead of ad-hoc `rm -rf` operations
## Worktree Creation Workflow
## Key Workflows
### Step 1: Create Worktree
### 1. Create a Fully-Prepared Worktree
1. Pick a branch name and worktree name.
2. Run the manager script (creates branch if missing).
3. Review generated port map.
4. Start app using allocated ports.
```bash
# Create worktree for a new feature branch
git worktree add ../project-feature-auth -b feature/auth
# Create worktree from an existing remote branch
git worktree add ../project-fix-123 origin/fix/issue-123
# Create worktree with tracking
git worktree add --track -b feature/new-api ../project-new-api origin/main
python scripts/worktree_manager.py \
--repo . \
--branch feature/new-auth \
--name wt-auth \
--base-branch main \
--install-deps \
--format text
```
### Step 2: Environment Setup
After creating the worktree, automatically:
1. **Copy environment files:**
```bash
cp .env ../project-feature-auth/.env
cp .env.local ../project-feature-auth/.env.local 2>/dev/null
```
2. **Install dependencies:**
```bash
cd ../project-feature-auth
[ -f "pnpm-lock.yaml" ] && pnpm install
[ -f "yarn.lock" ] && yarn install
[ -f "package-lock.json" ] && npm install
[ -f "bun.lockb" ] && bun install
```
3. **Allocate ports:**
```
Main worktree: localhost:3000 (dev), :5432 (db), :6379 (redis)
Worktree 1: localhost:3010 (dev), :5442 (db), :6389 (redis)
Worktree 2: localhost:3020 (dev), :5452 (db), :6399 (redis)
```
### Step 3: Docker Compose Override
For Docker Compose projects, generate per-worktree override:
```yaml
# docker-compose.worktree.yml (auto-generated)
services:
app:
ports:
- "3010:3000"
db:
ports:
- "5442:5432"
redis:
ports:
- "6389:6379"
```
Usage: `docker compose -f docker-compose.yml -f docker-compose.worktree.yml up`
### Step 4: Database Isolation
If you use JSON automation input:
```bash
# Option A: Separate database per worktree
createdb myapp_feature_auth
# Option B: DATABASE_URL override
echo 'DATABASE_URL="postgresql://localhost:5442/myapp_wt1"' >> .env.local
# Option C: SQLite — file-based, automatic isolation
cat config.json | python scripts/worktree_manager.py --format json
# or
python scripts/worktree_manager.py --input config.json --format json
```
## Monorepo Optimization
### 2. Run Parallel Sessions
Combine worktrees with sparse checkout for large repos:
Recommended convention:
- Main repo: integration branch (`main`/`develop`) on default port
- Worktree A: feature branch + offset ports
- Worktree B: hotfix branch + next offset
Each worktree contains `.worktree-ports.json` with assigned ports.
### 3. Cleanup with Safety Checks
1. Scan all worktrees and stale age.
2. Inspect dirty trees and branch merge status.
3. Remove only merged + clean worktrees, or force explicitly.
```bash
git worktree add --no-checkout ../project-packages-only
cd ../project-packages-only
git sparse-checkout init --cone
git sparse-checkout set packages/shared packages/api
git checkout feature/api-refactor
python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text
```
## Claude Code Integration
### 4. Docker Compose Pattern
Each worktree gets auto-generated CLAUDE.md:
Use per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to `docker-compose.worktree.yml`.
```markdown
# Worktree: feature/auth
# Dev server port: 3010
# Created: 2026-03-01
See [docker-compose-patterns.md](references/docker-compose-patterns.md) for concrete templates.
## Scope
Focus on changes related to this branch only.
### 5. Port Allocation Strategy
## Commands
- Dev: PORT=3010 npm run dev
- Test: npm test -- --related
- Lint: npm run lint
```
Default strategy is `base + (index * stride)` with collision checks:
Run parallel sessions:
```bash
# Terminal 1: Main feature
cd ~/project && claude
# Terminal 2: Hotfix
cd ~/project-hotfix && claude
# Terminal 3: PR review
cd ~/project-pr-review && claude
```
- App: `3000`
- Postgres: `5432`
- Redis: `6379`
- Stride: `10`
See [port-allocation-strategy.md](references/port-allocation-strategy.md) for the full strategy and edge cases.
## Script Interfaces
- `python scripts/worktree_manager.py --help`
- Create/list worktrees
- Allocate/persist ports
- Copy `.env*` files
- Optional dependency installation
- `python scripts/worktree_cleanup.py --help`
- Stale detection by age
- Dirty-state detection
- Merged-branch detection
- Optional safe removal
Both tools support stdin JSON and `--input` file mode for automation pipelines.
## Common Pitfalls
1. **Shared node_modules** — Worktrees share git dir but NOT node_modules. Always install deps.
2. **Port conflicts** — Two dev servers on :3000 = silent failures. Always allocate unique ports.
3. **Database migrations** — Migrations in one worktree affect all if sharing same DB. Isolate.
4. **Git hooks** — Live in `.git/hooks` (shared). Worktree-specific hooks need symlinks.
5. **IDE confusion** — VSCode may show wrong branch. Open as separate window.
6. **Stale worktrees** — Prune regularly: `git worktree prune`.
1. Creating worktrees inside the main repo directory
2. Reusing `localhost:3000` across all branches
3. Sharing one database URL across isolated feature branches
4. Removing a worktree with uncommitted changes
5. Forgetting to prune old metadata after branch deletion
6. Assuming merged status without checking against the target branch
## Best Practices
1. Name worktrees by purpose: `project-auth`, `project-hotfix-123`, `project-pr-456`
2. Never create worktrees inside the main repo directory
3. Keep worktrees short-lived — merge and cleanup within days
4. Use the setup script — manual creation skips env/port/deps
5. One Claude Code instance per worktree — isolation is the point
6. Commit before switching — even WIP commits prevent lost work
1. One branch per worktree, one agent per worktree.
2. Keep worktrees short-lived; remove after merge.
3. Use a deterministic naming pattern (`wt-<topic>`).
4. Persist port mappings in file, not memory or terminal notes.
5. Run cleanup scan weekly in active repos.
6. Use `--format json` for machine flows and `--format text` for human review.
7. Never force-remove dirty worktrees unless changes are intentionally discarded.
## Validation Checklist
Before claiming setup complete:
1. `git worktree list` shows expected path + branch.
2. `.worktree-ports.json` exists and contains unique ports.
3. `.env` files copied successfully (if present in source repo).
4. Dependency install command exits with code `0` (if enabled).
5. Cleanup scan reports no unintended stale dirty trees.
## References
- [port-allocation-strategy.md](references/port-allocation-strategy.md)
- [docker-compose-patterns.md](references/docker-compose-patterns.md)
- [README.md](README.md) for quick start and installation details
## Decision Matrix
Use this quick selector before creating a new worktree:
- Need isolated dependencies and server ports -> create a new worktree
- Need only a quick local diff review -> stay on current tree
- Need hotfix while feature branch is dirty -> create dedicated hotfix worktree
- Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day
## Operational Checklist
### Before Creation
1. Confirm main repo has clean baseline or intentional WIP commits.
2. Confirm target branch naming convention.
3. Confirm required base branch exists (`main`/`develop`).
4. Confirm no reserved local ports are already occupied by non-repo services.
### After Creation
1. Verify `git status` branch matches expected branch.
2. Verify `.worktree-ports.json` exists.
3. Verify app boots on allocated app port.
4. Verify DB and cache endpoints target isolated ports.
### Before Removal
1. Verify branch has upstream and is merged when intended.
2. Verify no uncommitted files remain.
3. Verify no running containers/processes depend on this worktree path.
## CI and Team Integration
- Use worktree path naming that maps to task ID (`wt-1234-auth`).
- Include the worktree path in terminal title to avoid wrong-window commits.
- In automated setups, persist creation metadata in CI artifacts/logs.
- Trigger cleanup report in scheduled jobs and post summary to team channel.
## Failure Recovery
- If `git worktree add` fails due to existing path: inspect path, do not overwrite.
- If dependency install fails: keep worktree created, mark status and continue manual recovery.
- If env copy fails: continue with warning and explicit missing file list.
- If port allocation collides with external service: rerun with adjusted base ports.