pluidr 0.3.0 → 0.4.0

package/README.md

@@ -1,5 +1,9 @@
 # Pluidr
 
+[![npm version](https://img.shields.io/npm/v/pluidr)](https://www.npmjs.com/package/pluidr)
+[![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).
 
 ## How it works
@@ -10,7 +14,7 @@ Pluidr sets up a **14-agent** pipeline in OpenCode organized under **4 primary a
 
 **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.
 
-**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 before asking you to confirm. Planner never edits files directly.
+**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.
 
 **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.
 
@@ -65,7 +69,8 @@ Each subagent belongs to exactly one primary agent and cannot be invoked by anyo
 | **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) |
-| **Loop limit** | 3 consecutive FAILs from Tester or Reviewer → Builder surfaces to you |
+| **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 |
 
@@ -110,3 +115,22 @@ Prompts you to select models for two agent tiers, then:
 - 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)
+
+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.
+
+## Bundled plugins
+
+Pluidr ships with one plugin: [`parent-session`](src/plugins/README.md), which gives subagents 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.

package/package.json

@@ -1,11 +1,32 @@
 {
   "name": "pluidr",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Opinionated Engineering Workflow for OpenCode — Plan, Build, Review.",
+  "keywords": [
+    "opencode",
+    "workflow",
+    "engineering",
+    "pipeline",
+    "ai-agents",
+    "code-review",
+    "debugging",
+    "planner",
+    "builder",
+    "cli"
+  ],
+  "license": "MIT",
   "type": "module",
   "bin": {
     "pluidr": "bin/pluidr.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funara/pluidr.git"
+  },
+  "homepage": "https://github.com/funara/pluidr#readme",
+  "bugs": {
+    "url": "https://github.com/funara/pluidr/issues"
+  },
   "engines": {
     "node": ">=18"
   },

package/src/cli/commands/init.js

@@ -6,11 +6,18 @@ 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 { getConfigPath, getPromptsDir } from "../../core/paths.js"
+import { writePluginBundle, writePluginPackageJson } from "../../core/pluginWriter.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"))
@@ -22,8 +29,8 @@ export async function runInit() {
   const configObject = buildConfig(tierChoices, TEMPLATES_DIR)
   writeConfig(configObject)
   writeAgentPrompts(TEMPLATES_DIR)
+  writePluginBundle()
+  writePluginPackageJson()
 
-  console.log("\nPluidr init complete!")
-  console.log(`  Config  : ${getConfigPath()}`)
-  console.log(`  Prompts : ${getPromptsDir()}`)
+  console.log(`Pluidr setup complete!\nYou can update your agent model settings later in ${makeFileHyperlink(getConfigPath(), "opencode.jsonc")}`)
 }

package/src/core/agentPromptWriter.js

@@ -1,6 +1,12 @@
-import { mkdirSync, readdirSync, copyFileSync } from "node:fs"
-import { resolve } from "node:path"
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { basename, extname, resolve } from "node:path"
 import { getPromptsDir } from "./paths.js"
