isolating

Files (2)

• SKILL.md
• setup-commands.md · references/

SKILL.md (first lines)

# Isolating

Announce at start: "I'm applying the isolating skill to set up a separate workspace."

## Directory Resolution

Resolve the worktree root in this order — stop at first match:

1. **Existing directory** — check for `.worktrees/` then `worktrees/` in repo root
2. **CLAUDE.md directive** — `grep -i "worktree.*director" CLAUDE.md`
3. **Prompt** — offer `.worktrees/` (project-local, hidden) or `~/.config/arsyn/worktrees/<project>/` (global)

## Gitignore Gate

For project-local directories only:

```bash
git check-ignore -q .worktrees 2>/dev/null
```

If NOT ignored: add to `.gitignore`, commit, then proceed. Worktree contents tracked in git cause nested-repo confusion that is painful to untangle.

Global directories (`~/.config/arsyn/worktrees/`) skip this check entirely.

## Worktree Lifecycle

```bash
# 1. Detect project
project=$(basename "$(git rev-parse --show-toplevel)")

# 2. Create worktree + branch
git worktree add "$WORKTREE_ROOT/$BRANCH_NAME" -b "$BRANCH_NAME"
cd "$WORKTREE_ROOT/$BRANCH_NAME"

# 3. Install dependencies (auto-detect)
# 4. Run test suite for clean baseline
```

See [references/setup-commands.md](references/setup-commands.md) for dependency installation and test commands by ecosystem.

If baseline tests fail: report failures and ask whether to proceed or investigate. Do not silently continue.

Report when ready:

```
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```

## Quick Reference

| Situation | Action |
|-----------|--------|
| `.worktrees/` exists | Use it (verify ignored) |
| `worktrees/` exists | Use it (verify ignored) |
| Both exist | Use `.worktrees/` |
| Neither exists | Check CLAUDE.md, then ask |
| Directory not ignored | Add to .gitignore, commit |
| Tests fail at baseline | Report + ask |
| No recognizable build file | Skip dependency install |

## Gotchas

- **Shared database state** — Worktrees share git objects but not app state. A migration in one worktree affects every worktree hitting the same database. Coordinate or use separate databases.
- **Stale worktrees accumulate** — Merged branches leave orphaned worktrees. `git worktree list` to audit; `git worktree remove` to clean.
- **Wrong base branch** — Creating from a stale local ref instead of latest `main`/`develop`. Always `git fetch` and branch from the updated remote tip.
- **Forgetting ignore verification** — The single most common mistake. Project-local worktree directories that aren't gitignored pollute `git status` and risk accidental commits.

## Integration

**Called by:**
- **ideating** (Phase 4) — when design is approved and implementation follows
- **orchestrating** — before dispatching subagent tasks
- **executing** — before running plan batches

**Pairs with:**
- **finalizing** — cleans up the worktree after work completes

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn