/incubate

name: incubate
description: Clone or create repos for active development — the right hand of /learn. Use when user says "incubate [repo]", "work on [repo]", "clone for dev", or wants to set up a dev workflow. Use --wt SLUG to give each agent its own git worktree body when several agents develop the same repo in parallel. Do NOT trigger for study/exploration (use /learn), finding projects (use /trace), or session mining (use /dig).
argument-hint: "<repo-url|slug|name> [--wt <slug> [--task \"...\"] [--from <ref>]] [--flash | --contribute | --status | --offload [--wt <slug> | --all-wt]]"

/incubate — Active Development Workflow

Clone or create repos for active development → set up branches, make changes, push PRs.

> "/learn reads the book. /incubate writes the next chapter."

Usage

/incubate [url]                          # Clone via ghq, symlink, ready for dev
/incubate [slug]                         # Use slug from ψ/memory/slugs.yaml
/incubate [repo-name]                    # Finds in ghq or creates with default org
/incubate [url] --flash "fix desc"       # Issue → branch → fix → PR → offload
/incubate [url] --contribute             # Fork if needed → branch per feature → PRs
/incubate --status                       # List all active ψ/incubate/ with git status
/incubate --status --include-offloaded   # Also list offloaded entries from .origins (#280)
/incubate --offload [slug]               # Remove symlink, keep ghq clone
/incubate --offload [slug] --purge       # Also drop entry from .origins manifest (#280)
/incubate --init                         # Restore all origins after git clone

# Parallel bodies — one git worktree per agent, same mother clone (#487)
/incubate [slug] --wt <name>             # Claim a body on branch incubate/<name>
/incubate [slug] --wt <name> --task "…"  # Same, recording who + why (worktree lock reason)
/incubate [slug] --wt <name> --from <ref># Branch from <ref> (default: origin/HEAD)
/incubate --offload [slug] --wt <name>   # Retire ONE body (branch survives)
/incubate --offload [slug] --all-wt      # Retire every body on this machine

---

Workflow Modes

| Flag | Scope | Duration | Cleanup | |------|-------|----------|---------| | (default) | Long-term dev | Weeks/months | Manual offload | | `--wt <slug>` | One agent's parallel body | Hours/days | `--offload --wt <slug>` (branch survives) | | `--flash` | Single fix | Minutes | Issue → PR → auto-offload + purge | | `--contribute` | Multi-feature | Days/weeks | Offload when all PRs done | | `--status` | Query | — | Read-only listing | | `--offload` | Cleanup | — | Remove symlink (keep ghq) |

incubate        → Long-term dev (manual cleanup)
    ↓
--wt <slug>     → N agents, N worktrees, 1 mother clone (parallel bodies)
    ↓
--contribute    → Push → offload (keep ghq)
    ↓
--flash         → Issue → Branch → PR → offload → purge (complete cycle)

**Mother and bodies (#487).** One `ghq` clone per repo per machine = one working tree = one checked-out branch, so N agents on the same repo stomp each other. `--wt` gives each agent a **body**: a `git worktree` on its own branch `incubate/<slug>`, sharing the mother's object store. The mother clone is untouched — on the `--wt` path it is **fetch-only**, never pulled, never stashed.

The claim is atomic for free: `git worktree add -b` creates the branch ref in a single ref transaction, so of N agents racing for the same slug **exactly one wins** and the losers touch nothing. No lockfiles, no `flock` (unreliable on NFS, meaningless across machines), no claim directory.

---

Directory Structure

ψ/incubate/
├── .origins                          # Manifest of incubated MOTHERS (committed)
└── OWNER/
    └── REPO/
        ├── origin                    # Symlink to mother ghq clone (gitignored)
        ├── REPO.md                   # Hub file — tracks incubation sessions (committed)
        └── wt/                       # Parallel bodies (#487)
            └── <slug>/
                └── origin            # Symlink to the worktree (gitignored)

Machine-local side (never in ψ, never committed):

$(ghq root)/github.com/OWNER/REPO   # mother clone — one per repo per machine
$WT_ROOT/OWNER/REPO/<slug>/         # body — branch incubate/<slug>

WT_ROOT="${INCUBATE_WT_ROOT:-${XDG_STATE_HOME:-$HOME/.local/state}/incubate/worktrees}"

**ψ is the committed soul; worktrees are machine-local scratch.** Bodies live outside ψ **and** outside `$(ghq root)`. ψ gets one gitignored symlink per body and nothing else.

**Bodies must not live under `$(ghq root)` (#487).** ghq decides "this is a repository" by `stat`-ing `<dir>/.git`, and a linked worktree's `.git` is a regular file that passes that test. Measured on ghq 1.10.1, with bodies under `$(ghq root)/.worktrees/`:

$ ghq list
.worktrees/acme/api/fix-auth      ← phantom
github.com/acme/api

Every consumer of `ghq list` then sees phantom repos, and `.worktrees` sorts *before* `github.com`, so any "first match wins" resolver returns the body instead of the repo. That is a regression in **other** skills caused by this one, so the body root lives in the XDG state directory. `$INCUBATE_WT_ROOT` relocates it; any path outside `$(ghq root)` works, including a different filesystem (E17).

**The body link filename is literally `origin` — this is load-bearing.** It means the existing `.gitignore` rule `ψ/incubate/**/origin` already covers bodies (no new rule), `wt/<slug>/` contains nothing git tracks (no `.gitkeep`), and the `--status`/`--offload` finders keep working unmodified.

**There is no per-body manifest file.** The registry is `git -C <mother> worktree list --porcelain -z`, which git maintains atomically and which cannot drift from reality. A committed `.origins.d/<slug>.yaml` was rejected (#487): committed files mean N agents each `git add`/commit/push into ψ, converting a benign file race into a git non-fast-forward race one layer up.

Per-body metadata (who, when, why)