kirocrew-worktree-dev

Kiro Crew worktree development

This skill applies ONLY to the Kiro Crew source repository or a worktree of it. Ignore it for other projects. One feature uses one dedicated worktree containing both src/kiro_crew/ and website/, including backend-only changes. Never edit the live checkout or start/stop the live gateway from a feature session.

Worktree and environment

# From the main clone; skip creation when already in the assigned worktree.
git fetch origin main
git worktree add ../kirocrew-wt-<name> -b feat/<name> origin/main
cd ../kirocrew-wt-<name>
python3 -m venv .venv
.venv/bin/pip install -e ".[voice]" --group dev
cd website && npm ci && cd ..
git worktree list

To bring the main clone itself current (the first path git worktree list prints), fast-forward it and nothing else:

git -C <main clone> symbolic-ref --short HEAD   # must print main
git -C <main clone> fetch origin main
git -C <main clone> merge --ff-only --no-autostash --no-overwrite-ignore origin/main

It refuses, changing nothing, when local main has diverged or a local change would be overwritten; then stop and report, because that state belongs to whoever left it. Before any rebase, checkout, switch, merge, pull or reset in a clone, run python3 <this skill>/scripts/live_checkout_guard.py <clone>. Exit 30 (or 2): a running gateway runs from it, so make a worktree; the operator's dashboard Update syncs that clone. Never overlay a whole tree with git checkout <ref> -- . or git restore --source <ref> .: neither moves HEAD, both overwrite local edits without asking, and the checkout form keeps every file upstream deleted. Never git stash: every worktree shares one stash list, so a pop can apply another session's work.

Working from several worktrees? If uv resolves in your shell (command -v uv — it is a declared dependency of the package, so any activated Kiro Crew venv has it on PATH; a bare shell may not), build the venv with it instead: same deps, but site-packages are copy-on-write clones out of one global cache, so on a reflink filesystem (XFS with reflink, btrfs, APFS) each extra venv costs ~10 MB of unique disk and ~10 s instead of ~400 MB and ~1 min; without reflink uv copies, so you keep the speed and lose the disk saving. kirocrew pod provision runs the same two steps (without the [voice] extra) when KIROCREW_PROVISION_USE_UV=1 is set (opt-in for now; design record: the "Shared Dependency Cache for Worktrees" RFC under docs/request-for-change):

uv venv --seed --allow-existing --link-mode clone --python 3.12 .venv
uv pip install --link-mode clone --python .venv/bin/python --project . -e ".[voice]" --group dev

--link-mode clone must be explicit (uv's Linux default has been seen to copy on a reflink-capable filesystem), --project . makes --group read this worktree's pyproject.toml from any cwd, and --seed keeps .venv/bin/pip present for make backend. Do not use --link-mode hardlink: it shares the inode, so an in-place edit under .venv/lib/.../site-packages would land in every sibling venv and in the cache. A clone is safe to edit; the write copies the block.