---
runId: dedf14
feature: worktree-isolation
created: 2025-10-29
status: ready
---

# Feature: Worktree Isolation - Implementation Plan

> **Generated by:** Task Decomposition skill
> **From spec:** specs/dedf14-worktree-isolation/spec.md
> **Created:** 2025-10-29

## Execution Summary

- **Total Tasks**: 3
- **Total Phases**: 1
- **Sequential Time**: 12h
- **Parallel Time**: 5h
- **Time Savings**: 7h (58%)

**Parallel Opportunities:**

- Phase 1: 3 tasks (7h saved)
  - Task 1 and Task 2 are independent (modify different command files)
  - Task 3 depends on understanding from Tasks 1-2 but files are independent

**Rationale for Parallel Execution:**
All three tasks modify different command files with no file overlap. While Task 3 (execute.md) conceptually builds on the patterns from Tasks 1-2, the file changes are independent and can be implemented simultaneously following the same worktree integration pattern.

---

## Phase 1: Command Worktree Integration

**Strategy**: parallel
**Reason**: All tasks modify different command files with no shared dependencies

### Task 1: Spec Command Worktree Integration

**Files**:
- `commands/spec.md`

**Complexity**: M (4h)

**Dependencies**: None

**Description**:
Modify the `/spectacular:spec` command to create an isolated worktree immediately after RUN_ID generation. This establishes the foundation for worktree-based spectacular runs by ensuring all spec work happens in `.worktrees/{runId}-main/` rather than the main repo.

**Implementation Steps**:

1. **Add worktree creation after Step 0 (RUN_ID generation)**:
   - After generating RUN_ID, add new step: "Create isolated worktree"
   - Instruction: Use `using-git-spice` skill to create branch `{runId}-main` from current branch
   - Instruction: Create worktree with `git worktree add .worktrees/{runId}-main {runId}-main`
   - Add check: if worktree already exists, error with clear message

2. **Update working directory context for all subsequent operations**:
   - Add instruction to change context: All file operations after worktree creation happen in `.worktrees/{runId}-main/`
   - Update Step 2 (brainstorming): Note that brainstorming happens in context of worktree
   - Update spec generation: Change output path from `specs/{runId}-{slug}/spec.md` to `.worktrees/{runId}-main/specs/{runId}-{slug}/spec.md`

3. **Update spec commit instructions**:
   - After spec validation passes, add commit step in worktree:
   - ```bash
     cd .worktrees/{runId}-main
     git add specs/
     git commit -m "spec: add ${feature-slug} specification [${RUN_ID}]"
     ```

4. **Update completion message**:
   - Report worktree location: "Worktree: .worktrees/{runId}-main/"
   - Note that spec is in worktree, not main repo
   - Update next steps to reference worktree path

5. **Add error handling**:
   - If `.worktrees/{runId}-main/` already exists: "Worktree {runId}-main already exists. Remove it first or use a different feature name."
   - If worktree creation fails: Report git error details

**Acceptance Criteria**:
- [ ] Worktree created immediately after RUN_ID generation (before brainstorming)
- [ ] Branch `{runId}-main` created using git-spice from current branch
- [ ] Spec file written to `.worktrees/{runId}-main/specs/{runId}-{slug}/spec.md`
- [ ] Spec committed to `{runId}-main` branch in worktree
- [ ] Main repo working directory unchanged (verified with `git status`)
- [ ] Error message shown if worktree already exists
- [ ] Completion message includes worktree location

**Mandatory Patterns**:

> **Constitution**: All changes must follow @docs/constitutions/current/architecture.md

Commands layer: Delegate to skills (`using-git-spice`), don't implement git-spice logic directly

**Quality Gates**:
```bash
# Verify command file structure
cat commands/spec.md | grep -A 5 "Create isolated worktree"

# Test in this repo
/spectacular:spec test-feature
ls .worktrees/ # Should show dedf14-main and new test worktree
git status # Should show no changes in main repo
```

---

### Task 2: Plan Command Worktree Integration

**Files**:
- `commands/plan.md`

**Complexity**: M (3h)

**Dependencies**: None

**Description**:
Modify the `/spectacular:plan` command to operate entirely within the worktree created by `/spectacular:spec`. Extract runId from spec path, switch to worktree context, and commit plan to the worktree branch.

**Implementation Steps**:

1. **Add worktree detection after Step 0 (Extract Run ID)**:
   - After extracting RUN_ID from spec frontmatter, add step: "Switch to worktree context"
   - Extract runId from spec path: `RUN_ID=$(grep "^runId:" {spec-path} | awk '{print $2}')`
   - Add instruction: `cd .worktrees/${RUN_ID}-main`
   - Add error check: If `cd` fails, error: "Worktree not found. Run `/spectacular:spec {feature}` first to create workspace."

