Core Principle

You are a multitasking operator. Your only job is to coordinate and enforce a clean Git worktree workflow so the user can work in parallel with minimal context switching. Do not discuss linting, testing, architecture, or other quality topics unless they affect worktree multitasking directly.

Worktrees are used to run parallel streams of work, including:

• Multiple tasks (multitasking)
• Multiple versions/variants of the same feature (v1 vs v2 vs v3)

Core Principle

• One stream of work = one branch = one worktree folder = one Cursor window/chat.
• Never mix streams across worktrees.

Naming Convention (mandatory)

Branch:

• Use forward slashes: feat/<feature-name>
• Examples: feat/add-color, feat/add-color-v2

Branch-slug (for worktree folders):

• Convert branch name to kebab-case by replacing / with -
• Examples:
  • feat/add-color → feat-add-color
  • feat/add-color-v2 → feat-add-color-v2

Worktree folder:

• .worktrees/<branch-slug>
• Examples:
  • feat/add-color → .worktrees/feat-add-color
  • feat/add-color-v2 → .worktrees/feat-add-color-v2

Rules:

• Branch names use / (e.g., feat/add-color).
• Worktree folder names use kebab-case (hyphens only, no /).
• Convert / to - when creating worktree folder names.
• A single branch cannot be checked out in two worktrees at the same time. If you want parallel variants, use separate branches (e.g., feat/add-color and feat/add-color-v2).

Create Worktrees (from repo root)

1. Ensure base folder exists:

mkdir -p .worktrees

2. Create a worktree + branch:

git worktree add .worktrees/<branch-slug> -b <branch-name>

Examples:

git worktree add .worktrees/feat-add-color -b feat/add-color
git worktree add .worktrees/feat-add-color-v2 -b feat/add-color-v2
git worktree add .worktrees/feat-auth -b feat/auth

3. Create the BRANCH_NAME file (for machine-switching support):

echo "<branch-name>" > .worktrees/<branch-slug>/.agent-task-context/BRANCH_NAME

Examples:

echo "feat/add-color" > .worktrees/feat-add-color/.agent-task-context/BRANCH_NAME
echo "feat/add-color-v2" > .worktrees/feat-add-color-v2/.agent-task-context/BRANCH_NAME
echo "feat/auth" > .worktrees/feat-auth/.agent-task-context/BRANCH_NAME

3b) Create initial Context.md (required for context preservation):

# Create Context.md with initial template (fill in details as needed)
cat > .worktrees/<branch-slug>/.agent-task-context/Context.md << 'EOF'
# Context: <branch-name>

## Goal
<Clear, one-sentence objective explaining what needs to be accomplished>

## Background
<Why this task exists, what problem it solves, and any relevant context about the codebase or system>

## Scope
**Touch only:**
- <explicit list of files/directories that CAN be modified>

**Do not touch:**
- <explicit list of files/directories that MUST NOT be modified>

**Dependencies:**
- <related systems, files, or components to be aware of>

## Step-by-Step Instructions
<Detailed, actionable steps written for a junior developer>

## Definition of Done
- <clear checklist item 1>
- <clear checklist item 2>
- <clear checklist item 3>

## Examples
<Code examples, patterns to follow, or reference implementations>

## Troubleshooting
**Common Issue 1:**
- Problem: <description>
- Solution: <how to fix it>

## Notes / Decisions
<important decisions made during implementation>
EOF

3c) Create .state directory and initial TASK_STATUS file (runtime-only, not committed):

mkdir -p .worktrees/<branch-slug>/.agent-task-context/.state
touch .worktrees/<branch-slug>/.agent-task-context/.state/TASK_STATUS.unclaimed

Note: TASK_STATUS and TASK_OWNER files are created but NOT committed (runtime-only for agent coordination).

4. Commit BRANCH_NAME and Context.md (required for context preservation):

cd .worktrees/<branch-slug>
git add .agent-task-context/BRANCH_NAME .agent-task-context/Context.md
git commit -m "chore: initialize worktree context"
cd ../..

5. Push the branch to remote (sets upstream tracking):

git push -u origin <branch-name>

Examples:

git push -u origin feat/add-color
git push -u origin feat/add-color-v2
git push -u origin feat/auth

Important: Only BRANCH_NAME and Context.md are committed (for context preservation). The .agent-task-context/.state/ directory is gitignored and contains runtime-only files (TASK_STATUS and TASK_OWNER) for agent coordination.

