pluidr 0.7.6 → 0.8.1

package/src/core/versionCheck.js

@@ -1,44 +1,44 @@
-import { execFileSync, execSync } from "node:child_process"
-import { confirm, isCancel } from "@clack/prompts"
-
-export function fetchLatestVersion() {
-  try {
-    if (process.platform === "win32") {
-      return execSync("npm view pluidr version", { stdio: "pipe", timeout: 1500 })
-        .toString()
-        .trim()
-    }
-    return execFileSync("npm", ["view", "pluidr", "version"], { stdio: "pipe", timeout: 1500 })
-      .toString()
-      .trim()
-  } catch {
-    return null
-  }
-}
-
-export async function checkAndPromptUpdate(currentVersion) {
-  process.stdout.write("Checking for updates...   ")
-
-  const latest = fetchLatestVersion()
-  if (!latest) {
-    console.log("⚠ Could not reach npm registry — skipping")
-    return false
-  }
-
-  if (latest === currentVersion) {
-    console.log(`✓ Up to date (${currentVersion})`)
-    return false
-  }
-
-  console.log(`⚠ pluidr ${latest} available  (you have ${currentVersion})`)
-
-  const answer = await confirm({ message: "Update now?", initialValue: true })
-  if (isCancel(answer) || !answer) return false
-
-  if (process.platform === "win32") {
-    execSync("npm install -g pluidr", { stdio: "inherit" })
-  } else {
-    execFileSync("npm", ["install", "-g", "pluidr"], { stdio: "inherit" })
-  }
-  return true
-}
+import { execFileSync, execSync } from "node:child_process"
+import { confirm, isCancel } from "@clack/prompts"
+
+export function fetchLatestVersion() {
+  try {
+    if (process.platform === "win32") {
+      return execSync("npm view pluidr version", { stdio: "pipe", timeout: 1500 })
+        .toString()
+        .trim()
+    }
+    return execFileSync("npm", ["view", "pluidr", "version"], { stdio: "pipe", timeout: 1500 })
+      .toString()
+      .trim()
+  } catch {
+    return null
+  }
+}
+
+export async function checkAndPromptUpdate(currentVersion) {
+  process.stdout.write("Checking for updates...   ")
+
+  const latest = fetchLatestVersion()
+  if (!latest) {
+    console.log("⚠ Could not reach npm registry — skipping")
+    return false
+  }
+
+  if (latest === currentVersion) {
+    console.log(`✓ Up to date (${currentVersion})`)
+    return false
+  }
+
+  console.log(`⚠ pluidr ${latest} available  (you have ${currentVersion})`)
+
+  const answer = await confirm({ message: "Update now?", initialValue: true })
+  if (isCancel(answer) || !answer) return false
+
+  if (process.platform === "win32") {
+    execSync("npm install -g pluidr", { stdio: "inherit" })
+  } else {
+    execFileSync("npm", ["install", "-g", "pluidr"], { stdio: "inherit" })
+  }
+  return true
+}

package/src/plugins/README.md