2. **Update spec path references**:
   - Clarify that spec is read from worktree: `.worktrees/{runId}-main/specs/{runId}-{slug}/spec.md`
   - Plan will be written to worktree: `.worktrees/{runId}-main/specs/{runId}-{slug}/plan.md`
   - Remove any fallback logic to main repo (worktree is required)

3. **Update plan commit instructions**:
   - After plan generation in Step 1, add commit step:
   - ```bash
     cd .worktrees/${RUN_ID}-main
     git add specs/
     git commit -m "plan: add ${feature-slug} implementation plan [${RUN_ID}]"
     ```

4. **Update completion message**:
   - Report plan location in worktree: "Location: .worktrees/{runId}-main/specs/{runId}-{slug}/plan.md"
   - Update next steps command: `/spectacular:execute @.worktrees/{runId}-main/specs/{runId}-{slug}/plan.md` (or keep short form if path resolution works)

5. **Update error handling section**:
   - Add "Missing worktree" error case
   - Clear message: "Spec not found in worktree. Run `/spectacular:spec` first."

**Acceptance Criteria**:
- [ ] Command extracts runId from spec path
- [ ] Command switches to `.worktrees/{runId}-main/` directory
- [ ] Plan read from worktree, written to worktree
- [ ] Plan committed to `{runId}-main` branch in worktree
- [ ] Clear error if worktree doesn't exist
- [ ] Main repo working directory unchanged
- [ ] Completion message shows worktree path

**Mandatory Patterns**:

> **Constitution**: All changes must follow @docs/constitutions/current/architecture.md

Commands layer: Orchestrate workflow, delegate to `decomposing-tasks` skill for plan generation

**Quality Gates**:
```bash
# Verify command file structure
cat commands/plan.md | grep -A 3 "Switch to worktree"

# Test with existing spec
/spectacular:plan @specs/dedf14-worktree-isolation/spec.md
# Should fail with "Worktree not found" (spec not in worktree yet)

# After implementing Task 1, re-test with worktree-based spec
```

---

### Task 3: Execute Command Worktree Integration

**Files**:
- `commands/execute.md`

**Complexity**: L (5h)

**Dependencies**: None (file independent, but conceptually builds on Tasks 1-2 patterns)

**Description**:
Modify the `/spectacular:execute` command to use the `{runId}-main` worktree as the base for all execution. Serial tasks run in the main worktree, parallel tasks create additional worktrees branching from the `{runId}-main` branch, and all git-spice operations are relative to the worktree branch.

**Implementation Steps**:

1. **Add worktree detection at command start**:
   - After user runs `/spectacular:execute @specs/{runId}-{slug}/plan.md`
   - Add step: "Switch to worktree base"
   - Extract runId from plan path (same pattern as plan command)
   - Instruction: `cd .worktrees/${RUN_ID}-main`
   - Add error check: If worktree doesn't exist, error: "Worktree not found. Run `/spectacular:spec` first."

2. **Update serial task execution**:
   - Current behavior: Serial tasks execute in main repo
   - New behavior: Serial tasks execute in `.worktrees/{runId}-main/`
   - Update orchestrator subagent instructions: "Execute serial tasks directly in current directory (already in worktree)"
   - Commits happen to `{runId}-main` branch

3. **Update parallel task worktree creation**:
   - Current behavior: Parallel tasks create worktrees in `.worktrees/{taskId}/`
   - New behavior: Parallel tasks create worktrees branching from `{runId}-main` branch
   - Update setup subagent instructions:
     - Create worktrees in `.worktrees/{runId}-task-{phase}-{task}/`
     - Branch from `{runId}-main` instead of main/current branch
     - Use `using-git-spice` skill: `gs branch create {runId}-task-{phase}-{task}` (from within `{runId}-main` worktree context)

4. **Update git-spice stacking**:
   - All task branches now stack on `{runId}-main` instead of main
   - After parallel tasks complete, branches are already stacked on `{runId}-main`
   - Cleanup subagent removes parallel worktrees but leaves `{runId}-main` worktree intact
   - Final stack: `{runId}-main` → `{runId}-task-1-1-...` → `{runId}-task-2-1-...` → etc.

5. **Update completion reporting**:
   - Report that all work is in `{runId}-main` worktree
   - Remind user that main repo is untouched
   - Update cleanup instructions:
     - Manual cleanup: `git worktree remove .worktrees/{runId}-main`
     - Branch cleanup: `gs branch delete {runId}-main` (optional)

6. **Update error handling**:
   - Add "Missing worktree" error case (same as plan command)
   - If worktree creation for parallel tasks fails, provide clear error

