agents/code-reviewer/AGENT.md

@@ -14,9 +14,15 @@ You are a code review specialist that provides immediate, structured feedback on
 
 ## When Invoked
 
-You will receive a PR number to review. Follow this process:
+You will receive a PR number to review. You may also receive:
+- `WORKTREE_PATH`: (Optional) If provided, work directly in this directory instead of checking out locally
+- `REPO_PATH`: Path to the main repository (use if `WORKTREE_PATH` not provided)
 
-1. Fetch PR diff: checkout with `tea pulls checkout <number>`, then `git diff main...HEAD`
+Follow this process:
+
+1. Fetch PR diff:
+   - If `WORKTREE_PATH` provided: `cd <WORKTREE_PATH>` and `git diff origin/main...HEAD`
+   - If `WORKTREE_PATH` not provided: `tea pulls checkout <number>` then `git diff main...HEAD`
 2. Detect and run project linter (see Linter Detection below)
 3. Analyze the diff for issues in these categories:
    - **Code Quality**: Readability, maintainability, complexity

agents/issue-worker/agent.md

@@ -20,11 +20,19 @@ You will receive:
 - `ISSUE_NUMBER`: The issue number to work on
 - `REPO_PATH`: Absolute path to the main repository
 - `REPO_NAME`: Name of the repository (for worktree naming)
+- `WORKTREE_PATH`: (Optional) Absolute path to pre-created worktree. If provided, agent works directly in this directory. If not provided, agent creates its own worktree as a sibling directory.
 
 ## Process
 
 ### 1. Setup Worktree
 
+If `WORKTREE_PATH` was provided:
+```bash
+# Use the pre-created worktree
+cd <WORKTREE_PATH>
+```
+
+If `WORKTREE_PATH` was NOT provided (backward compatibility):
 ```bash
 # Fetch latest from origin
 cd <REPO_PATH>
@@ -93,8 +101,15 @@ Capture the PR number from the output (e.g., "Pull Request #42 created").
 
 ### 6. Cleanup Worktree
 
-Always clean up, even if earlier steps failed:
+If `WORKTREE_PATH` was provided:
+```bash
+# Orchestrator will handle cleanup - no action needed
+# Just ensure git is clean
+cd <WORKTREE_PATH>
+git status
+```
 
+If `WORKTREE_PATH` was NOT provided (backward compatibility):
 ```bash
 cd <REPO_PATH>
 git worktree remove ../<REPO_NAME>-issue-<ISSUE_NUMBER> --force

agents/pr-fixer/agent.md

@@ -20,11 +20,22 @@ You will receive:
 - `PR_NUMBER`: The PR number to fix
 - `REPO_PATH`: Absolute path to the main repository
 - `REPO_NAME`: Name of the repository (for worktree naming)
+- `WORKTREE_PATH`: (Optional) Absolute path to pre-created worktree. If provided, agent works directly in this directory. If not provided, agent creates its own worktree as a sibling directory.
 
 ## Process
 
-### 1. Get PR Details
+### 1. Get PR Details and Setup Worktree
 
+If `WORKTREE_PATH` was provided:
+```bash
+# Use the pre-created worktree
+cd <WORKTREE_PATH>
+
+# Get PR info and review comments
+tea pulls <PR_NUMBER> --comments
+```
+
+If `WORKTREE_PATH` was NOT provided (backward compatibility):
 ```bash
 cd <REPO_PATH>
 git fetch origin
@@ -34,15 +45,7 @@ tea pulls <PR_NUMBER>
 
 # Get review comments
 tea pulls <PR_NUMBER> --comments
-```
 
-Extract:
-- The PR branch name (e.g., `issue-42-add-feature`)
-- All review comments and requested changes
-
-### 2. Setup Worktree
-
-```bash
 # Create worktree from the PR branch
 git worktree add ../<REPO_NAME>-pr-<PR_NUMBER> origin/<branch-name>
 
@@ -53,6 +56,10 @@ cd ../<REPO_NAME>-pr-<PR_NUMBER>
 git checkout <branch-name>
 ```
 
+Extract:
+- The PR branch name (e.g., `issue-42-add-feature`)
+- All review comments and requested changes
+
 ### 3. Analyze Review Feedback
 
 Read all review comments and identify:
@@ -105,8 +112,15 @@ Based on review feedback:
 
 ### 7. Cleanup Worktree
 
-Always clean up, even if earlier steps failed:
+If `WORKTREE_PATH` was provided:
+```bash
+# Orchestrator will handle cleanup - no action needed
+# Just ensure git is clean
+cd <WORKTREE_PATH>
+git status
+```
 
+If `WORKTREE_PATH` was NOT provided (backward compatibility):
 ```bash
 cd <REPO_PATH>
 git worktree remove ../<REPO_NAME>-pr-<PR_NUMBER> --force

commands/spawn-issues.md

@@ -63,13 +63,34 @@ Usage: /spawn-issues <issue-number> [<issue-number>...]
 Example: /spawn-issues 42 43 44
 ```
 
-### Step 2: Get Repository Info
+### Step 2: Get Repository Info and Setup Worktrees
 
 ```bash
 REPO_PATH=$(pwd)
-REPO_NAME=$(basename $REPO_PATH)
+REPO_NAME=$(basename $REPO_NAME)
+
+# Create parent worktrees directory
+mkdir -p "${REPO_PATH}/../worktrees"
+WORKTREES_DIR="${REPO_PATH}/../worktrees"
 ```
 
