Finish a pull request end-to-end from the canonical/root session: investigate PR health (base freshness, checks, review threads, version bumps, local builds), hand off any needed worktree changes to the worktree session as a fix prompt — never mutating the worktree from this session — merge the PR after explicit confirmation, verify post-merge GitHub/Railway deployment health, and close or update related GitHub and Linear issues. Use when the user says a PR is ready to finish, ship, merge, or close out.
Run the packages/protocol eval harnesses correctly — the live LLM harnesses (bun run eval:matching/hyde/premise/profile/opportunity/clarification, which need OPENROUTER_API_KEY auto-loaded from root .env.test) versus the provider-free CI gate (bun run eval:verify, which strips credentials and never calls a model). Use when asked to "run the evals", verify eval suites, add a new eval harness, update a baseline, or when eval:verify fails on an unlisted directory or a baseline-coverage spec after adding a corpus case.
Ship a change to the Edge-City agentvillage submodule end-to-end and bump the index monorepo's submodule pointer, without initializing the submodule in a worktree. Use after merging a PR in Edge-City/agentvillage (or when the pointer at packages/edge-city/agentvillage is stale) — covers the branch-in-submodule → PR-to-Edge-City → pointer-bump-PR-to-dev flow, the git update-index --cacheinfo 160000 plumbing trick for committing a gitlink from a worktree with an empty submodule dir, and restoring the root submodule to a clean detached checkout.
Ship and flip feature flags consistently across ALL env surfaces in the index monorepo — .env.example (committed, commented docs), root .env.development (gitignored local mirror of Railway dev), Railway dev service variables (Railway MCP), and startup.env.ts registration. Use when adding a new env-gated feature flag, enabling/disabling a flag on dev, or when a flag behaves differently locally vs on Railway. Covers the ship-dark→flip order, railway_set_variables gotchas (snake_case ids, map-shaped variables, auto-redeploy), and why the root-dev-guard warning on .env.development edits is safe to ignore.
Create and operate git worktrees in the index monorepo using the project's `bun run worktree:*` helpers instead of raw git. Use whenever you need an isolated branch checkout to make changes (the canonical root must stay on dev and is read-only for the assistant, enforced by the root-dev-guard extension), or when a worktree is missing env files, node_modules, or git hooks, or when a tool/bash call is blocked for touching the canonical root, or when `git commit`/`git rebase` fails with "gpg: signing failed: Inappropriate ioctl for device" in a non-interactive shell. Covers the dashed-folder / slashed-branch naming convention, why `worktree:setup` is mandatory after creating a worktree, and how to disable GPG signing worktree-locally without touching the user's repo-wide signing config.
Open a dated release branch from dev and create a GitHub pull request into main with a generated changelog from git log and git diff. Use when preparing a dev-to-main release PR or when the user asks to cut/open a release PR.
Handle incoming PR review feedback, especially GitHub Copilot conversations, by fetching unresolved review threads, deciding whether fixes are needed, applying fixes, replying with reasoning, and resolving conversations. Use when the user asks to receive, address, or resolve PR review feedback.
Coordinate feature and fix development across two Pi sessions — a main session in the canonical root checkout and a worktree session in a git worktree — through explicit named-prompt handoffs: create and set up a worktree with a semantic branch name, hand implementation to a new worktree session, request acceptance before commit, open the PR, hand back to the main session for finish-pr, and run the fix loop where finish-pr findings return as prompts that the worktree session fixes before redirecting the user back. Use when Index work moves from investigation into implementation, when a PR needs fixes after review or finish-pr findings, or when working through Zed's worktree UI.