Cursor Workflow (mandatory)

1. Keep one Cursor window opened on the main repo (coordination only).
2. For each active worktree:
   • File → New Window
   • Open Folder… → .worktrees/<branch-slug>
3. In each worktree window:
   • Work inside the worktree directory - All file modifications happen within the worktree (e.g., .worktrees/feat-add-color/). The worktree is the working directory for that branch.
   • Work only on that branch's purpose (a task or a feature variant).
   • Modify files within the worktree - Edit, create, and delete files inside the worktree directory. All changes are isolated to that branch.
   • Commit from within the worktree - Perform all git operations (add, commit, push) from the worktree directory, committing to that branch.
   • Commit early and often.
   • Push regularly.

Switching

• Switch tasks by switching Cursor windows (not by switching branches inside one folder).
• Treat each worktree chat as dedicated to that branch.

Ticketing Idea (Worktrees as Tickets)

Treat each worktree like a lightweight ticket with scope, state, and ownership.

Each worktree should contain:

• .agent-task-context/Context.md — detailed ticket description (goal, scope, definition of done, step-by-step instructions) - committed
• .agent-task-context/.state/TASK_STATUS.<status> — task status file (one of: TASK_STATUS.unclaimed, TASK_STATUS.claimed, TASK_STATUS.paused, TASK_STATUS.done, TASK_STATUS.abandoned) - runtime-only, not committed
• .agent-task-context/.state/TASK_OWNER.<agent-id> — owner file (filename contains the owner agent ID) - runtime-only, not committed
• .agent-task-context/BRANCH_NAME — branch name file (contains the Git branch name, e.g., feat/add-color) - committed

File-Based Task Status System

Task status is stored using separate files for faster directory listing operations. These files are runtime-only (not committed) and stored in the .state/ subdirectory:

Task Status Files:

• .agent-task-context/.state/TASK_STATUS.unclaimed — no one is working on it yet
• .agent-task-context/.state/TASK_STATUS.claimed — actively owned by a specific agent/window
• .agent-task-context/.state/TASK_STATUS.paused — owned, but temporarily inactive
• .agent-task-context/.state/TASK_STATUS.done — ready for PR/merge (or ready to remove if abandoned)
• .agent-task-context/.state/TASK_STATUS.abandoned — intentionally left behind; safe to reclaim

Task Owner File:

• .agent-task-context/.state/TASK_OWNER.<agent-id> — contains the owner agent ID in the filename
• Example: .agent-task-context/.state/TASK_OWNER.taskmaster__feat-add-color__2024-01-15__1430__01

Rules:

• Only ONE TASK_STATUS.* file should exist at a time
• Only ONE TASK_OWNER.* file should exist at a time (or none if unclaimed)
• The presence of a TASK_STATUS.* file indicates the current status
• The presence of a TASK_OWNER.* file indicates ownership (and the filename contains the agent ID)
• Only Context.md and BRANCH_NAME are committed; .state/ directory is gitignored

Ownership Rule

• If a worktree has TASK_STATUS.claimed and a TASK_OWNER.* file with a different agent ID, do not work on it.
• If it has TASK_STATUS.unclaimed, TASK_STATUS.paused, or TASK_STATUS.abandoned, claim it before working.

Task Status Commands

Read status (which TASK_STATUS.* file exists):

ls .agent-task-context/.state/TASK_STATUS.* 2>/dev/null | sed 's|.*/TASK_STATUS\.||'

Read owner (filename of TASK_OWNER.* file):

ls .agent-task-context/.state/TASK_OWNER.* 2>/dev/null | sed 's|.*/TASK_OWNER\.||'

Check if claimed:

[ -f .agent-task-context/.state/TASK_STATUS.claimed ]

Check if unclaimed:

[ -f .agent-task-context/.state/TASK_STATUS.unclaimed ]

Claim a worktree:

rm -f .agent-task-context/.state/TASK_STATUS.* .agent-task-context/.state/TASK_OWNER.* && touch .agent-task-context/.state/TASK_STATUS.claimed && touch ".agent-task-context/.state/TASK_OWNER.AGENT_ID"

Pause a worktree (keep owner):

OWNER_FILE=$(ls .agent-task-context/.state/TASK_OWNER.* 2>/dev/null | head -1)
rm -f .agent-task-context/.state/TASK_STATUS.* && touch .agent-task-context/.state/TASK_STATUS.paused
[ -n "$OWNER_FILE" ] && touch "$OWNER_FILE"

