supipowers 1.2.6 → 1.5.0

package/src/planning/approval-flow.ts

@@ -1,5 +1,7 @@
 import type { Platform } from "../platform/types.js";
+import type { DebugLogger } from "../debug/logger.js";
 import type { ResolvedModel } from "../types.js";
+import type { PlanningSystemPromptOptions } from "./system-prompt.js";
 import { applyModelOverride } from "../config/model-resolver.js";
 import { listPlans, readPlanFile } from "../storage/plans.js";
 
@@ -18,6 +20,12 @@ let planCwd: string = "";
 let capturedNewSession: ((options?: any) => Promise<{ cancelled: boolean }>) | null = null;
 /** Resolved model for plan action — re-applied on execution handoff. */
 let capturedResolvedModel: ResolvedModel | null = null;
+/** Guards against concurrent approval prompts from rapid agent_end events. */
+let approvalPending = false;
+/** Planning-system-prompt options captured from the command context at plan start. */
+let planningPromptOptions: PlanningSystemPromptOptions | null = null;
+/** Active debug logger for the current planning session. */
+let planningDebugLogger: DebugLogger | null = null;
 
 /** Mark planning as started (called by plan command after sending steer). */
 export function startPlanTracking(
@@ -25,12 +33,25 @@ export function startPlanTracking(
   paths: any,
   newSession?: (options?: any) => Promise<{ cancelled: boolean }>,
   resolvedModel?: ResolvedModel,
-): void {
+  promptOptions?: PlanningSystemPromptOptions,
+  debugLogger?: DebugLogger,
+ ): void {
   planningActive = true;
   planCwd = cwd;
   plansBefore = listPlans(paths, cwd);
   capturedNewSession = newSession ?? null;
   capturedResolvedModel = resolvedModel ?? null;
+  planningPromptOptions = promptOptions ?? null;
+  planningDebugLogger = debugLogger ?? null;
+  approvalPending = false;
+
+  planningDebugLogger?.log("planning_tracking_started", {
+    cwd,
+    existingPlanCount: plansBefore.length,
+    hasNewSession: Boolean(newSession),
+    hasResolvedModel: Boolean(resolvedModel),
+    promptOptions: promptOptions ?? null,
+  });
 }
 
 /** Cancel plan tracking (e.g., session change). */
@@ -40,6 +61,9 @@ export function cancelPlanTracking(): void {
   planCwd = "";
   capturedNewSession = null;
   capturedResolvedModel = null;
+  planningPromptOptions = null;
+  planningDebugLogger = null;
+  approvalPending = false;
 }
 
 /** Whether a planning session is currently active. */
@@ -47,6 +71,14 @@ export function isPlanningActive(): boolean {
   return planningActive;
 }
 
+export function getPlanningPromptOptions(): PlanningSystemPromptOptions | null {
+  return planningPromptOptions;
+}
+
+export function getPlanningDebugLogger(): DebugLogger | null {
+  return planningDebugLogger;
+}
+
 /**
  * Build the execution handoff prompt from an approved plan.
  *
@@ -93,23 +125,40 @@ async function executeApproveFlow(
   ctx: any,
   planContent: string,
   planPath: string,
-): Promise<void> {
+  newSession: ((options?: any) => Promise<{ cancelled: boolean }>) | null,
+  resolvedModel: ResolvedModel | null,
+  debugLogger: DebugLogger | null,
+ ): Promise<void> {
   const prompt = buildExecutionPrompt(planContent, planPath);
+  debugLogger?.log("execution_handoff_started", {
+    planPath,
+    promptLength: prompt.length,
+    usesNewSession: Boolean(newSession),
+  });
 
   // Re-apply the plan model override for the execution turn.
   // The planning turn's restore hook already fired (model reverted to default).
   // We must switch again so the execution LLM turn uses the configured model.
-  if (capturedResolvedModel) {
-    await applyModelOverride(platform, ctx, "plan", capturedResolvedModel);
+  if (resolvedModel) {
+    await applyModelOverride(platform, ctx, "plan", resolvedModel);
+    debugLogger?.log("execution_handoff_model_override_applied", {
+      configuredAction: "plan",
+    });
   }
 
-  if (capturedNewSession) {
-    const result = await capturedNewSession();
+  if (newSession) {
+    const result = await newSession();
     if (result?.cancelled) {
+      debugLogger?.log("execution_handoff_new_session_cancelled", {
+        planPath,
+      });
       ctx.ui.notify("Session start cancelled. Plan saved; run /supi:plan again to execute.");
       return;
     }
     platform.sendUserMessage(prompt);
+    debugLogger?.log("execution_handoff_user_message_sent", {
+      planPath,
+    });
   } else {
     // Fallback: headless/SDK mode — steer in the current session.
     platform.sendMessage(
@@ -120,6 +169,9 @@ async function executeApproveFlow(
       },
       { deliverAs: "steer", triggerTurn: true },
     );
+    debugLogger?.log("execution_handoff_same_session_steer_sent", {
+      planPath,
+    });
     ctx.ui.notify("Plan approved — starting execution");
   }
 }
@@ -135,7 +187,7 @@ async function executeApproveFlow(
  */
 export function registerPlanApprovalHook(platform: Platform): void {
   platform.on("agent_end", async (_event: any, ctx: any) => {
-    if (!planningActive || !ctx?.hasUI) return;
+    if (!planningActive || !ctx?.hasUI || approvalPending) return;
 
     // Detect newly written plan files
     const plansNow = listPlans(platform.paths, planCwd);
@@ -151,20 +203,47 @@ export function registerPlanApprovalHook(platform: Platform): void {
     // Pick the most recent new plan
     const planName = newPlans[newPlans.length - 1];
     const planContent = readPlanFile(platform.paths, planCwd, planName);
-    if (!planContent) return;
+    const debugLogger = planningDebugLogger;
+    if (!planContent) {
+      debugLogger?.log("approval_flow_plan_content_missing", {
+        planName,
+      });
+      return;
+    }
 
     const planPath = `${platform.paths.dotDirDisplay}/supipowers/plans/${planName}`;
-
-    const choice = await ctx.ui.select("Plan complete — what next?", [
+    const approvalOptions = [
       "Approve and execute",
       "Refine plan",
       "Stay in plan mode",
-    ]);
+    ];
+
+    approvalPending = true;
+    debugLogger?.log("approval_flow_presented", {
+      planName,
+      planPath,
+      options: approvalOptions,
+    });
+    const choice = await ctx.ui.select("Plan complete — what next?", approvalOptions);
+    approvalPending = false;
+    debugLogger?.log("approval_flow_choice", {
+      choice: choice ?? null,
+      planPath,
+    });
 
     if (choice === "Approve and execute") {
-      planningActive = false;
-      plansBefore = [];
-      await executeApproveFlow(platform, ctx, planContent, planPath);
+      const executionNewSession = capturedNewSession;
+      const executionModel = capturedResolvedModel;
+      cancelPlanTracking();
+      await executeApproveFlow(
+        platform,
+        ctx,
+        planContent,
+        planPath,
+        executionNewSession,
+        executionModel,
+        debugLogger,
+      );
     } else if (choice === "Refine plan") {
       // Keep planning active, let user type refinement.
       // Empty input is treated as misclick → fall through to approve.
@@ -172,16 +251,43 @@ export function registerPlanApprovalHook(platform: Platform): void {
       const refinement = await ctx.ui.input("What should be refined?");
       if (!refinement || !refinement.trim()) {
         // Misclick: treat empty input as approval
-        planningActive = false;
-        plansBefore = [];
-        await executeApproveFlow(platform, ctx, planContent, planPath);
+        debugLogger?.log("approval_flow_empty_refinement_treated_as_approve", {
+          planPath,
+        });
+        const executionNewSession = capturedNewSession;
+        const executionModel = capturedResolvedModel;
+        cancelPlanTracking();
+        await executeApproveFlow(
+        platform,
+        ctx,
+        planContent,
+        planPath,
+        executionNewSession,
+        executionModel,
+        debugLogger,
+      );
       } else {
+        debugLogger?.log("approval_flow_refine_requested", {
+          planPath,
+          refinementLength: refinement.length,
+        });
         ctx.ui.setEditorText?.(refinement);
       }
-    } else {
-      // Stay in plan mode — user keeps control, tracking cancelled
+    } else if (choice === "Stay in plan mode") {
+      // Explicit user choice — cancel tracking, return control
+      debugLogger?.log("planning_tracking_cancelled", {
+        reason: "stay_in_plan_mode",
+        planPath,
+      });
       cancelPlanTracking();
       ctx.ui.notify("Planning complete. Plan saved but not executing.");
+    } else {
+      // Select was cancelled (returned undefined/null) — likely because a new
+      // agent turn started (e.g., background job completion). Don't cancel
+      // tracking; the next agent_end will re-prompt.
+      debugLogger?.log("approval_flow_choice_cancelled", {
+        planPath,
+      });
     }
   });
 }

package/src/planning/plan-writer-prompt.ts

@@ -25,7 +25,8 @@ export function buildPlanWriterPrompt(options: PlanWriterOptions): string {
     "",
     "Write the plan assuming the implementing engineer has zero context for this codebase.",
     "Document everything they need: which files to touch, complete code, testing, exact commands.",
-    "Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.",
+    "Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD.",
+    "Keep the plan local-only: do NOT include git add, git commit, git push, or other VCS steps in the plan.",
     "",
 
     // ── Scope Check ──────────────────────────────────────────────
@@ -73,7 +74,6 @@ export function buildPlanWriterPrompt(options: PlanWriterOptions): string {
     "- Run it to verify it fails — one step",
     "- Write minimal implementation — one step",
     "- Run tests to verify it passes — one step",
-    "- Commit — one step",
     "",
 
     // ── Task Structure ───────────────────────────────────────────
@@ -113,13 +113,6 @@ export function buildPlanWriterPrompt(options: PlanWriterOptions): string {
     "",
     "Run: `bun test tests/path/test.ts`",
     "Expected: PASS",
-    "",
-    "- [ ] **Step 5: Commit**",
-    "",
-    "```bash",
-    "git add tests/path/test.ts src/path/file.ts",
-    'git commit -m "feat: add specific feature"',
-    "```",
     "````",
     "",
 
@@ -129,9 +122,9 @@ export function buildPlanWriterPrompt(options: PlanWriterOptions): string {
     "- Exact file paths always",
     "- Complete code in plan (not 'add validation' — show the actual code)",
     "- Exact commands with expected output",
-    "- DRY, YAGNI, TDD, frequent commits",
+    "- DRY, YAGNI, TDD",
+    "- No git commit, push, or other VCS steps in the plan",
     "",
-
     // ── Plan Review Loop ─────────────────────────────────────────
     "## Step 4: plan review loop",
     "",

package/src/planning/planning-ask-tool.ts

@@ -0,0 +1,81 @@
+import type { Platform } from "../platform/types.js";
+
+/**
+ * Register a `planning_ask` tool — identical to the built-in `ask` tool
+ * but with **no timeout**. OMP's built-in ask tool applies the user's
+ * `ask.timeout` setting (default 30s) and only disables it for OMP's
+ * native plan mode. Since `/supi:plan` is not native plan mode, planning
+ * questions would auto-dismiss. This tool bypasses that limitation.
+ *
+ * The tool is always registered (lightweight) but the planning system
+ * prompt directs the model to use it only during planning sessions.
+ */
+export function registerPlanningAskTool(platform: Platform): void {
+  if (!platform.registerTool) return;
+
+  platform.registerTool({
+    name: "planning_ask",
+    label: "Planning Question",
+    description:
+      "Ask the user questions during planning sessions. Use this instead of the ask tool when in /supi:plan planning mode. No timeout — the user can take as long as needed.",
+    promptSnippet:
+      "planning_ask — ask user questions during planning (no timeout, unlimited thinking time)",
+    parameters: {
+      type: "object",
+      properties: {
+        question: {
+          type: "string",
+          description: "Question text to present to the user",
+        },
+        options: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              label: { type: "string", description: "Option label" },
+            },
+            required: ["label"],
+          },
+          description: "Available options for the user to choose from",
+        },
+        recommended: {
+          type: "number",
+          description: "Index of recommended option (0-indexed)",
+        },
+      },
+      required: ["question", "options"],
+    },
+    async execute(
+      _toolCallId: string,
+      params: { question: string; options: { label: string }[]; recommended?: number },
+      _signal: AbortSignal,
+      _onUpdate: unknown,
+      ctx: any,
+    ) {
+      const labels = params.options.map((o) => o.label);
+      if (labels.length === 0) {
+        return {
+          content: [{ type: "text", text: "Error: options must not be empty" }],
+          details: {},
+        };
+      }
+
+      const choice = await ctx.ui.select(params.question, labels, {
+        initialIndex: params.recommended,
+        // No timeout — planning decisions need unlimited time
+      });
+
+      const selected = choice ?? labels[params.recommended ?? 0] ?? labels[0];
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ question: params.question, selected }),
+          },
+        ],
+        details: { question: params.question, selected },
+      };
+    },
+  });
+}