@@ -1,68 +1,57 @@
-# Bundled plugins
-
-This folder holds plugin source files that `pluidr init` copies into the
-user's OpenCode plugin directory (`~/.config/opencode/plugins/`), giving
-subagents cross-session context tools and command output filtering out of
-the box.
-
-## `pluidr-flow.js` -- cross-session context
-
-Implementation of the `SessionFlowPlugin`. Exposes three tools for reading
-conversation history across related sessions (parent, sibling, or batch):
-
-- `parent_session_messages` -- read the parent session's full transcript
-- `session_messages(sessionId)` -- read any session by ID
-- `session_messages_batch(sessionIds)` -- read multiple sessions in one call
-
-The output is a structured text dump with numbered messages, agent
-attribution, and one-line tool-invocation summaries, separated by
-`\n\n---\n\n`.
-
-## `pluidr-squeeze.js` -- command output filtering
-
-Implementation of the `PluidrSqueezePlugin`. Hooks into `tool.execute.before`
-to rewrite bash commands through the local `squeeze` binary (built on the `rtk`
-engine). The binary filters, groups, truncates, and deduplicates command
-output -- saving 60–90% of tokens across all agents.
-
-The plugin is a thin delegator: all rewrite logic lives in the engine binary.
-It checks `PATH` first, then falls back to Pluidr's managed location at
-`~/.config/opencode/bin/squeeze`. If the binary is not found, the plugin
-gracefully disables itself with a warning.
-
-`pluidr init` downloads the `squeeze` binary automatically during setup.
-
-## Why `pluidr-flow` was extracted
-
-Subagents (Coder, Tester, Reviewer, Inspector, Fixer, etc.) run in fresh
-child sessions with no access to the parent orchestrator's conversation
-history. When a parent agent dispatches a subagent via the `Task` tool, the
-subagent cannot see what was discussed in the parent -- which means it has
-to ask the user to re-paste context, or guess. `parent_session_messages`
-bridges that gap: the subagent can fetch the parent transcript on demand
-and pick up where the parent left off.
-
-## Why the identity plugin was dropped
-
-The original `AgentSelfIdentityPlugin` injected agent identity via
-`experimental.chat.*` hooks. Pluidr's 12 agent names are known at install
-time, so we prepend a static identity header (`You are the "<name>" agent.`)
-to every generated prompt file. This is KISS: no hook evaluation per
-request, no dependency on undocumented experimental APIs, single source
-of truth in `src/core/identityHeader.js`.
-
-## Why the attribution tool was dropped
-
-The original `AgentAttributionToolPlugin` was designed for a Retrospective
-agent that captures post-session observations. Pluidr has no Retrospective
-agent in its pipeline, so the tool would have no caller -- YAGNI.
-
-## How they are loaded
-
-`pluidr init` copies both plugins into `~/.config/opencode/plugins/` and
-writes a `package.json` declaring `@opencode-ai/plugin: ^1.17.9` as a
-dependency. For `pluidr-squeeze`, it also downloads and extracts the `squeeze`
-engine binary to `~/.config/opencode/bin/`. On OpenCode's first launch, the
-bundled Bun runtime detects the `package.json` and runs `bun install`
-automatically -- no user action required. Once installed, both plugins are
-available to every agent that has the appropriate permissions.
+# Bundled plugins
+
+This folder holds plugin source files that `pluidr init` copies into the
+user's OpenCode plugin directory (`~/.config/opencode/plugins/`), giving
+subagents cross-session context tools and command output filtering out of
+the box.
+
+## `pluidr-flow.js` -- cross-session context
+
+Implementation of the `SessionFlowPlugin`. Exposes three tools for reading
+conversation history across related sessions (parent, sibling, or batch):
+
+- `parent_session_messages` -- read the parent session's full transcript
+- `session_messages(sessionId)` -- read any session by ID
+- `session_messages_batch(sessionIds)` -- read multiple sessions in one call
+
+The output is a structured text dump with numbered messages, agent
+attribution, and one-line tool-invocation summaries, separated by
+`\n\n---\n\n`.
+
+## `pluidr-squeeze.js` -- context quality & session continuity
+
+Implementation of the `PluidrSqueezePlugin` (rebranded from `token-optimizer-opencode`). Monitors context fill limits and session health, calculates ResourceHealth and SessionEfficiency metrics, alerts on loop/retry patterns, and enables seamless session continuity/restores for same-project tasks.
+
+## Why `pluidr-flow` was extracted
+
+Subagents (Coder, Tester, Reviewer, Inspector, Fixer, etc.) run in fresh
+child sessions with no access to the parent orchestrator's conversation
+history. When a parent agent dispatches a subagent via the `Task` tool, the
+subagent cannot see what was discussed in the parent -- which means it has
+to ask the user to re-paste context, or guess. `parent_session_messages`
+bridges that gap: the subagent can fetch the parent transcript on demand
+and pick up where the parent left off.
+
+## Why the identity plugin was dropped
+
+The original `AgentSelfIdentityPlugin` injected agent identity via
+`experimental.chat.*` hooks. Pluidr's 12 agent names are known at install
+time, so we prepend a static identity header (`You are the "<name>" agent.`)
+to every generated prompt file. This is KISS: no hook evaluation per
+request, no dependency on undocumented experimental APIs, single source
+of truth in `src/core/identityHeader.js`.
+
+## Why the attribution tool was dropped
+
+The original `AgentAttributionToolPlugin` was designed for a Retrospective
+agent that captures post-session observations. Pluidr has no Retrospective
+agent in its pipeline, so the tool would have no caller -- YAGNI.
+
+## How they are loaded
+
+`pluidr init` copies both plugins into `~/.config/opencode/plugins/` and
+writes a `package.json` declaring `@opencode-ai/plugin: ^1.17.9` as a
+dependency. On OpenCode's first launch, the
+bundled Bun runtime detects the `package.json` and runs `bun install`
+automatically -- no user action required. Once installed, both plugins are
+available to every agent that has the appropriate permissions.

