---
name: working-in-parallel
description: Use git worktrees to work in parallel with other sf agents or alongside the user. Each worktree is an isolated checkout of a branch; changes in one don't affect others. sf already manages worktrees for slice parallelism — this skill is the manual workflow when you need a parallel branch outside the auto-loop.
---

# Working in Parallel

Use **git worktrees** to work in parallel when another agent is in the same directory or when you need an isolated branch for an out-of-band change.

Git worktrees let you check out multiple branches into separate directories. Each worktree has its own isolated files while sharing the same `.git` and remote connections. Changes in one worktree won't affect others, so parallel agents can't interfere with each other.

sf already uses worktrees internally for slice parallelism (see `auto-worktree.ts`, `worktree-manager.ts`). This skill is the manual workflow for the cases where you need a parallel branch outside that auto-managed flow — a hot-fix, an exploration, or a side-chain debug.

Reference: [Git worktree documentation](https://git-scm.com/docs/git-worktree).

## Relationship to SF Swarms

Use the lightest parallelism that is safe:

- **Inline tool batching** for independent reads/searches inside one agent turn.
- **`subagent` research/review swarms** for independent questions or review lenses.
- **2-3 worker execution swarms** only when one task has disjoint file/directory shards and the parent can merge and verify the result.
- **Git worktrees / `/parallel`** when workers need isolated branches or when edits may overlap, touch shared interfaces, or run for a long time.

If file ownership is ambiguous, prefer worktree isolation over same-checkout subagents.

## Before Running Any Command

1. **Read the project's setup notes.** `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `README.md` — in that order. Each may name the canonical commands.
2. **Don't assume the package manager.** sf is `npm` (canonical — never commit `bun.lock` or `pnpm-lock.yaml` per `AGENTS.md`). Other repos differ.
3. **Check for protected files.** sf protects `SPEC.md`, `BUILD_PLAN.md`, `AGENTS.md`, `CLAUDE.md`, `docs/SPEC_FIRST_TDD.md`, `docs/dev/ADR-*.md` from autonomous mutation — those need human approval even on a side branch.

## Quick Start

```bash
# Create worktree with new branch (from the main repo dir)
git worktree add -b fix/my-feature ../singularity-forge-my-feature main

# Work in the worktree
cd ../singularity-forge-my-feature

# Install dependencies (sf is npm)
npm install

# Make changes; verify
npm run typecheck:extensions
npm run test:unit -- <pattern>

# Commit and push
git add <files>
git commit -m "fix(scope): description"
git push -u origin fix/my-feature

# Open a PR
gh pr create --title "fix(scope): description" --body "..."

# Clean up when done (from main repo dir)
git worktree remove ../singularity-forge-my-feature
```

## Key Commands

| Command | Purpose |
|---|---|
| `git worktree add -b <branch> <path> main` | Create a new worktree on a new branch off main |
| `git worktree add <path> <existing-branch>` | Check out an existing branch into a worktree |
| `git worktree list` | Show all worktrees and their branches |
| `git worktree remove <path>` | Remove a worktree (branch is preserved) |
| `git worktree prune` | Clean up references to deleted worktree dirs |

## When to Use

- Another agent (sf autonomous-loop, another Claude session, a teammate) is working in the current directory.
- A long-running build or test is in flight in one terminal and you need a parallel branch.
- You're exploring a refactor that you may abandon — keep main clean.
- You need to apply an upstream cherry-pick from `pi-mono` while a separate legacy port is in progress.

## When NOT to Use

- A trivial single-file change — the overhead is not worth it.
- When sf's auto-loop is already managing the worktree for you (don't fight it; check `git worktree list` first).
- When the change touches *protected* files — those need human approval, not a parallel branch.

## Pre-commit Hooks in Worktrees

Worktrees share `.git`, but hook installation may need re-running depending on the project's setup. After creating a worktree and installing dependencies, verify hooks are active before committing:

```bash
ls .git/hooks/   # in a worktree, .git is a file pointing to the main worktree
ls $(git rev-parse --git-common-dir)/hooks/   # the actual hooks dir
```

In sf, install via:

```bash
npm run secret-scan:install-hook
```

## Tips

- **Name worktree directories clearly**: `../singularity-forge-fix-claim-race`, `../singularity-forge-port-pi-mono-3851`.
- **Push before removing.** `git worktree remove` deletes uncommitted work.
- **Don't share `node_modules` between worktrees** — sf has native bindings (`forge_engine.node`) that need a worktree-local install.
- **Run `git worktree prune` periodically** if you delete worktree directories without `git worktree remove`.

## Alternative: Repo Clones

Some users prefer cloning the repo multiple times (`gh repo clone singularity-ng/singularity-forge sf-feature-auth`) for a simpler mental model. This uses more disk space but provides complete isolation. If you find worktrees confusing or hit edge cases (e.g. shared hooks misbehaving), a fresh clone is a fine alternative.

## sf-Specific: Auto-Loop Awareness

If sf's auto-loop is running in the main repo dir, **do not** start a worktree on the same branch — the auto-loop's commits and yours will race. Either:

- Pause the loop (`/pause` or `Ctrl-C`).
- Work on a different branch in the worktree.
- Or wait for the current slice to merge.
