pluidr 0.4.0 → 0.5.0

package/README.md

@@ -4,75 +4,108 @@
 [![npm downloads](https://img.shields.io/npm/dm/pluidr)](https://www.npmjs.com/package/pluidr)
 [![License](https://img.shields.io/npm/l/pluidr)](https://github.com/funara/pluidr/blob/main/LICENSE)
 
-**Plan · Build · Review · Debug** — opinionated engineering workflow installer for [OpenCode](https://opencode.ai).
+**Explore · Plan · Build · Debug** — opinionated engineering workflow installer for [OpenCode](https://opencode.ai).
 
 ## How it works
 
-Pluidr sets up a **14-agent** pipeline in OpenCode organized under **4 primary agents**, each with a dedicated tab and exclusive subagents. Every agent has a strict role, scoped permissions, and no shared subagents.
+Pluidr sets up a **12-agent** pipeline in OpenCode organized under **2 primary agents**: **Composer** (orchestrating 7 subagents across 3 phases) and **Debugger** (standalone, 3 subagents). Every agent has a strict role, scoped permissions, and no shared subagents.
 
 ### Primary Agents
 
-**1. Explorer tab** (optional, research-only) — Brainstorms with you, scans the codebase and web for context, then produces actionable recommendations. No subagents, no file editing. Handoff to Planner when you're ready to formalize.
+**1. Composer tab** — The single entry point for all feature work. Composer runs 3 strict, sequential phases:
 
-**2. Planner tab** — Turns your request into a verified PRD. It researches technical facts via Researcher, writes the spec via Plan-Writer, and validates it for completeness via Plan-Checker. On FAIL, Planner surfaces gap remedies to you via the question tool (you pick the fix direction) — Planner never silently re-routes. After your input, Planner internally delegates to Researcher or Plan-Writer. Max 3 loops, then surfaces to you for direction. Planner never edits files directly.
+- **EXPLORE phase** (mandatory start) — Brainstorms with you, then delegates ALL research to the Researcher subagent — Composer itself has no read/glob/grep/webfetch/websearch/bash permissions. Produces actionable recommendations with certainty marking. Uses a **guardrail gate**: must ask you "Ready to write the PRD?" before proceeding to Plan.
 
-**3. Builder tab** — Executes a confirmed PRD. It delegates implementation to Coder, tests via Tester, checks traceability with Reviewer, and produces a completion report via Writer. Builder never edits files or runs bash directly.
+- **PLAN phase** — Turns findings into a verified PRD via Plan-Writer → Plan-Checker. Plan-Writer writes the PRD to `docs/plans/`. Plan-Checker validates against your original request (PASS/FAIL + gap list only). On FAIL, surfaces gap remedies to you via the question tool (max 3 loops). On PASS, uses a **guardrail gate**: must ask you "Build from this PRD?" before proceeding to Build.
 
-**4. Debugger tab** (standalone, user-triggered at any time) — Root-cause analysis using the **Brooks-Lint methodology** (Iron Law + 6 Decay Risks). Delegates investigation to Inspector, fixes to Fixer, and reports to Reporter. Does not depend on Builder — triggered directly by you.
+- **BUILD phase** — Executes the confirmed PRD via Coder → Tester → Reviewer → Writer in strict sequence. Coder implements, Tester validates (PASS/FAIL/BLOCKED), Reviewer gates against the PRD definition-of-done, Writer produces a completion report to `docs/reports/`. Coder→Coder loops without verification are forbidden. Max 3 consecutive FAILs before surfacing to you.
+
+Composer never edits files or runs bash directly — all work is delegated to subagents.
+
+After presenting the completion report, Composer resets to EXPLORE phase and asks what you'd like to do next: start a new feature, switch to Debugger for bugs, or iterate on the current result.
+
+**2. Debugger tab** (standalone, user-triggered at any time) — Root-cause analysis using the **Brooks-Lint methodology** (Iron Law + 6 Decay Risks). Delegates investigation to Inspector, fixes to Fixer, and reports to Reporter. Does not depend on Composer — triggered directly by you.
+Debugger never reads files, edits code, or runs bash directly — all investigation, fixes, and reports are delegated to subagents.
+
+After presenting the investigation outcome, Debugger resets and asks what you'd like to do next: investigate a new bug, switch to Composer for feature work, or re-investigate with new information.
 
 ### Exclusive Subagents
 
 Each subagent belongs to exactly one primary agent and cannot be invoked by anyone else:
 
-| Primary | Subagents | Role |
-|---------|-----------|------|
-| Explorer | *(none)* | Research + recommendations only |
-| Planner | Researcher | Technical/codebase fact-finding (confirmed_facts/inferred_facts/unknowns/risks) |
-| Planner | Plan-Writer | Stateless PRD formatter — missing input = TBD |
-| Planner | Plan-Checker | **Gate** — validates PRD against original request, PASS/FAIL + gap list only |
-| Builder | Coder | Writes and edits implementation code |
-| Builder | Tester | Runs tests, reports PASS/FAIL/BLOCKED + coverage gaps |
-| Builder | Reviewer | **Gate** — compares implementation against definition-of-done, PASS/FAIL + gap list only |
-| Builder | Writer | Stateless document formatter — completion reports |
-| Debugger | Inspector | Brooks-Lint RCA (Iron Law + 6 decay risks + 4 review modes) |
-| Debugger | Fixer | Applies minimal, root-cause-targeted fixes |
-| Debugger | Reporter | Stateless diagnosis report formatter (Iron Law structure) |
+| Primary | Phase | Subagents | Role |
+|---------|-------|-----------|------|
+| Composer | EXPLORE | Researcher | Technical/codebase fact-finding (confirmed_facts/inferred_facts/unknowns/risks) |
+| Composer | PLAN | Plan-Writer | Stateless PRD formatter — writes to `docs/plans/`, missing input = TBD |
+| Composer | PLAN | Plan-Checker | **Gate** — validates PRD against original request, PASS/FAIL + gap list only |
+| Composer | BUILD | Coder | Writes and edits implementation code |
+| Composer | BUILD | Tester | Runs tests, reports PASS/FAIL/BLOCKED + coverage gaps |
+| Composer | BUILD | Reviewer | **Gate** — compares implementation against definition-of-done, PASS/FAIL + gap list only |
+| Composer | BUILD | Writer | Stateless document formatter — writes completion reports to `docs/reports/` |
+| Debugger | DEBUG | Inspector | Brooks-Lint RCA (Iron Law + 6 decay risks + 4 review modes) |
+| Debugger | DEBUG | Fixer | Applies minimal, root-cause-targeted fixes |
+| Debugger | DEBUG | Reporter | Stateless diagnosis report formatter (Iron Law structure) |
 
 ### Workflow
 
 ```
   You describe a feature / idea
-         │
-         ▼
-  (Optional) Explorer → research + recommendations → User decides
-         │
-         ▼
-  Planner → (if needed) Researcher → Plan-Writer writes PRD →
-    Plan-Checker validates → you confirm → handoff to Builder
-         │
-         ▼
-  Builder → Coder implements → Tester runs tests →
-    Reviewer checks DoD → Writer produces completion report
+          │
+          ▼
+  Composer — always starts in EXPLORE phase
+          │
+  ┌───────┤
+  │       ▼
+  │  [Optional] Researcher → deep fact-finding
+  │       ▼
+  │  Synthesize findings → Internally assess complexity
+  │    ├── Simple → GUARDRAIL GATE 1a (question tool):
+  │    │   "Ready to build directly?"
+  │    │   ├── "Yes" → BUILD phase
+  │    │   ├── "Write a PRD first" → PLAN phase
+  │    │   └── "More research" → continue exploring
+  │    └── Complex → GUARDRAIL GATE 1b (question tool):
+  │        "Ready to write the PRD?"
+  │        ├── "Yes" → PLAN phase
+  │        └── "More research" → continue exploring
+  │       │                              │
+  │       ▼ (PLAN)                       ▼ (direct BUILD)
+  │  Plan-Writer → docs/plans/      Coder → Tester →
+  │  Plan-Checker validates         Reviewer → Writer → docs/reports/
+  │       │
+  │       ▼ (FAIL, max 3 loops)
+  │  Surface gaps → you pick remedy
+  │       │
+  │       ▼ (PASS)
+  │  GUARDRAIL GATE 2 (question tool):
+  │    "Build from this PRD?"
+  │    └── "Yes" → BUILD phase
+  │         Coder → Tester → Reviewer → Writer → docs/reports/
          │
          ▼
   You review the result
          │
-  (If bug found at any point → Debugger → Inspector → Fixer →
-   Reporter → you verify)
+  (If bug found at any point → Debugger → Inspector → Fixer → Reporter → you verify)
 ```
 
 ### Flow Rules
 
 | Rule | Detail |
 |------|--------|
+| **Mandatory EXPLORE start** | Composer always starts in EXPLORE phase — no skipping to Plan or Build without passing a guardrail gate |
+| **Complexity assessment** | Composer internally evaluates if the feature is simple (few files, low risk, clear approach) — this is LLM judgment, not user choice |
+| **Guardrail Gate 1** | Simple → question tool: "Ready to build directly?" Complex → question tool: "Ready to write the PRD?" Both paths require user confirmation |
+| **Guardrail Gate 2** | PLAN→BUILD: question tool asks "Build from this PRD?" with explicit confirmation |
+| **Direct build path** | Simple features can skip PLAN phase — Composer determines simplicity, user just confirms |
 | **Gate agents** | Plan-Checker and Reviewer output PASS/FAIL + gap list only — no improvement suggestions, no decisions |
 | **Researcher agents** | Researcher and Inspector output confirmed_facts/inferred_facts/unknowns/risks — no recommendations |
 | **Writer agents** | Plan-Writer, Writer, and Reporter are stateless formatters — missing input = TBD, never invent content |
-| **Build gate order** | Coder → Tester → Reviewer → Writer (Builder orchestrates in sequence) |
-| **Planner FAIL loop** | Plan-checker FAIL → Planner surfaces gap remedies to you via question tool (MC options) → you pick → Planner internally routes to Researcher or Plan-Writer. Max 3 loops, then surfaces to you for direction |
-| **Builder FAIL loop** | 3 consecutive FAILs from Tester or Reviewer → Builder surfaces to you |
-| **No shared subagents** | Each subagent belongs to exactly one primary — no cross-primary delegation |
-| **Debugger independence** | Debugger is standalone — does not flow through Builder, triggered directly by you |
+| **Phase-scoped delegation** | EXPLORE: researcher only. PLAN: plan-writer, plan-checker only. BUILD: coder, tester, reviewer, writer only |
+| **Build gate order** | Coder → Tester → Reviewer → Writer — no skipping, no Coder→Coder without verification |
+| **Plan-Checker FAIL loop** | Plan-checker FAIL → Composer surfaces gap remedies to you via question tool (MC options) → you pick → Composer routes to Plan-Writer. Max 3 loops, then surfaces to you for direction |
+| **Build FAIL loop** | 3 consecutive FAILs from Tester or Reviewer → Composer surfaces to you |
+| **Output directories** | Plan-Writer writes to `docs/plans/`. Writer writes to `docs/reports/`. Enforced by permissions |
+| **Debugger independence** | Debugger is standalone — does not flow through Composer, triggered directly by you |
 
 ### Brooks-Lint Methodology (Debugger)
 
@@ -107,30 +140,63 @@ npx pluidr init
 
 ## Usage
 
-### `pluidr init`
+### pluidr init
 
 Prompts you to select models for two agent tiers, then:
 
-- Builds a complete `opencode.jsonc` config with the chosen models injected into the right agents
-- Backs up any existing config at `~/.config/opencode/opencode.jsonc` to `opencode.jsonc.bak`
-- Writes the new config to `~/.config/opencode/opencode.jsonc`
-- Copies agent system-prompt files into `~/.config/opencode/prompts/`
-- Copies the bundled `parent-session` plugin into `~/.config/opencode/plugins/`
-- Writes a `package.json` into `~/.config/opencode/` declaring `@opencode-ai/plugin` as a dependency (OpenCode installs it automatically on first launch via its bundled Bun runtime)
+- Asks whether to install the pluidr-squeeze plugin (can decline squeeze download)
+- Builds a complete opencode.jsonc config with the chosen models injected into the right agents
+- Backs up any existing config at ~/.config/opencode/opencode.jsonc to opencode.jsonc.bak
+- Writes the new config to ~/.config/opencode/opencode.jsonc
+- Copies agent system-prompt files into ~/.config/opencode/prompts/
+- Copies the bundled pluidr-flow and pluidr-squeeze plugins into ~/.config/opencode/plugins/
+- Writes a package.json into ~/.config/opencode/ declaring @opencode-ai/plugin as a dependency (OpenCode installs it automatically on first launch via its bundled Bun runtime)
 
 On completion, prints:
-```
+`
 Pluidr setup complete!
 You can update your agent model settings later in opencode.jsonc
-```
-The filename `opencode.jsonc` (second line) is a clickable terminal hyperlink — Ctrl+click to open the config in your default editor.
+`
+The filename opencode.jsonc (second line) is a clickable terminal hyperlink — Ctrl+click to open the config in your default editor.
+
+### pluidr uninstall
+
+Removes Pluidr artifacts and restores your previous configuration:
+
+- Finds the latest timestamped backup (opencode.jsonc.bak.*) in ~/.config/opencode/
+- Restores it to opencode.jsonc
+- Removes prompts/, plugins/, and bin/ directories
+- Does NOT remove opencode.jsonc itself (preserves user customizations)
+- Does NOT remove package.json (may be used by other plugins)
+- Prints a summary of what was removed and restored
+
+### pluidr update
+
+Re-runs the setup wizard (same as pluidr init). Before writing, warns if existing config is found and asks for confirmation.
+
+### pluidr doctor
+
+Checks installation health and reports PASS/FAIL for each component:
+
+- opencode.jsonc exists
+- All 13 prompt files exist
+- Both plugin files exist
+- package.json with @opencode-ai/plugin dependency
+- squeeze binary is available
+- Config is valid JSON
+
+Prints a summary table with ✓/✗ status. Exits with code 0 if all pass, 1 if any fail.
 
 ## Bundled plugins
 
-Pluidr ships with one plugin: [`parent-session`](src/plugins/README.md), which gives subagents three tools for cross-session context access:
+Pluidr ships with two plugins:
+
+**`pluidr-flow`** — provides subagents with three tools for cross-session context access:
 
 - `parent_session_messages` — read the parent session's transcript
 - `session_messages(sessionId)` — read any session by ID
 - `session_messages_batch(sessionIds)` — read multiple sessions in one call
 
-`pluidr init` installs the plugin and its dependency declaration automatically — no extra user action. On OpenCode's first launch, the bundled Bun runtime installs `@opencode-ai/plugin` from the generated `package.json`, then the plugin's tools become available to all subagents.
+**`pluidr-squeeze`** — hooks into tool execution to rewrite bash commands through the `squeeze` binary, filtering verbose output and saving 60-90% of tokens across all agents.
+
+`pluidr init` installs both plugins and their dependency declaration automatically — no extra user action. `pluidr-squeeze` also downloads the engine to `~/.config/opencode/bin/`. On OpenCode's first launch, the bundled Bun runtime installs `@opencode-ai/plugin` from the generated `package.json`, then both plugins become available to all agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluidr",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Opinionated Engineering Workflow for OpenCode — Plan, Build, Review.",
   "keywords": [
     "opencode",
@@ -16,6 +16,9 @@
   ],
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
   "bin": {
     "pluidr": "bin/pluidr.js"
   },

package/src/cli/commands/doctor.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+import { execFileSync } from "node:child_process"
+import { getConfigDir, getConfigPath, getPromptsDir } from "../../core/paths.js"
+import { findRtkPath } from "../../core/squeezeInstaller.js"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const EXPECTED_PROMPT_COUNT = 13
+const PLUGIN_FILES = ["pluidr-flow.js", "pluidr-squeeze.js"]
+
+export async function runDoctor() {
+  const configDir = getConfigDir()
+  const configPath = getConfigPath()
+  const promptsDir = getPromptsDir()
+  const pluginsDir = join(configDir, "plugins")
+  const packageJsonPath = join(configDir, "package.json")
+  const binDir = join(configDir, "bin")
+
+  const checks = []
+
+  // 1. opencode.jsonc exists
+  const configExists = existsSync(configPath)
+  checks.push({ component: "opencode.jsonc", pass: configExists })
+
+  // 2. All 13 prompt files exist
+  let promptCount = 0
+  if (existsSync(promptsDir)) {
+    try {
+      const files = readdirSync(promptsDir).filter((f) => f.endsWith(".txt"))
+      promptCount = files.length
+    } catch {
+      promptCount = 0
+    }
+  }
+  checks.push({ component: "13 prompt files", pass: promptCount === EXPECTED_PROMPT_COUNT, detail: `${promptCount}/${EXPECTED_PROMPT_COUNT}` })
+
+  // 3. Both plugin files exist
+  let pluginsFound = 0
+  for (const f of PLUGIN_FILES) {
+    if (existsSync(join(pluginsDir, f))) pluginsFound++
+  }
+  checks.push({ component: "plugin files", pass: pluginsFound === PLUGIN_FILES.length, detail: `${pluginsFound}/${PLUGIN_FILES.length}` })
+
+  // 4. package.json with @opencode-ai/plugin dependency
+  let pkgValid = false
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"))
+      pkgValid = !!(pkg.dependencies && pkg.dependencies["@opencode-ai/plugin"])
+    } catch {
+      pkgValid = false
+    }
+  }
+  checks.push({ component: "package.json + plugin dep", pass: pkgValid })
+
+  // 5. RTK binary exists
+  let rtkFound = false
+  const rtkOnPath = findRtkPath()
+  if (rtkOnPath) {
+    rtkFound = true
+  } else {
+    const binName = process.platform === "win32" ? "rtk.exe" : "rtk"
+    rtkFound = existsSync(join(binDir, binName))
+  }
+  checks.push({ component: "squeeze binary", pass: rtkFound })
+
+  // 6. Config is valid JSON/JSONC
+  let configValid = false
+  if (configExists) {
+    try {
+      const content = readFileSync(configPath, "utf-8")
+      const cleaned = content.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, g) => g ? "" : m)
+      JSON.parse(cleaned)
+      configValid = true
+    } catch {
+      configValid = false
+    }
+  }
+  checks.push({ component: "config JSON validity", pass: configValid })
+
+  // Print summary table
+  const allPass = checks.every((c) => c.pass)
+  console.log("\nPluidr Doctor — Installation Health Check\n")
+  for (const c of checks) {
+    const icon = c.pass ? "\u2713" : "\u2717"
+    const detail = c.detail ? ` (${c.detail})` : ""
+    console.log(`  ${icon} ${c.component}${detail}`)
+  }
+  console.log("")
+
+  if (allPass) {
+    console.log("All checks passed.")
+  } else {
+    console.log("Some checks failed. Re-run `pluidr init` to repair.")
+  }
+
+  process.exit(allPass ? 0 : 1)
+}

package/src/cli/commands/init.js

@@ -1,29 +1,32 @@
 import { readFileSync } from "node:fs"
 import { resolve, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
+import { confirm, isCancel } from "@clack/prompts"
 import { selectModelTier } from "../wizard/selectModelTier.js"
 import { backupExistingConfig } from "../../core/backup.js"
 import { buildConfig } from "../../core/configBuilder.js"
 import { writeConfig } from "../../core/configWriter.js"
 import { writeAgentPrompts } from "../../core/agentPromptWriter.js"
 import { writePluginBundle, writePluginPackageJson } from "../../core/pluginWriter.js"
+import { installSqueeze } from "../../core/squeezeInstaller.js"
 import { getConfigPath } from "../../core/paths.js"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const TEMPLATES_DIR = resolve(__dirname, "../../templates")
 
-function makeFileHyperlink(absolutePath, displayText) {
-  const normalized = absolutePath.replace(/\\/g, "/").replace(/^\//, "")
-  const fileUrl = `file:///${normalized}`
-  return `\x1b]8;;${fileUrl}\x1b\\${displayText}\x1b]8;;\x1b\\`
-}
-
 export async function runInit() {
   const defaultsPath = resolve(TEMPLATES_DIR, "model-defaults.json")
   const modelDefaults = JSON.parse(readFileSync(defaultsPath, "utf-8"))
 
   const tierChoices = await selectModelTier(modelDefaults)
 
+  const squeezeAnswer = await confirm({
+    message: "Install pluidr-squeeze plugin? Reduces bash output tokens by 60-90%.",
+    initialValue: true,
+  })
+
+  const installSqueezePlugin = isCancel(squeezeAnswer) ? true : squeezeAnswer
+
   backupExistingConfig()
 
   const configObject = buildConfig(tierChoices, TEMPLATES_DIR)
@@ -31,6 +34,10 @@ export async function runInit() {
   writeAgentPrompts(TEMPLATES_DIR)
   writePluginBundle()
   writePluginPackageJson()
+  if (installSqueezePlugin) {
+    await installSqueeze()
+  }
 
-  console.log(`Pluidr setup complete!\nYou can update your agent model settings later in ${makeFileHyperlink(getConfigPath(), "opencode.jsonc")}`)
+  const path = getConfigPath().replace(/\\/g, "/").replace(/^\//, "")
+  console.log(`Pluidr setup complete!\nYou can update your agent model settings later in \x1b]8;;file:///${path}\x1b\\opencode.jsonc\x1b]8;;\x1b\\`)
 }

package/src/cli/commands/uninstall.js

@@ -0,0 +1,67 @@
+import { existsSync, copyFileSync, rmSync, readdirSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { getConfigDir, getConfigPath } from "../../core/paths.js"
+
+function findLatestBackup() {
+  const dir = getConfigDir()
+  let backups = []
+  try {
+    backups = readdirSync(dir)
+      .filter((f) => f.startsWith("opencode.jsonc.bak."))
+      .sort()
+      .reverse()
+  } catch {
+    return null
+  }
+  return backups.length > 0 ? join(dir, backups[0]) : null
+}
+
+export async function runUninstall() {
+  const configDir = getConfigDir()
+  const configPath = getConfigPath()
+  const promptsDir = join(configDir, "prompts")
+  const pluginsDir = join(configDir, "plugins")
+  const binDir = join(configDir, "bin")
+
+  const summary = { restored: null, removed: [] }
+
+  // Restore latest backup
+  const latestBackup = findLatestBackup()
+  if (latestBackup && existsSync(configPath)) {
+    copyFileSync(latestBackup, configPath)
+    summary.restored = latestBackup
+  } else if (latestBackup) {
+    // Config doesn't exist but backup does — restore anyway
+    copyFileSync(latestBackup, configPath)
+    summary.restored = latestBackup
+  }
+
+  // Remove Pluidr-installed artifacts
+  if (existsSync(promptsDir)) {
+    rmSync(promptsDir, { recursive: true, force: true })
+    summary.removed.push("prompts/")
+  }
+  if (existsSync(pluginsDir)) {
+    rmSync(pluginsDir, { recursive: true, force: true })
+    summary.removed.push("plugins/")
+  }
+  if (existsSync(binDir)) {
+    rmSync(binDir, { recursive: true, force: true })
+    summary.removed.push("bin/")
+  }
+
+  // Print summary
+  console.log("Uninstall complete:")
+  if (summary.restored) {
+    console.log(`  ✓ Restored ${summary.restored}`)
+  } else {
+    console.log("  - No backup found to restore")
+  }
+  if (summary.removed.length > 0) {
+    console.log(`  ✓ Removed: ${summary.removed.join(", ")}`)
+  } else {
+    console.log("  - No Pluidr artifacts found to remove")
+  }
+  console.log("  - Kept opencode.jsonc (preserves user customizations)")
+  console.log("  - Kept package.json (may be used by other plugins)")
+}

package/src/cli/commands/update.js

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs"
+import { confirm, isCancel } from "@clack/prompts"
+import { getConfigPath } from "../../core/paths.js"
+import { runInit } from "./init.js"
+
+export async function runUpdate() {
+  const configPath = getConfigPath()
+
+  if (existsSync(configPath)) {
+    const answer = await confirm({
+      message: "Existing Pluidr config found. Overwrite? (Y/n)",
+      initialValue: true,
+    })
+
+    if (isCancel(answer) || !answer) {
+      console.log("Update cancelled.")
+      return
+    }
+  }
+
+  await runInit()
+}

package/src/cli/index.js

@@ -1,12 +1,53 @@
+import { readFileSync } from "node:fs"
+import { resolve, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
 import { runInit } from "./commands/init.js"
+import { runUninstall } from "./commands/uninstall.js"
+import { runUpdate } from "./commands/update.js"
+import { runDoctor } from "./commands/doctor.js"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkg = JSON.parse(readFileSync(resolve(__dirname, "../../package.json"), "utf-8"))
+
+const HELP = `Usage: pluidr <command>
+
+Commands:
+  init          Set up OpenCode with Pluidr's 12-agent pipeline
+  uninstall     Remove Pluidr artifacts and restore previous config
+  update        Re-run setup (overwrites current config)
+  doctor        Verify installation health
+  --version, -v  Print version number
+  --help, -h     Show this help message`
 
 export function run(argv) {
   const cmd = argv[2]
 
+  if (cmd === "--help" || cmd === "-h") {
+    console.log(HELP)
+    return
+  }
+
+  if (cmd === "--version" || cmd === "-v") {
+    console.log(pkg.version)
+    return
+  }
+
   if (cmd === "init") {
     return runInit()
   }
 
-  console.log("Usage: pluidr init")
+  if (cmd === "uninstall") {
+    return runUninstall()
+  }
+
+  if (cmd === "update") {
+    return runUpdate()
+  }
+
+  if (cmd === "doctor") {
+    return runDoctor()
+  }
+
+  console.log(HELP)
   process.exit(1)
 }

package/src/cli/wizard/selectModelTier.js

@@ -7,42 +7,33 @@ const TIER_LABELS = {
 
 export async function selectModelTier(modelDefaults) {
   const choices = {}
-
   for (const [tierKey, tierInfo] of Object.entries(modelDefaults)) {
     const defaultModel = `${tierInfo.provider}/${tierInfo.model}`
     const label = TIER_LABELS[tierKey] ?? tierKey
 
-    let selectedModel = defaultModel
-
-    try {
-      const answer = await select({
-        message: label,
-        options: [
-          { value: defaultModel, label: `default (${defaultModel})` },
-          { value: "__custom__", label: "custom  (provider/model)" },
-        ],
-      })
-
-      if (isCancel(answer)) {
-        selectedModel = defaultModel
-      } else if (answer === "__custom__") {
-        try {
-          const customModel = await text({
-            message: "Enter model:",
-          })
-          selectedModel = isCancel(customModel) ? defaultModel : (customModel || defaultModel)
-        } catch {
-          selectedModel = defaultModel
-        }
-      } else {
-        selectedModel = answer
-      }
-    } catch {
-      selectedModel = defaultModel
+    const recommendedOptions = (tierInfo.recommended || []).map((r) => ({
+      value: r.value,
+      label: r.label,
+    }))
+
+    const options = [
+      ...recommendedOptions,
+      { value: "__custom__", label: "custom  (enter provider/model)" },
+    ]
+
+    const answer = await select({
+      message: label,
+      options,
+    })
+
+    if (isCancel(answer)) {
+      choices[tierKey] = defaultModel
+    } else if (answer === "__custom__") {
+      const customModel = await text({ message: "Enter model:" })
+      choices[tierKey] = isCancel(customModel) ? defaultModel : (customModel || defaultModel)
+    } else {
+      choices[tierKey] = answer
     }
-
-    choices[tierKey] = selectedModel
   }
-
   return choices
 }

package/src/core/agentPromptWriter.js

@@ -8,9 +8,9 @@ import IDENTITY_HEADER from "./identityHeader.js"
 // copied verbatim — no agent-identity header.
 const REFERENCE_FILES = new Set(["hierarchy"])
 
-export function writeAgentPrompts(templatesDir) {
+export function writeAgentPrompts(templatesDir, destDir) {
   const sourceDir = resolve(templatesDir, "agent-prompts")
-  const destDir = getPromptsDir()
+  if (!destDir) destDir = getPromptsDir()
 
   mkdirSync(destDir, { recursive: true })