EPIC: pi-worktree plugin development roadmap

[randomm]

Goal

Ship a robust git-worktree management plugin for the Pi agent harness, with safety guardrails informed by lessons from randomm/pi-permissions and from documented agentic-AI worktree disasters (Claude Code #39394 etc.).

Recommended order of work

Phase 0: Quality gate (DONE)

• chore: AGENTS.md with worktree-safety section #6 — AGENTS.md with worktree-safety section ✅ landed as inaugural commit on main

Phase 1: Foundation (DONE)

• chore: repo bootstrap (license, AGENTS.md, package.json, tsconfig, biome, vitest) #4 — repo bootstrap (license, package.json, tsconfig, biome, vitest)
• chore: GitHub repo settings + CI workflow #5 — GitHub repo settings + CI workflow
• chore: README + CONTRIBUTING.md + issue templates #7 — README + CONTRIBUTING.md + issue templates

Phase 2: Core plugin (DONE)

• feat: worktree plugin #2 — feat: worktree plugin (Worktree.create/list/remove/reset, state machine, persistence, EventBus, five-footgun guardrails)

Phase 3: Polish (in flight)

• fix: normalize saveLocks key in persistence.ts to prevent trailing-slash collisions #11 — normalize saveLocks key in persistence.ts (trailing-slash key collision)
• fix: detect actual detached HEAD in worktree-ops.create() simplified path #12 — detect actual detached HEAD in worktree-ops.create() simplified path

Out of scope (moved upstream)

• feat: slash command handlers — /start, /research, /plan, /work in TypeScript #3 — slash command handlers (/start /research /plan /work) — closed as not-planned for this repo (Apr 2026). Slash commands belong in the upstream PM-harness migration tracked in randomm/pi-an (private; see PI_MIGRATION.md). Authoritative tracking lives in randomm/pi-an#6. The eventual home will depend on @randomm/pi-worktree for worktree primitives.

Sequencing notes

• AGENTS.md (chore: AGENTS.md with worktree-safety section #6) shipped first to establish quality gates before any other agent work
• Repo settings (squash-only, PR_BODY) already applied via API
• Phase 1 (chore: repo bootstrap (license, AGENTS.md, package.json, tsconfig, biome, vitest) #4 + chore: GitHub repo settings + CI workflow #5 + chore: README + CONTRIBUTING.md + issue templates #7) shipped as one bootstrap PR (chore: Phase 1 bootstrap — tooling, CI, and contributor docs #9, merged ad563da)
• Phase 2 (feat: worktree plugin #2) shipped as PR feat(#2): worktree plugin with five-footgun guardrails #10 (merged d5dacca) with 169 tests, persistence.ts ≥ 85%, worktree-ops.ts ≥ 99%
• Phase 3 polish (fix: normalize saveLocks key in persistence.ts to prevent trailing-slash collisions #11, fix: detect actual detached HEAD in worktree-ops.create() simplified path #12) can ship together or independently — both are small

Definition of done for the epic

• Plugin source: @randomm/pi-worktree v0.1.0 (Apache-2.0, Bun + Vitest + Biome 1.9.4)
• CI green on every PR (workflow active since chore: Phase 1 bootstrap — tooling, CI, and contributor docs #9)
• 80%+ global coverage; 85%+ on safety-critical modules (persistence.ts, worktree-ops.ts)
• README documents safety guarantees against the five footguns
• Polish issues (fix: normalize saveLocks key in persistence.ts to prevent trailing-slash collisions #11, fix: detect actual detached HEAD in worktree-ops.create() simplified path #12) closed
• Plugin published to npm as @randomm/pi-worktree (deferred until v0.2.0; pre-1.0 distribution via manual install)

Slash commands removed from this epic; tracked upstream in randomm/pi-an#6.