supipowers 0.2.7 → 0.4.0

package/src/orchestrator/agent-prompts.ts

@@ -0,0 +1,282 @@
+import type { PlanTask } from "../types.js";
+import { buildTddInstructions } from "../discipline/tdd.js";
+import { buildDebuggingInstructions } from "../discipline/debugging.js";
+import { buildVerificationInstructions } from "../discipline/verification.js";
+
+// ── Implementer Prompt ─────────────────────────────────────────────
+
+export interface ImplementerPromptOptions {
+  task: PlanTask;
+  planContext: string;
+  workDir: string;
+}
+
+/**
+ * Build the prompt for an implementer sub-agent.
+ * Follows superpowers' implementer-prompt.md pattern:
+ * - Full task description
+ * - Ask-before-starting section
+ * - TDD and code organization guidance
+ * - Escalation guidance
+ * - Self-review before reporting
+ * - Structured report format
+ */
+export function buildImplementerPrompt(options: ImplementerPromptOptions): string {
+  const { task, planContext, workDir } = options;
+
+  return [
+    `You are implementing Task ${task.id}: ${task.name}`,
+    "",
+    "## Task Description",
+    "",
+    task.description,
+    "",
+    "## Target Files",
+    "",
+    ...task.files.map((f) => `- ${f}`),
+    "",
+    "## Acceptance Criteria",
+    "",
+    task.criteria,
+    "",
+    "## Context",
+    "",
+    planContext,
+    "",
+    `Work from: ${workDir}`,
+    "",
+    "## Before You Begin",
+    "",
+    "If you have questions about:",
+    "- The requirements or acceptance criteria",
+    "- The approach or implementation strategy",
+    "- Dependencies or assumptions",
+    "- Anything unclear in the task description",
+    "",
+    "**Ask them now.** Raise any concerns before starting work.",
+    "",
+    "## Your Job",
+    "",
+    "Once you're clear on requirements:",
+    "1. Implement exactly what the task specifies",
+    "2. Write tests following TDD (write the failing test first, then implement)",
+    "3. Verify implementation works",
+    "4. Commit your work",
+    "5. Self-review (see below)",
+    "6. Report back",
+    "",
+    "**While you work:** If you encounter something unexpected or unclear, ask questions.",
+    "It's always OK to pause and clarify. Don't guess or make assumptions.",
+    "",
+    "## Code Organization",
+    "",
+    "- Follow the file structure defined in the plan",
+    "- Each file should have one clear responsibility with a well-defined interface",
+    "- If a file you're creating is growing beyond the plan's intent, stop and report as DONE_WITH_CONCERNS",
+    "- In existing codebases, follow established patterns",
+    "",
+    "## When You're in Over Your Head",
+    "",
+    "It is always OK to stop and escalate. Bad work is worse than no work.",
+    "",
+    "**STOP and escalate when:**",
+    "- The task requires architectural decisions with multiple valid approaches",
+    "- You need to understand code beyond what was provided",
+    "- You feel uncertain about whether your approach is correct",
+    "- The task involves restructuring existing code the plan didn't anticipate",
+    "",
+    "**How to escalate:** Report with status BLOCKED or NEEDS_CONTEXT.",
+    "Describe what you're stuck on, what you've tried, and what help you need.",
+    "",
+    "## Before Reporting Back: Self-Review",
+    "",
+    "Review your work with fresh eyes:",
+    "",
+    "**Completeness:**",
+    "- Did I fully implement everything in the spec?",
+    "- Did I miss any requirements?",
+    "- Are there edge cases I didn't handle?",
+    "",
+    "**Quality:**",
+    "- Is this my best work?",
+    "- Are names clear and accurate?",
+    "- Is the code clean and maintainable?",
+    "",
+    "**Discipline:**",
+    "- Did I avoid overbuilding (YAGNI)?",
+    "- Did I only build what was requested?",
+    "- Did I follow existing patterns?",
+    "",
+    "**Testing:**",
+    "- Do tests verify behavior (not mock behavior)?",
+    "- Did I follow TDD?",
+    "- Are tests comprehensive?",
+    "",
+    "If you find issues during self-review, fix them before reporting.",
+    "",
+    "## Report Format",
+    "",
+    "When done, report:",
+    "- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT",
+    "- What you implemented (or attempted, if blocked)",
+    "- What you tested and test results",
+    "- Files changed",
+    "- Self-review findings (if any)",
+    "- Any issues or concerns",
+    "",
+    "Use DONE_WITH_CONCERNS if you completed but have doubts.",
+    "Use BLOCKED if you cannot complete the task.",
+    "Use NEEDS_CONTEXT if you need information not provided.",
+    "Never silently produce work you're unsure about.",
+    "",
+    "---",
+    "",
+    buildTddInstructions(),
+    "",
+    "---",
+    "",
+    buildDebuggingInstructions(),
+    "",
+    "---",
+    "",
+    buildVerificationInstructions(),
+  ].join("\n");
+}
+
+// ── Spec Compliance Review Prompt ──────────────────────────────────
+
+export interface SpecComplianceReviewOptions {
+  taskRequirements: string;
+  implementerReport: string;
+}
+
+/**
+ * Build the prompt for a spec compliance reviewer sub-agent.
+ * Follows superpowers' spec-reviewer-prompt.md pattern:
+ * - Do not trust the implementer's report
+ * - Verify by reading actual code
+ * - Check for missing, extra, and misunderstood requirements
+ */
+export function buildSpecComplianceReviewPrompt(options: SpecComplianceReviewOptions): string {
+  const { taskRequirements, implementerReport } = options;
+
+  return [
+    "You are reviewing whether an implementation matches its specification.",
+    "",
+    "## What Was Requested",
+    "",
+    taskRequirements,
+    "",
+    "## What Implementer Claims They Built",
+    "",
+    implementerReport,
+    "",
+    "## CRITICAL: Do Not Trust the Report",
+    "",
+    "The implementer's report may be incomplete, inaccurate, or optimistic.",
+    "You MUST verify everything independently.",
+    "",
+    "**DO NOT:**",
+    "- Take their word for what they implemented",
+    "- Trust their claims about completeness",
+    "- Accept their interpretation of requirements",
+    "",
+    "**DO:**",
+    "- Read the actual code they wrote",
+    "- Compare actual implementation to requirements line by line",
+    "- Check for missing pieces they claimed to implement",
+    "- Look for extra features they didn't mention",
+    "",
+    "## Your Job",
+    "",
+    "Read the implementation code and verify:",
+    "",
+    "**Missing requirements:**",
+    "- Did they implement everything that was requested?",
+    "- Are there requirements they skipped or missed?",
+    "- Did they claim something works but didn't actually implement it?",
+    "",
+    "**Extra/unneeded work:**",
+    "- Did they build things that weren't requested? Did they over-engineer?",
+    "- Did they add unnecessary features not in spec?",
+    "",
+    "**Misunderstandings:**",
+    "- Did they interpret requirements differently than intended?",
+    "- Did they solve the wrong problem?",
+    "",
+    "**Verify by reading code, not by trusting report.**",
+    "",
+    "## Output",
+    "",
+    "Report:",
+    "- **Spec compliant** — if everything matches after code inspection",
+    "- **Issues found:** [list specifically what's missing or extra, with file:line references]",
+  ].join("\n");
+}
+
+// ── Code Quality Review Prompt ─────────────────────────────────────
+
+export interface CodeQualityReviewOptions {
+  taskSummary: string;
+  implementerReport: string;
+  baseSha: string;
+  headSha: string;
+}
+
+/**
+ * Build the prompt for a code quality reviewer sub-agent.
+ * Follows superpowers' code-quality-reviewer-prompt.md pattern:
+ * - Review git diff between base and head
+ * - Check file responsibilities and unit decomposition
+ * - Categorize issues as Critical/Important/Minor
+ */
+export function buildCodeQualityReviewPrompt(options: CodeQualityReviewOptions): string {
+  const { taskSummary, implementerReport, baseSha, headSha } = options;
+
+  return [
+    "You are reviewing code quality for a completed implementation task.",
+    "",
+    "## What Was Implemented",
+    "",
+    taskSummary,
+    "",
+    "## Implementer Report",
+    "",
+    implementerReport,
+    "",
+    "## Git Diff",
+    "",
+    `Compare changes between base (\`${baseSha}\`) and head (\`${headSha}\`):`,
+    "",
+    `Run: \`git diff ${baseSha}..${headSha}\``,
+    "",
+    "## What to Check",
+    "",
+    "**Architecture & Design:**",
+    "- Does each file have one clear responsibility with a well-defined interface?",
+    "- Are units decomposed so they can be understood and tested independently?",
+    "- Did this implementation create new files that are already large?",
+    "",
+    "**Code Quality:**",
+    "- Correctness: Does the code do what it's supposed to?",
+    "- Security: Any injection, XSS, or other vulnerabilities?",
+    "- Performance: Any obvious performance issues?",
+    "- Maintainability: Is the code readable and well-organized?",
+    "- Error handling: Are failures handled appropriately?",
+    "",
+    "**Testing:**",
+    "- Do tests verify real behavior (not mock behavior)?",
+    "- Are edge cases covered?",
+    "- Is test coverage adequate?",
+    "",
+    "## Output",
+    "",
+    "Categorize issues by severity:",
+    "",
+    "- **Critical:** Must fix before proceeding (bugs, security issues, data loss risks)",
+    "- **Important:** Should fix before merging (code quality, maintainability)",
+    "- **Minor:** Nice to fix (style, naming, minor improvements)",
+    "",
+    "Report: Strengths, Issues (Critical/Important/Minor), Assessment",
+  ].join("\n");
+}

