index

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.

Fix and prevent the Railway "login every 5 minutes" loop: diagnose Unauthorized / invalid_grant errors from the railway CLI or the local `railway mcp` server, and set up headless auth via RAILWAY_API_TOKEN so agents never depend on browser-session tokens. Use when Railway MCP tools return "Unauthorized. Please run railway login again", when `railway whoami` fails right after a successful login, when a token pasted from the dashboard is rejected, or when deciding between account, team, and project tokens for agent/CI use.

Safely run an ad-hoc data backfill/UPDATE against the Index production database (Neon project "Protocol", database protocol_prod) via the Neon MCP tools. Use when reclassifying rows, fixing bad statuses, or any one-off prod data mutation outside Drizzle migrations. Covers the mandatory sequence — validate the predicate with a control group, dry-run the UPDATE on the dev branch, snapshot a backup branch, execute in a transaction, verify exact counts — plus the Neon MCP gotchas (default branch/database resolve to empty neondb; always pass branchId + databaseName=protocol_prod).

Review or change opportunity card/list/discovery/home/digest presentation safely. Use when code touches OpportunityPresenter, list_opportunities/discover_opportunities card formatting, home feed cards, delivery cards, raw interpretation.reasoning/matchReason fallbacks, or any user-facing opportunity description text. Prevents leaking non-LLM evaluator reasoning or heuristic/minimal descriptions into UI, chat, MCP, or digest surfaces.

Review or design Index connect-link (/c/:code) routing changes safely. Use when a PR changes connect links, Telegram/web redirect behavior, preferredSurface/clientSurface, user_socials-based reachability, or drops connect_links columns. Prevents forcing the clicker into Telegram based only on the counterparty and flags mixed-version migration risk.

Pre-merge and post-merge safety checks for promoting a dev→main release in this monorepo, capturing two non-obvious ways a release can break or lose data: (1) a stale root bun.lock fails the prod build under --frozen-lockfile even though dev never caught it, and (2) a destructive Drizzle migration (e.g. DROP TABLE) silently loses prod data when the operational backfill never ran on prod. Use when cutting/merging a release PR to main, when a prod deploy build fails on 'lockfile is frozen', or before merging any PR carrying a DROP/destructive migration.

Use when the user asks about negotiations, pending turns, reviewing what their agent sent, accepting or rejecting a proposal, or countering an offer on Index Network.

Use when the user asks about finding people, connections, opportunities, signals/intents, contacts, community indexes, or anything related to Index Network discovery and network management.

Use in Hermes for autonomous Index Network personal-agent negotiation runs, pending negotiation turns, proposal acceptance/rejection/counters, or explaining what the user's Index negotiator submitted.

Use in Hermes when the user asks to inspect Index Network signals/intents, reason about what they are looking for, or prepare next steps for Index Network discovery.

Diagnose and fix Bun/Linux CI failures where hermetic API tests fail with Drizzle root-barrel export errors such as "Export named 'sql' not found in module node_modules/drizzle-orm/index.js" or missing `relations`. Use after a PR or dev push fails in GitHub Actions despite the same tests passing locally or on the PR branch.

Systematically audit and clean a package in the index monorepo for dead code, unused exports, scope creep, anti-patterns, complexity, coupling, and architectural drift. Asks 'should this exist?' before 'how do I improve this?', fans out a per-dimension audit with hard metric thresholds, classifies findings into tiers (T1 safe deletes through T4 architectural), negotiates scope with the owner, and verifies lint/test/build before and after every change. Use when reviewing or cleaning a api/web/protocol/cli package, removing cruft from a rapidly-developed feature, or doing a pre-refactor audit. Not for greenfield code or single targeted bug fixes.

Author a correct, well-triggered Pi skill (SKILL.md) — frontmatter rules, name constraints, progressive-disclosure description writing, structure, and validation. Use when creating a new skill by hand or reviewing an existing SKILL.md for spec compliance. For deciding WHETHER a session learning is worth capturing, use learn-skill instead; this skill covers HOW to write the file correctly.

Diagnose why the Edge/AgentVillage afternoon negotiation-summary cron "triggered but sent no Telegram message" on a tenant sidecar. Use when a user manually triggered the negotiation summary and nothing arrived. Walks the dedup-by-design check (heartbeat-state reportedCompletedIds), a non-mutating sidecar probe of the data script, and rules out OpenRouter/Telegram/index-MCP causes. The usual cause is correct anti-spam dedup, not a bug.

Capture a reusable learning from the current session and persist it as a new skill, or fold it into an existing one. Use at the end of a session, or whenever a non-obvious workflow, fix, command sequence, or gotcha was discovered that would save time if it were reusable. Writes only to the project-local target (.pi/skills by default); protected locations such as the home folder are never modified in place — a relevant protected skill is migrated (copied) locally first, then updated.

Query Railway logs, variables, services, and status for the Edge City control-plane and per-tenant Hermes sidecars via the Railway MCP. Use when debugging agentvillage card/digest generation, OpenRouter credits, or sidecar health and you need Railway data for a project OTHER than the default-linked Index project. Covers the snake_case project_id/environment_id gotcha and the known Edge City IDs.

Draft the next Agent Village / Edge City Telegram changelog from the last message the user sent and its date/range. Use when the user provides the latest Telegram changelog and wants changes after it detected under packages/edge-city and rewritten as a concise channel-ready update.

Fetch daily digest cards from the agentvillage control-plane and audit them: verify each opportunity belongs to the receiving tenant (ownership / cross-user leaks) AND check overall card quality — broken links, hallucinated content, grammatical/template errors, out-of-order calendar events, and draft-vs-pending status gating. Use when the user asks to audit digests, verify digest ownership, check for cross-user leaks, or asks whether digest cards have problems (bad links, hallucinations, grammar, wrong opportunities).

Use when investigating why the Index Network opportunity evaluator scores matches wrong, or when asked to explain, diagnose, or report on matching-eval results — turning a matching-eval run report (packages/protocol/eval/matching/runs/*.json) into a root-cause and fix report.

Use when a PR needs Copilot code review and the full review-fix-rereview cycle should be handled autonomously

Use when a design spec is approved and needs to be decomposed into tracked, independently deliverable slices before writing implementation plans. Triggers on completed designs, multi-phase features, or when the user asks to break work into pieces with Linear tracking.