@mrclrchtr/supi-review 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @mrclrchtr/supi-review
 
-Structured code review for the [pi coding agent](https://github.com/earendil-works/pi).
+Adds a guided `/supi-review` command to the [pi coding agent](https://github.com/earendil-works/pi) for structured code review.
 
 ## Install
 
@@ -8,71 +8,111 @@ Structured code review for the [pi coding agent](https://github.com/earendil-wor
 pi install npm:@mrclrchtr/supi-review
 ```
 
-> **🧪 Beta package** — not included in the `@mrclrchtr/supi` meta-package.
-> Install directly when you need structured code reviews.
+This is a **beta** package. It is not bundled in `@mrclrchtr/supi`.
 
-## What it adds
+For local development:
 
-This extension registers `/supi-review`, which launches an in-process managed child session to review:
+```bash
+pi install ./packages/supi-review
+```
 
-- uncommitted changes
-- a base-branch diff
-- a specific commit
-- custom review instructions
+After editing the source, run `/reload`.
+
+## What you get
+
+After install, pi gets one command:
+
+- `/supi-review` — launch an interactive review flow and render a structured review result
 
-Review results are emitted as a `supi-review` custom message. Optional auto-fix mode can send a follow-up user message to fix the findings.
+The reviewer runs in a managed child agent session with read-only review tools:
+
+- `read`
+- `grep`
+- `find`
+- `ls`
+- `submit_review` (internal result-submission tool)
 
 ## Review flow
 
-```text
-/supi-review
-    ↓
-select preset + auto-fix mode
-    ↓
-collect diff / commit / custom target
-    ↓
-create child reviewer session
-    ↓
-submit_review tool returns structured findings
-    ↓
-render supi-review message
-```
+`/supi-review` walks you through:
 
-## Configuration
+1. choose a review mode
+2. choose a review target
+3. build a review brief
+4. edit and approve the final review prompt
+5. run the review with a live progress widget
+6. show the result as a structured custom message
+7. optionally trigger an auto-fix follow-up turn
 
-If your install surface includes `/supi-settings` (for example when also installing the `@mrclrchtr/supi` meta-package), this package contributes review settings there.
+## Review modes
 
-## Architecture
+### Dynamic review
 
-```text
-src/
-├── review.ts             command registration and orchestration
-├── runner.ts             managed child-session execution
-├── target-resolution.ts  git-backed target hydration
-├── prompts.ts            review prompt generation
-├── git.ts                git helpers for diffs, commits, and branches
-├── progress-widget.ts    live TUI progress overlay
-├── renderer.ts           custom message renderer
-├── settings.ts           review model + behavior settings
-└── types.ts              shared result and target types
-```
+You provide:
 
-## Requirements
+- what changed
+- the intended outcome
+- what the reviewer should focus on
 
-- `@earendil-works/pi-ai`
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-- `typebox`
-- `@mrclrchtr/supi-core`
+The package turns that into a review brief and lets you edit the final prompt before the review starts.
 
-## Development
+### Standard review
 
-```bash
-pnpm vitest run packages/supi-review/
-pnpm exec tsc --noEmit -p packages/supi-review/tsconfig.json
-pnpm exec biome check packages/supi-review/
+You choose one of the built-in profiles:
+
+- `general`
+- `security`
+- `api-maintainability`
+
+The package builds the review brief from the selected profile and again lets you edit the final prompt before running.
+
+## Review targets
+
+Current target presets:
+
+- base branch diff
+- uncommitted changes
+- one commit
+- custom review instructions
+
+## Result shape
+
+A successful review includes:
+
+- overall correctness verdict
+- overall explanation
+- overall confidence score
+- structured findings with title, body, priority, confidence score, and code location
+
+The renderer also handles failed, canceled, and timed-out reviews.
+
+## Settings
+
+This package registers a **Review** section in `/supi-settings`.
+
+Available settings:
+
+- `reviewModel` — preselect the model used by `/supi-review`; empty means inherit the active session model
+- `maxDiffBytes` — maximum diff size before the prompt builder truncates the diff
+- `autoFix` — automatically send a follow-up user message to fix findings after a successful review with findings
+
+Defaults:
+
+```json
+{
+  "review": {
+    "reviewModel": "",
+    "maxDiffBytes": 100000,
+    "autoFix": false
+  }
+}
 ```
 
-## License
+## Source
 
-MIT
+- `src/review.ts` — command orchestration and interactive flow
+- `src/ui.ts` — TUI selection and approval steps
+- `src/profiles.ts` — built-in review profiles
+- `src/runner.ts` — managed reviewer session
+- `src/settings.ts` — `/supi-settings` integration
+- `src/renderer.ts` — structured result rendering

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -1,65 +1,78 @@
 # @mrclrchtr/supi-core
 
-Shared infrastructure for SuPi packages.
+Shared infrastructure for SuPi extensions.
+
+This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
 
 ## Install
 
-Use it as a dependency in another extension package:
+### As a dependency for another extension
 
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-## Package role
-
-`@mrclrchtr/supi-core` now has two explicit surfaces:
+### As a pi package
 
-- `@mrclrchtr/supi-core/api` — shared library helpers for other SuPi packages
-- `@mrclrchtr/supi-core/extension` — a minimal pi extension that registers `/supi-settings`
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
 
-## What it provides
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
 
-Current exports cover:
+## Package surfaces
 
-- shared config loading, scoped reads, writes, and key removal
-- config-backed settings registration helpers for `/supi-settings`
-- the shared settings registry, overlay UI, and `registerSettingsCommand()` helper
-- XML `<extension-context>` wrapping plus context-message utilities
-- context-provider and debug-event registries reused across SuPi packages
-- project root and path helpers reused by packages such as `supi-lsp`
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
-## Config system
+## What you get from the API
 
-Config resolution order:
+### Config helpers
 
-```text
-defaults <- global <- project
-```
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
 
 - global: `~/.pi/agent/supi/config.json`
 - project: `.pi/supi/config.json`
 
-Main helpers:
+### Settings helpers
+
+- `registerSettings()` — register an arbitrary settings section
+- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand()` — register `/supi-settings`
+- `openSettingsOverlay()` — open the shared settings UI directly
+- `createInputSubmenu()` — helper for simple text-entry submenus
+
+The built-in settings UI supports:
 
-- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
-- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
-- `writeSupiConfig()`
-- `removeSupiConfigKey()`
-- `registerConfigSettings()`
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
 
-## Context and settings helpers
+### Context helpers
 
-- `wrapExtensionContext()`
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 - `findLastUserMessageIndex()`
 - `getContextToken()`
+- `getPromptContent()`
 - `pruneAndReorderContextMessages()`
-- `registerSettings()`
-- `registerSettingsCommand()`
-- `openSettingsOverlay()`
+- `restorePromptContent()`
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry for producers that want shared debug capture
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
 ## Example
 
@@ -80,17 +93,15 @@ registerConfigSettings({
 });
 
 const message = wrapExtensionContext("my-extension", "hello", {
-  turn: 1,
   file: "CLAUDE.md",
+  turn: 1,
 });
 ```
 
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-
 ## Source
 
-- Library surface: `src/api.ts`
-- Extension surface: `src/extension.ts`
+- `src/api.ts` — exported library surface
+- `src/extension.ts` — minimal `/supi-settings` entrypoint
+- `src/config.ts` — shared config loading and writing
+- `src/config-settings.ts` — config-backed settings registration helper
+- `src/settings-ui.ts` — shared settings overlay

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{config-settings.ts → config/config-settings.ts}

@@ -2,9 +2,9 @@
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
-import type { SettingsScope } from "./settings-registry.ts";
-import { registerSettings } from "./settings-registry.ts";
 
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */

package/node_modules/@mrclrchtr/supi-core/src/{context-provider-registry.ts → context/context-provider-registry.ts}

@@ -3,7 +3,7 @@
 // Extensions declare context data providers via `registerContextProvider()` during their
 // factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
 
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export interface ContextProvider {
   /** Unique identifier — e.g. "rtk" */

package/node_modules/@mrclrchtr/supi-core/src/extension.ts

@@ -1 +1 @@
-export { registerSettingsCommand as default } from "./settings-command.ts";
+export { registerSettingsCommand as default } from "./settings/settings-command.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{settings-registry.ts → settings/settings-registry.ts}

@@ -4,7 +4,7 @@
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export type SettingsScope = "project" | "global";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi Review extension — structured code review via /supi-review command",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.3.0"
+    "@mrclrchtr/supi-core": "1.4.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -47,7 +47,8 @@
   },
   "pi": {
     "extensions": [
-      "./src/extension.ts"
+      "./src/extension.ts",
+      "node_modules/@mrclrchtr/supi-core/src/extension.ts"
     ]
   },
   "main": "src/api.ts",

package/src/briefs.ts

@@ -0,0 +1,101 @@
+import { getProfile } from "./profiles.ts";
+import type { BuildPromptOptions } from "./prompts.ts";
+import { buildReviewPrompt } from "./prompts.ts";
+import type { ReviewBrief, ReviewTarget } from "./types.ts";
+
+// ── Dynamic brief construction ───────────────────────────────────
+
+export interface DynamicBriefInputs {
+  summary: string;
+  intent: string;
+  focus: string;
+}
+
+/**
+ * Build a dynamic review brief from structured user inputs.
+ * The finalPrompt field is empty — it must be set later by the caller
+ * via `assembleReviewerPrompt()` or explicitly assigned.
+ */
+export function buildDynamicBrief(inputs: DynamicBriefInputs): ReviewBrief {
+  const title = `Review: ${inputs.summary}`;
+  return {
+    mode: "dynamic",
+    title,
+    summary: inputs.summary,
+    intent: inputs.intent,
+    focus: inputs.focus,
+    finalPrompt: "",
+  };
+}
+
+// ── Standard brief construction ──────────────────────────────────
+
+/**
+ * Build a standard review brief from a named profile.
+ * The summary/intent/focus are derived from the profile definition.
+ * The finalPrompt field is empty — it must be set later by the caller
+ * via `assembleReviewerPrompt()` or explicitly assigned.
+ */
+export function buildStandardBrief(profileId: string): ReviewBrief {
+  const profile = getProfile(profileId);
+  if (!profile) {
+    throw new Error(`Unknown profile: "${profileId}"`);
+  }
+  return {
+    mode: "standard",
+    title: `${profile.label} Review`,
+    summary: profile.description,
+    intent: profile.description,
+    focus: profile.label,
+    profileId: profile.id,
+    finalPrompt: "",
+  };
+}
+
+// ── Prompt assembly ──────────────────────────────────────────────
+
+/**
+ * Assemble the full reviewer prompt from a review brief and target.
+ *
+ * The output has two sections:
+ * 1. **Review Request** — the brief's summary, intent, focus, and profile (if standard)
+ * 2. **Changes to review** — the existing target preamble + diff/custom instructions
+ */
+export function assembleReviewerPrompt(
+  brief: ReviewBrief,
+  target: ReviewTarget,
+  diff: string = "",
+  options?: BuildPromptOptions,
+): string {
+  const parts: string[] = [];
+
+  // Review request summary from the brief
+  parts.push("## Review Request");
+  parts.push("");
+  parts.push(`**Summary:** ${brief.summary}`);
+  parts.push(`**Intended outcome:** ${brief.intent}`);
+  parts.push(`**Focus areas:** ${brief.focus}`);
+  if (brief.mode === "standard" && brief.profileId) {
+    parts.push(`**Review profile:** ${brief.profileId}`);
+  }
+  parts.push("");
+
+  // Existing target preamble + diff
+  parts.push(buildReviewPrompt(target, diff, options));
+
+  return parts.join("\n");
+}
+
+/**
+ * Build a fully resolved brief by assembling the prompt and setting
+ * the finalPrompt field. Used after the brief has been approved.
+ */
+export function resolveBrief(
+  brief: ReviewBrief,
+  target: ReviewTarget,
+  diff: string = "",
+  options?: BuildPromptOptions,
+): ReviewBrief {
+  const finalPrompt = assembleReviewerPrompt(brief, target, diff, options);
+  return { ...brief, finalPrompt };
+}

package/src/profiles.ts

@@ -0,0 +1,52 @@
+import type { ReviewProfile } from "./types.ts";
+
+const STARTER_PROFILES: ReviewProfile[] = [
+  {
+    id: "general",
+    label: "General",
+    description: "Standard review covering correctness, security, performance, and maintainability",
+    systemPrompt: "",
+  },
+  {
+    id: "security",
+    label: "Security",
+    description:
+      "Focused security review — injection risks, auth bypasses, secrets exposure, data validation",
+    systemPrompt: [
+      "--- Security review guidance ---",
+      "Prioritize the following areas:",
+      "- Injection risks: SQL, command, template injection in user-facing inputs",
+      "- Authentication & authorization: missing checks, privilege escalation, session handling",
+      "- Secrets exposure: hardcoded keys/tokens, logging sensitive data, insecure storage",
+      "- Data validation: insufficient input sanitisation, unsafe deserialization",
+      "- Cryptographic misuse: weak algorithms, hardcoded IVs/seeds, signature validation gaps",
+      "",
+      "Flag anything that could lead to data loss, unauthorized access, or privilege escalation as critical priority.",
+    ].join("\n"),
+  },
+  {
+    id: "api-maintainability",
+    label: "API & Maintainability",
+    description:
+      "Focused on API design, breaking changes, consistency, and long-term code maintainability",
+    systemPrompt: [
+      "--- API & maintainability review guidance ---",
+      "Prioritize the following areas:",
+      "- API design: inconsistent signatures, breaking contract changes, poor ergonomics",
+      "- Breaking changes: modified exported types, removed public APIs, changed parameter shapes",
+      "- Code clarity: unclear naming, missing abstractions, overly nested control flow",
+      "- Duplication: repeated patterns that should be extracted, copy-pasted code blocks",
+      "- Documentation gaps: missing JSDoc, stale comments, undocumented exports",
+    ].join("\n"),
+  },
+];
+
+/** Returns all available starter review profiles. */
+export function getProfiles(): ReviewProfile[] {
+  return STARTER_PROFILES;
+}
+
+/** Returns the profile with the given id, or undefined if not found. */
+export function getProfile(id: string): ReviewProfile | undefined {
+  return STARTER_PROFILES.find((p) => p.id === id);
+}

package/src/review.ts

@@ -1,6 +1,7 @@
+// biome-ignore lint/nursery/noExcessiveLinesPerFile: pre-existing, needs refactoring
 import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { formatReviewContent } from "./format-content.ts";
+import { buildDynamicBrief, buildStandardBrief } from "./briefs.ts";
 import {
   getCommitFileNames,
   getCommitShow,
@@ -10,11 +11,7 @@ import {
   getUncommittedDiff,
   getUncommittedFileNames,
 } from "./git.ts";
-import { ReviewProgressWidget } from "./progress-widget.ts";
 import { buildReviewPrompt } from "./prompts.ts";
-import { registerReviewRenderer } from "./renderer.ts";
-import { runReviewer } from "./runner.ts";
-import type { ReviewerInvocation } from "./runner-types.ts";
 import {
   filterByEnabledModels,
   loadReviewSettings,
@@ -22,14 +19,29 @@ import {
   registerReviewSettings,
   setReviewModelChoices,
 } from "./settings.ts";
-import { resolveGitTarget } from "./target-resolution.ts";
-import type { ReviewResult, ReviewTarget } from "./types.ts";
-import { selectAutoFix, selectBranch, selectCommit, selectPreset } from "./ui.ts";
+import { runReviewer } from "./tool/runner.ts";
+import type { ReviewerInvocation } from "./tool/runner-types.ts";
+import { resolveGitTarget } from "./tool/target-resolution.ts";
+import type { ReviewBrief, ReviewResult, ReviewTarget } from "./types.ts";
+import { formatReviewContent } from "./ui/format-content.ts";
+import { ReviewProgressWidget } from "./ui/progress-widget.ts";
+import { registerReviewRenderer } from "./ui/renderer.ts";
+import {
+  approveBriefViaEditor,
+  collectDynamicInputs,
+  selectAutoFix,
+  selectBranch,
+  selectCommit,
+  selectPreset,
+  selectProfile,
+  selectReviewMode,
+} from "./ui/ui.ts";
 
 type CommandContext = Parameters<Parameters<ExtensionAPI["registerCommand"]>[1]["handler"]>[1];
 
 interface ReviewExecutionOptions {
   target: ReviewTarget;
+  brief: ReviewBrief;
   maxDiffBytes: number;
   ctx: CommandContext;
   signal?: AbortSignal;
@@ -52,7 +64,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
       return;
     }
 
-    // Try to respect PI’s scoped models (enabledModels).
+    // Try to respect PI's scoped models (enabledModels).
     // Workaround for pi-mono#3535 — swap to ctx.scopedModels when exposed by PI.
     const enabledPatterns = readPiEnabledModels();
     const models = enabledPatterns ? filterByEnabledModels(enabledPatterns, allModels) : allModels;
@@ -83,21 +95,88 @@ async function handleInteractive(
   ctx: CommandContext,
   pi: ExtensionAPI,
 ): Promise<void> {
+  // Step 1: Select review mode
+  const mode = await selectReviewMode(ctx);
+  if (!mode) return;
+
+  // Step 2: Select review target
   const preset = await selectPreset(ctx);
   if (!preset) return;
 
-  const autoFix = await selectAutoFix(ctx, autoFixDefault);
-  if (autoFix === undefined) return;
-
   const target = await resolvePresetTarget(preset, ctx);
   if (!target) return;
 
-  const result = await runReviewWithLoader(target, maxDiffBytes, ctx, pi);
+  // Step 3: Build the review brief
+  let brief: ReviewBrief;
+  if (mode === "standard") {
+    const profileId = await selectProfile(ctx);
+    if (!profileId) return;
+    brief = buildStandardBrief(profileId);
+  } else {
+    const inputs = await collectDynamicInputs(ctx);
+    if (!inputs) return;
+    brief = buildDynamicBrief(inputs);
+  }
+
+  // Step 4: Assemble the full prompt and get user approval
+  const diffOrBody = getDiffText(target);
+  const truncated = maybeTruncateDiff(diffOrBody, maxDiffBytes);
+  const draftPrompt = buildReviewPrompt(
+    target,
+    truncated.text,
+    truncated.wasTruncated
+      ? { truncated: true, truncatedBytes: truncated.truncatedBytes }
+      : undefined,
+  );
+
+  // Show the brief context + draft prompt for approval
+  const approvalText = await approveBriefViaEditor(ctx, formatBriefWithPrompt(brief, draftPrompt));
+  if (!approvalText) return;
+
+  brief.finalPrompt = approvalText;
+
+  // Step 5: Auto-fix preference
+  const autoFix = await selectAutoFix(ctx, autoFixDefault);
+  if (autoFix === undefined) return;
+
+  // Step 6: Run the review
+  const result = await runReviewWithLoader(brief, target, maxDiffBytes, ctx, pi);
   injectReviewMessage(pi, result, autoFix);
 }
 
+/** Extract the diff/show text from a target for display. */
+function getDiffText(target: ReviewTarget): string {
+  if (target.type === "base-branch" || target.type === "uncommitted") {
+    return target.diff;
+  }
+  if (target.type === "commit") {
+    return target.show;
+  }
+  return "";
+}
+
+/** Format the brief summary + full prompt for editor approval. */
+function formatBriefWithPrompt(brief: ReviewBrief, prompt: string): string {
+  return [
+    "# Review Brief",
+    "",
+    brief.mode === "standard"
+      ? `Profile: ${brief.profileId ?? "standard"}`
+      : "Review mode: dynamic",
+    `Summary: ${brief.summary}`,
+    `Intended outcome: ${brief.intent}`,
+    `Focus areas: ${brief.focus}`,
+    "",
+    "# Suggested review prompt",
+    "",
+    "Edit the prompt below if needed, then save and close to start the review.",
+    "",
+    prompt,
+  ].join("\n");
+}
+
 async function resolvePresetTarget(
-  preset: import("./ui.ts").Preset,
+  preset: import("./ui/ui.ts").Preset,
   ctx: CommandContext,
 ): Promise<ReviewTarget | undefined> {
   switch (preset) {
@@ -160,7 +239,9 @@ async function executeReview(options: ReviewExecutionOptions): Promise<ReviewRes
   return runReview({ ...options, target: resolved.target });
 }
 
+// biome-ignore lint/complexity/useMaxParams: needs to pass brief, target, diffBytes, ctx, and pi for the full pipeline
 async function runReviewWithLoader(
+  brief: ReviewBrief,
   target: ReviewTarget,
   maxDiffBytes: number,
   ctx: CommandContext,
@@ -183,6 +264,7 @@ async function runReviewWithLoader(
 
     executeReview({
       target,
+      brief,
       maxDiffBytes,
       ctx,
       signal: widget.signal,
@@ -206,9 +288,8 @@ async function runReviewWithLoader(
 }
 
 function runReview(options: ReviewExecutionOptions): Promise<ReviewResult> {
-  const { target, maxDiffBytes, ctx, signal, onToolActivity, onProgress } = options;
+  const { target, brief, ctx, signal, onToolActivity, onProgress } = options;
   const settings = loadReviewSettings(ctx.cwd);
-  // ctx.modelRegistry is available because CommandContext extends ExtensionContext
   const model = resolveReviewerModel(settings, ctx.modelRegistry, ctx.model);
   if (!model) {
     return Promise.resolve({
@@ -219,24 +300,8 @@ function runReview(options: ReviewExecutionOptions): Promise<ReviewResult> {
     });
   }
 
-  let diffOrBody = "";
-  if (target.type === "base-branch" || target.type === "uncommitted") {
-    diffOrBody = target.diff;
-  } else if (target.type === "commit") {
-    diffOrBody = target.show;
-  }
-
-  const truncated =
-    target.type === "custom"
-      ? { text: "", wasTruncated: false, truncatedBytes: 0 }
-      : maybeTruncateDiff(diffOrBody, maxDiffBytes);
-  const prompt = buildReviewPrompt(
-    target,
-    truncated.text,
-    truncated.wasTruncated
-      ? { truncated: true, truncatedBytes: truncated.truncatedBytes }
-      : undefined,
-  );
+  // Use the approved brief's final prompt directly
+  const prompt = brief.finalPrompt;
 
   const invocation: ReviewerInvocation = {
     prompt,
@@ -244,6 +309,7 @@ function runReview(options: ReviewExecutionOptions): Promise<ReviewResult> {
     modelRegistry: ctx.modelRegistry,
     cwd: ctx.cwd,
     target,
+    brief,
     signal,
     onToolActivity,
     onProgress,

package/src/{runner-types.ts → tool/runner-types.ts}

@@ -1,6 +1,6 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import type { ReviewTarget } from "./types.ts";
+import type { ReviewBrief, ReviewTarget } from "../types.ts";
 
 /** Progress state exposed by the runner for widget integration. */
 export interface ReviewProgress {
@@ -24,6 +24,8 @@ export interface ReviewerInvocation {
   cwd: string;
   signal?: AbortSignal;
   target: ReviewTarget;
+  /** The approved review brief used to generate the prompt. */
+  brief?: ReviewBrief;
   timeoutMs?: number;
   /** Callback for tool activity events (starts/ends) for widget integration. */
   onToolActivity?: (event: { toolName: string; phase: "start" | "end" }) => void;

package/src/{runner.ts → tool/runner.ts}

@@ -10,8 +10,8 @@ import {
   SessionManager,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import type { ReviewOutputEvent, ReviewResult, ReviewTarget } from "../types.ts";
 import type { ReviewerInvocation, ReviewProgress } from "./runner-types.ts";
-import type { ReviewOutputEvent, ReviewResult, ReviewTarget } from "./types.ts";
 
 export type { ReviewerInvocation } from "./runner-types.ts";
 
@@ -249,8 +249,15 @@ function handleToolEnd(
   ctx.onToolActivity?.({ toolName: event.toolName, phase: "end" });
   ctx.onProgress?.({ ...ctx.progress, activities: [...ctx.progress.activities] });
 }
-function handleAgentEnd(ctx: RunnerContext): void {
+function handleAgentEnd(
+  event: Extract<AgentSessionEvent, { type: "agent_end" }>,
+  ctx: RunnerContext,
+): void {
   if (ctx.state.settled || ctx.signal?.aborted || ctx.timeout.aborting) return;
+  const retryAwareEvent = event as Extract<AgentSessionEvent, { type: "agent_end" }> & {
+    willRetry?: boolean;
+  };
+  if (retryAwareEvent.willRetry) return;
   if (ctx.resultHolder.value) {
     ctx.resolve(
       ctx.cleanup({ kind: "success", output: ctx.resultHolder.value, target: ctx.target }),
@@ -284,7 +291,7 @@ function handleSessionEvent(event: AgentSessionEvent, ctx: RunnerContext): void
       handleToolEnd(event, ctx);
       break;
     case "agent_end":
-      handleAgentEnd(ctx);
+      handleAgentEnd(event, ctx);
       break;
     // Ignore other events (queue_update, compaction, auto_retry, etc.)
     default:
@@ -299,12 +306,13 @@ export async function runReviewer(inv: ReviewerInvocation): Promise<ReviewResult
     cwd,
     signal,
     target,
+    brief,
     onToolActivity,
     onProgress,
     timeoutMs = DEFAULT_TIMEOUT_MS,
   } = inv;
   if (signal?.aborted) {
-    return { kind: "canceled", target };
+    return { kind: "canceled", target, brief };
   }
   // Holder for the submit_review tool result
   const resultHolder: { value: ReviewOutputEvent | undefined } = { value: undefined };
@@ -314,7 +322,7 @@ export async function runReviewer(inv: ReviewerInvocation): Promise<ReviewResult
     session = await createReviewerSession(model, cwd, submitReviewTool, modelRegistry);
   } catch (err) {
     const reason = `Failed to create reviewer session: ${err instanceof Error ? err.message : String(err)}`;
-    return { kind: "failed" as const, reason, target };
+    return { kind: "failed" as const, reason, target, brief };
   }
   const progress: ReviewProgress = { turns: 0, toolUses: 0, activities: [], tokens: undefined };
   const state = { settled: false };
@@ -324,7 +332,7 @@ export async function runReviewer(inv: ReviewerInvocation): Promise<ReviewResult
     state.settled = true;
     cancelTeardown?.();
     session.dispose();
-    return result;
+    return brief ? { ...result, brief } : result;
   };
   return new Promise<ReviewResult>((resolve) => {
     const timeoutRef = {

package/src/{target-resolution.ts → tool/target-resolution.ts}

@@ -6,8 +6,8 @@ import {
   getMergeBase,
   getUncommittedDiff,
   getUncommittedFileNames,
-} from "./git.ts";
-import type { ReviewResult, ReviewTarget } from "./types.ts";
+} from "../git.ts";
+import type { ReviewResult, ReviewTarget } from "../types.ts";
 
 interface TargetResolutionContext {
   cwd: string;

package/src/types.ts

@@ -31,6 +31,48 @@ export type ReviewTarget =
   | { type: "commit"; sha: string; show: string; changedFiles?: string[] }
   | { type: "custom"; instructions: string; changedFiles?: string[] };
 
+// ── Review modes and profiles ───────────────────────────────
+
+/** Standard vs dynamic review mode. */
+export type ReviewMode = "standard" | "dynamic";
+
+/**
+ * A review profile definition for standard reviews.
+ * Each profile provides a named set of review focus areas
+ * and optional system prompt guidance for the reviewer session.
+ */
+export interface ReviewProfile {
+  id: string;
+  label: string;
+  description: string;
+  /**
+   * Additional system-prompt guidance injected into the
+   * reviewer child session for this type of review.
+   */
+  systemPrompt: string;
+}
+
+/**
+ * A review brief captures what the user wants the reviewer to examine.
+ * It is assembled before the child reviewer session starts and
+ * influences both the prompt and the final result rendering.
+ */
+export interface ReviewBrief {
+  mode: ReviewMode;
+  /** Human-readable title for the review (e.g. "Review: auth middleware"). */
+  title: string;
+  /** Summary of what changed (dynamic) or profile description (standard). */
+  summary: string;
+  /** Intended outcome of the change being reviewed. */
+  intent: string;
+  /** Focus areas or risk areas for the reviewer to examine. */
+  focus: string;
+  /** Profile id when mode === "standard", undefined otherwise. */
+  profileId?: string;
+  /** The assembled final prompt text sent to the reviewer. */
+  finalPrompt: string;
+}
+
 export interface ReviewSettings {
   reviewModel: string;
   maxDiffBytes: number;
@@ -38,12 +80,13 @@ export interface ReviewSettings {
 }
 
 export type ReviewResult =
-  | { kind: "success"; output: ReviewOutputEvent; target: ReviewTarget }
-  | { kind: "failed"; reason: string; target: ReviewTarget }
-  | { kind: "canceled"; target: ReviewTarget }
+  | { kind: "success"; output: ReviewOutputEvent; target: ReviewTarget; brief?: ReviewBrief }
+  | { kind: "failed"; reason: string; target: ReviewTarget; brief?: ReviewBrief }
+  | { kind: "canceled"; target: ReviewTarget; brief?: ReviewBrief }
   | {
       kind: "timeout";
       target: ReviewTarget;
       timeoutMs: number;
       partialOutput?: string;
+      brief?: ReviewBrief;
     };

package/src/{format-content.ts → ui/format-content.ts}

@@ -1,4 +1,4 @@
-import type { ReviewResult } from "./types.ts";
+import type { ReviewResult } from "../types.ts";
 
 function priorityLabel(priority: number): string {
   switch (priority) {
@@ -39,11 +39,22 @@ function formatTimeoutContent(result: Extract<ReviewResult, { kind: "timeout" }>
 function formatSuccessContent(result: Extract<ReviewResult, { kind: "success" }>): string {
   const output = result.output;
   const confidencePercent = Math.round(output.overall_confidence_score * 100);
-  const lines = [
-    "## Code Review Result",
-    "",
-    `Verdict: ${output.overall_correctness} (confidence: ${confidencePercent}%)`,
-  ];
+  const lines: string[] = ["## Code Review Result"];
+
+  // Show the review request context (if brief is available)
+  if (result.brief) {
+    lines.push("", "### Review Requested", "");
+    if (result.brief.mode === "standard" && result.brief.profileId) {
+      lines.push(`**Mode:** Standard (${result.brief.profileId})`);
+    } else {
+      lines.push("**Mode:** Dynamic");
+    }
+    lines.push(`**Summary:** ${result.brief.summary}`);
+    lines.push(`**Intended outcome:** ${result.brief.intent}`);
+    lines.push(`**Focus areas:** ${result.brief.focus}`);
+  }
+
+  lines.push("", `Verdict: ${output.overall_correctness} (confidence: ${confidencePercent}%)`);
 
   if (output.findings.length > 0) {
     lines.push("", "### Findings", "", ...formatFindings(output.findings));

package/src/{progress-widget.ts → ui/progress-widget.ts}

@@ -1,7 +1,11 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { CancellableLoader, Container, Text, type TUI } from "@earendil-works/pi-tui";
-import { formatTokens } from "./runner.ts";
-import type { ReviewProgress } from "./runner-types.ts";
+import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
+import { formatTokens } from "../tool/runner.ts";
+import type { ReviewProgress } from "../tool/runner-types.ts";
+
+interface ReviewProgressTui {
+  requestRender(): void;
+}
 
 /**
  * Live progress widget for code review.
@@ -13,16 +17,16 @@ export class ReviewProgressWidget extends Container {
   private _message: string;
   private _progress: ReviewProgress = { turns: 0, toolUses: 0, activities: [] };
   private _loader: CancellableLoader;
-  private _tui: TUI;
+  private _tui: ReviewProgressTui;
   private _theme: Theme;
 
-  constructor(tui: TUI, theme: Theme, message: string) {
+  constructor(tui: ReviewProgressTui, theme: Theme, message: string) {
     super();
     this._tui = tui;
     this._theme = theme;
     this._message = message;
     this._loader = new CancellableLoader(
-      tui,
+      tui as ConstructorParameters<typeof CancellableLoader>[0],
       (s: string) => theme.fg("accent", s),
       (s: string) => theme.fg("muted", s),
       message,

package/src/{renderer.ts → ui/renderer.ts}

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Spacer, Text } from "@earendil-works/pi-tui";
-import type { ReviewFinding, ReviewResult } from "./types.ts";
+import type { ReviewFinding, ReviewResult } from "../types.ts";
 
 export function registerReviewRenderer(pi: ExtensionAPI): void {
   pi.registerMessageRenderer("supi-review", (message, { expanded }, theme) => {
@@ -35,6 +35,18 @@ function renderSuccess(
   container.addChild(new Text(theme.fg("accent", "◆ Code Review Results"), 1, 0));
   container.addChild(new Spacer(1));
 
+  // Brief context
+  if (result.brief) {
+    const modeLabel =
+      result.brief.mode === "standard" && result.brief.profileId
+        ? `Standard (${result.brief.profileId})`
+        : "Dynamic";
+    container.addChild(new Text(theme.fg("muted", `Review mode: ${modeLabel}`), 1, 0));
+    container.addChild(new Text(theme.fg("muted", `Summary: ${result.brief.summary}`), 1, 0));
+    container.addChild(new Text(theme.fg("muted", `Focus: ${result.brief.focus}`), 1, 0));
+    container.addChild(new Spacer(1));
+  }
+
   const normalizedVerdict = output.overall_correctness.toLowerCase();
   const verdictColor = normalizedVerdict.includes("incorrect")
     ? "warning"

package/src/{ui.ts → ui/ui.ts}

@@ -1,9 +1,17 @@
 import { DynamicBorder, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Container, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
-import { getLocalBranches, getRecentCommits } from "./git.ts";
+import { getLocalBranches, getRecentCommits } from "../git.ts";
+import { getProfiles } from "../profiles.ts";
+import type { ReviewMode } from "../types.ts";
 
 export type Preset = "base-branch" | "uncommitted" | "commit" | "custom";
 
+export interface DynamicInputs {
+  summary: string;
+  intent: string;
+  focus: string;
+}
+
 interface SelectFromListOptions<T> {
   items: SelectItem[];
   title: string;
@@ -83,6 +91,90 @@ export async function selectAutoFix(
   });
 }
 
+/** Select review mode: standard or dynamic. */
+export async function selectReviewMode(ctx: ExtensionContext): Promise<ReviewMode | undefined> {
+  return selectFromList(ctx, {
+    items: [
+      {
+        value: "dynamic",
+        label: "Dynamic review",
+        description:
+          "Describe what changed and what to focus on — the agent drafts the review brief",
+      },
+      {
+        value: "standard",
+        label: "Standard review",
+        description: "Use a predefined review profile (general, security, API & maintainability)",
+      },
+    ],
+    title: "Select review mode",
+    maxHeight: 4,
+    onSelect: (item) => item.value as ReviewMode,
+  });
+}
+
+/** Select a standard review profile. */
+export async function selectProfile(ctx: ExtensionContext): Promise<string | undefined> {
+  const profiles = getProfiles();
+  return selectFromList(ctx, {
+    items: profiles.map((p) => ({
+      value: p.id,
+      label: p.label,
+      description: p.description,
+    })),
+    title: "Select review profile",
+    maxHeight: Math.min(profiles.length + 1, 6),
+    onSelect: (item) => item.value as string,
+  });
+}
+
+/** Collect structured inputs for a dynamic review brief via a single editor prompt. */
+export async function collectDynamicInputs(
+  ctx: ExtensionContext,
+): Promise<DynamicInputs | undefined> {
+  const template = [
+    "# Dynamic Review Brief",
+    "",
+    "Fill in the fields below. Lines starting with `#` are comments and will be stripped.",
+    "",
+    "# What changed? (summary of the changes being reviewed)",
+    "",
+    "# What is the intended outcome of this change?",
+    "",
+    "# What should the reviewer focus on? (risk areas, specific concerns)",
+    "",
+  ].join("\n");
+
+  const text = await ctx.ui.editor("Dynamic Review Brief", template);
+  if (!text?.trim()) return undefined;
+
+  // Parse non-comment lines into sections
+  const lines = text.split("\n").filter((l) => !l.trim().startsWith("#") && l.trim().length > 0);
+  if (lines.length < 3) {
+    ctx.ui.notify("Please provide all three fields: summary, intent, and focus", "warning");
+    return undefined;
+  }
+
+  return {
+    summary: lines[0]?.trim() ?? "",
+    intent: lines[1]?.trim() ?? "",
+    focus: lines.slice(2).join(" ").trim(),
+  };
+}
+
+/**
+ * Show the full draft prompt in an editor for review and editing.
+ * Returns the edited prompt text, or undefined if the user cancels.
+ */
+export async function approveBriefViaEditor(
+  ctx: ExtensionContext,
+  draftPrompt: string,
+): Promise<string | undefined> {
+  const result = await ctx.ui.editor("Review the draft and edit if needed", draftPrompt);
+  if (!result?.trim()) return undefined;
+  return result;
+}
+
 export async function selectBranch(ctx: ExtensionContext): Promise<string | undefined> {
   const branches = await getLocalBranches(ctx.cwd);
   if (branches.length === 0) {