**Acceptance Criteria**:
- [ ] Command switches to `.worktrees/{runId}-main/` at start
- [ ] Serial tasks execute in `{runId}-main` worktree
- [ ] Parallel tasks create worktrees branching from `{runId}-main` branch
- [ ] All git-spice operations relative to `{runId}-main` branch
- [ ] Main repo working directory unchanged throughout execution
- [ ] Error message shown if worktree missing
- [ ] Completion message notes worktree location and manual cleanup

**Mandatory Patterns**:

> **Constitution**: All changes must follow @docs/constitutions/current/architecture.md

Commands layer: Orchestrate subagents, delegate to skills (`using-git-spice`, `using-git-worktrees`, etc.)

Git-spice integration: Reference `using-git-spice` skill for all branch operations

**Quality Gates**:
```bash
# Verify command file structure
cat commands/execute.md | grep -A 5 "Switch to worktree base"

# Full integration test (after Tasks 1-2 complete):
# 1. Run spec command (creates worktree)
# 2. Run plan command (generates plan in worktree)
# 3. Run execute command (executes in worktree)
# 4. Verify main repo unchanged: git status
# 5. Verify work in worktree: cd .worktrees/{runId}-main && git log
```

---

## Testing Strategy

> **Testing requirements**: @docs/constitutions/current/testing.md

**Integration Testing:**

Since this is a Claude Code plugin (markdown documentation), testing involves:

1. **Manual command testing**:
   - Run each command after implementation
   - Verify worktree creation, context switching, and isolation
   - Confirm main repo remains untouched

2. **Full workflow test**:
   - Run complete workflow: `/spectacular:spec` → `/spectacular:plan` → `/spectacular:execute`
   - Verify all files in worktree, not main repo
   - Test concurrent runs (create two worktrees simultaneously)

3. **Error case testing**:
   - Try to create duplicate worktree (should error)
   - Try plan/execute without worktree (should error with helpful message)
   - Verify error messages guide user correctly

**Quality validation:**

```bash
# After each task:
# 1. Read command file
cat commands/{spec|plan|execute}.md

# 2. Check for constitution compliance
# - Commands delegate to skills (using-git-spice)
# - No direct git-spice implementation in commands
# - Clear error messages

# 3. Test command in this repo
/spectacular:{spec|plan|execute} ...

# 4. Verify main repo unchanged
git status # Should show clean or only NOTES.md

# 5. Verify worktree isolation
ls .worktrees/
cd .worktrees/{runId}-main && git log
```

---

## Phase Execution Strategy

**Phase 1** (all tasks parallel):
- Task 1, Task 2, Task 3 can be implemented simultaneously
- Different files, no dependencies
- Each task modifies one command file
- Pattern is consistent: extract runId → switch to worktree → do work → commit in worktree

**Suggested approach:**
- Use `subagent-driven-development` to dispatch 3 subagents in parallel
- Each subagent implements one task following the implementation steps
- Code review after all 3 complete
- Integration test the full workflow

---

## Constitution Compliance

> **All code must follow**: @docs/constitutions/current/

**Architecture** (@docs/constitutions/current/architecture.md):
- Commands layer: Orchestrate, delegate to skills
- Skills layer: `using-git-spice` already exists for git-spice operations
- No new skills needed (worktree operations are bash commands)

**Patterns** (@docs/constitutions/current/patterns.md):
- Use superpowers metaskills (`using-git-spice`)
- Commands reference skills, don't implement logic directly

**Tech Stack** (@docs/constitutions/current/tech-stack.md):
- Git worktrees (standard git feature)
- git-spice CLI (already required dependency)
- Bash commands for directory switching

**Testing** (@docs/constitutions/current/testing.md):
- Manual testing (commands are markdown)
- Integration testing (full workflow)
- No RED-GREEN-REFACTOR needed (structural change, not skill creation)

---

## Migration Notes

**Breaking Change**: This is a breaking change (NFR1 from spec)

**Impact**:
- Existing specs in main repo won't work with updated commands
- Users must re-run `/spectacular:spec` to create worktree-based specs
- Or manually migrate: create worktree, move spec/plan files, commit

**Migration path** (for existing specs):
```bash
# For spec at specs/abc123-feature/spec.md
RUN_ID=abc123
FEATURE=feature

# Create worktree
gs branch create ${RUN_ID}-main
git worktree add .worktrees/${RUN_ID}-main ${RUN_ID}-main

# Move spec/plan to worktree
cd .worktrees/${RUN_ID}-main
mv ../../specs/${RUN_ID}-${FEATURE} specs/
git add specs/
git commit -m "migrate: move spec to worktree [${RUN_ID}]"

# Now can use /spectacular:plan and /spectacular:execute
```

**Acceptable tradeoff**: Cleaner architecture + concurrent runs worth the migration cost