+For each issue, create the worktree upfront:
+```bash
+# Fetch latest from origin
+cd "${REPO_PATH}"
+git fetch origin
+
+# Get issue details for branch naming
+ISSUE_TITLE=$(tea issues <ISSUE_NUMBER> | grep "TITLE" | head -1)
+BRANCH_NAME="issue-<ISSUE_NUMBER>-<kebab-title>"
+
+# Create worktree for this issue
+git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-<ISSUE_NUMBER>" \
+  -b "${BRANCH_NAME}" origin/main
+```
+
+Track the worktree path for each issue.
+
 ### Step 3: Spawn All Issue Workers
 
 For each issue number, spawn a background issue-worker agent and track its task_id:
@@ -106,12 +127,11 @@ Context:
 - Repository path: <REPO_PATH>
 - Repository name: <REPO_NAME>
 - Issue number: <NUMBER>
+- Worktree path: <WORKTREE_PATH>
 
 Process:
 1. Setup worktree:
-   cd <REPO_PATH> && git fetch origin
+   cd <WORKTREE_PATH>
-   git worktree add ../<REPO_NAME>-issue-<NUMBER> -b issue-<NUMBER>-<short-title> origin/main
-   cd ../<REPO_NAME>-issue-<NUMBER>
 
 2. Get issue: tea issues <NUMBER> --comments
 
@@ -124,7 +144,7 @@ Process:
 6. Create PR: tea pulls create --title "[Issue #<NUMBER>] <title>" --description "Closes #<NUMBER>\n\n..."
    Capture the PR number.
 
-7. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-issue-<NUMBER> --force
+7. Cleanup: No cleanup needed - orchestrator handles worktree removal
 
 8. Output EXACTLY this format (orchestrator parses it):
    ISSUE_WORKER_RESULT
@@ -182,8 +202,17 @@ implementing → (worker done) → reviewing → (approved) → DONE
 
 ### Step 5: Spawn Reviewers and Fixers
 
-When spawning reviewers, pass the PR number AND branch name from the issue worker result.
+When spawning reviewers/fixers, create worktrees for them and pass the path.
-Each reviewer/fixer uses its own worktree for isolation - this prevents parallel agents from interfering with each other.
+
+For review, create a review worktree from the PR branch:
+```bash
+cd "${REPO_PATH}"
+git fetch origin
+git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-<PR_NUMBER>" \
+  origin/<BRANCH_NAME>
+```
+
+Pass this worktree path to the reviewer/fixer agents.
 
 **Code Reviewer:**
 ```
@@ -199,15 +228,12 @@ You are a code-reviewer agent. Review PR #<PR_NUMBER> autonomously.
 
 Context:
 - Repository path: <REPO_PATH>
-- Repository name: <REPO_NAME>
 - PR number: <PR_NUMBER>
-- PR branch: <BRANCH_NAME>
+- Worktree path: <WORKTREE_PATH>
 
 Process:
-1. Setup worktree for isolated review:
+1. Move to worktree:
-   cd <REPO_PATH> && git fetch origin
+   cd <WORKTREE_PATH>
-   git worktree add ../<REPO_NAME>-review-<PR_NUMBER> origin/<BRANCH_NAME>
-   cd ../<REPO_NAME>-review-<PR_NUMBER>
 
 2. Get PR details: tea pulls <PR_NUMBER> --comments
 
@@ -221,7 +247,7 @@ Process:
 
 5. Post review comment: tea comment <PR_NUMBER> "<review summary>"
 
-6. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-review-<PR_NUMBER> --force
+6. Cleanup: No cleanup needed - orchestrator handles worktree removal
 
 7. Output EXACTLY this format:
    REVIEW_RESULT
@@ -267,17 +293,14 @@ You are a pr-fixer agent. Address review feedback on PR #<NUMBER>.
 
 Context:
 - Repository path: <REPO_PATH>
-- Repository name: <REPO_NAME>
 - PR number: <NUMBER>
+- Worktree path: <WORKTREE_PATH>
 
 Process:
-1. Get feedback: tea pulls <NUMBER> --comments
+1. Move to worktree:
+   cd <WORKTREE_PATH>
 
-2. Setup worktree from PR branch:
+2. Get feedback: tea pulls <NUMBER> --comments
-   cd <REPO_PATH> && git fetch origin
-   git worktree add ../<REPO_NAME>-pr-<NUMBER> origin/<branch-name>
-   cd ../<REPO_NAME>-pr-<NUMBER>
-   git checkout <branch-name>
 
 3. Address each piece of feedback
 
@@ -285,7 +308,7 @@ Process:
    git add -A && git commit -m "Address review feedback\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
    git push
 
-5. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-pr-<NUMBER> --force
+5. Cleanup: No cleanup needed - orchestrator handles worktree removal
 
 6. Output EXACTLY:
    PR_FIXER_RESULT
@@ -296,9 +319,29 @@ Process:
 Work autonomously. If feedback is unclear, make reasonable judgment calls.
 ```
 
+## Worktree Cleanup
+
+After all issues reach terminal state, clean up all worktrees:
+
+```bash
+# Remove all worktrees created for this run
+for worktree in "${WORKTREES_DIR}"/*; do
+  if [ -d "$worktree" ]; then
+    cd "${REPO_PATH}"
+    git worktree remove "$worktree" --force
+  fi
+done
+
+# Remove worktrees directory if empty
+rmdir "${WORKTREES_DIR}" 2>/dev/null || true
+```
+
+**Important:** Always clean up worktrees, even if the orchestration failed partway through.
+
 ## Error Handling
 
 - If an issue-worker fails, continue with others
 - If a review fails, mark as "review-failed" and continue
 - If pr-fixer fails after 3 iterations, mark as "needs-manual-review"
 - Always report final status even if some items failed
+- Always clean up all worktrees before exiting