@pi-stef/pair 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefano Fiorini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agents/reviewer.md

@@ -0,0 +1,53 @@
+---
+description: Plan/Implementation Reviewer
+tools: read, grep, find, ls
+model: {{REVIEWER_MODEL}}
+thinking: high
+max_turns: 30
+isolated: true
+---
+
+You are a code reviewer. Your job is to review plans and implementation diffs for correctness, completeness, and risk.
+
+When reviewing a plan:
+- Check that milestones are well-defined with clear acceptance criteria
+- Check that stories are bite-sized (2-5 min each)
+- Check that the plan is detailed enough for a less intelligent model to follow
+- Check for missing edge cases or error handling
+
+When reviewing an implementation:
+- Check that the diff matches the plan
+- Check for bugs, security issues, and missing error handling
+- Check that tests cover the changes
+- Check that verification (lint/typecheck/tests) passes
+
+Return exactly this structure:
+
+## Summary
+[One paragraph summary of the review]
+
+## Findings
+
+### P0
+- None.
+
+### P1
+- None.
+
+### P2
+- None.
+
+### P3
+- None.
+
+## Verdict
+VERDICT: APPROVED
+
+Rules:
+- P0 = total blocker (must fix)
+- P1 = major risk (must fix)
+- P2 = must-fix before approval
+- P3 = cosmetic / nice-to-have (non-blocking)
+- Use `- None.` when a severity has no findings
+- VERDICT: APPROVED is valid only when no P0, P1, or P2 findings remain
+- Order findings from highest to lowest severity

