@pi-stef/pair 0.1.1

package/src/register.ts

@@ -0,0 +1,232 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  loadAndResolveDefaults,
+  resolveReviewerModel,
+} from "./config/load";
+
+export const PAIR_TOOL_NAMES = [
+  "sf_pair_plan",
+  "sf_pair_implement",
+  "sf_pair_task",
+] as const;
+
+const REVIEWER_AGENT_PATH = ".pi/agents/reviewer.md";
+
+/**
+ * Write the reviewer agent file with the resolved model.
+ * This ensures pi-subagents spawns the reviewer with the correct model.
+ */
+async function writeReviewerAgent(
+  repoRoot: string,
+  model: string
+): Promise<void> {
+  const agentPath = join(repoRoot, REVIEWER_AGENT_PATH);
+  await mkdir(dirname(agentPath), { recursive: true });
+
+  // Read the template file from the package
+  const templatePath = join(dirname(fileURLToPath(import.meta.url)), "..", "agents", "reviewer.md");
+  const template = await readFile(templatePath, "utf8");
+
+  // Replace the {{REVIEWER_MODEL}} placeholder with the resolved model
+  const content = template.replace("{{REVIEWER_MODEL}}", model);
+
+  await writeFile(agentPath, content, "utf8");
+}
+
+/**
+ * Extract reviewer model from prompt string.
+ * Looks for patterns like "use <model> as reviewer" or "reviewer: <model>"
+ */
+function extractReviewerModelFromPrompt(prompt: string): string | undefined {
+  const patterns = [
+    /use\s+([\w/.-]+)\s+as\s+reviewer/i,
+    /reviewer[:\s]+([\w/.-]+)/i,
+    /review\s+with\s+([\w/.-]+)/i,
+  ];
+  for (const pattern of patterns) {
+    const match = prompt.match(pattern);
+    if (match) return match[1];
+  }
+  return undefined;
+}
+
+export function registerSfPair(pi: ExtensionAPI): void {
+  // Register plan tool
+  const planSchema = Type.Object(
+    {
+      prompt: Type.Optional(
+        Type.String({ description: "The task to plan. May include reviewer model override." })
+      ),
+      reviewer_model: Type.Optional(
+        Type.String({ description: "Override reviewer model (e.g. 'anthropic/sonnet-4-6')" })
+      ),
+    },
+    { additionalProperties: false }
+  );
+
+  pi.registerTool({
+    name: "sf_pair_plan",
+    label: "sf_pair_plan",
+    description:
+      "Create a multi-milestone implementation plan with iterative reviewer approval. Produces a plan folder under ai_plan/.",
+    parameters: planSchema as any,
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      const repoRoot = ctx.cwd ?? process.cwd();
+      const defaults = await loadAndResolveDefaults(repoRoot);
+      const promptModel = extractReviewerModelFromPrompt((params as any).prompt ?? "");
+      const model = resolveReviewerModel(
+        (params as any).reviewer_model ?? promptModel,
+        defaults
+      );
+
+      if (!model) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "No reviewer model configured. Please provide one via:\n1. The prompt (e.g. 'use anthropic/sonnet-4-6 as reviewer')\n2. Config file at .pi/sf/pair/config.json\n3. Environment variable SF_PAIR_REVIEWER_MODEL\n4. Or pass reviewer_model parameter",
+            },
+          ],
+          details: { configured: false },
+        };
+      }
+
+      await writeReviewerAgent(repoRoot, model);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Reviewer configured with model: ${model}\nAgent file written to ${REVIEWER_AGENT_PATH}\n\nNow load and follow the plan skill.`,
+          },
+        ],
+        details: { configured: true, model },
+      };
+    },
+  });
+
+  // Register implement tool
+  const implementSchema = Type.Object(
+    {
+      path: Type.String({
+        description:
+          "Plan folder path or slug (e.g. '2026-06-17-add-auth' or 'ai_plan/2026-06-17-add-auth')",
+      }),
+      reviewer_model: Type.Optional(
+        Type.String({ description: "Override reviewer model" })
+      ),
+    },
+    { additionalProperties: false }
+  );
+
+  pi.registerTool({
+    name: "sf_pair_implement",
+    label: "sf_pair_implement",
+    description:
+      "Execute an approved plan milestone-by-milestone in a git worktree. Creates worktree, implements all milestones with reviewer approval, then rolls up commits and deletes worktree.",
+    parameters: implementSchema as any,
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      const repoRoot = ctx.cwd ?? process.cwd();
+      const defaults = await loadAndResolveDefaults(repoRoot);
+      const model = resolveReviewerModel((params as any).reviewer_model, defaults);
+
+      if (!model) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "No reviewer model configured. Please provide one via:\n1. Config file at .pi/sf/pair/config.json\n2. Environment variable SF_PAIR_REVIEWER_MODEL\n3. Or pass reviewer_model parameter",
+            },
+          ],
+          details: { configured: false },
+        };
+      }
+
+      await writeReviewerAgent(repoRoot, model);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Reviewer configured with model: ${model}\nPlan path: ${(params as any).path}\nAgent file written to ${REVIEWER_AGENT_PATH}\n\nNow load and follow the implement skill.`,
+          },
+        ],
+        details: { configured: true, model, path: (params as any).path },
+      };
+    },
+  });
+
+  // Register task tool
+  const taskSchema = Type.Object(
+    {
+      prompt: Type.String({
+        description: "The task to execute end-to-end",
+      }),
+      reviewer_model: Type.Optional(
+        Type.String({ description: "Override reviewer model" })
+      ),
+    },
+    { additionalProperties: false }
+  );
+
+  pi.registerTool({
+    name: "sf_pair_task",
+    label: "sf_pair_task",
+    description:
+      "Execute a single task end-to-end: plan, review, implement, verify, commit. Uses current branch (no worktree).",
+    parameters: taskSchema as any,
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      const repoRoot = ctx.cwd ?? process.cwd();
+      const defaults = await loadAndResolveDefaults(repoRoot);
+      const promptModel = extractReviewerModelFromPrompt((params as any).prompt);
+      const model = resolveReviewerModel(
+        (params as any).reviewer_model ?? promptModel,
+        defaults
+      );
+
+      if (!model) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "No reviewer model configured. Please provide one via:\n1. The prompt (e.g. 'use anthropic/sonnet-4-6 as reviewer')\n2. Config file at .pi/sf/pair/config.json\n3. Environment variable SF_PAIR_REVIEWER_MODEL\n4. Or pass reviewer_model parameter",
+            },
+          ],
+          details: { configured: false },
+        };
+      }
+
+      await writeReviewerAgent(repoRoot, model);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Reviewer configured with model: ${model}\nTask: ${(params as any).prompt}\nAgent file written to ${REVIEWER_AGENT_PATH}\n\nNow load and follow the task skill.`,
+          },
+        ],
+        details: { configured: true, model, prompt: (params as any).prompt },
+      };
+    },
+  });
+
+  // Register slash commands
+  for (const name of PAIR_TOOL_NAMES) {
+    const slashName = name.replace(/_/g, "-");
+    const descriptions: Record<string, string> = {
+      sf_pair_plan: "Create implementation plan with reviewer loop",
+      sf_pair_implement: "Execute plan in worktree with milestone reviews",
+      sf_pair_task: "Execute single task end-to-end",
+    };
+    pi.registerCommand(slashName, {
+      description: descriptions[name] ?? name,
+      handler: async (_args, _ctx) => {
+        // Slash commands are handled by the agent loading the skill
+      },
+    });
+  }
+}

package/src/worktree/cleanup.ts

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { WorktreeError } from "./validate";
+
+const execFileAsync = promisify(execFile);
+
+export interface CleanupOptions {
+  worktreePath: string;
+  branchName: string;
+  baseBranch?: string; // defaults to current branch
+}
+
+/**
+ * Rollup worktree commits to base branch and delete the worktree.
+ *
+ * Steps:
+ * 1. Get current branch (base)
+ * 2. Merge worktree branch into base (--ff-only)
+ * 3. Remove worktree
+ * 4. Delete branch
+ */
+export async function rollupAndCleanup(opts: CleanupOptions): Promise<void> {
+  const { worktreePath, branchName, baseBranch } = opts;
+
+  // Get base branch if not specified
+  let base = baseBranch;
+  if (!base) {
+    const { stdout } = await execFileAsync("git", [
+      "branch",
+      "--show-current",
+    ]);
+    base = stdout.trim();
+  }
+
+  if (!base) {
+    throw new WorktreeError("Could not determine base branch");
+  }
+
+  // Switch to base branch
+  await execFileAsync("git", ["checkout", base]);
+
+  // Merge worktree branch (ff-only) — MUST succeed before cleanup
+  try {
+    await execFileAsync("git", ["merge", "--ff-only", branchName]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new WorktreeError(
+      `Failed to merge ${branchName} into ${base}: ${msg}. Worktree preserved at ${worktreePath} for manual resolution.`
+    );
+  }
+
+  // Only remove worktree after successful merge
+  try {
+    await execFileAsync("git", ["worktree", "remove", worktreePath]);
+  } catch {
+    // Try force remove if normal remove fails
+    await execFileAsync("git", [
+      "worktree",
+      "remove",
+      "--force",
+      worktreePath,
+    ]);
+  }
+
+  // Delete branch after successful merge
+  try {
+    await execFileAsync("git", ["branch", "-d", branchName]);
+  } catch {
+    // Branch may already be deleted by merge
+  }
+}
+
+/**
+ * Remove a worktree without merging (for abort/cleanup scenarios).
+ */
+export async function removeWorktree(worktreePath: string): Promise<void> {
+  try {
+    await execFileAsync("git", ["worktree", "remove", "--force", worktreePath]);
+  } catch {
+    // Ignore errors during cleanup
+  }
+}

package/src/worktree/create.ts

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { validateRepoState, requireInsideWorkTree, WorktreeError } from "./validate";
+
+const execFileAsync = promisify(execFile);
+
+export interface CreateWorktreeOptions {
+  slug: string;
+  branchPrefix?: string;
+  baseRef?: string;
+  allowDirty?: boolean;
+}
+
+export interface WorktreeResult {
+  worktreePath: string;
+  branchName: string;
+  baseSha: string;
+}
+
+function validateSlug(slug: string): void {
+  if (!/^[a-zA-Z0-9._-]+$/.test(slug)) {
+    throw new WorktreeError(
+      `Invalid slug "${slug}". Only alphanumeric, dots, hyphens, and underscores allowed.`
+    );
+  }
+}
+
+export async function createWorktree(
+  opts: CreateWorktreeOptions
+): Promise<WorktreeResult> {
+  const { slug, branchPrefix = "pair/", baseRef = "HEAD", allowDirty } = opts;
+  validateSlug(slug);
+
+  // Validate repo state
+  await validateRepoState({ allowDirty });
+  const repoRoot = await requireInsideWorkTree();
+
+  const branchName = `${branchPrefix}${slug}`;
+
+  // Check branch doesn't exist
+  try {
+    await execFileAsync("git", ["rev-parse", "--verify", branchName]);
+    throw new WorktreeError(`Branch ${branchName} already exists`);
+  } catch (err) {
+    if (err instanceof WorktreeError) throw err;
+    // Branch doesn't exist — good
+  }
+
+  // Resolve base SHA
+  const { stdout: baseShaRaw } = await execFileAsync("git", [
+    "rev-parse",
+    "--verify",
+    baseRef,
+  ]);
+  const baseSha = baseShaRaw.trim();
+
+  // Pick worktree directory (sibling to repo)
+  const parentDir = dirname(repoRoot);
+  const worktreeDirName = `pair-${slug}`;
+  let worktreePath = join(parentDir, worktreeDirName);
+
+  // Handle collision
+  let suffix = 2;
+  while (existsSync(worktreePath)) {
+    worktreePath = join(parentDir, `${worktreeDirName}-${suffix}`);
+    suffix++;
+  }
+
+  // Create parent if needed
+  await mkdir(dirname(worktreePath), { recursive: true });
+
+  // Create worktree
+  await execFileAsync("git", [
+    "worktree",
+    "add",
+    "-b",
+    branchName,
+    worktreePath,
+    baseSha,
+  ]);
+
+  return { worktreePath, branchName, baseSha };
+}

package/src/worktree/validate.ts

@@ -0,0 +1,50 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export class WorktreeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorktreeError";
+  }
+}
+
+export async function requireGitOrThrow(): Promise<void> {
+  try {
+    await execFileAsync("git", ["--version"]);
+  } catch {
+    throw new WorktreeError("git is not available in PATH");
+  }
+}
+
+export async function validateRepoState(opts: {
+  allowDirty?: boolean;
+} = {}): Promise<void> {
+  await requireGitOrThrow();
+
+  if (opts.allowDirty) return;
+
+  const { stdout } = await execFileAsync("git", ["status", "--porcelain"]);
+  if (stdout.trim().length > 0) {
+    throw new WorktreeError(
+      "Working tree is dirty. Commit or stash changes before creating a worktree."
+    );
+  }
+}
+
+export async function requireInsideWorkTree(): Promise<string> {
+  const { stdout } = await execFileAsync("git", [
+    "rev-parse",
+    "--is-inside-work-tree",
+  ]);
+  if (stdout.trim() !== "true") {
+    throw new WorktreeError("Not inside a git repository");
+  }
+
+  const { stdout: root } = await execFileAsync("git", [
+    "rev-parse",
+    "--show-toplevel",
+  ]);
+  return root.trim();
+}

package/templates/continuation-runbook.md

@@ -0,0 +1,145 @@
+# Continuation Runbook: [Plan Title]
+
+## Reference Files (START HERE)
+
+Upon resumption, these files in this folder are the ONLY source of truth:
+
+| File | Purpose | When to Use |
+|------|---------|-------------|
+| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST |
+| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story |
+| `milestone-plan.md` | Complete plan with specifications | Reference implementation details |
+| `original-plan.md` | Original approved plan | Reference original intent |
+| `final-transcript.md` | Final planning transcript | Reference reasoning/context |
+
+Do NOT reference planner-private files during implementation.
+
+---
+
+## Skill Workflow Guardrails
+
+- Load relevant skills before action. If pi did not auto-load them, use `/skill:<name>`.
+- Announce which skill is being used and why.
+- If a checklist-driven workflow applies, keep its state current in the plan artifacts.
+- Do not use deprecated wrapper CLIs.
+
+---
+
+## Quick Resume Instructions
+
+1. Read this runbook completely.
+2. Check `story-tracker.md`.
+3. Find next `pending` story and mark as `in-dev` before starting.
+4. Implement the story.
+5. Update tracker immediately after each change.
+
+---
+
+## Mandatory Execution Workflow
+
+Work from this folder (`ai_plan/[plan-slug]/`) and always follow this order:
+
+1. Read `continuation-runbook.md` first.
+2. Execute stories milestone by milestone.
+3. After completing a milestone:
+   - Run lint/typecheck/tests, prioritizing changed files for speed.
+   - Commit locally (**DO NOT PUSH**).
+   - Stop and ask user for feedback.
+4. If feedback is provided:
+   - Apply feedback changes.
+   - Re-run checks for changed files.
+   - Commit locally again.
+   - Ask for milestone approval.
+5. Only move to next milestone after explicit approval.
+6. After all milestones are completed and approved:
+   - Ask permission to push.
+   - If approved, push.
+   - Mark plan status as `completed`.
+
+---
+
+## Git Note
+
+`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
+
+---
+
+## Full Context Reproduction
+
+### Project Overview
+
+[Description of what we're building]
+
+### User Requirements
+
+[Numbered list of requirements]
+
+### Scope
+
+**In scope:**
+- [Items]
+
+**Out of scope:**
+- [Items]
+
+### Dependencies
+
+- [External dependencies]
+
+---
+
+## Key Specifications
+
+### Type Definitions
+
+```typescript
+[Types]
+```
+
+### Enums & Constants
+
+```typescript
+[Constants]
+```
+
+---
+
+## Critical Design Decisions
+
+| Decision | Chosen Approach | Alternatives Rejected | Rationale |
+|----------|----------------|----------------------|-----------|
+| [Topic] | [What] | [What else] | [Why] |
+
+---
+
+## Verification Commands
+
+### Lint (changed files first)
+
+```bash
+[lint command]
+```
+
+### Typecheck
+
+```bash
+[typecheck command]
+```
+
+### Tests (target changed scope first)
+
+```bash
+[test command]
+```
+
+---
+
+## File Quick Reference
+
+| File | Purpose |
+|------|---------|
+| `original-plan.md` | Original approved plan |
+| `final-transcript.md` | Final planning transcript |
+| `milestone-plan.md` | Full specification |
+| `story-tracker.md` | Current progress tracker |
+| `continuation-runbook.md` | This runbook |

package/templates/milestone-plan.md

@@ -0,0 +1,108 @@
+[Plan Title]
+==============
+
+Overview
+--------
+
+*   **Goal:** [One sentence describing the end state]
+*   **Created:** [YYYY-MM-DD]
+*   **Status:** [Draft | In Review | Approved | In Progress | Completed]
+
+Context
+-------
+
+### Requirements
+
+[Numbered list of what the user asked for]
+
+### Constraints
+
+[Technical or process constraints]
+
+### Success Criteria
+
+[How we know when we're done]
+
+Architecture
+------------
+
+### Design Decisions
+
+| Decision | Chosen Approach | Rationale |
+|----------|----------------|-----------|
+| [Topic] | [What we chose] | [Why] |
+
+### Component Relationships
+
+```
+[ASCII or mermaid diagram]
+```
+
+### Data Flow
+
+[How data moves through the system]
+
+Milestones
+----------
+
+### M1: [Milestone Name]
+
+**Description:** [What this milestone delivers]
+
+**Acceptance Criteria:**
+
+*   [ ] [Testable criterion 1]
+*   [ ] [Testable criterion 2]
+
+**Stories:** S-101, S-102, S-103
+
+**Milestone Completion Rule (MANDATORY):**
+
+*   Run lint/typecheck/tests for changed files.
+*   Commit locally (DO NOT push).
+*   Stop and ask user for feedback.
+*   Apply feedback, re-check changed files, commit again.
+*   Move to next milestone only after user approval.
+
+---
+
+### M2: [Milestone Name]
+
+[Same structure as M1]
+
+---
+
+Technical Specifications
+------------------------
+
+### Types & Interfaces
+
+```typescript
+[Type definitions]
+```
+
+### Constants & Enums
+
+```typescript
+[Constants and enums]
+```
+
+Files Inventory
+---------------
+
+File | Purpose | Milestone
+--- | --- | ---
+`path/to/file` | What it does | M1
+
+---
+
+Related Plan Files
+------------------
+
+This file is part of the plan folder under `ai_plan/`:
+
+*   `original-plan.md` - Original approved plan (reference for original intent)
+*   `final-transcript.md` - Final planning transcript (reference for rationale/context)
+*   `milestone-plan.md` - This file (full specification)
+*   `story-tracker.md` - Status tracking (must be kept up to date)
+*   `continuation-runbook.md` - Resume/execution context (read first)