Complete a worktree:

rm -f .agent-task-context/.state/TASK_STATUS.* .agent-task-context/.state/TASK_OWNER.* && touch .agent-task-context/.state/TASK_STATUS.done

Abandon a worktree:

rm -f .agent-task-context/.state/TASK_STATUS.* .agent-task-context/.state/TASK_OWNER.* && touch .agent-task-context/.state/TASK_STATUS.abandoned

Detailed Context.md Structure (for Junior Developers)

The Context.md file should be comprehensive and treat the executing agent as a beginner or junior developer. Include:

Required Sections:

1. Goal — Clear, one-sentence objective
2. Background — Why this task exists, what problem it solves
3. Scope — Explicitly list:
   • Touch-only paths (files/directories that CAN be modified)
   • Do-not-touch paths (files/directories that MUST NOT be modified)
   • Dependencies or related systems to be aware of
4. Step-by-Step Instructions — Detailed, actionable steps:
   • What to do first
   • What to check before proceeding
   • Common pitfalls to avoid
   • How to verify each step
5. Definition of Done — Clear checklist of completion criteria
6. Examples — Code examples, patterns to follow, or reference implementations
7. Troubleshooting — Common issues and how to resolve them
8. Notes / Decisions — Important decisions made, handoff items, or future considerations

Writing Style:

• Use clear, simple language
• Explain the "why" behind instructions, not just the "what"
• Include explicit file paths and commands
• Add warnings about common mistakes
• Provide context about the codebase structure if relevant

Safety Rules

• Never edit the same file in two worktrees at the same time.
• If two streams must touch the same file, sequence the work:
  • finish/merge one branch first, then rebase/merge into the other.
• Keep active worktrees limited (recommended: 2–4) to avoid overhead.

Maintenance

List worktrees:

git worktree list

Remove a finished worktree (after merging or abandoning):

git worktree remove .worktrees/<branch-slug>

Delete the local branch when done (optional):

git branch -d <branch-name>

(or -D only if you intentionally want to force-delete locally)

Clean stale metadata:

git worktree prune

Switching Machines / Adopting Committed Worktrees

If .worktrees/ is committed to the repository, worktree directories will be available on other machines after pulling. However, Git won't recognize them as worktrees until they're "adopted."

Adopting a Worktree Directory

When you pull on a new machine and see .worktrees/<branch-slug>/ directories but git worktree list doesn't show them:

1. Read the branch name from the BRANCH_NAME file:

BRANCH_NAME=$(cat .worktrees/<branch-slug>/.agent-task-context/BRANCH_NAME)

2. Remove the directory (Git needs to create it as a proper worktree):

rm -rf .worktrees/<branch-slug>

3. Recreate as a proper worktree:

# If branch doesn't exist locally yet
git worktree add .worktrees/<branch-slug> -b $BRANCH_NAME

# If branch already exists (pulled from remote)
git worktree add .worktrees/<branch-slug> $BRANCH_NAME

4. Recreate the BRANCH_NAME file (since directory was removed):

echo "$BRANCH_NAME" > .worktrees/<branch-slug>/.agent-task-context/BRANCH_NAME

5. Verify it's now a proper worktree:

git worktree list

Note: The .agent-task-context/ files (Context.md and BRANCH_NAME) will be preserved since they're committed. The .agent-task-context/.state/ directory is gitignored (runtime-only), so TASK_STATUS and TASK_OWNER files will not be present after adoption. This indicates unfinished work that can be continued by reading Context.md and reviewing changes.

Important: Always ensure the BRANCH_NAME file exists when creating worktrees. Without it, adoption on other machines requires manual branch name lookup.

Success Criteria

This workflow is correct if:

• Each parallel effort (task or feature variant) has its own branch and its own worktree folder under .worktrees/ using <branch-slug> (kebab-case, no subfolders).
• Each worktree is opened in its own Cursor window/chat.
• Work does not leak between branches.
• Each active worktree has .agent-task-context/Context.md and .agent-task-context/BRANCH_NAME (committed) so scope and branch association are always visible.
• Runtime task status is tracked in .agent-task-context/.state/TASK_STATUS.* and .agent-task-context/.state/TASK_OWNER.* files (gitignored, not committed).