@pi-stef/pair 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-stef/pair",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Pi extension for plan/review/implement workflows using pi-subagents for reviewer spawning.",
   "type": "module",
   "pi": {

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

@@ -17,7 +17,14 @@ Create a multi-milestone implementation plan with iterative reviewer approval.
 
 ### Phase 1: Analyze
 
-Explore the codebase and existing patterns. Use `Agent()` to understand the project structure — this inherits the current session model. Do NOT specify a model or agentType unless explicitly asked.
+Explore the codebase and existing patterns. Use `Agent({ agentType: "general-purpose" })` to understand the project structure.
+
+If an explorer model was configured (via prompt, config, or env), use it:
+```
+Agent({ agentType: "general-purpose", model: "<explorer_model>" })
+```
+
+If no explorer model is configured, omit the `model` parameter to inherit the current session model. Do NOT use the default `Explore` agent (it uses Haiku).
 
 ### Phase 2: Gather Requirements
 
@@ -35,7 +42,7 @@ 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.
+Load `brainstorming` skill. Present 2-3 approaches and recommend one. Use `AskUserQuestion` to get the user's approval on the chosen approach before proceeding. Do NOT move to Phase 5 until the user confirms the design.
 
 ### Phase 5: Plan
 
@@ -69,16 +76,33 @@ Scan the response for `VERDICT: APPROVED` (case-insensitive, line must start wit
 
 ### 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
+**CRITICAL: The plan is NOT complete until ALL files are created in `ai_plan/`. Do NOT stop or ask the user how to proceed.**
+
+Once the plan is approved by the reviewer, you MUST:
+
+1. **Check `.gitignore`**: Run `grep -qx '/ai_plan/' .gitignore || echo '/ai_plan/' >> .gitignore`
+2. **Create the plan folder**: `mkdir -p ai_plan/YYYY-MM-DD-<slug>/` (use today's date and a descriptive slug)
+3. **Read the templates**: Read the 3 templates from the `templates/` directory (relative to this skill: `../../templates/`). Note: `task-plan.md` is for the task skill only — ignore it here.
+4. **Write ALL 5 files** (use the same slug throughout):
+   - `ai_plan/YYYY-MM-DD-<slug>/original-plan.md` — the raw approved plan from the review
+   - `ai_plan/YYYY-MM-DD-<slug>/final-transcript.md` — conversation log of the planning session
+   - `ai_plan/YYYY-MM-DD-<slug>/milestone-plan.md` — filled from `milestone-plan.md` template
+   - `ai_plan/YYYY-MM-DD-<slug>/story-tracker.md` — filled from `story-tracker.md` template
+   - `ai_plan/YYYY-MM-DD-<slug>/continuation-runbook.md` — filled from `continuation-runbook.md` template
+
+5. **Verify all files exist**:
+   ```
+   ls -la ai_plan/YYYY-MM-DD-<slug>/
+   ```
+   If any file is missing, create it immediately.
+
+6. **Present the plan folder to the user**: Show the file list and confirm the plan is ready for implementation.
+
+**DO NOT:**
+- Say "Plan complete" without creating the ai_plan/ folder
+- Ask the user how to proceed with implementation
+- Save the plan to any other location (docs/plans/, etc.)
+- Skip any of the 5 required files
 
 ### Phase 8: Telegram Notification
 

package/src/config/load.ts

@@ -69,6 +69,10 @@ export async function loadConfig(
       ...(global.reviewer ?? {}),
       ...(project.reviewer ?? {}),
     },
+    explorer: {
+      ...(global.explorer ?? {}),
+      ...(project.explorer ?? {}),
+    },
   };
 }
 
@@ -77,6 +81,9 @@ export function resolveDefaults(loaded: PairConfig = {}): ResolvedPairConfig {
     reviewer: {
       model: loaded.reviewer?.model ?? DEFAULT_CONFIG.reviewer.model,
     },
+    explorer: {
+      model: loaded.explorer?.model ?? DEFAULT_CONFIG.explorer.model,
+    },
   };
 }
 
@@ -121,3 +128,28 @@ export function resolveReviewerModel(
   // 4. Not found — caller must ask user
   return null;
 }
+
+/**
+ * Resolve explorer model from the 3-step chain:
+ * 1. Prompt argument (parsed by caller)
+ * 2. Project/global config
+ * 3. Environment variable SF_PAIR_EXPLORER_MODEL
+ * 4. Returns null to inherit parent model (no need to ask user)
+ */
+export function resolveExplorerModel(
+  promptArg: string | undefined,
+  config: ResolvedPairConfig
+): string | null {
+  // 1. Prompt argument
+  if (promptArg) return promptArg;
+
+  // 2. Config file
+  if (config.explorer.model) return config.explorer.model;
+
+  // 3. Environment variable
+  const envModel = process.env.SF_PAIR_EXPLORER_MODEL;
+  if (envModel) return envModel;
+
+  // 4. Not found — inherit parent model
+  return null;
+}

