Cursor rule

1---
2description: Autonomous task workflow using git worktrees
3alwaysApply: false
4version: 1.0.0
5---
6 
7# Git Worktree Task Workflow
8 
9<objective>
10Deliver 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.
11</objective>
12 
13<why-worktrees>
14Worktrees 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.
15</why-worktrees>
16 
17<workspace-setup>
18Create 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.
19 
20Always base worktrees on `origin/main`, not local `main`. Local main may have unpushed
21commits from other work that will bleed into your branch. </workspace-setup>
22 
23<port-isolation>
24Each 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.
25</port-isolation>
26 
27<environment-initialization>
28Run /setup-environment if available, otherwise install dependencies and set up environment files manually. After proper setup, all tests (unit + integration) should pass.
29</environment-initialization>
30 
31<standards-discovery>
32Read all cursor rules in rules/. If CLAUDE.md or AGENTS.md exist at project root, read those too. Every applicable rule must be followed.
33</standards-discovery>
34 
35<implementation>
36Write 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.
37</implementation>
38 
39<local-validation>
40Run 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.
41</local-validation>
42 
43<self-review>
44Invoke code-reviewer agent to review changes before pushing. Address critical issues, consider warnings seriously, evaluate suggestions for merit. Learn from feedback.
45</self-review>
46 
47<pull-request-creation>
48Push commits and create pull request with clear description of what changed and why. Help reviewers understand context and decisions made.
49</pull-request-creation>
50 
51<ci-validation>
52Let 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.
53</ci-validation>
54 
55<bot-review-handling>
56AI code review bots will analyze the pull request. Evaluate feedback critically—you have full project context, bots don't.
57 
58Fix valuable feedback that identifies real issues. Mark as WONTFIX with clear reasoning
59if feedback is incorrect, not applicable, conflicts with project standards, or would
60break functionality.
61 
62You are smarter than the bots. Be discerning. </bot-review-handling>
63 
64<merge-and-cleanup>
65Once CI is green, bot reviews are addressed, and all checks pass, merge the PR. After merge, remove the worktree.
66</merge-and-cleanup>
67 
68<critical-success-factors>
69Environment setup is not optional. Type errors and test failures often stem from missing code generation or dependencies.
70 
71Local validation saves time. Don't push without running pre-push checks. Local tooling
72catches issues in seconds vs waiting for CI.
73 
74Bot feedback requires judgment. Bots provide suggestions, not mandates. Evaluate each
75piece based on your context and project standards.
76 
77Full test suite must pass after setup. Fix setup or code before pushing.
78 
79Successful autonomous task: original request completed, all automated checks pass, code
80follows all cursor rules, tests green, code review addressed, bot feedback evaluated
81intelligently, PR merges without human intervention requesting changes.
82</critical-success-factors>
83