+import IDENTITY_HEADER from "./identityHeader.js"
+
+// hierarchy.txt is a global reference document (referenced from
+// opencode.config.json's `instructions`), not an agent prompt. It must be
+// copied verbatim — no agent-identity header.
+const REFERENCE_FILES = new Set(["hierarchy"])
 
 export function writeAgentPrompts(templatesDir) {
   const sourceDir = resolve(templatesDir, "agent-prompts")
@@ -9,6 +15,18 @@ export function writeAgentPrompts(templatesDir) {
   mkdirSync(destDir, { recursive: true })
 
   for (const file of readdirSync(sourceDir)) {
-    copyFileSync(resolve(sourceDir, file), resolve(destDir, file))
+    if (extname(file) !== ".txt") continue
+
+    const sourcePath = resolve(sourceDir, file)
+    const destPath = resolve(destDir, file)
+    const content = readFileSync(sourcePath, "utf-8")
+
+    const agentName = basename(file, ".txt")
+    if (REFERENCE_FILES.has(agentName)) {
+      writeFileSync(destPath, content, "utf-8")
+      continue
+    }
+
+    writeFileSync(destPath, IDENTITY_HEADER(agentName) + content, "utf-8")
   }
 }

package/src/core/identityHeader.js

@@ -0,0 +1,8 @@
+// Single source of truth for the agent identity prefix prepended to every
+// generated prompt file. Mirrors the system identity concept from the
+// dropped hook-based AgentSelfIdentityPlugin, but as a static prepend
+// (KISS: agent names are known at install time).
+
+export default function IDENTITY_HEADER(agentName) {
+  return `You are the "${agentName}" agent.\n\n`
+}

package/src/core/pluginWriter.js

@@ -0,0 +1,25 @@
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { getConfigDir } from "./paths.js"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PLUGIN_NAME = "parent-session.js"
+const PACKAGE_JSON = {
+  dependencies: { "@opencode-ai/plugin": "^1.17.9" },
+}
+
+export function writePluginBundle() {
+  const pluginsDir = join(getConfigDir(), "plugins")
+  mkdirSync(pluginsDir, { recursive: true })
+
+  const sourcePath = resolve(__dirname, "../plugins", PLUGIN_NAME)
+  copyFileSync(sourcePath, join(pluginsDir, PLUGIN_NAME))
+}
+
+export function writePluginPackageJson() {
+  const packageJsonPath = join(getConfigDir(), "package.json")
+  if (existsSync(packageJsonPath)) return
+
+  writeFileSync(packageJsonPath, JSON.stringify(PACKAGE_JSON, null, 2), "utf-8")
+}

package/src/plugins/README.md

@@ -0,0 +1,54 @@
+# 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 out of the box.
+
+## What is `parent-session.js`?
+
+It is the implementation of the `ParentSessionPlugin`, registered by
+OpenCode at startup. It exposes three tools that subagents use to read
+the conversation history of 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`.
+
+## Why `parent-session` 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 14 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 it is loaded
+
+`pluidr init` copies `parent-session.js` into
+`~/.config/opencode/plugins/` and writes a `package.json` next to it
+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,
+the plugin's three tools are available to every agent that has the
+appropriate permissions.

package/src/plugins/parent-session.js

@@ -0,0 +1,142 @@
+// Parent-session plugin: provides tools for cross-session context access in
+// subagent workflows. Translated from the original TypeScript implementation
+// in addition/opencode-session-context/src/parent-session.ts to plain ESM JS
+// (no build step required). Behavior, formatting, and tool names are unchanged.
+
+import { tool } from "@opencode-ai/plugin"
+
+function formatInput(input) {
+  if (
+    input == null ||
+    (typeof input === "object" &&
+      !Array.isArray(input) &&
+      Object.keys(input).length === 0)
+  ) {
+    return ""
+  }
+  return `\n    input: ${JSON.stringify(input)}`
+}
+
+function formatTool(part) {
+  const state = part.state
+  const status = state.status
+  const title = state.title ?? part.tool
+  const input = formatInput(state.input)
+  if (status === "error") {
+    return `  [tool] ${title} → error: ${state.error}${input}`
+  }
+  return `  [tool] ${title} → ${status}${input}`
+}
+
+function formatParts(parts) {
+  const lines = []
+  for (const part of parts) {
+    if (part.type === "text") {
+      lines.push(part.text)
+    } else if (part.type === "tool") {
+      lines.push(formatTool(part))
+    }
+  }
+  return lines.join("\n")
+}
+
+function formatModel(info) {
+  const base = `${info.providerID}/${info.modelID}`
+  return info.variant ? `${base} (${info.variant})` : base
+}
+
+function formatMessage(msg, index) {
+  const num = index + 1
+  if (msg.info.role === "assistant") {
+    const info = msg.info
+    const agent = info.agent ?? "unknown"
+    const header = `${num}. assistant (${agent}) [${formatModel(info)}]`
+    return `${header}\n${formatParts(msg.parts)}`
+  }
+  return `${num}. ${msg.info.role}\n${formatParts(msg.parts)}`
+}
+
+export const ParentSessionPlugin = async ({ client }) => {
+  async function formatSessionMessages(sessionID, emptyMessage) {
+    const response = await client.session.messages({
+      path: { id: sessionID },
+    })
+    const messages = response.data ?? []
+    if (messages.length === 0) {
+      return emptyMessage
+    }
+
+    return messages.map(formatMessage).join("\n\n---\n\n")
+  }
+
+  async function formatSessionMessagesBatch(sessionIDs) {
+    const sections = await Promise.all(
+      sessionIDs.map(async (sessionID) => {
+        const emptyMessage = "(No messages found or session not accessible)"
+
+        try {
+          const output = await formatSessionMessages(sessionID, emptyMessage)
+          return `=== Session: ${sessionID} ===\n${output}`
+        } catch {
+          return `=== Session: ${sessionID} ===\n${emptyMessage}`
+        }
+      }),
+    )
+
+    return sections.join("\n\n")
+  }
+
+  return {
+    tool: {
+      parent_session_messages: tool({
+        description:
+          "Fetch all messages from the parent session. " +
+          "Returns the full conversation with agent attribution " +
+          "and message content. Only works from subagent sessions " +
+          "(sessions with a parentID).",
+        args: {},
+        async execute(_args, context) {
+          const session = await client.session.get({
+            path: { id: context.sessionID },
+          })
+          const parent = session.data?.parentID
+          if (!parent) {
+            return `Error: Session ${context.sessionID} has no parent. This tool only works from subagent sessions.`
+          }
+
+          return formatSessionMessages(
+            parent,
+            `Session ${parent} has no messages.`,
+          )
+        },
+      }),
+      session_messages: tool({
+        description:
+          "Fetch all messages from a session by ID. " +
+          "Returns the full conversation with agent attribution " +
+          "and message content.",
+        args: {
+          sessionId: tool.schema.string().describe("The session ID to read"),
+        },
+        async execute(args) {
+          return formatSessionMessages(
+            args.sessionId,
+            `Session ${args.sessionId} has no messages.`,
+          )
+        },
+      }),
+      session_messages_batch: tool({
+        description:
+          "Fetch all messages from multiple sessions by ID. Returns the full conversations concatenated with session delimiters. Useful for reading multiple related sessions (e.g., TDD phase sessions from a dispatch log) in a single tool call.",
+        args: {
+          sessionIds: tool.schema
+            .array(tool.schema.string())
+            .describe("Array of session IDs to fetch messages from."),
+        },
+        async execute(args) {
+          return formatSessionMessagesBatch(args.sessionIds)
+        },
+      }),
+    },
+  }
+}

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

@@ -25,19 +25,33 @@ edit code or files — this is a hard constraint, not a guideline.
      of the plan-writer's PRD output — Planner does not write or edit the
      file directly. Then present the PRD to the user, ask for confirmation
      to proceed to Builder.
-   - FAIL → determine what the gap requires:
-     * If the gap needs new research (missing information, unverified
-       assumption) → delegate to researcher with the gap list first, then
-       delegate to plan-writer (PRD mode) with the updated input, then loop back
-       to step 5 (plan-checker).
-     * If the gap is a decision only the user can make → surface it to the
-       user, do not guess.
-     * Never delegate directly to plan-writer on a FAIL — plan-writer fills in the
-       updated content, it does not decide what the content should be.
-     * After 3 consecutive FAIL verdicts from plan-checker on the same PRD,
-       surface the accumulated gap list to the user with a summary of what
-       has been tried, and ask the user for direction rather than continuing
-       to loop. A PASS from plan-checker resets the counter.
+   - FAIL → Surface gap list to user with remedy options:
+     * The Planner does NOT decide the gap remedies — the user does.
+     * The Planner DOES decide the delegation route (researcher vs.
+       plan-writer) — that is a process decision, not a domain decision.
+     * On plan-checker FAIL, the Planner MUST surface the gap list to the
+       user with gap-remedy options using the question tool. This is the
+       ONLY permitted mechanism for gathering user input on gaps. The
+       Planner MUST NOT invent remedies, assume the user's choice, or use
+       silent interpretation, auto-pick, or prose-only responses.
+     * Present each gap via the question tool with 2-4 multiple-choice
+       remedy options per gap. The question is GAP-RELATED (what remedy
+       should be applied), not ROUTE-RELATED (do not ask the user to pick
+       researcher vs. plan-writer).
+     * After the user submits their gap-remedy answers, the Planner
+       internally decides the delegation route:
+       - Knowledge/research gaps → delegate to researcher.
+       - Revision/content gaps → delegate to plan-writer (PRD mode).
+     * The Planner does NOT ask the user for the route choice.
+     * After delegation, loop back to step 5 (plan-checker).
+     * If plan-checker returns PASS → done, loop counter resets.
+     * If plan-checker returns FAIL again → increment loop counter by 1,
+       repeat from step 1 (surface gaps to user again).
+     * After 3 consecutive FAIL→user→delegate→plan-checker loops without
+       PASS, the Planner MUST surface the accumulated gap list with the
+       loop count to the user, and ask for direction (without auto-delegating
+       further). The user decides whether to continue, change approach, or
+       cancel.
 
 ## Delegation rules
 

package/src/templates/model-defaults.json

@@ -2,11 +2,11 @@
   "reasoningHeavy": {
     "provider": "opencode",
     "model": "big-pickle",
-    "agents": ["planner", "debugger", "explorer", "researcher", "plan-writer", "plan-checker", "inspector", "reporter"]
+    "agents": ["planner", "debugger", "explorer", "researcher", "plan-checker", "inspector", "builder"]
   },
   "fast": {
     "provider": "opencode",
     "model": "deepseek-v4-flash-free",
-    "agents": ["builder", "coder", "tester", "reviewer", "writer", "fixer"]
+    "agents": ["coder", "tester", "reviewer", "writer", "fixer", "plan-writer", "reporter"]
   }
 }