{"id":"9e8ebe53-fe98-4ae8-a216-a025117ddeaf","shortId":"4Lmvsv","kind":"skill","title":"using-git-worktrees","tagline":"Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification","description":"# Using Git Worktrees\n\n## Overview\n\nGit worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.\n\n**Core principle:** Systematic directory selection + safety verification = reliable isolation.\n\n**Announce at start:** \"I'm using the using-git-worktrees skill to set up an isolated workspace.\"\n\n## Directory Selection Process\n\nFollow this priority order:\n\n### 1. Check Existing Directories\n\n```bash\n# Check in priority order\nls -d .worktrees 2>/dev/null     # Preferred (hidden)\nls -d worktrees 2>/dev/null      # Alternative\n```\n\n**If found:** Use that directory. If both exist, `.worktrees` wins.\n\n### 2. Check CLAUDE.md\n\n```bash\ngrep -i \"worktree.*director\" CLAUDE.md 2>/dev/null\n```\n\n**If preference specified:** Use it without asking.\n\n### 3. Ask User\n\nIf no directory exists and no CLAUDE.md preference:\n\n```\nNo worktree directory found. Where should I create worktrees?\n\n1. .worktrees/ (project-local, hidden)\n2. ~/.config/superpowers/worktrees/<project-name>/ (global location)\n\nWhich would you prefer?\n```\n\n## Safety Verification\n\n### For Project-Local Directories (.worktrees or worktrees)\n\n**MUST verify directory is ignored before creating worktree:**\n\n```bash\n# Check if directory is ignored (respects local, global, and system gitignore)\ngit check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null\n```\n\n**If NOT ignored:**\n\nPer Jesse's rule \"Fix broken things immediately\":\n1. Add appropriate line to .gitignore\n2. Commit the change\n3. Proceed with worktree creation\n\n**Why critical:** Prevents accidentally committing worktree contents to repository.\n\n### For Global Directory (~/.config/superpowers/worktrees)\n\nNo .gitignore verification needed - outside project entirely.\n\n## Creation Steps\n\n### 1. Detect Project Name\n\n```bash\nproject=$(basename \"$(git rev-parse --show-toplevel)\")\n```\n\n### 2. Create Worktree\n\n```bash\n# Determine full path\ncase $LOCATION in\n  .worktrees|worktrees)\n    path=\"$LOCATION/$BRANCH_NAME\"\n    ;;\n  ~/.config/superpowers/worktrees/*)\n    path=\"~/.config/superpowers/worktrees/$project/$BRANCH_NAME\"\n    ;;\nesac\n\n# Create worktree with new branch\ngit worktree add \"$path\" -b \"$BRANCH_NAME\"\ncd \"$path\"\n```\n\n### 3. Run Project Setup\n\nAuto-detect and run appropriate setup:\n\n```bash\n# Node.js\nif [ -f package.json ]; then npm install; fi\n\n# Rust\nif [ -f Cargo.toml ]; then cargo build; fi\n\n# Python\nif [ -f requirements.txt ]; then pip install -r requirements.txt; fi\nif [ -f pyproject.toml ]; then poetry install; fi\n\n# Go\nif [ -f go.mod ]; then go mod download; fi\n```\n\n### 4. Verify Clean Baseline\n\nRun tests to ensure worktree starts clean:\n\n```bash\n# Examples - use project-appropriate command\nnpm test\ncargo test\npytest\ngo test ./...\n```\n\n**If tests fail:** Report failures, ask whether to proceed or investigate.\n\n**If tests pass:** Report ready.\n\n### 5. Report Location\n\n```\nWorktree ready at <full-path>\nTests passing (<N> tests, 0 failures)\nReady to implement <feature-name>\n```\n\n## Quick Reference\n\n| Situation | Action |\n|-----------|--------|\n| `.worktrees/` exists | Use it (verify ignored) |\n| `worktrees/` exists | Use it (verify ignored) |\n| Both exist | Use `.worktrees/` |\n| Neither exists | Check CLAUDE.md → Ask user |\n| Directory not ignored | Add to .gitignore + commit |\n| Tests fail during baseline | Report failures + ask |\n| No package.json/Cargo.toml | Skip dependency install |\n\n## Common Mistakes\n\n### Skipping ignore verification\n\n- **Problem:** Worktree contents get tracked, pollute git status\n- **Fix:** Always use `git check-ignore` before creating project-local worktree\n\n### Assuming directory location\n\n- **Problem:** Creates inconsistency, violates project conventions\n- **Fix:** Follow priority: existing > CLAUDE.md > ask\n\n### Proceeding with failing tests\n\n- **Problem:** Can't distinguish new bugs from pre-existing issues\n- **Fix:** Report failures, get explicit permission to proceed\n\n### Hardcoding setup commands\n\n- **Problem:** Breaks on projects using different tools\n- **Fix:** Auto-detect from project files (package.json, etc.)\n\n## Example Workflow\n\n```\nYou: I'm using the using-git-worktrees skill to set up an isolated workspace.\n\n[Check .worktrees/ - exists]\n[Verify ignored - git check-ignore confirms .worktrees/ is ignored]\n[Create worktree: git worktree add .worktrees/auth -b feature/auth]\n[Run npm install]\n[Run npm test - 47 passing]\n\nWorktree ready at /Users/jesse/myproject/.worktrees/auth\nTests passing (47 tests, 0 failures)\nReady to implement auth feature\n```\n\n## Red Flags\n\n**Never:**\n- Create worktree without verifying it's ignored (project-local)\n- Skip baseline test verification\n- Proceed with failing tests without asking\n- Assume directory location when ambiguous\n- Skip CLAUDE.md check\n\n**Always:**\n- Follow directory priority: existing > CLAUDE.md > ask\n- Verify directory is ignored for project-local\n- Auto-detect and run project setup\n- Verify clean test baseline\n\n## Integration\n\n**Called by:**\n- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows\n- **subagent-driven-development** - REQUIRED before executing any tasks\n- **executing-plans** - REQUIRED before executing any tasks\n- Any skill needing isolated workspace\n\n**Pairs with:**\n- **finishing-a-development-branch** - REQUIRED for cleanup after work complete","tags":["using","git","worktrees","synapse","deve1993","agent-skills","ai-agents","ai-coding","ai-workspace","anti-poisoning","auto-learning-ai","automation"],"capabilities":["skill","source-deve1993","skill-using-git-worktrees","topic-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workspace","topic-anti-poisoning","topic-auto-learning-ai","topic-automation","topic-claude-code","topic-code-quality","topic-cursor","topic-developer-tools","topic-devops"],"categories":["Synapse"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/deve1993/Synapse/using-git-worktrees","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add deve1993/Synapse","source_repo":"https://github.com/deve1993/Synapse","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (5,380 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:14.756Z","embedding":null,"createdAt":"2026-05-18T13:21:48.034Z","updatedAt":"2026-05-18T19:14:14.756Z","lastSeenAt":"2026-05-18T19:14:14.756Z","tsv":"'/.config/superpowers/worktrees':164,255,295,297 '/cargo.toml':468 '/dev/null':100,107,129,208,216 '/users/jesse/myproject/.worktrees/auth':605 '0':420,610 '1':87,157,228,265 '2':99,106,119,128,163,207,215,234,279 '3':137,238,316 '4':370,679 '47':600,608 '5':411 'accident':246 'action':428 'add':229,309,454,590 'allow':45 'altern':108 'alway':486,648 'ambigu':644 'announc':62 'appropri':230,325,386 'approv':684 'ask':136,138,400,449,464,512,639,654 'assum':498,640 'auth':615 'auto':321,548,664 'auto-detect':320,547,663 'b':311,592 'baselin':373,461,631,673 'basenam':271 'bash':91,122,189,269,282,327,381 'brainstorm':677 'branch':49,293,299,306,312,716 'break':540 'broken':225 'bug':522 'build':342 'call':675 'cargo':341,390 'cargo.toml':339 'case':286 'cd':314 'chang':237 'check':88,92,120,190,203,211,447,490,573,580,647 'check-ignor':202,210,489,579 'claude.md':121,127,146,448,511,646,653 'clean':372,380,671 'cleanup':719 'command':387,538 'commit':235,247,457 'common':472 'complet':722 'confirm':582 'content':249,479 'convent':506 'core':53 'creat':21,38,155,187,280,302,493,502,586,620 'creation':242,263 'critic':244 'current':14 'd':97,104 'depend':470 'design':682 'detect':266,322,549,665 'determin':283 'develop':691,715 'differ':544 'director':126 'directori':27,56,80,90,113,142,150,177,183,192,254,451,499,641,650,656 'distinguish':520 'download':368 'driven':690 'ensur':377 'entir':262 'esac':301 'etc':554 'exampl':382,555 'execut':18,694,698,702 'executing-plan':697 'exist':89,116,143,430,436,442,446,510,526,575,652 'explicit':532 'f':330,338,346,355,363 'fail':397,459,515,636 'failur':399,421,463,530,611 'featur':8,616 'feature/auth':593 'fi':335,343,353,360,369 'file':552 'finish':713 'finishing-a-development-branch':712 'fix':224,485,507,528,546 'flag':618 'follow':83,508,649,687 'found':110,151 'full':284 'get':480,531 'git':3,23,33,36,71,201,209,272,307,483,488,564,578,588 'gitignor':200,233,257,456 'global':165,197,253 'go':361,366,393 'go.mod':364 'grep':123 'hardcod':536 'hidden':102,162 'ignor':185,194,204,212,219,434,440,453,475,491,577,581,585,626,658 'immedi':227 'implement':19,424,614,686 'inconsist':503 'instal':334,350,359,471,596 'integr':674 'investig':405 'isol':12,22,39,61,78,571,708 'issu':527 'jess':221 'line':231 'local':161,176,196,496,629,662 'locat':166,287,292,413,500,642 'ls':96,103 'm':66,559 'mistak':473 'mod':367 'multipl':48 'must':181 'name':268,294,300,313 'need':11,259,707 'neither':445 'never':619 'new':305,521 'node.js':328 'npm':333,388,595,598 'order':86,95 'outsid':260 'overview':35 'package.json':331,467,553 'package.json/cargo.toml':466 'pair':710 'pars':275 'pass':408,418,601,607 'path':285,291,296,310,315 'per':220 'permiss':533 'phase':678 'pip':349 'plan':20,699 'poetri':358 'pollut':482 'pre':525 'pre-exist':524 'prefer':101,131,147,170 'prevent':245 'principl':54 'prioriti':85,94,509,651 'problem':477,501,517,539 'proceed':239,403,513,535,634 'process':82 'project':160,175,261,267,270,298,318,385,495,505,542,551,628,661,668 'project-appropri':384 'project-loc':159,174,494,627,660 'pyproject.toml':356 'pytest':392 'python':344 'q':205,213 'quick':425 'r':351 'readi':410,415,422,603,612 'red':617 'refer':426 'reliabl':60 'report':398,409,412,462,529 'repositori':44,251 'requir':680,692,700,717 'requirements.txt':347,352 'respect':195 'rev':274 'rev-pars':273 'rule':223 'run':317,324,374,594,597,667 'rust':336 'safeti':30,58,171 'select':28,57,81 'set':75,568 'setup':319,326,537,669 'share':41 'show':277 'show-toplevel':276 'simultan':50 'situat':427 'skill':73,566,706 'skill-using-git-worktrees' 'skip':469,474,630,645 'smart':26 'source-deve1993' 'specifi':132 'start':7,64,379 'status':484 'step':264 'subag':689 'subagent-driven-develop':688 'switch':52 'system':199 'systemat':55 'task':696,704 'test':375,389,391,394,396,407,417,419,458,516,599,606,609,632,637,672 'thing':226 'tool':545 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workspace' 'topic-anti-poisoning' 'topic-auto-learning-ai' 'topic-automation' 'topic-claude-code' 'topic-code-quality' 'topic-cursor' 'topic-developer-tools' 'topic-devops' 'toplevel':278 'track':481 'use':2,5,32,67,70,111,133,383,431,437,443,487,543,560,563 'user':139,450 'using-git-worktre':1,69,562 'verif':31,59,172,258,476,633 'verifi':182,371,433,439,576,623,655,670 'violat':504 'whether':401 'win':118 'without':51,135,622,638 'work':9,46,721 'workflow':556 'workspac':15,40,79,572,709 'worktre':4,24,34,37,72,98,105,117,125,149,156,158,178,180,188,206,214,241,248,281,289,290,303,308,378,414,429,435,444,478,497,565,574,583,587,589,602,621 'worktrees/auth':591 'would':168","prices":[{"id":"2217e00a-c55b-4d55-a686-b45120652e92","listingId":"9e8ebe53-fe98-4ae8-a216-a025117ddeaf","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"deve1993","category":"Synapse","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:48.034Z"}],"sources":[{"listingId":"9e8ebe53-fe98-4ae8-a216-a025117ddeaf","source":"github","sourceId":"deve1993/Synapse/using-git-worktrees","sourceUrl":"https://github.com/deve1993/Synapse/tree/main/skills/using-git-worktrees","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:48.034Z","lastSeenAt":"2026-05-18T19:14:14.756Z"}],"details":{"listingId":"9e8ebe53-fe98-4ae8-a216-a025117ddeaf","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"deve1993","slug":"using-git-worktrees","github":{"repo":"deve1993/Synapse","stars":7,"topics":["agent-skills","ai-agents","ai-coding","ai-workspace","anti-poisoning","auto-learning-ai","automation","claude-code","code-quality","cursor","developer-tools","devops","fullstack-development","multi-agent-systems","nextjs","opencode","persistent-memory","self-improving","telegram-bot"],"license":"other","html_url":"https://github.com/deve1993/Synapse","pushed_at":"2026-05-15T21:34:01Z","description":"Self-improving AI brain for Claude Code & Desktop — 28 MCP tools, 253 skills, collective memory, project tracking, work logs. One server, all your sessions share the same knowledge. Deploy on Coolify in 2 minutes.","skill_md_sha":"faabe4059bafe4209f3134d52a56b1ca59f187c2","skill_md_path":"skills/using-git-worktrees/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/deve1993/Synapse/tree/main/skills/using-git-worktrees"},"layout":"multi","source":"github","category":"Synapse","frontmatter":{"name":"using-git-worktrees","description":"Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification"},"skills_sh_url":"https://skills.sh/deve1993/Synapse/using-git-worktrees"},"updatedAt":"2026-05-18T19:14:14.756Z"}}