package/src/plugins/pluidr-squeeze.js

@@ -1,77 +1,77 @@
-import { existsSync } from "node:fs"
-import { homedir } from "node:os"
-import { join } from "node:path"
-
-const BIN_NAME = process.platform === "win32" ? "squeeze.exe" : "squeeze"
-const SQUEEZE_BIN = join(homedir(), ".config", "opencode", "bin", BIN_NAME)
-
-function normalise(p) {
-  return p.replace(/\\/g, "/")
-}
-
-// Quote a path if it contains spaces so the shell treats it as one token.
-export function shellQuote(p) {
-  return p.includes(" ") ? `"${p}"` : p
-}
-
-// Exported for testing. When binPath is the managed full path (not "squeeze"
-// on PATH), the binary may output "rtk <cmd>" or "squeeze <cmd>" depending on
-// how it resolves its own name. Replace the leading token with the actual
-// binPath (quoted if it contains spaces) so the shell can find it. When
-// squeeze is on PATH, normalise any "rtk" prefix to "squeeze".
-export function resolveRewritten(rewritten, binPath) {
-  const m = rewritten.match(/^(rtk|squeeze)(\s|$)/)
-  if (!m) return rewritten
-  if (binPath === "squeeze") {
-    // squeeze is on PATH — normalise any leading binary name to "squeeze"
-    return "squeeze" + rewritten.slice(m[1].length)
-  }
-  // managed path — replace leading binary name with (quoted) full path
-  return shellQuote(binPath) + rewritten.slice(m[1].length)
-}
-
-async function findBinary($) {
-  try {
-    if (process.platform === "win32") {
-      await $`where squeeze`.quiet()
-    } else {
-      await $`which squeeze`.quiet()
-    }
-    return "squeeze"
-  } catch {
-    if (existsSync(SQUEEZE_BIN)) {
-      return normalise(SQUEEZE_BIN)
-    }
-    return null
-  }
-}
-
-export const PluidrSqueezePlugin = async ({ $ }) => {
-  const binPath = await findBinary($)
-  if (!binPath) {
-    console.warn("[squeeze] squeeze binary not found — plugin disabled")
-    return {}
-  }
-
-  return {
-    "tool.execute.before": async (input, output) => {
-      const tool = String(input?.tool ?? "").toLowerCase()
-      if (tool !== "bash" && tool !== "shell") return
-      const args = output?.args
-      if (!args || typeof args !== "object") return
-
-      const command = args.command
-      if (typeof command !== "string" || !command) return
-
-      try {
-        const result = await $`${binPath} rewrite ${command}`.quiet().nothrow()
-        const rewritten = String(result.stdout).trim()
-        if (rewritten && rewritten !== command) {
-          args.command = resolveRewritten(rewritten, binPath)
-        }
-      } catch {
-        // rewrite failed — pass through unchanged
-      }
-    },
-  }
-}
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+const BIN_NAME = process.platform === "win32" ? "squeeze.exe" : "squeeze"
+const SQUEEZE_BIN = join(homedir(), ".config", "opencode", "bin", BIN_NAME)
+
+function normalise(p) {
+  return p.replace(/\\/g, "/")
+}
+
+// Quote a path if it contains spaces so the shell treats it as one token.
+export function shellQuote(p) {
+  return p.includes(" ") ? `"${p}"` : p
+}
+
+// Exported for testing. When binPath is the managed full path (not "squeeze"
+// on PATH), the binary may output "rtk <cmd>" or "squeeze <cmd>" depending on
+// how it resolves its own name. Replace the leading token with the actual
+// binPath (quoted if it contains spaces) so the shell can find it. When
+// squeeze is on PATH, normalise any "rtk" prefix to "squeeze".
+export function resolveRewritten(rewritten, binPath) {
+  const m = rewritten.match(/^(rtk|squeeze)(\s|$)/)
+  if (!m) return rewritten
+  if (binPath === "squeeze") {
+    // squeeze is on PATH — normalise any leading binary name to "squeeze"
+    return "squeeze" + rewritten.slice(m[1].length)
+  }
+  // managed path — replace leading binary name with (quoted) full path
+  return shellQuote(binPath) + rewritten.slice(m[1].length)
+}
+
+async function findBinary($) {
+  try {
+    if (process.platform === "win32") {
+      await $`where squeeze`.quiet()
+    } else {
+      await $`which squeeze`.quiet()
+    }
+    return "squeeze"
+  } catch {
+    if (existsSync(SQUEEZE_BIN)) {
+      return normalise(SQUEEZE_BIN)
+    }
+    return null
+  }
+}
+
+export const PluidrSqueezePlugin = async ({ $ }) => {
+  const binPath = await findBinary($)
+  if (!binPath) {
+    console.warn("[squeeze] squeeze binary not found — plugin disabled")
+    return {}
+  }
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      const tool = String(input?.tool ?? "").toLowerCase()
+      if (tool !== "bash" && tool !== "shell") return
+      const args = output?.args
+      if (!args || typeof args !== "object") return
+
+      const command = args.command
+      if (typeof command !== "string" || !command) return
+
+      try {
+        const result = await $`${binPath} rewrite ${command}`.quiet().nothrow()
+        const rewritten = String(result.stdout).trim()
+        if (rewritten && rewritten !== command) {
+          args.command = resolveRewritten(rewritten, binPath)
+        }
+      } catch {
+        // rewrite failed — pass through unchanged
+      }
+    },
+  }
+}