package/src/planning/prompt-builder.ts

@@ -1,181 +1,21 @@
-import { buildSpecReviewerPrompt } from "./spec-reviewer.js";
-import { buildPlanWriterPrompt } from "./plan-writer-prompt.js";
-
 export interface PlanningPromptOptions {
   topic?: string;
-  skillContent?: string;
-  dotDirDisplay: string;
 }
 
 /**
- * Build the comprehensive planning prompt that encodes the full brainstorming flow.
- * This is the steering prompt sent to the agent when `/supi:plan` runs.
- *
- * Follows supipowers' brainstorming skill flow:
- * 1. Explore project context
- * 2. Ask clarifying questions (one at a time)
- * 3. Propose 2-3 approaches with trade-offs
- * 4. Present design section by section
- * 5. Write design doc to .omp/supipowers/specs/
- * 6. Spec review loop (dispatch reviewer sub-agent)
- * 7. User review gate
- * 8. Handoff to implementation plan
+ * Build the kickoff steer prompt for collaborative planning.
+ * The planning workflow itself lives in the planning-mode system prompt.
  */
 export function buildPlanningPrompt(options: PlanningPromptOptions): string {
-  const { topic, skillContent, dotDirDisplay } = options;
-
-  const sections: string[] = [
-    "You are starting a collaborative planning session with the user.",
-    "Follow this process step by step. Do NOT skip phases or combine them.",
-    "",
-
-    // ── Phase 1: Context ─────────────────────────────────────────
-    "## Phase 1: Explore project context",
-    "",
-    "Before asking questions, understand the current project context:",
-    "- Check files, docs, recent commits",
-    "- Understand existing architecture and patterns",
-    "- Assess scope: if the request describes multiple independent subsystems, flag it immediately and help decompose into sub-projects before proceeding",
-    "",
-
-    // ── Topic ────────────────────────────────────────────────────
-    topic
-      ? `The user wants to plan: ${topic}`
-      : "Ask the user what they want to build or accomplish.",
-    "",
-
-    // ── Phase 2: Clarify ─────────────────────────────────────────
-    "## Phase 2: Ask Clarifying Questions",
-    "",
-    "- Ask one question at a time — never overwhelm with multiple questions",
-    "- Prefer **multiple choice** questions when possible, but open-ended is fine too",
-    "- Focus on: purpose, constraints, success criteria",
-    "- If a topic needs more exploration, break it into multiple questions",
-    "- Continue until you have enough clarity to propose approaches",
-    "",
-
-    // ── Phase 3: Approaches ──────────────────────────────────────
-    "## Phase 3: Propose 2-3 Approaches",
-    "",
-    "- Present 2-3 different approaches with trade-offs",
-    "- Lead with your recommended option and explain why",
-    "- Present options conversationally with your recommendation and reasoning",
-    "- Wait for the user to choose before proceeding",
-    "",
-
-    // ── Phase 4: Design ──────────────────────────────────────────
-    "## Phase 4: Present Design",
-    "",
-    "Once aligned on approach, present the design:",
-    "- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced",
-    "- Cover: architecture, components, data flow, error handling, testing",
-    "- Ask after each section whether it looks right so far",
-    "- Design for isolation and clarity: smaller units with clear boundaries",
-    "- Apply YAGNI ruthlessly — remove unnecessary features",
-    "- Be ready to go back and clarify if something doesn't make sense",
-    "",
-
-    // ── Phase 5: Write Spec ──────────────────────────────────────
-    "## Phase 5: Write Design Doc",
-    "",
-    "Once the user approves the design:",
-    "- Write the validated design doc to `.omp/supipowers/specs/YYYY-MM-DD-<topic>-design.md`",
-    "- Use clear, concise writing",
-    "- Commit the design document to git",
-    "",
-
-    // ── Phase 6: Spec Review Loop ────────────────────────────────
-    "## Phase 6: Spec Review Loop",
-    "",
-    "After writing the design doc, dispatch a spec-document-reviewer sub-agent to verify it:",
-    "",
-    "1. Dispatch the reviewer with this prompt:",
-    "",
-    "```",
-    buildSpecReviewerPrompt("<path-to-spec-file>"),
-    "```",
-    "",
-    "(Replace `<path-to-spec-file>` with the actual spec path.)",
-    "",
-    "2. If **Issues Found**: fix the issues, re-dispatch the reviewer",
-    "3. Repeat until **Approved** (max 5 iterations, then surface to human for guidance)",
-    "",
-
-    // ── Phase 7: User Gate ───────────────────────────────────────
-    "## Phase 7: User Review Gate",
-    "",
-    "After the spec review loop passes, ask the user to review the spec before proceeding:",
-    "",
-    '> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."',
-    "",
-    "Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.",
-    "",
-
-    // ── Phase 8: Handoff ─────────────────────────────────────────
-    "## Phase 8: Transition to Implementation Plan",
-    "",
-    "Once the user approves the spec, write a comprehensive implementation plan.",
-    "Follow these plan writing instructions:",
-    "",
-    buildPlanWriterPrompt({ specPath: "<path-to-approved-spec>", dotDirDisplay }),
-    "",
-    "(Replace `<path-to-approved-spec>` with the actual spec file path from Phase 5.)",
-    "",
-
-    // ── Principles ───────────────────────────────────────────────
-    "## Key Principles",
-    "",
-    "- **One question at a time** — Don't overwhelm with multiple questions",
-    "- **Multiple choice preferred** — Easier to answer than open-ended when possible",
-    "- **YAGNI ruthlessly** — Remove unnecessary features from all designs",
-    "- **Explore alternatives** — Always propose 2-3 approaches before settling",
-    "- **Incremental validation** — Present design, get approval before moving on",
-    "- **Decompose large scope** — If the request covers multiple independent subsystems, decompose into sub-projects first",
-    "- **Design for isolation** — Smaller units with clear boundaries and well-defined interfaces",
-    "",
-  ];
-
-  if (skillContent) {
-    sections.push("## Additional Planning Guidelines", "", skillContent, "");
-  }
-
-  return sections.join("\n");
+  return options.topic
+    ? "Begin planning. Follow the planning phases in order."
+    : "Ask the user what they want to build or accomplish."
 }
 
 /**
- * Build the quick plan prompt that skips brainstorming.
- * Used when `/supi:plan --quick <description>` is invoked.
+ * Build the quick-plan kickoff steer prompt.
+ * The detailed quick-planning rules live in the planning-mode system prompt.
  */
-export function buildQuickPlanPrompt(
-  description: string,
-  skillContent?: string,
-): string {
-  const sections: string[] = [
-    "Generate a concise implementation plan for the following task.",
-    "Skip brainstorming — go straight to task breakdown.",
-    "",
-    `Task: ${description}`,
-    "",
-    "Format the plan as markdown with YAML frontmatter:",
-    "",
-    "```yaml",
-    "---",
-    "name: <feature-name>",
-    "created: YYYY-MM-DD",
-    "tags: [tag1, tag2]",
-    "---",
-    "```",
-    "",
-    "Each task should have: name, **files**, **criteria**, and **complexity** (small/medium/large).",
-    "",
-    "After generating the plan, save it and tell the user:",
-    '> "Plan saved to `<path>`. Review it and approve when ready."',
-    "Then stop and wait. The user will see an approval prompt.",
-  ];
-
-  if (skillContent) {
-    sections.push("", "Follow these planning guidelines:", skillContent);
-  }
-
-  return sections.join("\n");
+export function buildQuickPlanPrompt(description: string): string {
+  return `Generate a concise implementation plan for: ${description}. Skip brainstorming — go straight to task breakdown.`;
 }