feat: slash command handlers — /start, /research, /plan, /work in TypeScript

[randomm]

Goal

Convert OpenCode markdown slash commands to Pi TypeScript handlers with programmatic subagent orchestration.

Migrated from pi-an#6.

Commands to implement

• /start — session bootstrap (memory search, project context)
• /research — multi-pronged parallel research with @explore
• /plan — structured GitHub issue creation with type-specific templates
• /work — full 9-step issue execution workflow

/work workflow (the heart of this issue)

Encode the steps from pi-permissions' AGENTS.md /work slash command:

1. Read issue + project context (parallel: @explore for AGENTS.md/codebase/memory)
2. Decompose and plan; decide worktree strategy
3. Setup branch + worktrees if needed
4. Execute in parallel (@developer + @explore + @ops where independent)
5. Adversarial review (mandatory gate) — dispatch @adversarial-developer with diff; APPROVED required before commit
6. Commit + PR (cherry-pick from worktrees if multi-task; one PR per issue)
7. Six-pass code review — six parallel @code-review-specialist tasks (SECURITY, ERROR_HANDLING, TYPE_SAFETY, PERFORMANCE, ARCHITECTURE, SIMPLICITY); deduplicate by (path, line, title); precedence ladder SECURITY > ERROR_HANDLING > TYPE_SAFETY > PERFORMANCE > ARCHITECTURE > SIMPLICITY
8. CI watch + merge (per AGENTS.md merge policy; gh pr merge --squash --delete-branch)
9. Store learnings in vipune

Hard-enforced loop limits (in TypeScript, not just docs)

• Max 3 adversarial re-dispatches per round
• Max 3 review cycles total (developer-fix → adversarial → six-pass)
• Max 90 minutes wall-clock for entire Step 7
• On limit hit: STOP, emit user-escalation event, do NOT proceed silently

Required PR-creation guardrails

• Always pass --base main to gh pr create (lesson from pi-permissions PR chore: AGENTS.md with worktree-safety section #6)
• Fixes #N on its own line at top of PR body (pre-merge auto-close)
• After merge: verify auto-close via gh issue view N --json state after ~60s wait

Synthesis logic for six-pass review

Verdict ladder (first match wins):

1. ANY CRITICAL → CRITICAL_ISSUES_FOUND
2. ANY HIGH → ISSUES_FOUND
3. ANY MEDIUM → ISSUES_FOUND (user can override)
4. Only LOW or none → APPROVED

Deduplication: group findings by (normalized_path, line, title); on conflict keep highest-precedence lens.

Acceptance criteria

Functional

• Four slash commands implemented in TypeScript (one file per command, plus shared helpers)
• /work executes the full 9-step workflow programmatically
• Loop limits hard-enforced; user-escalation event emitted on limit hit
• PR creation always uses --base main and Fixes #N in body
• Six-pass synthesis with deduplication and precedence ladder

Quality gates

• TDD: tests written before implementation
• 80%+ coverage; 85%+ for /work handler (safety-critical orchestration logic)
• Loop limits have dedicated tests (proving they actually halt at the cap)
• Mocked subagent dispatch in tests (no real LLM calls in CI)
• biome / tsc --noEmit / bun test green
• No any, @ts-ignore, biome-ignore

Documentation

• Each slash command's behavior documented in README
• /work workflow diagram in AGENTS.md (or linked doc)

Dependencies

• Requires pi-worktree plugin (feat: worktree plugin #2) for the worktree creation step in /work
• Requires AGENTS.md (chore chore: AGENTS.md with worktree-safety section #6) so handlers can reference its guidance
• Requires foundation chores 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 landed first

Out of scope (file separately if needed)

• Additional slash commands beyond the four listed (/lint, /test, /deploy, etc.)
• Slash command auto-discovery / extension registry
• Conversational continuation between commands (each invocation is stateless)

[randomm]

Closing as out-of-scope for pi-worktree.

On review, the four slash commands (/start, /research, /plan, /work) are a Pi-harness orchestration concern, not a git-worktree concern. /work uses worktree primitives but the surface itself — programmatic subagent dispatch, hard-enforced loop limits, six-pass review synthesis, GitHub issue lifecycle — has no cohesion with safe git worktree management.

The natural home is a separate plugin (working name: pi-orchestration or similar) that depends on @randomm/pi-worktree for the worktree-creation step in /work. Splitting it out keeps both plugins focused, lets each evolve independently, and avoids forcing every consumer of worktree primitives to also pull in PM-orchestration code.

The scope itself is also larger than the title suggests: building /work means encoding the full PM-as-code orchestration loop in TypeScript with mocked subagent dispatch for tests — a substantial project on its own.

This issue and its scope will be re-filed in the new repo when it's created. Tracking continues in the upstream pi-an migration plan.

[randomm]

Correction to my earlier comment on this issue: the natural home for these slash commands is @randomm/pi-pm, not a hypothetical pi-orchestration. Per the upstream migration plan (randomm/pi-an, private), pi-pm is the planned single npm package that ships:

• The 4 slash commands (/start /research /plan /work)
• 6 agent definitions (PM, developer, ops, explore, code-review, adversarial)
• 18 skills
• The bash permission hook
• Dependency on @randomm/pi-worktree (this repo) for worktree primitives in /work

Authoritative tracking for the slash commands scope is randomm/pi-an#6 (the upstream issue this issue was originally migrated from — it should remain open there as the canonical tracker). Closing here was correct; no need to re-file.

[randomm]

Correction to my earlier comments: the slash commands belong upstream in randomm/pi-an, not in any new package. The authoritative tracker is randomm/pi-an#6 (the upstream issue this issue was originally migrated from). The package name and exact home are decisions tracked in pi-an itself; what matters here is that this scope does NOT belong in pi-worktree. Closing was correct; no need to re-file.