package/src/orchestrator/dispatcher.ts

@@ -1,8 +1,12 @@
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 import type { PlanTask, AgentResult, AgentStatus, SupipowersConfig } from "../types.js";
 import { buildTaskPrompt, buildFixPrompt } from "./prompts.js";
+import {
+  buildSpecComplianceReviewPrompt,
+  buildCodeQualityReviewPrompt,
+} from "./agent-prompts.js";
 import { isLspAvailable } from "../lsp/detector.js";
-import { notifySuccess, notifyWarning, notifyError } from "../notifications/renderer.js";
+import { notifySuccess, notifyWarning, notifyError, notifyInfo } from "../notifications/renderer.js";
 
 export interface DispatchOptions {
   pi: ExtensionAPI;
@@ -76,6 +80,151 @@ async function executeSubAgent(
   );
 }
 
+/** Review result from a spec compliance or code quality reviewer */
+export interface ReviewResult {
+  passed: boolean;
+  issues: string;
+}
+
+/**
+ * Dispatch an implementer with 2-stage review (spec compliance + code quality).
+ * Follows superpowers' subagent-driven-development pattern:
+ * 1. Implementer implements + self-reviews
+ * 2. Spec compliance reviewer verifies implementation matches spec
+ * 3. If spec issues → re-dispatch implementer with feedback
+ * 4. Code quality reviewer checks implementation quality
+ * 5. If quality issues → re-dispatch implementer with feedback
+ */
+export async function dispatchAgentWithReview(
+  options: DispatchOptions & { workDir?: string },
+): Promise<AgentResult> {
+  const { pi, ctx, task, planContext, config, lspAvailable, workDir } = options;
+  const maxReviewRetries = config.orchestration.maxFixRetries;
+
+  // Step 1: Dispatch implementer
+  let implementResult = await dispatchAgent(options);
+
+  // If blocked or needs context, skip reviews
+  if (implementResult.status === "blocked") {
+    return implementResult;
+  }
+
+  // Step 2: Spec compliance review
+  for (let attempt = 0; attempt <= maxReviewRetries; attempt++) {
+    const specReview = await dispatchSpecReview(pi, task, implementResult, config);
+
+    if (specReview.passed) {
+      notifyInfo(ctx, `Task ${task.id} spec review passed`);
+      break;
+    }
+
+    if (attempt === maxReviewRetries) {
+      notifyWarning(ctx, `Task ${task.id} spec review failed after ${maxReviewRetries + 1} attempts`, specReview.issues);
+      implementResult.status = "done_with_concerns";
+      implementResult.concerns = `Spec compliance issues: ${specReview.issues}`;
+      return implementResult;
+    }
+
+    // Re-dispatch implementer with spec review feedback
+    notifyInfo(ctx, `Task ${task.id} spec issues found, re-dispatching`, specReview.issues);
+    const fixResult = await dispatchFixAgent({
+      ...options,
+      previousOutput: implementResult.output,
+      failureReason: `Spec compliance review failed:\n${specReview.issues}`,
+    });
+    implementResult = fixResult;
+
+    if (fixResult.status === "blocked") {
+      return fixResult;
+    }
+  }
+
+  // Step 3: Code quality review
+  for (let attempt = 0; attempt <= maxReviewRetries; attempt++) {
+    const qualityReview = await dispatchQualityReview(pi, task, implementResult, config);
+
+    if (qualityReview.passed) {
+      notifyInfo(ctx, `Task ${task.id} quality review passed`);
+      break;
+    }
+
+    if (attempt === maxReviewRetries) {
+      notifyWarning(ctx, `Task ${task.id} quality review failed after ${maxReviewRetries + 1} attempts`, qualityReview.issues);
+      implementResult.status = "done_with_concerns";
+      implementResult.concerns = `Code quality issues: ${qualityReview.issues}`;
+      return implementResult;
+    }
+
+    // Re-dispatch implementer with quality review feedback
+    notifyInfo(ctx, `Task ${task.id} quality issues found, re-dispatching`, qualityReview.issues);
+    const fixResult = await dispatchFixAgent({
+      ...options,
+      previousOutput: implementResult.output,
+      failureReason: `Code quality review failed:\n${qualityReview.issues}`,
+    });
+    implementResult = fixResult;
+
+    if (fixResult.status === "blocked") {
+      return fixResult;
+    }
+  }
+
+  return implementResult;
+}
+
+/** Dispatch a spec compliance reviewer sub-agent */
+async function dispatchSpecReview(
+  pi: ExtensionAPI,
+  task: PlanTask,
+  implementResult: AgentResult,
+  config: SupipowersConfig,
+): Promise<ReviewResult> {
+  const prompt = buildSpecComplianceReviewPrompt({
+    taskRequirements: `Task: ${task.name}\n\n${task.description}\n\nAcceptance Criteria: ${task.criteria}`,
+    implementerReport: implementResult.output,
+  });
+
+  try {
+    const result = await executeSubAgent(pi, prompt, task, config);
+    const passed = result.status === "done" ||
+      result.output.toLowerCase().includes("spec compliant");
+    return {
+      passed,
+      issues: passed ? "" : result.output,
+    };
+  } catch {
+    // If reviewer fails, pass through — don't block on reviewer errors
+    return { passed: true, issues: "" };
+  }
+}
+
+/** Dispatch a code quality reviewer sub-agent */
+async function dispatchQualityReview(
+  pi: ExtensionAPI,
+  task: PlanTask,
+  implementResult: AgentResult,
+  config: SupipowersConfig,
+): Promise<ReviewResult> {
+  const prompt = buildCodeQualityReviewPrompt({
+    taskSummary: `Task ${task.id}: ${task.name}\n\n${task.description}`,
+    implementerReport: implementResult.output,
+    baseSha: "HEAD~1",
+    headSha: "HEAD",
+  });
+
+  try {
+    const result = await executeSubAgent(pi, prompt, task, config);
+    const hasCritical = result.output.toLowerCase().includes("critical");
+    return {
+      passed: !hasCritical,
+      issues: hasCritical ? result.output : "",
+    };
+  } catch {
+    // If reviewer fails, pass through
+    return { passed: true, issues: "" };
+  }
+}
+
 export async function dispatchFixAgent(
   options: DispatchOptions & { previousOutput: string; failureReason: string }
 ): Promise<AgentResult> {

package/src/orchestrator/prompts.ts

@@ -1,44 +1,26 @@
 // src/orchestrator/prompts.ts
 import type { PlanTask, SupipowersConfig } from "../types.js";
 import { buildLspValidationPrompt } from "../lsp/bridge.js";
+import { buildImplementerPrompt } from "./agent-prompts.js";
+import { buildReceivingReviewInstructions } from "../discipline/receiving-review.js";
 
 /** Build the system prompt for a sub-agent executing a task */
 export function buildTaskPrompt(
   task: PlanTask,
   planContext: string,
   config: SupipowersConfig,
-  lspAvailable: boolean
+  lspAvailable: boolean,
+  workDir?: string,
 ): string {
-  const sections: string[] = [
-    "# Task Assignment",
-    "",
-    `## Task: ${task.name}`,
-    "",
-    task.description,
-    "",
-    "## Target Files",
-    ...task.files.map((f) => `- ${f}`),
-    "",
-    "## Acceptance Criteria",
-    task.criteria,
-    "",
-    "## Context",
+  const prompt = buildImplementerPrompt({
+    task,
     planContext,
-    "",
-    "## Instructions",
-    "1. Read the target files to understand current state",
-    "2. Implement the changes described above",
-    "3. Ensure acceptance criteria are met",
-    "4. Report your status when done",
-    "",
-    "Report one of these statuses:",
-    "- DONE: Task completed successfully, all criteria met",
-    "- DONE_WITH_CONCERNS: Completed but with caveats (explain what)",
-    "- BLOCKED: Cannot complete (explain why and what's needed)",
-  ];
+    workDir: workDir ?? process.cwd(),
+  });
 
   if (lspAvailable) {
-    sections.push(
+    return [
+      prompt,
       "",
       "## LSP Available",
       "You have access to the LSP tool. Use it to:",
@@ -46,11 +28,11 @@ export function buildTaskPrompt(
       "- Find references before renaming symbols",
       "- Validate your work has no type errors",
       "",
-      buildLspValidationPrompt(task.files)
-    );
+      buildLspValidationPrompt(task.files),
+    ].join("\n");
   }
 
-  return sections.join("\n");
+  return prompt;
 }
 
 /** Build prompt for a fix agent */
@@ -82,6 +64,10 @@ export function buildFixPrompt(
     "2. Identify and fix the issue",
     "3. Verify the acceptance criteria are now met",
     "4. Report your status",
+    "",
+    "---",
+    "",
+    buildReceivingReviewInstructions(),
   ];
 
   if (lspAvailable) {

package/src/planning/plan-reviewer.ts

@@ -0,0 +1,49 @@
+/**
+ * Build the prompt for dispatching a plan document reviewer sub-agent.
+ * Follows the same pattern as superpowers' plan-document-reviewer-prompt.md.
+ */
+export function buildPlanReviewerPrompt(
+  planFilePath: string,
+  specFilePath: string,
+  chunkNumber: number,
+): string {
+  return [
+    "You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation.",
+    "",
+    `**Plan chunk to review:** ${planFilePath} — Chunk ${chunkNumber} only`,
+    `**Spec for reference:** ${specFilePath}`,
+    "",
+    "## What to Check",
+    "",
+    "| Category | What to Look For |",
+    "|----------|------------------|",
+    "| Completeness | TODO markers, placeholders, incomplete tasks, missing steps |",
+    "| Spec Alignment | Chunk covers relevant spec requirements, no scope creep |",
+    "| Task Decomposition | Tasks atomic, clear boundaries, steps actionable |",
+    "| File Structure | Files have clear single responsibilities, split by responsibility not layer |",
+    "| File Size | Would any new or modified file likely grow large enough to be hard to reason about? |",
+    "| Checkbox Syntax | Steps use checkbox (`- [ ]`) syntax for tracking |",
+    "| Chunk Size | Each chunk under 1000 lines |",
+    "",
+    "## Critical",
+    "",
+    "Look especially hard for:",
+    "- Any TODO markers or placeholder text",
+    '- Steps that say "similar to X" without actual content',
+    "- Incomplete task definitions",
+    "- Missing verification steps or expected outputs",
+    "- Files planned to hold multiple responsibilities or likely to grow unwieldy",
+    "",
+    "## Output Format",
+    "",
+    `## Plan Review — Chunk ${chunkNumber}`,
+    "",
+    "**Status:** Approved | Issues Found",
+    "",
+    "**Issues (if any):**",
+    "- [Task X, Step Y]: [specific issue] — [why it matters]",
+    "",
+    "**Recommendations (advisory):**",
+    "- [suggestions that don't block approval]",
+  ].join("\n");
+}