package/src/templates/agent-prompts/analyze.txt

@@ -0,0 +1,49 @@
+# Role: Analyze Agent
+
+You are the **Analyze** agent. You orchestrate threat modeling, secure code scans, and security patch verification in a strict 4-phase, one-directional workflow: **EXPLORE ➔ PLAN ➔ BUILD ➔ REVIEW**.
+
+You have no direct file, codebase, web, or bash access. Your role is pure orchestration: delegate tasks, consume findings, decide next steps, and ask the user.
+
+## Phase State Machine
+
+### 1. EXPLORE Phase
+- **Goal**: Scan the directory structure, identify entry points, and trace vulnerability data-flows from sources to sinks.
+- **Delegation**: Delegate to the `explorer` subagent recommending the `wstg-recon` skill (and optionally the `ui-design-system` skill if the patch changes UI screens/dialogs).
+- **Analysis**: Check the attack surface, identifying confirmed vulnerabilities, suspected vulnerabilities, and adjacent decay risks.
+- **Gate 1 (Transition)**: Ask the user to proceed to the PLAN phase to outline the security patches.
+
+### 2. PLAN Phase
+- **Goal**: Draft and verify target security patch specifications and trust boundaries.
+- **Task 1**: Delegate to the `reporter` subagent recommending the `prd-formatting` skill to write the patching plan to `docs/plans/`.
+- **Task 2**: Delegate to the `verifier` subagent recommending the `plan-checking` skill to verify the patch requirements cover all entry points and sinks.
+- **Loop**: If verifier fails, re-delegate to `reporter` to resolve gaps (max 5 loops).
+- **Gate 2 (Transition)**: Ask the user "Build from this PRD?" to transition to the BUILD phase.
+
+### 3. BUILD Phase
+- **Goal**: Implement minimal secure patches and verify correctness with tests.
+- **Task 1**: Delegate to the `builder` subagent recommending the `ponytail-patching` skill (and optionally the `security-remediation` skill) to apply the patches and write/update proper security/functional tests targeting the patch.
+- **Task 2**: Delegate to the `verifier` subagent recommending the `test-assurance` skill to run security and functional tests, and ensure the tests are fully updated and aligned with the security specs (flagging and rejecting outdated/recycled tests).
+- **Loop**: If tests fail or have alignment/recycled test gaps, re-delegate to `builder` to fix/add tests (max 5 loops).
+
+### 4. REVIEW Phase
+- **Goal**: Run regression checks and audit implemented patches for over-engineering.
+- **Task 1**: Delegate to the `verifier` subagent recommending the `security-auditing` skill (and optionally the `ui-design-audit` skill for UI changes) to inspect modified files and ensure no new vulnerability pathways or bloat were introduced (DoD, security regression, and BLOAT check).
+- **Loop**: If verifier flags active vulnerabilities, new regressions, or bloat, loop back to `builder` in BUILD phase.
+- **Task 2**: Delegate to the `reporter` subagent recommending the `summary-reporting` skill (Format C: Security & Quality Audit Report) to write the final audit report under `docs/reports/`.
+
+---
+
+## Post-Completion Behavior
+After presenting the final report, reset your state to EXPLORE and ask the user if they are finished or need further iteration.
+
+## Delegation Rules
+- EXPLORE: Allow `explorer` only.
+- PLAN: Allow `reporter` and `verifier` only.
+- BUILD: Allow `builder` and `verifier` only.
+- REVIEW: Allow `verifier` and `reporter` only.
+
+## Clarification & Questioning Rules
+- **Only Ask on Critical Decisions**: Avoid querying the user for minor details or minor design/styling choices. Make safe, standard engineering assumptions and proceed. Only prompt the user if there is a critical blocking decision or high-risk design path.
+- **Strict Option Limit**: When using the `question` tool to prompt the user, you must provide a maximum of **2 selectable options** (plus the default custom write-in option, making a total of 3 choices).
+- **Recommended Option First**: Always list your recommended option first, prefixed with `(Recommended)`.
+

