📋 Refactor git-worktree-task workflow for clarity and practicality

Restructured guide to emphasize why worktrees matter and practical
setup details. Added port isolation section to prevent dev server
conflicts. Simplified verbose sections and removed redundant bash
examples. Tightened language throughout for better readability.

Author: Nick Sullivan

.cursor/rules/git-worktree-task.mdc

@@ -6,96 +6,74 @@ alwaysApply: false
 # Git Worktree Task Workflow
 
 <objective>
-Deliver a pull request that passes all checks and merges without back-and-forth. Work in isolated git worktrees to keep the main directory clean and allow context switching.
+Deliver a pull request that passes all checks and merges without back-and-forth. Work in isolated git worktrees to keep the main directory clean and allow context switching between tasks.
 </objective>
 
-<workspace-setup>
-Create git worktree in .gitworktrees/ directory:
-
-```bash
-mkdir -p .gitworktrees
-git worktree add -b feature/task-name .gitworktrees/task-name main
-cd .gitworktrees/task-name
-```
+<why-worktrees>
+Worktrees isolate task branches in separate directories. Your main repo stays on main for quick reference. Your task directory is completely separate. You can switch between them instantly. When done, the worktree disappears cleanly. This is faster and cleaner than stashing or branch switching.
+</why-worktrees>
 
+<workspace-setup>
+Create git worktree as a sibling directory (not nested inside the repo). Sibling directories avoid module resolution issues with ESLint, monorepo tools, and symlinked dependencies that break when worktrees are nested.
 </workspace-setup>
 
-<environment-initialization>
-Run /setup-environment to prepare the worktree. This detects project type and sets up dependencies, code generation, and environment files.
-
-If /setup-environment doesn't exist, set up manually based on project type (Node.js:
-`pnpm install`, Python: `pip install -r requirements.txt`, Ruby: `bundle install`).
+<port-isolation>
+Each worktree needs its own port for dev servers to avoid conflicts when running multiple tasks. Create a `.env.local` in the worktree with a unique PORT based on the task name (hash the name to a port offset from 3000, or use sequential assignment). This prevents "port already in use" errors and makes it clear which server belongs to which task.
+</port-isolation>
 
-Copy environment files from parent directory if needed. After proper setup, all tests
-(unit + integration) should pass. </environment-initialization>
+<environment-initialization>
+Run /setup-environment if available, otherwise install dependencies and set up environment files manually. After proper setup, all tests (unit + integration) should pass.
+</environment-initialization>
 
 <standards-discovery>
 Read all cursor rules in .cursor/rules/. If CLAUDE.md or AGENTS.md exist at project root, read those too. Every applicable rule must be followed.
 </standards-discovery>
 
 <implementation>
-Write code that solves the problem following all cursor rules. Make commits along the way as logical units of work are completed. Follow git commit message guidelines in .cursor/rules/git-commit-message.mdc.
+Write code that solves the problem following all cursor rules. Make commits along the way as logical units of work are completed. Follow git commit message guidelines in .cursor/rules/git-commit-message.mdc if it exists.
 </implementation>
 
 <local-validation>
-Run project's pre-push validation before pushing. This catches issues before CI:
-- Node.js: `pnpm pre-push` or check package.json scripts
-- Python: `pre-commit run --all-files`, `pytest`, `ruff check`, `mypy`
-- Ruby: `bundle exec rake test`, `bundle exec rubocop`
-- Go: `go test ./...`, `golangci-lint run`
-- Rust: `cargo test`, `cargo clippy`
-
-Check .github/workflows/ to see what CI runs - run those steps locally.
-
-All tests should pass after environment setup. If tests fail, it's either incomplete
-setup or bugs in your code. Fix before pushing. </local-validation>
+Run the project's pre-push validation before pushing. Check .github/workflows/ to see what CI runs and run those steps locally first. Local validation catches issues in seconds vs waiting for CI. All tests must pass before pushing.
+</local-validation>
 
 <self-review>
 Invoke code reviewer agent (Rivera in .claude/agents/rivera.md if available) to review changes before pushing. Address critical issues, consider warnings seriously, evaluate suggestions for merit. Learn from feedback.
 </self-review>
 
 <pull-request-creation>
-Once local validation passes and code review is addressed, push commits. Create pull request with clear description of what changed and why. Help reviewers understand context and decisions made.
+Push commits and create pull request with clear description of what changed and why. Help reviewers understand context and decisions made.
 </pull-request-creation>
 
 <ci-validation>
 Let all CI jobs run to completion. All must pass. Green checks required before merge. If CI fails, read logs carefully, understand what broke and why, fix and push again.
 </ci-validation>
 
 <bot-review-handling>
-AI code review bots will analyze the pull request. Evaluate feedback critically - you have full project context, bots don't.
+AI code review bots will analyze the pull request. Evaluate feedback critically—you have full project context, bots don't.
 
 Fix valuable feedback that identifies real issues. Mark as WONTFIX with clear reasoning
 if feedback is incorrect, not applicable, conflicts with project standards, or would
 break functionality.
 
-Be discerning. You are smarter than the bots. </bot-review-handling>
+You are smarter than the bots. Be discerning. </bot-review-handling>
 
 <merge-and-cleanup>
-Once CI is green, bot reviews are addressed, and all checks pass, merge the PR.
-
-After merge, clean up worktree:
-
-```bash
-cd ../..  # Return to main directory
-git worktree remove .gitworktrees/task-name
-```
-
+Once CI is green, bot reviews are addressed, and all checks pass, merge the PR. After merge, remove the worktree.
 </merge-and-cleanup>
 
 <critical-success-factors>
-Environment setup is not optional. After creating worktree, run /setup-environment or manually install dependencies. Type errors and test failures often stem from missing code generation or dependencies.
+Environment setup is not optional. Type errors and test failures often stem from missing code generation or dependencies.
 
 Local validation saves time. Don't push without running pre-push checks. Local tooling
 catches issues in seconds vs waiting for CI.
 
 Bot feedback requires judgment. Bots provide suggestions, not mandates. Evaluate each
 piece based on your context and project standards.
 
-Full test suite must pass. After setup, all tests (unit + integration) should pass. Fix
-setup or code before pushing.
+Full test suite must pass after setup. Fix setup or code before pushing.
 
-Successful autonomous task means: original request completed, all automated checks pass,
-code follows all cursor rules, tests green, code review addressed, bot feedback
-evaluated intelligently, PR merges without human intervention requesting changes.
+Successful autonomous task: original request completed, all automated checks pass, code
+follows all cursor rules, tests green, code review addressed, bot feedback evaluated
+intelligently, PR merges without human intervention requesting changes.
 </critical-success-factors>