supipowers 0.2.7 → 0.4.0

package/src/commands/release.ts

@@ -12,7 +12,7 @@ export function registerReleaseCommand(pi: ExtensionAPI): void {
       let lastTag: string | null = null;
       try {
         const result = await pi.exec("git", ["describe", "--tags", "--abbrev=0"], { cwd: ctx.cwd });
-        if (result.exitCode === 0) lastTag = result.stdout.trim();
+        if (result.code === 0) lastTag = result.stdout.trim();
       } catch {
         // no tags yet
       }

package/src/commands/review.ts

@@ -49,7 +49,7 @@ export function registerReviewCommand(pi: ExtensionAPI): void {
       let changedFiles: string[] = [];
       try {
         const result = await pi.exec("git", ["diff", "--name-only", "HEAD"], { cwd: ctx.cwd });
-        if (result.exitCode === 0) {
+        if (result.code === 0) {
           changedFiles = result.stdout
             .split("\n")
             .map((f) => f.trim())
@@ -62,7 +62,7 @@ export function registerReviewCommand(pi: ExtensionAPI): void {
       if (changedFiles.length === 0) {
         try {
           const result = await pi.exec("git", ["diff", "--name-only", "--cached"], { cwd: ctx.cwd });
-          if (result.exitCode === 0) {
+          if (result.code === 0) {
             changedFiles = result.stdout
               .split("\n")
               .map((f) => f.trim())

package/src/commands/run.ts

@@ -11,7 +11,7 @@ import {
   loadAllAgentResults,
 } from "../storage/runs.js";
 import { scheduleBatches } from "../orchestrator/batch-scheduler.js";
-import { dispatchAgent, dispatchFixAgent } from "../orchestrator/dispatcher.js";
+import { dispatchAgent, dispatchAgentWithReview, dispatchFixAgent } from "../orchestrator/dispatcher.js";
 import { summarizeBatch, buildRunSummary } from "../orchestrator/result-collector.js";
 import { analyzeConflicts } from "../orchestrator/conflict-resolver.js";
 import { isLspAvailable } from "../lsp/detector.js";
@@ -22,6 +22,8 @@ import {
   notifyError,
   notifySummary,
 } from "../notifications/renderer.js";
+import { buildWorktreePrompt } from "../git/worktree.js";
+import { buildBranchFinishPrompt } from "../git/branch-finish.js";
 import type { RunManifest, AgentResult } from "../types.js";
 
 export function registerRunCommand(pi: ExtensionAPI): void {
@@ -32,6 +34,7 @@ export function registerRunCommand(pi: ExtensionAPI): void {
       const profile = resolveProfile(ctx.cwd, config, args?.replace("--profile ", "") || undefined);
 
       let manifest = findActiveRun(ctx.cwd);
+      let branchName: string | null = null;
 
       if (!manifest) {
         const plans = listPlans(ctx.cwd);
@@ -60,6 +63,36 @@ export function registerRunCommand(pi: ExtensionAPI): void {
         };
         createRun(ctx.cwd, manifest);
         notifyInfo(ctx, `Run started: ${manifest.id}`, `${plan.tasks.length} tasks in ${batches.length} batches`);
+
+        // Offer worktree setup for isolated execution
+        if (ctx.hasUI) {
+          const useWorktree = await ctx.ui.select(
+            "Execution isolation",
+            [
+              "Run in current workspace",
+              "Create isolated worktree (recommended)",
+            ],
+            { helpText: "Worktrees prevent work-in-progress from polluting your workspace" },
+          );
+          if (!useWorktree) return;
+
+          if (useWorktree.startsWith("Create isolated")) {
+            branchName = `supi/${plan.name || manifest.id}`;
+            const worktreeInstructions = buildWorktreePrompt({
+              branchName,
+              cwd: ctx.cwd,
+            });
+            pi.sendMessage(
+              {
+                customType: "supi-worktree-setup",
+                content: [{ type: "text", text: worktreeInstructions }],
+                display: "none",
+              },
+              { deliverAs: "steer" },
+            );
+            notifyInfo(ctx, "Setting up worktree", `Branch: ${branchName}`);
+          }
+        }
       } else {
         notifyInfo(ctx, `Resuming run: ${manifest.id}`);
       }
@@ -89,7 +122,7 @@ export function registerRunCommand(pi: ExtensionAPI): void {
           const task = plan.tasks.find((t) => t.id === taskId);
           if (!task) return Promise.resolve(null);
 
-          return dispatchAgent({
+          return dispatchAgentWithReview({
             pi,
             ctx,
             task,
@@ -170,6 +203,23 @@ export function registerRunCommand(pi: ExtensionAPI): void {
         `(${runSummary.done} clean, ${runSummary.doneWithConcerns} with concerns, ` +
         `${runSummary.blocked} blocked) | ${runSummary.totalFilesChanged} files | ${durationSec}s`
       );
+
+      // Offer branch finish options if we created a worktree branch
+      if (branchName && manifest.status === "completed") {
+        const finishInstructions = buildBranchFinishPrompt({
+          branchName,
+          baseBranch: "main",
+        });
+        pi.sendMessage(
+          {
+            customType: "supi-branch-finish",
+            content: [{ type: "text", text: finishInstructions }],
+            display: "none",
+          },
+          { deliverAs: "steer" },
+        );
+        notifyInfo(ctx, "Run succeeded", "Follow branch finish instructions to integrate your work");
+      }
     },
   });
 }

package/src/commands/supi.ts

@@ -16,6 +16,7 @@ export function handleSupi(pi: ExtensionAPI, ctx: ExtensionContext): void {
       "/supi:run      — Execute a plan with sub-agents",
       "/supi:review   — Run quality gates",
       "/supi:qa       — Run QA pipeline",
+      "/supi:fix-pr   — Fix PR review comments",
       "/supi:release  — Release automation",
       "/supi:config   — Manage configuration",
       "/supi:status   — Check running tasks",

package/src/commands/update.ts

@@ -24,7 +24,7 @@ export function handleUpdate(pi: ExtensionAPI, ctx: ExtensionContext): void {
 
     // Check latest version on npm
     const checkResult = await pi.exec("npm", ["view", "supipowers", "version"], { cwd: tmpdir() });
-    if (checkResult.exitCode !== 0) {
+    if (checkResult.code !== 0) {
       ctx.ui.notify("Failed to check for updates — npm view failed", "error");
       return;
     }
@@ -46,7 +46,7 @@ export function handleUpdate(pi: ExtensionAPI, ctx: ExtensionContext): void {
         "npm", ["install", "--prefix", tempDir, `supipowers@${latestVersion}`],
         { cwd: tempDir },
       );
-      if (installResult.exitCode !== 0) {
+      if (installResult.code !== 0) {
         ctx.ui.notify("Failed to download latest version", "error");
         return;
       }

package/src/discipline/debugging.ts

@@ -0,0 +1,57 @@
+/**
+ * Systematic debugging instructions for sub-agent prompts.
+ * Matches superpowers' systematic-debugging skill depth.
+ */
+export function buildDebuggingInstructions(): string {
+  return [
+    "## Systematic Debugging",
+    "",
+    "### Iron Law",
+    "",
+    "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.",
+    "Symptom fixes are failure. Find root cause before attempting any fix.",
+    "",
+    "### Phase 1: Root Cause Investigation",
+    "",
+    "Complete this phase before proposing fixes:",
+    "",
+    "1. **Read the error message carefully.** Don't skip it; it often contains the solution.",
+    "2. **Reproduce consistently.** Exact steps, every time.",
+    "3. **Check recent changes.** Run `git diff` to see what changed. Check new dependencies, config changes.",
+    "4. **Gather evidence** in multi-component systems: add diagnostic instrumentation at each boundary.",
+    "5. **Trace the data flow** backward through the call stack to find the original trigger.",
+    "",
+    "### Phase 2: Pattern Analysis",
+    "",
+    "1. Find a working example in the codebase that does something similar.",
+    "2. Compare against the reference completely (don't skim).",
+    "3. Identify differences between working and broken.",
+    "4. Understand dependencies and assumptions.",
+    "",
+    "### Phase 3: Hypothesis and Testing",
+    "",
+    "1. Form a single, specific hypothesis (not vague).",
+    "2. Test minimally: smallest possible change, one variable at a time.",
+    "3. Verify before continuing. If wrong → form a NEW hypothesis, not more fixes.",
+    "4. Admit uncertainty. Don't pretend to know.",
+    "",
+    "### Phase 4: Implementation",
+    "",
+    "1. Create a failing test case first (automated or manual).",
+    "2. Implement a single fix that addresses the root cause only.",
+    "3. Verify the fix: test passes, no other tests broken.",
+    "4. **If the fix doesn't work:**",
+    "   - Fewer than 3 attempts → return to Phase 1 with new information",
+    "   - 3 or more attempts → STOP and question the architecture. Discuss with human partner.",
+    "",
+    "### Red Flags — STOP and Follow the Process",
+    "",
+    "- \"Quick fix for now, investigate later\"",
+    "- \"Just try changing X and see if it works\"",
+    "- \"Skip the test, I'll manually verify\"",
+    "- \"It's probably X, let me fix that\"",
+    "- \"I don't fully understand but this might work\"",
+    "- \"One more fix attempt\" (when already tried 2+)",
+    "- Each fix reveals a new problem in a different place",
+  ].join("\n");
+}

package/src/discipline/receiving-review.ts

@@ -0,0 +1,65 @@
+/**
+ * Receiving code review instructions for sub-agent prompts.
+ * Matches superpowers' receiving-code-review skill:
+ * technical rigor and verification, not performative agreement.
+ */
+export function buildReceivingReviewInstructions(): string {
+  return [
+    "## Receiving Code Review Feedback",
+    "",
+    "Code review requires technical evaluation, not emotional performance.",
+    "Verify before implementing. Ask before assuming. Technical correctness over social comfort.",
+    "",
+    "### The Response Pattern",
+    "",
+    "1. **READ:** Complete feedback without reacting.",
+    "2. **UNDERSTAND:** Restate the requirement in your own words, or ask for clarification.",
+    "3. **VERIFY:** Check against codebase reality.",
+    "4. **EVALUATE:** Is this technically sound for THIS codebase?",
+    "5. **RESPOND:** Technical acknowledgment or reasoned pushback.",
+    "6. **IMPLEMENT:** One at a time, test each change.",
+    "",
+    "### Forbidden Responses",
+    "",
+    "Never use performative agreement:",
+    "- \"You're absolutely right!\"",
+    "- \"Great point!\"",
+    "- \"Excellent catch!\"",
+    "",
+    "Instead: restate requirements, ask clarifying questions, take action.",
+    "",
+    "### Handling Unclear Feedback",
+    "",
+    "If any item is unclear, stop and ask for clarification before implementing anything.",
+    "Items may be related — clarify all unclear items before starting work.",
+    "",
+    "### Source-Specific Handling",
+    "",
+    "**From your human partner:** Trusted. Implement after understanding.",
+    "**From external reviewers:** Verify technically. Check for breaking changes.",
+    "Question whether the reviewer understands the full context.",
+    "",
+    "### YAGNI Check",
+    "",
+    "For suggested \"professional features\" — grep the codebase for actual usage.",
+    "If unused, suggest removal instead of implementing.",
+    "",
+    "### Implementation Order",
+    "",
+    "1. Clarify all unclear items first.",
+    "2. Then implement in order: blocking issues → simple fixes → complex fixes.",
+    "3. Test each change before moving to the next.",
+    "",
+    "### When to Push Back",
+    "",
+    "Push back when feedback would introduce bugs, break existing behavior,",
+    "add unnecessary complexity, or contradicts the codebase's established patterns.",
+    "Use technical reasoning, not defensiveness.",
+    "",
+    "### The Bottom Line",
+    "",
+    "External feedback = suggestions to evaluate, not orders to follow.",
+    "Verify before implementing. Question. Then implement.",
+    "No performative agreement. Technical rigor always.",
+  ].join("\n");
+}

package/src/discipline/tdd.ts

@@ -0,0 +1,77 @@
+/**
+ * TDD enforcement instructions for sub-agent prompts.
+ * Matches superpowers' test-driven-development skill depth.
+ */
+export function buildTddInstructions(): string {
+  return [
+    "## Test-Driven Development",
+    "",
+    "### Iron Law",
+    "",
+    "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.",
+    "",
+    "Write code before the test? Delete it. Start over.",
+    "",
+    "### Red-Green-Refactor Cycle",
+    "",
+    "**RED — Write failing test:**",
+    "- One behavior per test, clear name, real code (no mocks unless unavoidable)",
+    "- Watch it fail. MANDATORY. Never skip.",
+    "- Confirm: test fails (not errors), failure message is expected, fails because feature is missing",
+    "- Test passes? You're testing existing behavior. Fix the test.",
+    "",
+    "**GREEN — Write the simplest code to pass:**",
+    "- Minimal, simplest code that makes the test pass",
+    "- Don't add features, refactor other code, or improve beyond the test",
+    "- Watch it pass. MANDATORY.",
+    "- Confirm: test passes, other tests still pass, output pristine",
+    "- Test fails? Fix code, not test. Other tests fail? Fix now.",
+    "",
+    "**REFACTOR — Clean up (after green only):**",
+    "- Remove duplication, improve names, extract helpers",
+    "- Keep tests green. Don't add behavior.",
+    "",
+    "### Verification Checklist",
+    "",
+    "Before marking work complete:",
+    "- Every new function/method has a test",
+    "- Watched each test fail before implementing",
+    "- Each test failed for expected reason (feature missing, not typo)",
+    "- Wrote minimal code to pass each test",
+    "- All tests pass with pristine output",
+    "- Tests use real code (mocks only if unavoidable)",
+    "- Edge cases and errors covered",
+    "",
+    "### Red Flags — STOP and Start Over",
+    "",
+    "- Code before test",
+    "- Test after implementation",
+    "- Test passes immediately",
+    "- Can't explain why test failed",
+    "- Tests added later",
+    "- Rationalizing \"just this once\"",
+    "",
+    "### Testing Anti-Patterns",
+    "",
+    "- Don't test mock behavior instead of real behavior",
+    "- Don't add test-only methods to production classes",
+    "- Don't mock without understanding dependencies",
+    "- Don't use incomplete mocks (partial data structures)",
+    "- Mocks are tools to isolate, not things to test",
+    "",
+    "### When Stuck",
+    "",
+    "| Problem | Solution |",
+    "|---------|----------|",
+    "| Don't know how to test | Write wished-for API. Write assertion first. Ask. |",
+    "| Test too complicated | Design too complicated. Simplify interface. |",
+    "| Must mock everything | Code too coupled. Use dependency injection. |",
+    "| Test setup huge | Extract helpers. Still complex? Simplify design. |",
+    "",
+    "### Bug Fix Flow",
+    "",
+    "Bug found? Write a failing test reproducing it first.",
+    "Follow the TDD cycle. The test proves the fix and prevents regression.",
+    "Never fix bugs without a failing test.",
+  ].join("\n");
+}

package/src/discipline/verification.ts

@@ -0,0 +1,68 @@
+/**
+ * Verification-before-completion instructions for sub-agent prompts.
+ * Matches superpowers' verification-before-completion skill depth.
+ */
+export function buildVerificationInstructions(): string {
+  return [
+    "## Verification Before Completion",
+    "",
+    "### Iron Law",
+    "",
+    "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.",
+    "Evidence before assertions, always.",
+    "",
+    "### The Gate Function (Mandatory Before Any Status Claim)",
+    "",
+    "1. **IDENTIFY:** What command proves this claim?",
+    "2. **RUN:** Execute the FULL command (fresh, complete).",
+    "3. **READ:** Full output. Check exit code. Count failures.",
+    "4. **VERIFY:** Does output confirm the claim?",
+    "   - If NO: State actual status with evidence.",
+    "   - If YES: State claim WITH evidence.",
+    "5. **ONLY THEN:** Make the claim.",
+    "",
+    "Skip any step = lying, not verifying.",
+    "",
+    "### Common Failure Patterns",
+    "",
+    "| Claim | Requires | Not Sufficient |",
+    "|-------|----------|----------------|",
+    "| Tests pass | Test command output: 0 failures | Previous run, \"should pass\" |",
+    "| Build succeeds | Build command: exit 0 | Linter passing, logs look good |",
+    "| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |",
+    "| Regression test works | Red-green cycle verified | Test passes once |",
+    "| Agent completed | VCS diff shows changes | Agent reports \"success\" |",
+    "| Requirements met | Line-by-line checklist | Tests passing |",
+    "",
+    "### Red Flags — STOP Before Claiming",
+    "",
+    "- Using \"should\", \"probably\", \"seems to\"",
+    "- Expressing satisfaction before verification (\"Great!\", \"Perfect!\", \"Done!\")",
+    "- About to commit/push/PR without verification",
+    "- Trusting agent success reports without checking",
+    "- Relying on partial verification",
+    "- Thinking \"just this once\"",
+    "",
+    "### Verification Patterns",
+    "",
+    "**Tests:**",
+    "- Run test command → see actual pass count → then claim",
+    "- Never say \"should pass now\" or \"looks correct\"",
+    "",
+    "**Regression tests (TDD red-green):**",
+    "- Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)",
+    "- Never say \"I've written a regression test\" without red-green verification",
+    "",
+    "**Build:**",
+    "- Run build → see exit 0 → then claim",
+    "- Linter passing does not prove compilation",
+    "",
+    "**Requirements:**",
+    "- Re-read plan → create checklist → verify each → report gaps or completion",
+    "- Never say \"tests pass, phase complete\" without checking requirements",
+    "",
+    "**Agent delegation:**",
+    "- Agent reports success → check VCS diff → verify changes → report actual state",
+    "- Never trust agent report without independent verification",
+  ].join("\n");
+}

package/src/fix-pr/config.ts

@@ -0,0 +1,36 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { FixPrConfig } from "./types.js";
+
+const CONFIG_FILENAME = "fix-pr.json";
+
+function getConfigPath(cwd: string): string {
+  return path.join(cwd, ".omp", "supipowers", CONFIG_FILENAME);
+}
+
+export const DEFAULT_FIX_PR_CONFIG: FixPrConfig = {
+  reviewer: { type: "none", triggerMethod: null },
+  commentPolicy: "answer-selective",
+  loop: { delaySeconds: 180, maxIterations: 3 },
+  models: {
+    orchestrator: { provider: "anthropic", model: "claude-opus-4-6", tier: "high" },
+    planner: { provider: "anthropic", model: "claude-opus-4-6", tier: "high" },
+    fixer: { provider: "anthropic", model: "claude-sonnet-4-6", tier: "low" },
+  },
+};
+
+export function loadFixPrConfig(cwd: string): FixPrConfig | null {
+  const configPath = getConfigPath(cwd);
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf-8")) as FixPrConfig;
+  } catch {
+    return null;
+  }
+}
+
+export function saveFixPrConfig(cwd: string, config: FixPrConfig): void {
+  const configPath = getConfigPath(cwd);
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}

package/src/fix-pr/prompt-builder.ts

@@ -0,0 +1,201 @@
+import type { FixPrConfig } from "./types.js";
+import { buildReceivingReviewInstructions } from "../discipline/receiving-review.js";
+
+export interface FixPrPromptOptions {
+  prNumber: number;
+  repo: string;
+  comments: string;
+  sessionDir: string;
+  scriptsDir: string;
+  config: FixPrConfig;
+  iteration: number;
+  skillContent: string;
+}
+
+function buildReplyInstructions(config: FixPrConfig): string {
+  const { commentPolicy, repo, } = config;
+  const replyCmd = `gh api repos/REPO/pulls/PR/comments/COMMENT_ID/replies -f body="..."`;
+
+  switch (commentPolicy) {
+    case "no-answer":
+      return [
+        "### Comment Replies",
+        "",
+        "Policy: **Do not reply** to any comments. Focus only on fixing the code.",
+        "Do not post any replies via gh api.",
+      ].join("\n");
+    case "answer-all":
+      return [
+        "### Comment Replies",
+        "",
+        "Policy: **Answer all** comments — both accepted and rejected.",
+        "For each comment, post a reply explaining what was done or why it was rejected.",
+        `Use: \`${replyCmd}\``,
+        "Keep replies factual and technical. No performative agreement.",
+      ].join("\n");
+    case "answer-selective":
+      return [
+        "### Comment Replies",
+        "",
+        "Policy: **Answer selectively** — only reply to comments you reject or where clarification adds value.",
+        "For ACCEPT: fix silently (the code change speaks for itself).",
+        "For REJECT: explain why with technical reasoning.",
+        `Use: \`${replyCmd}\``,
+        "Keep replies factual. No performative agreement.",
+      ].join("\n");
+  }
+}
+
+export function buildFixPrOrchestratorPrompt(options: FixPrPromptOptions): string {
+  const { prNumber, repo, comments, sessionDir, scriptsDir, config, iteration, skillContent } = options;
+  const { loop, models, reviewer } = config;
+  const maxIter = loop.maxIterations;
+  const delay = loop.delaySeconds;
+
+  const sections: string[] = [
+    "# PR Review Fix Orchestration",
+    "",
+    `You are the orchestrator for fixing PR #${prNumber} on \`${repo}\`.`,
+    "",
+    "## Session Context",
+    "",
+    `- Session dir: \`${sessionDir}\``,
+    `- Iteration: ${iteration} of ${maxIter}`,
+    `- Comment reply policy: ${config.commentPolicy}`,
+    `- Reviewer: ${reviewer.type}${reviewer.triggerMethod ? ` (trigger: ${reviewer.triggerMethod})` : ""}`,
+    "",
+    "## Review Comments to Process",
+    "",
+    "Each line is a JSON object with comment data:",
+    "",
+    "```jsonl",
+    comments,
+    "```",
+    "",
+  ];
+
+  // Embedded skill
+  if (skillContent) {
+    sections.push(
+      "## Assessment Methodology",
+      "",
+      skillContent,
+      "",
+    );
+  }
+
+  // Receiving review discipline
+  sections.push(
+    "## Review Discipline",
+    "",
+    buildReceivingReviewInstructions(),
+    "",
+  );
+
+  // Step 1: Assess
+  sections.push(
+    "## Step 1: Assess Each Comment",
+    "",
+    "For each comment:",
+    "1. Read the actual code at the file and line referenced",
+    "2. Determine the verdict: **ACCEPT** / **REJECT** / **INVESTIGATE**",
+    "3. Check ripple effects — who calls this, what tests cover it",
+    "4. YAGNI check — does the reviewer's suggestion address a real problem?",
+    "",
+    "Record your assessment:",
+    "```",
+    "Comment #ID by @user on file:line",
+    "Verdict: ACCEPT | REJECT | INVESTIGATE",
+    "Reasoning: [1-2 sentences]",
+    "Ripple effects: [list or none]",
+    "Group: [group-id]",
+    "```",
+    "",
+  );
+
+  // Step 2: Group
+  sections.push(
+    "## Step 2: Group Comments",
+    "",
+    "Group accepted comments for parallel execution:",
+    "- Same file or tightly coupled files → same group",
+    "- Independent files/areas → separate groups",
+    "- Cosmetic vs functional → separate groups",
+    "",
+  );
+
+  // Step 3: Plan
+  sections.push(
+    "## Step 3: Plan Each Group",
+    "",
+    "For each group, create a fix plan:",
+    "- What changes are needed and why",
+    "- Which files to modify",
+    "- Expected ripple effects and how to handle them",
+    "- How to verify the fix (which tests to run)",
+    "",
+  );
+
+  // Step 4: Execute
+  sections.push(
+    "## Step 4: Execute Fixes",
+    "",
+    "For each group:",
+    "1. Make the code changes",
+    "2. Run relevant tests to verify",
+    "3. If tests fail, fix before moving on",
+    "",
+  );
+
+  // Step 5: Reply
+  sections.push(buildReplyInstructions(config), "");
+
+  // Step 6: Push and loop
+  sections.push(
+    "## Step 6: Push and Check for New Comments",
+    "",
+    '1. Stage and commit: `git add -A && git commit -m "fix: address PR review comments (iteration ' + iteration + ')"`',
+    "2. Push: `git push`",
+  );
+
+  if (reviewer.type !== "none" && reviewer.triggerMethod) {
+    sections.push(
+      `3. Trigger re-review: \`bash ${scriptsDir}/trigger-review.sh "${repo}" ${prNumber} "${reviewer.type}" "${reviewer.triggerMethod}"\``,
+    );
+  }
+
+  sections.push(
+    `${reviewer.type !== "none" ? "4" : "3"}. Run the check script:`,
+    "```bash",
+    `bash ${scriptsDir}/wait-and-check.sh "${sessionDir}" ${delay} ${iteration + 1} "${repo}" ${prNumber}`,
+    "```",
+    `${reviewer.type !== "none" ? "5" : "4"}. Read the last line of output:`,
+    `   - If \`hasNewComments: true\` and iteration < ${maxIter}: process the new comments (go back to Step 1)`,
+    `   - If \`hasNewComments: false\` or iteration >= ${maxIter}: report done`,
+    "",
+  );
+
+  // Script paths reference
+  sections.push(
+    "## Script Paths",
+    "",
+    `- fetch-pr-comments.sh: \`${scriptsDir}/fetch-pr-comments.sh\``,
+    `- diff-comments.sh: \`${scriptsDir}/diff-comments.sh\``,
+    `- trigger-review.sh: \`${scriptsDir}/trigger-review.sh\``,
+    `- wait-and-check.sh: \`${scriptsDir}/wait-and-check.sh\``,
+    "",
+  );
+
+  // Model guidance
+  sections.push(
+    "## Model Guidance",
+    "",
+    `- **Orchestrator** (assessment, grouping): ${models.orchestrator.model} (${models.orchestrator.tier} tier) — thorough analysis`,
+    `- **Planner** (fix planning): ${models.planner.model} (${models.planner.tier} tier) — detailed planning`,
+    `- **Fixer** (code changes): ${models.fixer.model} (${models.fixer.tier} tier) — focused execution`,
+    "",
+    "These indicate the expected reasoning depth for each phase of work.",
+  );
+
+  return sections.join("\n");
+}