package/extensions/pair.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerSfPair } from "../src/register";
+
+export default function pairExtension(pi: ExtensionAPI): void {
+  registerSfPair(pi);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pi-stef/pair",
+  "version": "0.1.1",
+  "description": "Pi extension for plan/review/implement workflows using pi-subagents for reviewer spawning.",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@tintinweb/pi-subagents": "*"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "*",
+    "@pi-stef/paths": "0.3.3"
+  },
+  "devDependencies": {
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "files": [
+    "src/",
+    "extensions/",
+    "skills/",
+    "templates/",
+    "agents/"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pair",
+    "plan",
+    "implement",
+    "review"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/skills/sf-pair-implement/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sf-pair-implement
+description: Use when a plan folder created by sf-pair-plan must be executed with milestone verification, reviewer gates, and automatic worktree management.
+---
+
+# sf-pair-implement
+
+Execute an existing plan milestone-by-milestone in a git worktree, with reviewer approval gates and automatic worktree lifecycle.
+
+## Prerequisites
+
+- pi-subagents extension installed
+- A plan folder under `ai_plan/`
+- Reviewer model configured
+- Obra Superpowers skills available to pi: `verification-before-completion`, `finishing-a-development-branch` (install from https://github.com/obra/superpowers)
+
+## Input Resolution
+
+The tool receives a `path` parameter. Resolve it:
+
+1. If path starts with `ai_plan/` → use as-is
+2. Otherwise → treat as slug, resolve to `ai_plan/YYYY-MM-DD-<slug>/`
+3. If multiple matches, list them and ask user to pick
+
+## Process
+
+### Phase 1: Locate Plan
+
+1. Read `continuation-runbook.md` first
+2. Read `story-tracker.md` to identify resume state
+3. Read `milestone-plan.md` for the implementation spec
+
+### Phase 2: Resolve Reviewer
+
+Verify `.pi/agents/reviewer.md` exists. If not, stop and ask for model.
+
+### Phase 3: Set Up Worktree
+
+Create a git worktree:
+- Branch: `pair/<slug>`
+- Base: HEAD
+- Install deps if missing (detect pnpm/npm/yarn)
+
+Use the worktree helpers from `src/worktree/create.ts` via the tool's execute function. The skill instructs the agent to:
+
+1. Run `git worktree add -b pair/<slug> <path> HEAD`
+2. Run package manager install in the worktree directory
+3. Switch to the worktree directory for implementation
+
+### Phase 4: Execute Milestones
+
+Do not stop between milestones. For each milestone:
+
+1. Mark stories `in-dev` in `story-tracker.md`
+2. Implement each story following the plan to the letter
+3. Mark stories `completed` with commit hash in notes
+4. Run verification (lint/typecheck/tests) for changed files
+5. Spawn reviewer on milestone diff:
+   ```
+   Agent({
+     subagent_type: "reviewer",
+     prompt: "Review the milestone implementation. [include diff and verification output]",
+     description: "Review milestone M<N>"
+   })
+   ```
+6. If APPROVED → commit locally, mark milestone `approved`
+7. If REVISE → fix findings, re-review
+
+### Phase 5: Finalization
+
+Once all milestones are approved and reviewed:
+
+1. Switch to base branch
+2. Merge worktree branch: `git merge --ff-only pair/<slug>`
+3. Remove worktree: `git worktree remove <worktree-path>`
+4. Delete branch: `git branch -d pair/<slug>`
+5. Stop for user's final review
+
+### Phase 6: Telegram Notification
+
+If configured, send completion summary.

package/skills/sf-pair-plan/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: sf-pair-plan
+description: Use when a user asks to create a structured implementation plan with milestones, stories, and reviewer approval using pi-subagents.
+---
+
+# sf-pair-plan
+
+Create a multi-milestone implementation plan with iterative reviewer approval.
+
+## Prerequisites
+
+- pi-subagents extension installed
+- Reviewer model configured (via config, env, or prompt)
+- Obra Superpowers skills available to pi: `brainstorming`, `writing-plans` (install from https://github.com/obra/superpowers)
+
+## Process
+
+### Phase 1: Analyze
+
+Explore the codebase and existing patterns. Use exploration agents to understand the project structure.
+
+### Phase 2: Gather Requirements
+
+Ask questions one at a time using `AskUserQuestion` until the scope is clear. Confirm constraints, success criteria, dependencies, and what is out of scope.
+
+### Phase 3: Resolve Reviewer Model
+
+The tool has already resolved the reviewer model and written `.pi/agents/reviewer.md`. Verify it exists:
+
+```
+test -f .pi/agents/reviewer.md
+```
+
+If it doesn't exist, stop and ask the user for a reviewer model.
+
+### Phase 4: Design
+
+Load `brainstorming` skill. Present 2-3 approaches and recommend one. Resolve open design questions before the milestone breakdown.
+
+### Phase 5: Plan
+
+Load `writing-plans` skill. Break the work into milestones and bite-sized stories (2-5 min each). Story IDs use `S-101`, `S-102` style.
+
+Each story must be detailed enough for a less intelligent model to follow to the letter.
+
+### Phase 6: Iterative Plan Review
+
+#### Step 1: Write plan to temp file
+
+Write the complete plan to `/tmp/pair-plan-{REVIEW_ID}.md` where REVIEW_ID is a random UUID.
+
+#### Step 2: Spawn reviewer
+
+```
+Agent({
+  subagent_type: "reviewer",
+  prompt: "Review the implementation plan at /tmp/pair-plan-{REVIEW_ID}.md. Return exactly the required ## Summary, ## Findings (P0-P3), and ## Verdict structure.",
+  description: "Review plan round N"
+})
+```
+
+#### Step 3: Parse verdict
+
+Scan the response for `VERDICT: APPROVED` (case-insensitive, line must start with `VERDICT:`).
+
+- If found AND no P0/P1/P2 findings → proceed to Phase 7
+- If not found OR P0/P1/P2 present → extract findings, fix, rewrite /tmp file, goto Step 2
+- If max rounds (10) reached → stop, present outcome to user
+
+### Phase 7: Generate Plan Files
+
+Once the plan is approved:
+
+1. Ensure `ai_plan/` exists in `.gitignore`
+2. Create `ai_plan/YYYY-MM-DD-<slug>/`
+3. Write using templates from this package's `templates/` directory:
+   - `original-plan.md` — raw approved plan
+   - `final-transcript.md` — conversation log
+   - `milestone-plan.md` — from template
+   - `story-tracker.md` — from template
+   - `continuation-runbook.md` — from template
+
+### Phase 8: Telegram Notification
+
+If `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured, send a completion summary via the Telegram notifier helper.

package/skills/sf-pair-task/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: sf-pair-task
+description: Execute a single task end-to-end with plan review, implementation review, verification, and one persistent task-plan artifact.
+---
+
+# sf-pair-task
+
+Execute a single user task end-to-end: clarify, plan, review, implement, verify, review, commit.
+
+## Prerequisites
+
+- pi-subagents extension installed
+- Reviewer model configured
+- Obra Superpowers skills available to pi: `brainstorming`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch` (install from https://github.com/obra/superpowers)
+
+## Process
+
+### Phase 1: Preflight
+
+1. Verify repo: `git rev-parse --is-inside-work-tree`
+2. Ensure `ai_plan/` exists in `.gitignore`
+3. Verify `.pi/agents/reviewer.md` exists
+
+### Phase 2: Parse Prompt And Clarify
+
+1. Capture the user's prompt verbatim
+2. Ask 1-3 clarifying questions one at a time using `AskUserQuestion`
+3. Load `brainstorming` for behavior-changing work
+
+### Phase 3: Initialize task-plan.md
+
+1. Compute `ai_plan/YYYY-MM-DD-<slug>/`
+2. Write `task-plan.md` from template
+3. Fill all sections: Metadata, Prompt, Interpretation, Assumptions, Files, Approach, TDD Approach, Acceptance Criteria, Verification, Rollback
+4. Set `Status: draft`
+
+### Phase 4: Plan Review
+
+1. Write task-plan content to `/tmp/pair-task-plan-{REVIEW_ID}.md`
+2. Spawn reviewer:
+   ```
+   Agent({
+     subagent_type: "reviewer",
+     prompt: "Review the task plan at /tmp/pair-task-plan-{REVIEW_ID}.md",
+     description: "Review task plan"
+   })
+   ```
+3. Fix P0/P1/P2 findings until APPROVED
+4. Set `Status: plan-approved`
+
+### Phase 5: Execute
+
+1. Set `Status: implementation-in-progress`
+2. Load `test-driven-development` for behavior-changing edits
+3. Implement following the plan to the letter
+4. Update `task-plan.md` as acceptance criteria are completed
+
+### Phase 6: Verification Gate
+
+1. Load `verification-before-completion`
+2. Run verification commands from task-plan.md
+3. Fix failures until green
+
+### Phase 7: Implementation Review
+
+1. Build review payload from approved plan + diff + verification output
+2. Spawn reviewer:
+   ```
+   Agent({
+     subagent_type: "reviewer",
+     prompt: "Review the implementation. [include diff and verification]",
+     description: "Review implementation"
+   })
+   ```
+3. Fix P0/P1/P2 findings until APPROVED
+4. Set `Status: implementation-approved`
+
+### Phase 8: Commit And Push
+
+1. Load `finishing-a-development-branch`
+2. Stage intended files
+3. Create one commit
+4. Ask whether to push or keep local
+
+### Phase 9: Telegram Notification
+
+If configured, send completion summary.

package/src/config/load.ts

@@ -0,0 +1,123 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { Value } from "@sinclair/typebox/value";
+import { globalConfig, projectConfig } from "@pi-stef/paths";
+import {
+  ConfigSchema,
+  DEFAULT_CONFIG,
+  type PairConfig,
+  type ResolvedPairConfig,
+} from "./schema";
+
+export class ConfigValidationError extends Error {
+  constructor(
+    public readonly filePath: string,
+    public readonly pointer: string,
+    message: string
+  ) {
+    super(`Config validation error in ${filePath} at ${pointer}: ${message}`);
+    this.name = "ConfigValidationError";
+  }
+}
+
+async function loadFile(filePath: string): Promise<PairConfig> {
+  const raw = await readFile(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  const errors = [...Value.Errors(ConfigSchema, parsed)];
+  if (errors.length > 0) {
+    const first = errors[0];
+    throw new ConfigValidationError(
+      filePath,
+      first.path,
+      first.message
+    );
+  }
+  return parsed as PairConfig;
+}
+
+/** Load file, returning null if not found (ENOENT), throwing on parse/validation errors. */
+async function loadFileOrNull(filePath: string): Promise<PairConfig | null> {
+  try {
+    return await loadFile(filePath);
+  } catch (err: unknown) {
+    if (
+      err &&
+      typeof err === "object" &&
+      "code" in err &&
+      (err as { code: string }).code === "ENOENT"
+    ) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+export async function loadConfig(
+  repoRoot: string,
+  opts: { homeDir?: string } = {}
+): Promise<PairConfig> {
+  const homeDir = opts.homeDir ?? homedir();
+  const globalPath = globalConfig("pair", homeDir);
+  const projectPath = projectConfig("pair", repoRoot);
+
+  const global = (await loadFileOrNull(globalPath)) ?? {};
+  const project = (await loadFileOrNull(projectPath)) ?? {};
+
+  // Deep merge: project wins on conflicts, but nested objects are merged field-by-field
+  return {
+    reviewer: {
+      ...(global.reviewer ?? {}),
+      ...(project.reviewer ?? {}),
+    },
+  };
+}
+
+export function resolveDefaults(loaded: PairConfig = {}): ResolvedPairConfig {
+  return {
+    reviewer: {
+      model: loaded.reviewer?.model ?? DEFAULT_CONFIG.reviewer.model,
+    },
+  };
+}
+
+export async function loadAndResolveDefaults(
+  repoRoot: string,
+  opts: { homeDir?: string; notify?: (msg: string, level: string) => void } = {}
+): Promise<ResolvedPairConfig> {
+  try {
+    const loaded = await loadConfig(repoRoot, { homeDir: opts.homeDir });
+    return resolveDefaults(loaded);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    opts.notify?.(
+      `sf-pair config: ${detail} — falling back to built-in defaults.`,
+      "warning"
+    );
+    return resolveDefaults({});
+  }
+}
+
+/**
+ * Resolve reviewer model from the 4-step chain:
+ * 1. Prompt argument (parsed by caller)
+ * 2. Project/global config
+ * 3. Environment variable SF_PAIR_REVIEWER_MODEL
+ * 4. Ask user (returns null, caller must prompt)
+ */
+export function resolveReviewerModel(
+  promptArg: string | undefined,
+  config: ResolvedPairConfig
+): string | null {
+  // 1. Prompt argument
+  if (promptArg) return promptArg;
+
+  // 2. Config file
+  if (config.reviewer.model) return config.reviewer.model;
+
+  // 3. Environment variable
+  const envModel = process.env.SF_PAIR_REVIEWER_MODEL;
+  if (envModel) return envModel;
+
+  // 4. Not found — caller must ask user
+  return null;
+}

package/src/config/schema.ts

@@ -0,0 +1,35 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+export const ConfigSchema = Type.Object(
+  {
+    reviewer: Type.Optional(
+      Type.Object(
+        {
+          model: Type.Optional(
+            Type.String({
+              minLength: 1,
+              description:
+                "Model for the reviewer agent (e.g. 'anthropic/sonnet-4-6')",
+            })
+          ),
+        },
+        { additionalProperties: false }
+      )
+    ),
+  },
+  { additionalProperties: false }
+);
+
+export type PairConfig = Static<typeof ConfigSchema>;
+
+export interface ResolvedPairConfig {
+  reviewer: {
+    model: string | null;
+  };
+}
+
+export const DEFAULT_CONFIG: ResolvedPairConfig = {
+  reviewer: {
+    model: null, // null = not configured, must ask user
+  },
+};