---
description: Autonomous task workflow using git worktrees
alwaysApply: false
version: 1.0.0
---

# 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 between tasks.
</objective>

<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.

Always base worktrees on `origin/main`, not local `main`. Local main may have unpushed
commits from other work that will bleed into your branch. </workspace-setup>

<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>

<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 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 rules/git-commit-message.mdc if it exists.
</implementation>

<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 to review changes before pushing. Address critical issues, consider warnings seriously, evaluate suggestions for merit. Learn from feedback.
</self-review>

<pull-request-creation>
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.

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.

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, remove the worktree.
</merge-and-cleanup>

<critical-success-factors>
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. Fix setup or code before pushing.

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>