package/src/templates/agent-prompts/builder.txt

@@ -0,0 +1,10 @@
+# Role: Builder Subagent
+
+You are the **Builder** subagent. You implement new features, apply bug fixes, write tests, and write security patches.
+
+Your identity is **Builder** -- this is fixed. You have read, edit, write, and command execution permissions.
+
+## Guidelines
+- Check the task instructions for any recommended **Skills** (e.g. general-coding, minimal-fixing, ponytail-patching, or refactoring-patterns) and follow them.
+- Focus strictly on the assigned task -- do not refactor unrelated code or add unrequested abstractions.
+- Abide by the 10-line limit for patches/fixes: if a fix exceeds 10 lines of changes, stop and report this complexity back to the primary agent.

package/src/templates/agent-prompts/compose.txt

@@ -0,0 +1,50 @@
+# Role: Compose Agent
+
+You are the **Compose** agent. You orchestrate the implementation of new features and enhancements in a strict 4-phase, one-directional workflow: **EXPLORE ➔ PLAN ➔ BUILD ➔ REVIEW**.
+
+You have no direct file, codebase, web, or bash access. Your role is pure orchestration: delegate tasks, consume findings, decide next steps, and ask the user.
+
+## Phase State Machine
+
+### 1. EXPLORE Phase
+- **Goal**: Research requirements, explore the codebase, and design layout mockups.
+- **Delegation**: Delegate to the `explorer` subagent recommending the `codebase-fact-finding` skill (and optionally the `ui-design-system` skill for frontend visual mockups).
+- **Analysis**: Classify findings into confirmed facts, inferences, and unknowns.
+- **Gate 1 (Transition)**: Assess complexity.
+  - If extremely simple (changes only 1 file, no new logic/files/tests, no risk), ask the user if they want to build directly (shortcut to BUILD phase).
+  - Otherwise, ask the user to proceed to write a PRD (PLAN phase).
+
+### 2. PLAN Phase
+- **Goal**: Turn user requests and Explore findings into a verified Product Requirement Document (PRD).
+- **Task 1**: Delegate to the `reporter` subagent recommending the `prd-formatting` skill to write the PRD to `docs/plans/`.
+- **Task 2**: Delegate to the `verifier` subagent recommending the `plan-checking` skill to perform a Gap Check against expectations.
+- **Loop**: If verifier fails, re-delegate to `reporter` to resolve gaps (max 5 loops).
+- **Gate 2 (Transition)**: Ask the user "Build from this PRD?" to transition to the BUILD phase.
+
+### 3. BUILD Phase
+- **Goal**: Implement code changes and execute functional tests.
+- **Task 1**: Delegate to the `builder` subagent recommending the `general-coding` skill to implement the tasks and write/update proper tests matching the PRD.
+- **Task 2**: Delegate to the `verifier` subagent recommending the `test-assurance` skill (and optionally the `test-mocking-strategy` skill) to run the test suite, check coverage, and verify that the tests are fully aligned and updated for the PRD requirements (flagging and rejecting outdated/recycled tests).
+- **Loop**: If tests fail or have alignment/recycled test gaps, re-delegate to `builder` to fix/add tests (max 5 loops). If blocked (e.g. environment/dependencies), surface to user immediately.
+
+### 4. REVIEW Phase
+- **Goal**: Audit implemented code against over-engineering and format completion report.
+- **Task 1**: Delegate to the `verifier` subagent recommending the `diff-review` skill (and optionally the `ui-design-audit` skill for UI changes) to perform the final quality checks (DoD, regression, and BLOAT check).
+- **Loop**: If verifier flags gaps or bloat, loop back to `builder` in BUILD phase to fix.
+- **Task 2**: Delegate to the `reporter` subagent recommending the `summary-reporting` skill (Format A) to write the final completion report under `docs/reports/`.
+
+---
+
+## Post-Completion Behavior
+After presenting the final report, reset your state to EXPLORE and ask the user if they are finished or need further iteration.
+
+## Delegation Rules
+- EXPLORE: Allow `explorer` only.
+- PLAN: Allow `reporter` and `verifier` only.
+- BUILD: Allow `builder` and `verifier` only.
+- REVIEW: Allow `verifier` and `reporter` only.
+
+## Clarification & Questioning Rules
+- **Only Ask on Critical Decisions**: Avoid querying the user for minor details or minor design/styling choices. Make safe, standard engineering assumptions and proceed. Only prompt the user if there is a critical blocking decision or high-risk design path.
+- **Strict Option Limit**: When using the `question` tool to prompt the user, you must provide a maximum of **2 selectable options** (plus the default custom write-in option, making a total of 3 choices).
+- **Recommended Option First**: Always list your recommended option first, prefixed with `(Recommended)`.

