{"id":"7775b707-f947-452c-8a43-65dad6ae212a","shortId":"DfZ7nJ","kind":"skill","title":"using-git-worktrees","tagline":"Use when starting feature work that needs isolation from the current workspace, or when an implementation plan should run outside the active working tree.","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/aegis/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/aegis/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/aegis/worktrees/*)\n    path=\"~/.config/aegis/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","aegis","ganyuanran","add","agent-skills","ai-agents","ai-coding","baseline-first","claude-code","codex"],"capabilities":["skill","source-ganyuanran","skill-using-git-worktrees","topic-add","topic-agent-skills","topic-ai-agents","topic-ai-coding","topic-baseline-first","topic-claude-code","topic-codex","topic-coding-agents","topic-evidence-driven","topic-first-principles","topic-opencode","topic-software-architecture"],"categories":["Aegis"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/GanyuanRan/Aegis/using-git-worktrees","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add GanyuanRan/Aegis","source_repo":"https://github.com/GanyuanRan/Aegis","install_from":"skills.sh"}},"qualityScore":"0.581","qualityRationale":"deterministic score 0.58 from registry signals: · indexed on github topic:agent-skills · 262 github stars · SKILL.md body (5,356 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-18T18:54:50.477Z","embedding":null,"createdAt":"2026-05-04T19:05:09.267Z","updatedAt":"2026-05-18T18:54:50.477Z","lastSeenAt":"2026-05-18T18:54:50.477Z","tsv":"'/.config/aegis/worktrees':161,252,292,294 '/cargo.toml':465 '/dev/null':97,104,126,205,213 '/users/jesse/myproject/.worktrees/auth':602 '0':417,607 '1':84,154,225,262 '2':96,103,116,125,160,204,212,231,276 '3':134,235,313 '4':367,676 '47':597,605 '5':408 'accident':243 'action':425 'activ':26 'add':226,306,451,587 'allow':42 'altern':105 'alway':483,645 'ambigu':641 'announc':59 'appropri':227,322,383 'approv':681 'ask':133,135,397,446,461,509,636,651 'assum':495,637 'auth':612 'auto':318,545,661 'auto-detect':317,544,660 'b':308,589 'baselin':370,458,628,670 'basenam':268 'bash':88,119,186,266,279,324,378 'brainstorm':674 'branch':46,290,296,303,309,713 'break':537 'broken':222 'bug':519 'build':339 'call':672 'cargo':338,387 'cargo.toml':336 'case':283 'cd':311 'chang':234 'check':85,89,117,187,200,208,444,487,570,577,644 'check-ignor':199,207,486,576 'claude.md':118,124,143,445,508,643,650 'clean':369,377,668 'cleanup':716 'command':384,535 'commit':232,244,454 'common':469 'complet':719 'confirm':579 'content':246,476 'convent':503 'core':50 'creat':35,152,184,277,299,490,499,583,617 'creation':239,260 'critic':241 'current':15 'd':94,101 'depend':467 'design':679 'detect':263,319,546,662 'determin':280 'develop':688,712 'differ':541 'director':123 'directori':53,77,87,110,139,147,174,180,189,251,448,496,638,647,653 'distinguish':517 'download':365 'driven':687 'ensur':374 'entir':259 'esac':298 'etc':551 'exampl':379,552 'execut':691,695,699 'executing-plan':694 'exist':86,113,140,427,433,439,443,507,523,572,649 'explicit':529 'f':327,335,343,352,360 'fail':394,456,512,633 'failur':396,418,460,527,608 'featur':8,613 'feature/auth':590 'fi':332,340,350,357,366 'file':549 'finish':710 'finishing-a-development-branch':709 'fix':221,482,504,525,543 'flag':615 'follow':80,505,646,684 'found':107,148 'full':281 'get':477,528 'git':3,30,33,68,198,206,269,304,480,485,561,575,585 'gitignor':197,230,254,453 'global':162,194,250 'go':358,363,390 'go.mod':361 'grep':120 'hardcod':533 'hidden':99,159 'ignor':182,191,201,209,216,431,437,450,472,488,574,578,582,623,655 'immedi':224 'implement':20,421,611,683 'inconsist':500 'instal':331,347,356,468,593 'integr':671 'investig':402 'isol':12,36,58,75,568,705 'issu':524 'jess':218 'line':228 'local':158,173,193,493,626,659 'locat':163,284,289,410,497,639 'ls':93,100 'm':63,556 'mistak':470 'mod':364 'multipl':45 'must':178 'name':265,291,297,310 'need':11,256,704 'neither':442 'never':616 'new':302,518 'node.js':325 'npm':330,385,592,595 'order':83,92 'outsid':24,257 'overview':32 'package.json':328,464,550 'package.json/cargo.toml':463 'pair':707 'pars':272 'pass':405,415,598,604 'path':282,288,293,307,312 'per':217 'permiss':530 'phase':675 'pip':346 'plan':21,696 'poetri':355 'pollut':479 'pre':522 'pre-exist':521 'prefer':98,128,144,167 'prevent':242 'principl':51 'prioriti':82,91,506,648 'problem':474,498,514,536 'proceed':236,400,510,532,631 'process':79 'project':157,172,258,264,267,295,315,382,492,502,539,548,625,658,665 'project-appropri':381 'project-loc':156,171,491,624,657 'pyproject.toml':353 'pytest':389 'python':341 'q':202,210 'quick':422 'r':348 'readi':407,412,419,600,609 'red':614 'refer':423 'reliabl':57 'report':395,406,409,459,526 'repositori':41,248 'requir':677,689,697,714 'requirements.txt':344,349 'respect':192 'rev':271 'rev-pars':270 'rule':220 'run':23,314,321,371,591,594,664 'rust':333 'safeti':55,168 'select':54,78 'set':72,565 'setup':316,323,534,666 'share':38 'show':274 'show-toplevel':273 'simultan':47 'situat':424 'skill':70,563,703 'skill-using-git-worktrees' 'skip':466,471,627,642 'source-ganyuanran' 'specifi':129 'start':7,61,376 'status':481 'step':261 'subag':686 'subagent-driven-develop':685 'switch':49 'system':196 'systemat':52 'task':693,701 'test':372,386,388,391,393,404,414,416,455,513,596,603,606,629,634,669 'thing':223 'tool':542 'topic-add' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-baseline-first' 'topic-claude-code' 'topic-codex' 'topic-coding-agents' 'topic-evidence-driven' 'topic-first-principles' 'topic-opencode' 'topic-software-architecture' 'toplevel':275 'track':478 'tree':28 'use':2,5,29,64,67,108,130,380,428,434,440,484,540,557,560 'user':136,447 'using-git-worktre':1,66,559 'verif':56,169,255,473,630 'verifi':179,368,430,436,573,620,652,667 'violat':501 'whether':398 'win':115 'without':48,132,619,635 'work':9,27,43,718 'workflow':553 'workspac':16,37,76,569,706 'worktre':4,31,34,69,95,102,114,122,146,153,155,175,177,185,203,211,238,245,278,286,287,300,305,375,411,426,432,441,475,494,562,571,580,584,586,599,618 'worktrees/auth':588 'would':165","prices":[{"id":"3b686873-909e-4166-929e-cdcda0ea3aa0","listingId":"7775b707-f947-452c-8a43-65dad6ae212a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"GanyuanRan","category":"Aegis","install_from":"skills.sh"},"createdAt":"2026-05-04T19:05:09.267Z"}],"sources":[{"listingId":"7775b707-f947-452c-8a43-65dad6ae212a","source":"github","sourceId":"GanyuanRan/Aegis/using-git-worktrees","sourceUrl":"https://github.com/GanyuanRan/Aegis/tree/main/skills/using-git-worktrees","isPrimary":false,"firstSeenAt":"2026-05-04T19:05:09.267Z","lastSeenAt":"2026-05-18T18:54:50.477Z"}],"details":{"listingId":"7775b707-f947-452c-8a43-65dad6ae212a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"GanyuanRan","slug":"using-git-worktrees","github":{"repo":"GanyuanRan/Aegis","stars":262,"topics":["add","agent-skills","ai-agents","ai-coding","architecture-driven-development","baseline-first","claude-code","codex","coding-agents","evidence-driven","first-principles","opencode","software-architecture","tdd","tlref"],"license":"mit","html_url":"https://github.com/GanyuanRan/Aegis","pushed_at":"2026-05-18T11:05:01Z","description":"Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.","skill_md_sha":"523b11d3eb774fcda9ad7089be2281aa0270afa6","skill_md_path":"skills/using-git-worktrees/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/GanyuanRan/Aegis/tree/main/skills/using-git-worktrees"},"layout":"multi","source":"github","category":"Aegis","frontmatter":{"name":"using-git-worktrees","description":"Use when starting feature work that needs isolation from the current workspace, or when an implementation plan should run outside the active working tree."},"skills_sh_url":"https://skills.sh/GanyuanRan/Aegis/using-git-worktrees"},"updatedAt":"2026-05-18T18:54:50.477Z"}}