package/src/config/schema.ts

@@ -16,6 +16,20 @@ export const ConfigSchema = Type.Object(
         { additionalProperties: false }
       )
     ),
+    explorer: Type.Optional(
+      Type.Object(
+        {
+          model: Type.Optional(
+            Type.String({
+              minLength: 1,
+              description:
+                "Model for the explorer agent (e.g. 'anthropic/sonnet-4-6'). Falls back to parent model if not set.",
+            })
+          ),
+        },
+        { additionalProperties: false }
+      )
+    ),
   },
   { additionalProperties: false }
 );
@@ -26,10 +40,16 @@ export interface ResolvedPairConfig {
   reviewer: {
     model: string | null;
   };
+  explorer: {
+    model: string | null;
+  };
 }
 
 export const DEFAULT_CONFIG: ResolvedPairConfig = {
   reviewer: {
     model: null, // null = not configured, must ask user
   },
+  explorer: {
+    model: null, // null = not configured, inherit parent model
+  },
 };

package/src/register.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import {
   loadAndResolveDefaults,
   resolveReviewerModel,
+  resolveExplorerModel,
 } from "./config/load";
 
 export const PAIR_TOOL_NAMES = [
@@ -54,16 +55,36 @@ function extractReviewerModelFromPrompt(prompt: string): string | undefined {
   return undefined;
 }
 
+/**
+ * Extract explorer model from prompt string.
+ * Looks for patterns like "use <model> as explorer" or "explorer: <model>"
+ */
+function extractExplorerModelFromPrompt(prompt: string): string | undefined {
+  const patterns = [
+    /use\s+([\w/.-]+)\s+as\s+explorer/i,
+    /explorer[:\s]+([\w/.-]+)/i,
+    /explore\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." })
+        Type.String({ description: "The task to plan. May include reviewer/explorer model overrides." })
       ),
       reviewer_model: Type.Optional(
         Type.String({ description: "Override reviewer model (e.g. 'anthropic/sonnet-4-6')" })
       ),
+      explorer_model: Type.Optional(
+        Type.String({ description: "Override explorer model (e.g. 'anthropic/sonnet-4-6'). Falls back to parent model if not set.", minLength: 1 })
+      ),
     },
     { additionalProperties: false }
   );
@@ -77,13 +98,16 @@ export function registerSfPair(pi: ExtensionAPI): void {
     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,
+      const prompt = (params as any).prompt ?? "";
+
+      // Resolve reviewer model
+      const promptReviewerModel = extractReviewerModelFromPrompt(prompt);
+      const reviewerModel = resolveReviewerModel(
+        (params as any).reviewer_model ?? promptReviewerModel,
         defaults
       );
 
-      if (!model) {
+      if (!reviewerModel) {
         return {
           content: [
             {
@@ -95,16 +119,27 @@ export function registerSfPair(pi: ExtensionAPI): void {
         };
       }
 
-      await writeReviewerAgent(repoRoot, model);
+      // Resolve explorer model (optional, falls back to parent)
+      const promptExplorerModel = extractExplorerModelFromPrompt(prompt);
+      const explorerModel = resolveExplorerModel(
+        (params as any).explorer_model ?? promptExplorerModel,
+        defaults
+      );
+
+      await writeReviewerAgent(repoRoot, reviewerModel);
+
+      const explorerInfo = explorerModel
+        ? `Explorer model: ${explorerModel}`
+        : "Explorer model: inherits from parent (not configured)";
 
       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.`,
+            text: `Reviewer configured with model: ${reviewerModel}\n${explorerInfo}\nAgent file written to ${REVIEWER_AGENT_PATH}\n\nNow load and follow the sf-pair-plan skill.`,
           },
         ],
-        details: { configured: true, model },
+        details: { configured: true, reviewerModel, explorerModel },
       };
     },
   });
@@ -152,10 +187,10 @@ export function registerSfPair(pi: ExtensionAPI): void {
         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.`,
+            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 sf-pair-implement skill.`,
           },
         ],
-        details: { configured: true, model, path: (params as any).path },
+        details: { configured: true, reviewerModel: model, path: (params as any).path },
       };
     },
   });
@@ -206,10 +241,10 @@ export function registerSfPair(pi: ExtensionAPI): void {
         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.`,
+            text: `Reviewer configured with model: ${model}\nTask: ${(params as any).prompt}\nAgent file written to ${REVIEWER_AGENT_PATH}\n\nNow load and follow the sf-pair-task skill.`,
           },
         ],
-        details: { configured: true, model, prompt: (params as any).prompt },
+        details: { configured: true, reviewerModel: model, prompt: (params as any).prompt },
       };
     },
   });