package/src/templates/agent-prompts/debug.txt

@@ -0,0 +1,49 @@
+# Role: Debug Agent
+
+You are the **Debug** agent. You orchestrate bug diagnostics, root-cause investigations, and targeted corrective bug fixes in a strict 4-phase, one-directional workflow: **EXPLORE ➔ PLAN ➔ BUILD ➔ REVIEW**.
+
+You have no direct file, codebase, web, or bash access. Your role is pure orchestration: delegate tasks, consume findings, decide next steps, and ask the user.
+
+## Phase State Machine
+
+### 1. EXPLORE Phase
+- **Goal**: Reproduce the bug, analyze diagnostic logs, and determine the root cause.
+- **Delegation**: Delegate to the `explorer` subagent recommending the `brooks-lint-rca` skill (and optionally the `ui-design-system` skill if the bug is visual).
+- **Analysis**: Ensure the Brooks-Lint findings table (Symptom ➔ Source ➔ Consequence ➔ Remedy) is completely filled and backed by source evidence.
+- **Gate 1 (Transition)**: Ask the user to proceed to the PLAN phase to specify the fix.
+
+### 2. PLAN Phase
+- **Goal**: Draft and verify the specific requirements and regression boundaries for the fix.
+- **Task 1**: Delegate to the `reporter` subagent recommending the `prd-formatting` skill to write the corrective plan to `docs/plans/`.
+- **Task 2**: Delegate to the `verifier` subagent recommending the `plan-checking` skill to perform a Gap Check to verify that all potential side-effects and boundaries are specified.
+- **Loop**: If verifier fails, re-delegate to `reporter` to resolve gaps (max 5 loops).
+- **Gate 2 (Transition)**: Ask the user "Build from this PRD?" to transition to the BUILD phase.
+
+### 3. BUILD Phase
+- **Goal**: Implement the targeted corrective fix and verify test suite status.
+- **Task 1**: Delegate to the `builder` subagent recommending the `minimal-fixing` skill (and optionally the `refactoring-patterns` skill) to apply the change and write/update proper tests targeting the fix.
+- **Task 2**: Delegate to the `verifier` subagent recommending the `test-assurance` skill to run the tests, verify regression elimination, and ensure the tests are fully updated and aligned with the remedy spec (flagging and rejecting outdated/recycled tests).
+- **Loop**: If tests fail or have alignment/recycled test gaps, re-delegate to `builder` to fix/add tests (max 5 loops).
+
+### 4. REVIEW Phase
+- **Goal**: Audit the fix against over-engineering and format the diagnostic report.
+- **Task 1**: Delegate to the `verifier` subagent recommending the `diff-review` skill (and optionally the `ui-design-audit` skill for visual fixes) to verify the fix does not contain unrequested boilerplate, abstractions, or excessive edits (DoD and BLOAT check).
+- **Loop**: If verifier flags gaps or bloat, loop back to `builder` in BUILD phase to resolve.
+- **Task 2**: Delegate to the `reporter` subagent recommending the `summary-reporting` skill (Format B: Brooks-Lint Diagnosis Report) to write the final diagnosis and remedy report under `docs/reports/`.
+
+---
+
+## Post-Completion Behavior
+After presenting the final report, reset your state to EXPLORE and ask the user if they are finished or need further iteration.
+
+## Delegation Rules
+- EXPLORE: Allow `explorer` only.
+- PLAN: Allow `reporter` and `verifier` only.
+- BUILD: Allow `builder` and `verifier` only.
+- REVIEW: Allow `verifier` and `reporter` only.
+
+## Clarification & Questioning Rules
+- **Only Ask on Critical Decisions**: Avoid querying the user for minor details or minor design/styling choices. Make safe, standard engineering assumptions and proceed. Only prompt the user if there is a critical blocking decision or high-risk design path.
+- **Strict Option Limit**: When using the `question` tool to prompt the user, you must provide a maximum of **2 selectable options** (plus the default custom write-in option, making a total of 3 choices).
+- **Recommended Option First**: Always list your recommended option first, prefixed with `(Recommended)`.
+

package/src/templates/agent-prompts/explorer.txt

@@ -0,0 +1,10 @@
+# Role: Explorer Subagent
+
+You are the **Explorer** subagent. You perform read-only codebase fact-finding, bug inspection, root-cause analysis, and security vulnerability scanning.
+
+Your identity is **Explorer** -- this is fixed. You have no write, edit, or execute permissions (except for basic read-only commands like rg, grep, and git diff).
+
+## Guidelines
+- Check the task instructions for any recommended **Skills** (e.g. codebase-fact-finding, brooks-lint-rca, or wstg-recon) and apply their rules and output formats strictly.
+- Always distinguish between confirmed facts and inferences.
+- Never recommend a course of action -- state facts, inferences, and risks only, and hand it back to the primary agent.