spec-kitty-worktree-guide

name	spec-kitty-worktree-guide
description	Hard-won lessons for working with spec-kitty worktrees, merges, and Python editable installs. Use whenever implementing, reviewing, or merging spec-kitty work packages.
user-invocable	false

Spec-Kitty Worktree Survival Guide

Lessons learned from real spec-kitty feature implementations. These are problems you WILL hit — follow these rules to avoid them.

1. Editable Installs Break in Worktrees

Problem: Worktrees are fresh git checkouts — they do NOT inherit pip install -e from the main repo. Tests fail with ModuleNotFoundError.

Rule: After creating any worktree, immediately install the package:

cd .worktrees/<feature>-WP##/
python3.11 -m pip install -e ".[dev]"

Also applies post-merge: When worktrees are deleted during merge cleanup, the editable install still points to the deleted worktree path. You MUST reinstall from main after every merge:

cd /path/to/main/repo
python3.11 -m pip install -e ".[dev]"

2. Subtasks Must Be Marked Done Before Moving WP

Problem: spec-kitty agent tasks move-task WP## --to for_review fails if any subtasks (T001, T002...) are still unchecked.

Rule: Mark all subtasks done first:

spec-kitty agent tasks mark-status T001 T002 T003 --status done

3. Marking Subtasks Puts Worktree Behind Main

Problem: Marking subtasks as done commits to main. The worktree branch is now behind main. spec-kitty rejects status moves on stale branches.

Rule: Rebase after marking subtasks and before every status move:

cd .worktrees/<feature>-WP##/
git stash
git rebase main
git stash pop  # only if you had uncommitted changes

Expect to do this 2-3 times per WP lifecycle.

4. .gitignore Modifications Block Everything

Problem: If .gitignore was modified on main outside the workflow, worktrees inherit this as an uncommitted change. spec-kitty's pre-flight checks reject all status transitions.

Rule: Use --force when you know the only dirty file is .gitignore:

spec-kitty agent tasks move-task WP## --to for_review --force --note "..."

Or clean it manually:

git checkout -- .gitignore

5. Merge Pre-flight Requires Pristine State EVERYWHERE

Problem: spec-kitty merge checks ALL worktrees AND the main repo. It fails if ANY have uncommitted or untracked changes. Common offenders:

• Modified .gitignore in worktrees
• .hypothesis/ directory from property tests
• Untracked files in main: .claudeignore, .kittify/, .claude/, .codex/

Rule — Clean ALL worktrees first:

# For each worktree
cd .worktrees/<feature>-WP##/
git checkout -- .gitignore
rm -rf .hypothesis/

Rule — Clean main repo:

cd /path/to/main/repo
git checkout -- .gitignore
git stash --include-untracked -m "temp stash for merge"

Note: plain git stash does NOT capture untracked files. You MUST use --include-untracked.

After merge succeeds:

git stash pop

6. WP Dependencies Require --base Flag

Problem: Implementing a WP that depends on another WP fails without specifying the base.

Rule:

spec-kitty agent workflow implement WP02 --base WP01 --agent <name>

7. Do NOT Automate Bulk Code Modifications

Problem: Scripts to bulk-modify source files (regex-based or AST-based) are fragile and have corrupted entire test suites. Regex matches too broadly (hits imports, other function calls). AST unparsing loses formatting.

Rule: Write each file individually. It takes longer but succeeds on the first try. Use parallel Write tool calls for efficiency — you can write all files in a single message.

If you must restore after a failed script:

git checkout -- tests/

8. Hypothesis Property Tests Need deadline=None

Problem: Hypothesis property tests that construct Pydantic models with uuid.uuid4() intermittently fail under pytest-cov coverage instrumentation. The default 200ms deadline is exceeded by Pydantic validation overhead.

Rule: Always add @settings(deadline=None) to property-based tests:

from hypothesis import given, strategies as st, settings

@settings(deadline=None)
@given(st.lists(my_strategy(), min_size=1, max_size=10))
def test_my_property(self, items):
    ...

9. Add .hypothesis/ to .gitignore

Running Hypothesis tests creates a .hypothesis/ cache directory. If not gitignored, it shows up as an untracked file and blocks merge pre-flight.

Add to .gitignore:

# Hypothesis
.hypothesis/

10. Python Version Awareness

Problem: Multiple Python versions may be installed (e.g., 3.11 and 3.14). The default python may not be the one with your editable install.

Rule: Always use the explicit version:

python3.11 -m pytest tests/
python3.11 -m pip install -e ".[dev]"

Never use bare python or python3.

Quick Reference: WP Lifecycle Checklist

[ ] Create worktree: spec-kitty agent workflow implement WP## --agent <name>
[ ] cd into worktree
[ ] Install: python3.11 -m pip install -e ".[dev]"
[ ] Implement changes
[ ] Run tests: python3.11 -m pytest tests/ -v
[ ] Commit: git add -A && git commit -m "feat(WP##): ..."
[ ] Mark subtasks: spec-kitty agent tasks mark-status T0## --status done
[ ] Rebase: git rebase main
[ ] Move to review: spec-kitty agent tasks move-task WP## --to for_review --note "..."
    (use --force if .gitignore is the only dirty file)

Quick Reference: Merge Checklist

[ ] All WPs in "done" lane
[ ] Clean each worktree: git checkout -- .gitignore && rm -rf .hypothesis/
[ ] Clean main: git checkout -- .gitignore
[ ] Stash main untracked: git stash --include-untracked
[ ] Verify: git status --short shows empty in main AND all worktrees
[ ] Merge: spec-kitty merge --feature <feature-slug>
[ ] Pop stash: git stash pop
[ ] Reinstall: python3.11 -m pip install -e ".[dev]"
[ ] Verify: python3.11 -m pytest tests/ -v