opencode-planpilot 0.1.2 → 0.2.1

package/README.md

@@ -1,31 +1,24 @@
 # opencode-planpilot
 
-Planpilot rewritten in TypeScript for OpenCode. Provides plan/step/goal workflow with auto-continue for AI steps and a native `planpilot` tool.
+Planpilot for OpenCode. Provides plan/step/goal workflow with auto-continue for AI steps and a native `planpilot` tool.
 
 ## Features
-- Plan/step/goal hierarchy with automatic status rollups
+- Plan/step/goal hierarchy with status auto-propagation upward (goals -> steps -> plan)
 - SQLite storage with markdown plan snapshots
-- Native OpenCode tool plus optional CLI
+- Native OpenCode tool for plan/step/goal operations
 - Auto-continue on `session.idle` when next step is assigned to `ai`
 
-## Requirements
-- Bun runtime (uses `bun:sqlite` at runtime)
-
 ## Install
 
 Add to `opencode.json`:
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
   "plugin": ["opencode-planpilot"]
 }
 ```
 
 OpenCode installs npm plugins automatically at startup.
 
-## Details
-Usage and storage info: `docs/planpilot.md`
-
 ## License
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-planpilot",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Planpilot plugin for OpenCode",
   "type": "module",
   "repository": {
@@ -14,18 +14,10 @@
   "packageManager": "bun@1.3.6",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
-  "bin": {
-    "planpilot": "src/cli.ts",
-    "opencode-planpilot": "src/cli.ts"
-  },
   "exports": {
     ".": {
       "import": "./src/index.ts",
       "types": "./src/index.ts"
-    },
-    "./cli": {
-      "import": "./src/cli.ts",
-      "types": "./src/cli.ts"
     }
   },
   "files": [
@@ -49,7 +41,7 @@
   },
   "devDependencies": {
     "@opencode-ai/plugin": "*",
-    "@types/node": "^25.0.8",
+    "@types/node": "^25.0.9",
     "bun-types": "^1.3.6",
     "eslint": "^9.39.2",
     "@eslint/js": "^9.39.2",

package/src/{cli.ts → command.ts}

@@ -1,4 +1,3 @@
-#!/usr/bin/env bun
 import fs from "fs"
 import { openDatabase, resolvePlanMarkdownPath, ensureParentDir } from "./lib/db"
 import { PlanpilotApp } from "./lib/app"
@@ -14,37 +13,31 @@ import {
 import { AppError, invalidInput } from "./lib/errors"
 import { ensureNonEmpty, projectMatchesPath, resolveMaybeRealpath } from "./lib/util"
 import { formatGoalDetail, formatPlanDetail, formatPlanMarkdown, formatStepDetail } from "./lib/format"
+import { PLANPILOT_HELP_TEXT } from "./prompt"
 
-const CWD_FLAG = "--cwd"
-const SESSION_ID_FLAG = "--session-id"
 const DEFAULT_PAGE = 1
 const DEFAULT_LIMIT = 20
 
-export type CliIO = {
+export type CommandIO = {
   log: (...args: any[]) => void
-  error: (...args: any[]) => void
 }
 
-const defaultIO: CliIO = {
-  log: (...args) => {
-    console.log(...args)
-  },
-  error: (...args) => {
-    console.error(...args)
-  },
+export type CommandContext = {
+  sessionId: string
+  cwd: string
 }
 
-let currentIO: CliIO = defaultIO
+const noopIO: CommandIO = {
+  log: () => {},
+}
+
+let currentIO: CommandIO = noopIO
 
 function log(...args: any[]) {
   currentIO.log(...args)
 }
 
-function error(...args: any[]) {
-  currentIO.error(...args)
-}
-
-async function withIO<T>(io: CliIO, fn: () => Promise<T> | T): Promise<T> {
+async function withIO<T>(io: CommandIO, fn: () => Promise<T> | T): Promise<T> {
   const prev = currentIO
   currentIO = io
   try {
@@ -54,7 +47,7 @@ async function withIO<T>(io: CliIO, fn: () => Promise<T> | T): Promise<T> {
   }
 }
 
-export function formatCliError(err: unknown): string {
+export function formatCommandError(err: unknown): string {
   if (err instanceof AppError) {
     return `Error: ${err.toDisplayString()}`
   }
@@ -64,28 +57,32 @@ export function formatCliError(err: unknown): string {
   return `Error: ${String(err)}`
 }
 
-export async function runCLI(argv: string[] = process.argv.slice(2), io: CliIO = defaultIO) {
+export async function runCommand(argv: string[], context: CommandContext, io: CommandIO = noopIO) {
   return withIO(io, async () => {
-    const { cwd, cwdFlagPresent, sessionId, remaining } = parseGlobalArgs(argv)
-
-    if (!remaining.length) {
-      throw invalidInput("missing command")
+    if (!argv.length) {
+      throw invalidInput("missing argv")
     }
 
-    const [section, subcommand, ...args] = remaining
-
-  const resolvedSessionId = resolveSessionId(sessionId)
+    const [section, subcommand, ...args] = argv
 
     const db = openDatabase()
-    const resolvedCwd = cwd ? resolveMaybeRealpath(cwd) : undefined
-    const app = new PlanpilotApp(db, resolvedSessionId, resolvedCwd)
+    const resolvedCwd = resolveMaybeRealpath(context.cwd)
+    const app = new PlanpilotApp(db, context.sessionId, resolvedCwd)
 
     let planIds: number[] = []
     let shouldSync = false
 
     switch (section) {
+      case "help": {
+        if (subcommand !== undefined || args.length) {
+          const rest = [subcommand, ...args].filter((x) => x !== undefined)
+          throw invalidInput(`help unexpected argument: ${rest.join(" ")}`)
+        }
+        log(PLANPILOT_HELP_TEXT)
+        return
+      }
       case "plan": {
-        const result = await handlePlan(app, subcommand, args, { cwd, cwdFlagPresent })
+        const result = await handlePlan(app, subcommand, args, { cwd: context.cwd })
         planIds = result.planIds
         shouldSync = result.shouldSync
         break
@@ -112,57 +109,20 @@ export async function runCLI(argv: string[] = process.argv.slice(2), io: CliIO =
   })
 }
 
-function parseGlobalArgs(argv: string[]) {
-  let cwd: string | undefined
-  let sessionId: string | undefined
-  let cwdFlagPresent = false
-  const remaining: string[] = []
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const token = argv[i]
-    if (token === CWD_FLAG) {
-      cwdFlagPresent = true
-      cwd = argv[i + 1]
-      i += 1
-      continue
-    }
-    if (token === SESSION_ID_FLAG) {
-      sessionId = argv[i + 1]
-      i += 1
-      continue
-    }
-    remaining.push(token)
-  }
-
-  return { cwd, cwdFlagPresent, sessionId, remaining }
-}
-
-function resolveSessionId(sessionId: string | undefined): string {
-  if (!sessionId) {
-    throw invalidInput(`${SESSION_ID_FLAG} is required`)
-  }
-  const trimmed = sessionId.trim()
-  if (!trimmed) {
-    throw invalidInput(`${SESSION_ID_FLAG} is empty`)
-  }
-  return trimmed
-}
-
-function requireCwd(cwdFlagPresent: boolean, cwd: string | undefined): string {
-  if (!cwdFlagPresent) {
-    throw invalidInput(`${CWD_FLAG} is required`)
-  }
+function requireCwd(cwd: string | undefined): string {
   if (!cwd || !cwd.trim()) {
-    throw invalidInput(`${CWD_FLAG} is empty`)
+    throw invalidInput("cwd is required")
   }
   return cwd
 }
 
+export type { CommandContext as PlanpilotCommandContext, CommandIO as PlanpilotCommandIO }
+
 async function handlePlan(
   app: PlanpilotApp,
   subcommand: string | undefined,
   args: string[],
-  context: { cwd: string | undefined; cwdFlagPresent: boolean },
+  context: { cwd: string | undefined },
 ) {
   switch (subcommand) {
     case "add":
@@ -212,6 +172,8 @@ async function handleStep(app: PlanpilotApp, subcommand: string | undefined, arg
       return { planIds: handleStepShow(app, args), shouldSync: false }
     case "show-next":
       return { planIds: handleStepShowNext(app), shouldSync: false }
+    case "wait":
+      return { planIds: handleStepWait(app, args), shouldSync: true }
     case "comment":
       return { planIds: handleStepComment(app, args), shouldSync: true }
     case "update":
@@ -281,13 +243,18 @@ function handlePlanAddTree(app: PlanpilotApp, args: string[]): number[] {
   log(`Created plan ID: ${result.plan.id}: ${result.plan.title} (steps: ${result.stepCount}, goals: ${result.goalCount})`)
   app.setActivePlan(result.plan.id, false)
   log(`Active plan set to ${result.plan.id}: ${result.plan.title}`)
+
+  // Print full detail so the AI can reference plan/step/goal IDs immediately.
+  const detail = app.getPlanDetail(result.plan.id)
+  log("")
+  log(formatPlanDetail(detail.plan, detail.steps, detail.goals))
   return [result.plan.id]
 }
 
 function handlePlanList(
   app: PlanpilotApp,
   args: string[],
-  context: { cwd: string | undefined; cwdFlagPresent: boolean },
+  context: { cwd: string | undefined },
 ): number[] {
   const { options, positionals } = parseOptions(args)
   if (positionals.length) {
@@ -304,7 +271,7 @@ function handlePlanList(
   }
 
   const desiredStatus: PlanStatus | null = parsePlanStatusFilter(options.status)
-  const cwd = requireCwd(context.cwdFlagPresent, context.cwd)
+  const cwd = requireCwd(context.cwd)
 
   const order = options.order ? parsePlanOrder(options.order) : "updated"
   const desc = options.desc ?? true
@@ -346,7 +313,7 @@ function handlePlanList(
 function handlePlanCount(
   app: PlanpilotApp,
   args: string[],
-  context: { cwd: string | undefined; cwdFlagPresent: boolean },
+  context: { cwd: string | undefined },
 ): number[] {
   const { options, positionals } = parseOptions(args)
   if (positionals.length) {
@@ -363,7 +330,7 @@ function handlePlanCount(
   }
 
   const desiredStatus: PlanStatus | null = parsePlanStatusFilter(options.status)
-  const cwd = requireCwd(context.cwdFlagPresent, context.cwd)
+  const cwd = requireCwd(context.cwd)
 
   let plans = app.listPlans()
   if (!plans.length) {
@@ -383,7 +350,7 @@ function handlePlanCount(
 function handlePlanSearch(
   app: PlanpilotApp,
   args: string[],
-  context: { cwd: string | undefined; cwdFlagPresent: boolean },
+  context: { cwd: string | undefined },
 ): number[] {
   const { options, positionals } = parseOptions(args)
   if (positionals.length) {
@@ -393,7 +360,7 @@ function handlePlanSearch(
     throw invalidInput("plan search requires at least one --search")
   }
   const desiredStatus: PlanStatus | null = parsePlanStatusFilter(options.status)
-  const cwd = requireCwd(context.cwdFlagPresent, context.cwd)
+  const cwd = requireCwd(context.cwd)
 
   const order = options.order ? parsePlanOrder(options.order) : "updated"
   const desc = options.desc ?? true
@@ -700,6 +667,30 @@ function handleStepShowNext(app: PlanpilotApp): number[] {
   return []
 }
 
+function handleStepWait(app: PlanpilotApp, args: string[]): number[] {
+  if (!args.length) {
+    throw invalidInput("step wait requires <id>")
+  }
+  const stepId = parseNumber(args[0], "step id")
+  const options = parseOptions(args.slice(1)).options
+  if (options.clear) {
+    const result = app.clearStepWait(stepId)
+    log(`Step ID: ${result.step.id} wait cleared.`)
+    return [result.step.plan_id]
+  }
+  if (options.delay === undefined) {
+    throw invalidInput("step wait requires --delay <ms> or --clear")
+  }
+  const delayMs = parseNumber(options.delay, "delay")
+  if (delayMs < 0) {
+    throw invalidInput("delay must be >= 0")
+  }
+  const reason = options.reason ? String(options.reason) : undefined
+  const result = app.setStepWait(stepId, delayMs, reason)
+  log(`Step ID: ${result.step.id} waiting until ${result.until}.`)
+  return [result.step.plan_id]
+}
+
 function handleStepUpdate(app: PlanpilotApp, args: string[]): number[] {
   if (!args.length) {
     throw invalidInput("step update requires <id>")
@@ -1034,18 +1025,31 @@ function parseOptions(args: string[]) {
         options.order = expectValue(args, i, token)
         i += 2
         break
-      case "--to":
-        options.to = expectValue(args, i, token)
-        i += 2
-        break
-      case "--goal":
-        if (!options.goals) options.goals = []
-        options.goals.push(expectValue(args, i, token))
-        i += 2
-        break
-      default:
-        throw invalidInput(`unexpected argument: ${token}`)
-    }
+    case "--to":
+      options.to = expectValue(args, i, token)
+      i += 2
+      break
+    case "--delay":
+      options.delay = expectValue(args, i, token)
+      i += 2
+      break
+    case "--reason":
+      options.reason = expectValue(args, i, token)
+      i += 2
+      break
+    case "--clear":
+      options.clear = true
+      i += 1
+      break
+    case "--goal":
+      if (!options.goals) options.goals = []
+      options.goals.push(expectValue(args, i, token))
+      i += 2
+      break
+    default:
+      throw invalidInput(`unexpected argument: ${token}`)
+  }
+
   }
   return { options, positionals }
 }
@@ -1474,10 +1478,3 @@ function syncPlanMarkdown(app: PlanpilotApp, planIds: number[]) {
     fs.writeFileSync(mdPath, markdown, "utf8")
   })
 }
-
-if (import.meta.main) {
-  runCLI(process.argv.slice(2), defaultIO).catch((err) => {
-    error(formatCliError(err))
-    process.exit(1)
-  })
-}

package/src/index.ts

@@ -1,23 +1,25 @@
 import { tool, type Plugin } from "@opencode-ai/plugin"
-import { runCLI, formatCliError } from "./cli"
+import { runCommand, formatCommandError } from "./command"
 import { PlanpilotApp } from "./lib/app"
-import { parseCommandArgs } from "./lib/argv"
 import { openDatabase } from "./lib/db"
 import { invalidInput } from "./lib/errors"
 import { formatStepDetail } from "./lib/format"
-import { loadPlanpilotInstructions } from "./lib/instructions"
+import { parseWaitFromComment } from "./lib/util"
+import { PLANPILOT_SYSTEM_INJECTION, PLANPILOT_TOOL_DESCRIPTION, formatPlanpilotAutoContinueMessage } from "./prompt"
 
 export const PlanpilotPlugin: Plugin = async (ctx) => {
   const inFlight = new Set<string>()
   const skipNextAuto = new Set<string>()
   const lastIdleAt = new Map<string, number>()
+  const waitTimers = new Map<string, ReturnType<typeof setTimeout>>()
 
-  const PLANPILOT_GUIDANCE = [
-    "Planpilot guidance:",
-    "- Do not read plan files from disk or follow plan file placeholders.",
-    "- Use the planpilot tool for plan/step/goal info (plan show-active, step show-next, goal list <step_id>).",
-    "- If you cannot continue or need human input, insert a new step with executor `human` before the next pending step using planpilot so auto-continue pauses.",
-  ].join("\n")
+  const clearWaitTimer = (sessionID: string) => {
+    const existing = waitTimers.get(sessionID)
+    if (existing) {
+      clearTimeout(existing)
+      waitTimers.delete(sessionID)
+    }
+  }
 
   const log = async (level: "debug" | "info" | "warn" | "error", message: string, extra?: Record<string, any>) => {
     try {
@@ -132,6 +134,32 @@ export const PlanpilotPlugin: Plugin = async (ctx) => {
       const next = app.nextStep(active.plan_id)
       if (!next) return
       if (next.executor !== "ai") return
+      const wait = parseWaitFromComment(next.comment)
+      if (wait && wait.until > now) {
+        clearWaitTimer(sessionID)
+        await log("info", "auto-continue delayed by step wait", {
+          sessionID,
+          stepId: next.id,
+          until: wait.until,
+          reason: wait.reason,
+        })
+        const msUntil = Math.max(0, wait.until - now)
+        const timer = setTimeout(() => {
+          waitTimers.delete(sessionID)
+          handleSessionIdle(sessionID).catch((err) => {
+            void log("warn", "auto-continue retry failed", {
+              sessionID,
+              error: err instanceof Error ? err.message : String(err),
+            })
+          })
+        }, msUntil)
+        waitTimers.set(sessionID, timer)
+        return
+      }
+      if (!wait) {
+        clearWaitTimer(sessionID)
+      }
+
       const goals = app.goalsForStep(next.id)
       const detail = formatStepDetail(next, goals)
       if (!detail.trim()) return
@@ -143,12 +171,11 @@ export const PlanpilotPlugin: Plugin = async (ctx) => {
       }
       if (autoContext?.aborted || autoContext?.ready === false) return
 
-      const message =
-        "Planpilot (auto):\n" +
-        "Before acting, think through the next step and its goals. Record implementation details using Planpilot comments (plan/step/goal --comment or comment commands). Continue with the next step (executor: ai). Do not ask for confirmation; proceed and report results.\n\n" +
-        PLANPILOT_GUIDANCE +
-        "\n\n" +
-        detail.trimEnd()
+      const timestamp = new Date().toISOString()
+      const message = formatPlanpilotAutoContinueMessage({
+        timestamp,
+        stepDetail: detail,
+      })
 
       const promptBody: any = {
         agent: autoContext?.agent ?? undefined,
@@ -171,76 +198,51 @@ export const PlanpilotPlugin: Plugin = async (ctx) => {
   }
 
   return {
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(PLANPILOT_SYSTEM_INJECTION)
+    },
     tool: {
       planpilot: tool({
-        description:
-          "Planpilot planner. Use for all plan/step/goal operations. Provide either argv (array) or command (string). " +
-          "Do not include --session-id/--cwd; they are injected automatically from the current session.",
+        description: PLANPILOT_TOOL_DESCRIPTION,
         args: {
-          argv: tool.schema.array(tool.schema.string()).optional(),
-          command: tool.schema.string().min(1),
+          argv: tool.schema.array(tool.schema.string()).min(1),
         },
         async execute(args, toolCtx) {
-          let argv: string[] = []
-          if (Array.isArray(args.argv) && args.argv.length) {
-            argv = args.argv
-          } else if (typeof args.command === "string" && args.command.trim()) {
-            argv = parseCommandArgs(args.command)
-          } else {
-            return formatCliError(invalidInput("missing command"))
-          }
-
-          const cwd = (ctx.directory ?? "").trim()
-          if (!cwd) {
-            return formatCliError(invalidInput(`${"--cwd"} is required`))
+          const argv = Array.isArray(args.argv) ? args.argv : []
+          if (!argv.length) {
+            return formatCommandError(invalidInput("missing argv"))
           }
 
           if (containsForbiddenFlags(argv)) {
-            return formatCliError(invalidInput("do not pass --cwd or --session-id"))
+            return formatCommandError(invalidInput("argv cannot include --cwd or --session-id"))
           }
 
-          const finalArgv = [...argv]
-          if (!finalArgv.includes("--cwd")) {
-            finalArgv.unshift("--cwd", cwd)
-          }
-          if (!finalArgv.includes("--session-id")) {
-            finalArgv.unshift("--session-id", toolCtx.sessionID)
+          const cwd = (ctx.directory ?? "").trim()
+          if (!cwd) {
+            return formatCommandError(invalidInput("cwd is required"))
           }
 
           const output: string[] = []
           const io = {
             log: (...parts: any[]) => output.push(parts.map(String).join(" ")),
-            error: (...parts: any[]) => output.push(parts.map(String).join(" ")),
           }
 
           try {
-            await runCLI(finalArgv, io)
+            await runCommand(argv, { sessionId: toolCtx.sessionID, cwd }, io)
           } catch (err) {
-            return formatCliError(err)
+            return formatCommandError(err)
           }
 
           return output.join("\n").trimEnd()
         },
       }),
     },
-    "experimental.chat.system.transform": async (_input, output) => {
-      const instructions = loadPlanpilotInstructions().trim()
-      const alreadyInjected = output.system.some((entry) => entry.includes("Planpilot (OpenCode Tool)"))
-      if (instructions && !alreadyInjected) {
-        output.system.push(instructions)
-      }
-      const guidanceInjected = output.system.some((entry) => entry.includes("Planpilot guidance:"))
-      if (!guidanceInjected) {
-        output.system.push(PLANPILOT_GUIDANCE)
-      }
-    },
     "experimental.session.compacting": async ({ sessionID }, output) => {
-      const hasGuidance = output.context.some((entry) => entry.includes("Planpilot guidance:"))
-      if (!hasGuidance) {
-        output.context.push(PLANPILOT_GUIDANCE)
-      }
       skipNextAuto.add(sessionID)
       lastIdleAt.set(sessionID, Date.now())
+
+      // Compaction runs with tools disabled; inject Planpilot guidance into the continuation summary.
+      output.context.push(PLANPILOT_TOOL_DESCRIPTION)
     },
     event: async ({ event }) => {
       if (event.type === "session.idle") {

package/src/lib/app.ts

@@ -22,7 +22,15 @@ import {
   type StepRow,
   type StepStatus,
 } from "./models"
-import { ensureNonEmpty, joinIds, normalizeCommentEntries, uniqueIds } from "./util"
+import {
+  ensureNonEmpty,
+  joinIds,
+  normalizeCommentEntries,
+  parseWaitFromComment,
+  removeWaitFromComment,
+  uniqueIds,
+  upsertWaitInComment,
+} from "./util"
 import { invalidInput, notFound } from "./errors"
 import { formatStepDetail } from "./format"
 
@@ -820,6 +828,44 @@ export class PlanpilotApp {
     return tx()
   }
 
+  setStepWait(stepId: number, delayMs: number, reason?: string): { step: StepRow; until: number } {
+    if (!Number.isFinite(delayMs) || delayMs < 0) {
+      throw invalidInput("delay must be a non-negative number")
+    }
+    const tx = this.db.transaction(() => {
+      const step = this.getStep(stepId)
+      const now = Date.now()
+      const until = now + Math.trunc(delayMs)
+      const comment = upsertWaitInComment(step.comment, until, reason)
+      this.db.prepare("UPDATE steps SET comment = ?, updated_at = ? WHERE id = ?").run(comment, now, stepId)
+      const updated = this.getStep(stepId)
+      this.touchPlan(updated.plan_id)
+      return { step: updated, until }
+    })
+
+    return tx()
+  }
+
+  clearStepWait(stepId: number): { step: StepRow } {
+    const tx = this.db.transaction(() => {
+      const step = this.getStep(stepId)
+      const comment = step.comment ? removeWaitFromComment(step.comment) : null
+      const now = Date.now()
+      this.db.prepare("UPDATE steps SET comment = ?, updated_at = ? WHERE id = ?").run(comment, now, stepId)
+      const updated = this.getStep(stepId)
+      this.touchPlan(updated.plan_id)
+      return { step: updated }
+    })
+
+    return tx()
+  }
+
+  getStepWait(stepId: number): { step: StepRow; wait: { until: number; reason?: string } | null } {
+    const step = this.getStep(stepId)
+    const wait = parseWaitFromComment(step.comment)
+    return { step, wait }
+  }
+
   commentGoals(entries: Array<[number, string]>): number[] {
     const normalized = normalizeCommentEntries(entries)
     if (!normalized.length) return []

package/src/lib/util.ts

@@ -49,6 +49,60 @@ export function normalizeCommentEntries(entries: Array<[number, string]>): Array
   return ordered
 }
 
+const WAIT_UNTIL_PREFIX = "@wait-until="
+const WAIT_REASON_PREFIX = "@wait-reason="
+
+export type WaitComment = {
+  until: number
+  reason?: string
+}
+
+export function parseWaitFromComment(comment?: string | null): WaitComment | null {
+  if (!comment) return null
+  let until: number | null = null
+  let reason: string | undefined
+  for (const line of comment.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith(WAIT_UNTIL_PREFIX)) {
+      const raw = trimmed.slice(WAIT_UNTIL_PREFIX.length).trim()
+      const value = Number(raw)
+      if (Number.isFinite(value)) {
+        until = value
+      }
+      continue
+    }
+    if (trimmed.startsWith(WAIT_REASON_PREFIX)) {
+      const raw = trimmed.slice(WAIT_REASON_PREFIX.length).trim()
+      if (raw) reason = raw
+    }
+  }
+  if (until === null) return null
+  return { until, reason }
+}
+
+function isWaitLine(line: string): boolean {
+  const trimmed = line.trim()
+  return trimmed.startsWith(WAIT_UNTIL_PREFIX) || trimmed.startsWith(WAIT_REASON_PREFIX)
+}
+
+export function upsertWaitInComment(comment: string | null, until: number, reason?: string): string {
+  const lines = comment ? comment.split(/\r?\n/) : []
+  const filtered = lines.filter((line) => !isWaitLine(line))
+  const waitLines = [`${WAIT_UNTIL_PREFIX}${Math.trunc(until)}`]
+  const reasonValue = reason?.trim()
+  if (reasonValue) {
+    waitLines.push(`${WAIT_REASON_PREFIX}${reasonValue}`)
+  }
+  return [...waitLines, ...filtered].join("\n").trimEnd()
+}
+
+export function removeWaitFromComment(comment?: string | null): string | null {
+  if (!comment) return null
+  const lines = comment.split(/\r?\n/).filter((line) => !isWaitLine(line))
+  const cleaned = lines.join("\n").trimEnd()
+  return cleaned.length ? cleaned : null
+}
+
 export function resolveMaybeRealpath(value: string): string {
   try {
     return fs.realpathSync.native(value)

package/src/prompt.ts

@@ -0,0 +1,104 @@
+export const PLANPILOT_HELP_TEXT = [
+  "Planpilot - Plan/Step/Goal auto-continue workflow.",
+  "",
+  "Model:",
+  "- plan -> step -> goal",
+  "- step.executor: ai | human",
+  "- status rolls up: goals -> steps -> plan",
+  "",
+  "Rules (important):",
+  "- Prefer assigning steps to ai. Use human steps only for actions that require human approval/credentials",
+  "  or elevated permissions / destructive operations (e.g. GitHub web UI, sudo, deleting data/files).",
+  "- One step = one executor. Do NOT mix ai/human work within the same step.",
+  "  If a person must do something, create a separate human step.",
+  "- Keep statuses up to date. Mark goals/steps done as soon as they are completed so roll-up and auto-continue stay correct.",
+  "- `step wait` is ONLY for asynchronous, non-blocking external work that is already in progress",
+  "  (build/test/job/CI/network/remote service).",
+  "  If you can run something now, do it instead of waiting.",
+  "  Do NOT use `step wait` to wait for human action.",
+  "- Keep comments short and decision-focused.",
+  "",
+  "Status propagation:",
+  "- Step with goals: done iff ALL goals are done; else todo.",
+  "- Plan with steps: done iff ALL steps are done; else todo.",
+  "- Step with 0 goals: manual status (`step update` / `step done`).",
+  "- Plan with 0 steps: manual status (`plan update` / `plan done`).",
+  "- When a plan becomes done, it is removed from active plan.",
+  "",
+  "Auto-continue:",
+  "- When the session is idle and an active plan exists:",
+  "  - if next pending step.executor is ai: Planpilot auto-sends the next step + goals.",
+  "  - if next pending step.executor is human: no auto-continue.",
+  "- Pause while waiting on external systems: `step wait`.",
+  "- Stop auto-continue:",
+  "  - `plan deactivate`, OR",
+  "  - insert a human step BEFORE the next pending ai step (so the next executor becomes human).",
+  "",
+  "Invocation:",
+  "- argv is tokenized: [section, subcommand, ...args]",
+  "- section: help | plan | step | goal",
+  "",
+  "Commands:",
+  "- help",
+  "",
+  "Plan:",
+  "- plan add <title> <content>",
+  "- plan add-tree <title> <content> --step <content> [--executor ai|human] [--goal <content>]... [--step ...]...",
+  "- plan list [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]",
+  "- plan count [--scope project|all] [--status todo|done|all]",
+  "- plan search --search <term> [--search <term> ...] [--search-mode any|all] [--search-field plan|title|content|comment|steps|goals|all] [--match-case] [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]",
+  "- plan show <id>",
+  "- plan export <id> <path>",
+  "- plan comment <id> <comment> [<id> <comment> ...]",
+  "- plan update <id> [--title <title>] [--content <content>] [--status todo|done] [--comment <comment>]",
+  "- plan done <id>",
+  "- plan remove <id>",
+  "- plan activate <id> [--force]",
+  "- plan show-active",
+  "- plan deactivate",
+  "",
+  "Step:",
+  "- step add <plan_id> <content...> [--executor ai|human] [--at <pos>]",
+  "- step add-tree <plan_id> <content> [--executor ai|human] [--goal <content> ...]",
+  "- step list <plan_id> [--status todo|done|all] [--executor ai|human] [--limit N] [--page N]",
+  "- step count <plan_id> [--status todo|done|all] [--executor ai|human]",
+  "- step show <id>",
+  "- step show-next",
+  "- step wait <id> --delay <ms> [--reason <text>]",
+  "- step wait <id> --clear",
+  "- step comment <id> <comment> [<id> <comment> ...]",
+  "- step update <id> [--content <content>] [--status todo|done] [--executor ai|human] [--comment <comment>]",
+  "- step done <id> [--all-goals]",
+  "- step move <id> --to <pos>",
+  "- step remove <id...>",
+  "",
+  "Goal:",
+  "- goal add <step_id> <content...>",
+  "- goal list <step_id> [--status todo|done|all] [--limit N] [--page N]",
+  "- goal count <step_id> [--status todo|done|all]",
+  "- goal show <id>",
+  "- goal comment <id> <comment> [<id> <comment> ...]",
+  "- goal update <id> [--content <content>] [--status todo|done] [--comment <comment>]",
+  "- goal done <id...>",
+  "- goal remove <id...>",
+].join("\n")
+
+export const PLANPILOT_TOOL_DESCRIPTION = [
+  "Planpilot planner for auto-continue plan workflows.",
+  "For multi-step and complex tasks, use Planpilot to structure work into plans/steps/goals.",
+  "Run `planpilot help` for full usage + rules.",
+].join("\n")
+
+export const PLANPILOT_SYSTEM_INJECTION =
+  "If the task is multi-step or complex, must use the `planpilot` plan tool. For full usage + rules, run: planpilot help."
+
+export function formatPlanpilotAutoContinueMessage(input: { timestamp: string; stepDetail: string }): string {
+  const detail = (input.stepDetail ?? "").trimEnd()
+  return [
+    `Planpilot @ ${input.timestamp}`,
+    "This message was automatically sent by the Planpilot tool because the next pending step executor is ai.",
+    "For full usage + rules, run: planpilot help",
+    "Next step details:",
+    detail,
+  ].join("\n")
+}

package/docs/planpilot.md

@@ -1,220 +0,0 @@
-# Planpilot (OpenCode Tool)
-
-## Tool Name
-`planpilot`
-
-## What it is
-Planpilot is a planner/tracker for multi-step work. It manages plans, steps, and goals, and automatically rolls up status.
-
-## OpenCode Tool Usage (Required)
-Use the custom `planpilot` tool. Do **not** call the CLI via `bash` for planning.
-
-### Tool schema
-- `argv?: string[]` - preferred; avoids quoting issues
-- `command?: string` - optional; one command string
-
-Rules:
-- Provide either `argv` or `command`.
-- Do **not** pass `--session-id` or `--cwd`; the tool injects them automatically from the current session.
-- If both `argv` and `command` are provided, `argv` is used.
-
-Example tool args:
-
-```json
-{ "argv": ["plan", "add", "Release v1.2", "Plan description"] }
-```
-
-```json
-{ "command": "plan add \"Release v1.2\" \"Plan description\"" }
-```
-
-## CLI (Optional)
-A CLI binary named `planpilot` is available for manual use. If you use the CLI directly, you must pass `--session-id` and `--cwd` yourself.
-
-## Storage
-- Database: `~/.config/opencode/.planpilot/planpilot.db`
-- Plan snapshots: `~/.config/opencode/.planpilot/plans/`
-- Override base directory: `OPENCODE_PLANPILOT_DIR` or `OPENCODE_PLANPILOT_HOME`
-
-## Hierarchy
-- Plan contains steps; step contains goals.
-- Goals are the smallest units of work; steps group goals; plans group steps.
-
-## AI Workflow Guidelines
-- Use Planpilot for all planning, status, and progress tracking; do not use built-in plan/todo tools or other methods to track plan/step/goal status.
-- Do not read plan files from disk or follow plan file placeholders; use the planpilot tool for plan/step/goal info.
-- Treat tool output as authoritative. Do not invent IDs; only use IDs shown by `list`/`show`.
-- If the tool is missing or unavailable, ask the user to enable/install the plugin.
-- Record implementation details using Planpilot comments (plan/step/goal `--comment` or `comment` commands). Before starting a step or goal, think through the next actions and capture that context in comments so the plan stays actionable.
-- Before starting a new plan, do deep analysis; then create the plan with clear steps and goals.
-- When creating a plan or step, prefer `add-tree` to define all steps/goals upfront.
-- Prefer assigning steps to `ai`; only assign `human` for truly critical/high-risk items or when passwords, `sudo` access, irreversible git history rewrites, or remote git changes are required. If `human` steps are necessary, batch them, make the step content explicit about what the human must do, and only ask for user input when the next step is assigned to `human`.
-- Adjust plans/steps/goals only when necessary; avoid frequent arbitrary changes.
-- Update status promptly as work completes; mark goals done, and let steps/plans auto-refresh unless a step/plan has no children (then use `step done`/`plan done`).
-- In each reply turn, complete at most one step; do not advance multiple steps in a single response.
-
-## Status Management
-- Status values: `todo`, `done`.
-- Goals are manual (`goal done`); steps/plans auto-refresh from child status, and use `step done`/`plan done` only when they have no children (`step done --all-goals` marks all goals done and then marks the step done). Auto status changes print as `Auto status updates:` with reasons.
-- Parent status auto-flips to `todo` on incomplete child work and to `done` when all children are done. If a plan has 0 steps or a step has 0 goals, no auto-flip happens; use `plan done` / `step done` as needed.
-- If the user completed a `human` step, verify/mark each goal and clearly list what remains.
-- When a step becomes `done` and there is another pending step, the CLI will print the next-step instruction: for `ai`, end the turn so Planpilot can surface it; for `human`, show the step detail and tell the user to complete the goals, then end the turn. When a plan becomes `done` (automatic or manual), the CLI will prompt you to summarize completed results and end the turn.
-
-## Active Plan Management
-- Use `plan activate` / `plan deactivate` to manage, and no active plan means the plan is paused until reactivated. Plans auto-deactivate on `done` (manual or automatic) or removal.
-- Each plan can be active in only one session at a time; use `plan activate --force` to take over. Default to no `--force`, and if activation fails due to another session, ask the user whether to take over.
-- Use `plan show-active` to know which plan is active and get its details.
-
-## Auto-Continue Behavior (OpenCode Plugin)
-- The plugin listens to `session.idle` / `session.status` (idle) events.
-- If there is an active plan and the next pending step is assigned to `ai`, it appends a `Planpilot (auto):` message to the prompt and submits it so the model continues the plan.
-- It does nothing when there is no active plan or when the next step is assigned to `human`.
-
-## ID Notes
-- Plan/step/goal IDs are database IDs and may be non-contiguous or not start at 1; always use the actual IDs shown by `list`/`show`.
-
-## Commands
-
-- IMPORTANT: Do NOT pass `--cwd` or `--session-id` when using the tool. These are injected automatically.
-
-### plan
-- Plan data is stored under OpenCode config: `~/.config/opencode/.planpilot/` (overridable via `OPENCODE_PLANPILOT_DIR` or `OPENCODE_PLANPILOT_HOME`).
-- `plan add <title> <content>`: create a plan.
-  - Output: `Created plan ID: <id>: <title>`.
-- `plan add-tree <title> <content> --step <content> [--executor ai|human] [--goal <goal> ...] [--step <content> ...]`: create a plan with steps/goals in one command.
-  - Output: `Created plan ID: <id>: <title> (steps: <n>, goals: <n>)`.
-  - Behavior: the newly created plan is automatically activated for the current session.
-  - Repeatable groups: you can repeat the `--step ... [--executor ...] [--goal ...]` group multiple times.
-  - Each `--executor` / `--goal` applies to the most recent `--step`.
-  - Example (tool args):
-    ```json
-    {"argv":["plan","add-tree","Release v1.2","Plan description","--step","Cut release branch","--executor","human","--goal","Create branch","--goal","Tag base","--step","Build artifacts","--executor","ai","--goal","Build packages"]}
-    ```
-  - Another example (3 steps, some without goals/executor):
-    ```json
-    {"argv":["plan","add-tree","Onboarding","Setup plan","--step","Create accounts","--goal","GitHub","--goal","Slack","--step","Install tooling","--executor","ai","--step","Read handbook"]}
-    ```
-- `plan list [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]`: list plans. Default: `--scope project`, `--status all`, `--limit 20`, `--page 1`, order by `updated` desc (most recent first).
-  - Output: prints a header line, then one line per plan with `ID STAT STEPS TITLE COMMENT` (`STEPS` is `done/total`); use `plan show` for full details.
-  - Output (empty): `No plans found.`
-  - Order: defaults to `updated` with most recent first. Use `--order` and `--desc` to override.
-  - Pagination: If `--page` is provided without `--limit`, the default limit is used.
-  - If `--page` exceeds the total pages, a warning is printed and no rows are returned.
-  - Footer: prints `Page N / Limit N` after the list.
-- `plan count [--scope project|all] [--status todo|done|all]`: count plans matching the filters. Output: `Total: <n>`.
-- `plan search --search <term> [--search <term> ...] [--search-mode any|all] [--search-field plan|title|content|comment|steps|goals|all] [--match-case] [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]`: search plans. Default: `--scope project`, `--status all`, `--limit 20`, `--page 1`, order by `updated` desc.
-  - Output: same format as `plan list`.
-  - Output (empty): `No plans found.`
-  - Advanced search:
-    - `--search <term>` (repeatable): filter plans by text (required).
-    - `--search-mode any|all`: match any term or require all terms (default: `all`).
-    - `--search-field plan|title|content|comment|steps|goals|all` (default: `plan`).
-    - `--match-case`: make search case-sensitive.
-  - Pagination: If `--page` is provided without `--limit`, the default limit is used.
-  - If `--page` exceeds the total pages, a warning is printed and no rows are returned.
-  - Footer: prints `Page N / Limit N` after the list.
-- `plan show <id>`: prints plan details and nested steps/goals (includes ids for plan/step/goal).
-  - Output: plan header includes `Plan ID: <id>`, `Title`, `Status`, `Content`, `Created`, `Updated`, and `Comment` when present.
-  - Output: each step line includes step id and executor; progress (`goals done/total`) is shown only when the step has goals. Each goal line includes goal id.
-- `plan export <id> <path>`: export plan details to a markdown file.
-  - Output: `Exported plan ID: <id> to <path>`.
-- `plan update <id> [--title <title>] [--content <content>] [--status todo|done] [--comment <comment>]`: update fields; `--status done` is allowed only when all steps are done or the plan has no steps.
-  - Output: `Updated plan ID: <id>: <title>`.
-  - Errors: multi-line `Error: Invalid input:` with `cannot mark plan done; next pending step:` on the next line, followed by the same step detail output as `step show`.
-- `plan done <id>`: mark plan done (same rule as `plan update --status done`).
-  - Output: `Plan ID: <id> marked done.`
-  - Output (active plan): `Active plan deactivated because plan is done.`
-  - Errors: multi-line `Error: Invalid input:` with `cannot mark plan done; next pending step:` on the next line, followed by the same step detail output as `step show`.
-- `plan comment <id1> <comment1> [<id2> <comment2> ...]`: add or replace comments for one or more plans.
-  - Output (single): `Updated plan comment for plan ID: <id>.`
-  - Output (batch): `Updated plan comments for <n> plans.`
-  - Each plan comment uses an `<id> <comment>` pair; you can provide multiple pairs in one call.
-  - Example:
-    ```json
-    {"argv":["plan","comment","12","high priority","15","waiting on input"]}
-    ```
-- `plan remove <id>`: remove plan (and its steps/goals).
-  - Output: `Plan ID: <id> removed.`
-- `plan activate <id> [--force]`: set the active plan.
-  - Output: `Active plan set to <id>: <title>`.
-  - `--force` takes over a plan already active in another session.
-  - Errors: `Error: Invalid input: cannot activate plan; plan is done`.
-  - Errors: `Error: Invalid input: plan id <id> is already active in session <session_id> (use --force to take over)`.
-- `plan show-active`: prints the active plan details (same format as `plan show`).
-  - Output: the same plan detail format as `plan show`.
-  - Output (empty): `No active plan.`
-  - Output (missing): `Active plan ID: <id> not found.`
-- `plan deactivate`: unset the active plan (does not delete any plan).
-  - Output: `Active plan deactivated.`
-
-### step
-- `step add <plan_id> <content1> [<content2> ...] [--at <pos>] [--executor ai|human]`: add steps.
-  - Output (single): `Created step ID: <id> for plan ID: <plan_id>`.
-  - Output (batch): `Created <n> steps for plan ID: <plan_id>`.
-- `step add-tree <plan_id> <content> [--executor ai|human] [--goal <goal> ...]`: create one step with goals in one command.
-  - Output: `Created step ID: <id> for plan ID: <plan_id> (goals: <n>)`.
-  - Example:
-    ```json
-    {"argv":["step","add-tree","1","Draft summary","--executor","ai","--goal","Collect inputs","--goal","Write draft"]}
-    ```
-- `step list <plan_id> [--status todo|done|all] [--executor ai|human] [--limit N] [--page N]`: list steps. Default: `--status all`, `--limit 20`, `--page 1`. Steps are always returned in their plan order.
-  - Output: prints a header line, then one line per step with `ID STAT ORD EXEC GOALS CONTENT COMMENT` (`ORD` is the step order within the plan; `GOALS` is `done/total`); use `step show` for full details.
-  - Output (empty): `No steps found for plan ID: <plan_id>.`
-  - Pagination: If `--page` is provided without `--limit`, the default limit is used.
-  - If `--page` exceeds the total pages, a warning is printed and no rows are returned.
-  - Footer: prints `Page N / Limit N` after the list.
-- `step count <plan_id> [--status todo|done|all] [--executor ai|human]`: count steps matching the filters. Output: `Total: <n>`.
-- `step show <id>`: prints a single step with full details and its nested goals (includes ids for step/goal).
-  - Output: step header includes `Step ID: <id>`, `Plan ID`, `Status`, `Executor`, `Content`, `Created`, `Updated`, and `Comment` when present.
-  - Output: lists all goals with `[status]` and goal id.
-- `step show-next`: show the next pending step for the active plan (same format as `step show`).
-  - Output (empty): `No active plan.` or `No pending step.`.
-- `step update <id> [--content <content>] [--status todo|done] [--executor ai|human] [--comment <comment>]`: update fields; `--status done` is allowed only when all goals are done or the step has no goals.
-  - Output: `Updated step ID: <id>.`.
-  - Errors: `Error: Invalid input: cannot mark step done; next pending goal: <content> (id <id>)`.
-- `step comment <id1> <comment1> [<id2> <comment2> ...]`: add or replace comments for one or more steps.
-  - Output (single): `Updated step comments for plan ID: <plan_id>.`
-  - Output (batch): `Updated step comments for <n> plans.`
-  - Each step comment uses an `<id> <comment>` pair; you can provide multiple pairs in one call.
-  - Example:
-    ```json
-    {"argv":["step","comment","45","blocked by API","46","ready to start"]}
-    ```
-- `step done <id> [--all-goals]`: mark step done (same rule as `step update --status done`). Use `--all-goals` to mark all goals in the step done first, then mark the step done.
-  - Output: `Step ID: <id> marked done.`
-  - Errors: `Error: Invalid input: cannot mark step done; next pending goal: <content> (id <id>)`.
-- `step move <id> --to <pos>`: reorder and print the same one-line list as `step list`.
-  - Output: `Reordered steps for plan ID: <plan_id>:` + list.
-- `step remove <id1> [<id2> ...]`: remove step(s).
-  - Output (single): `Step ID: <id> removed.`
-  - Output (batch): `Removed <n> steps.`
-  - Errors: `Error: Not found: step id(s) not found: <id1>[, <id2> ...]`.
-
-### goal
-- `goal add <step_id> <content1> [<content2> ...]`: add goals to a step.
-  - Output (single): `Created goal ID: <id> for step ID: <step_id>`.
-  - Output (batch): `Created <n> goals for step ID: <step_id>`.
-- `goal list <step_id> [--status todo|done|all] [--limit N] [--page N]`: list goals. Default: `--status all`, `--limit 20`, `--page 1`, order by `updated` desc (most recent first).
-  - Output: prints a header line, then one line per goal with `ID STAT CONTENT COMMENT`.
-  - Output (empty): `No goals found for step ID: <step_id>.`
-  - Pagination: If `--page` is provided without `--limit`, the default limit is used.
-  - If `--page` exceeds the total pages, a warning is printed and no rows are returned.
-  - Footer: prints `Page N / Limit N` after the list.
-- `goal count <step_id> [--status todo|done|all]`: count goals matching the filters. Output: `Total: <n>`.
-- `goal update <id> [--content <content>] [--status todo|done] [--comment <comment>]`: update fields.
-  - Output: `Updated goal <id>.`
-- `goal comment <id1> <comment1> [<id2> <comment2> ...]`: add or replace comments for one or more goals.
-  - Output (single): `Updated goal comments for plan ID: <plan_id>.`
-  - Output (batch): `Updated goal comments for <n> plans.`
-  - Each goal comment uses an `<id> <comment>` pair; you can provide multiple pairs in one call.
-  - Example:
-    ```json
-    {"argv":["goal","comment","78","done","81","needs review"]}
-    ```
-- `goal done <id1> [<id2> ...]`: mark one or more goals done.
-  - Output (single): `Goal ID: <id> marked done.`
-  - Output (batch): `Goals marked done: <n>.`
-- `goal remove <id1> [<id2> ...]`: remove goal(s).
-  - Output (single): `Goal ID: <id> removed.`
-  - Output (batch): `Removed <n> goals.`
-  - Errors: `Error: Not found: goal id(s) not found: <id1>[, <id2> ...]`.

package/src/lib/argv.ts

@@ -1,58 +0,0 @@
-import { invalidInput } from "./errors"
-
-export function parseCommandArgs(input: string): string[] {
-  const args: string[] = []
-  let current = ""
-  let inSingle = false
-  let inDouble = false
-  let escapeNext = false
-
-  for (let i = 0; i < input.length; i += 1) {
-    const ch = input[i]
-
-    if (escapeNext) {
-      current += ch
-      escapeNext = false
-      continue
-    }
-
-    if (ch === "\\" && !inSingle) {
-      escapeNext = true
-      continue
-    }
-
-    if (ch === "'" && !inDouble) {
-      inSingle = !inSingle
-      continue
-    }
-
-    if (ch === '"' && !inSingle) {
-      inDouble = !inDouble
-      continue
-    }
-
-    if (!inSingle && !inDouble && /\s/.test(ch)) {
-      if (current.length) {
-        args.push(current)
-        current = ""
-      }
-      continue
-    }
-
-    current += ch
-  }
-
-  if (escapeNext) {
-    current += "\\"
-  }
-
-  if (inSingle || inDouble) {
-    throw invalidInput("unterminated quote in command")
-  }
-
-  if (current.length) {
-    args.push(current)
-  }
-
-  return args
-}

package/src/lib/instructions.ts

@@ -1,26 +0,0 @@
-import fs from "fs"
-import path from "path"
-import { fileURLToPath } from "url"
-
-let cached: string | null = null
-
-export function loadPlanpilotInstructions(): string {
-  if (cached !== null) return cached
-  try {
-    const moduleDir = path.dirname(fileURLToPath(import.meta.url))
-    const candidates = [
-      path.resolve(moduleDir, "../../docs/planpilot.md"),
-      path.resolve(moduleDir, "../../../docs/planpilot.md"),
-    ]
-    for (const candidate of candidates) {
-      if (fs.existsSync(candidate)) {
-        cached = fs.readFileSync(candidate, "utf8")
-        return cached
-      }
-    }
-    cached = ""
-  } catch {
-    cached = ""
-  }
-  return cached
-}