pi-quests 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-13
+
+- feat: add configurable shortcut to open quest list, default: `ctrl+shift+l`
+- feat: add sub-quest support with lifecycle management
+- feat: add user-configurable settings via pi settings files
+- feat: use random 2-digit hex IDs and targetId-based reorder
+- fix: add .pi/setting.json for development
+
+## [0.3.0] - 2026-04-11
+
+- feat: add reorder action to move quests by position (dataplane, tool, /quests command, renderer, revert support)
+- feat: extend clear action with optional all flag to remove all quests regardless of done state
+- feat: detect appended completion markers (e.g. "- DONE") and inject correction nudge via context hook
+- feat: update list rendering to show 1-based positions instead of raw IDs
+- fix: inline type imports across test files to comply with no-inline-imports rule
+- chore: extract shared prompt strings into prompts.ts to eliminate duplication
+- chore: fix release workflow output mapping in create-release job
+
 ## [0.2.0] - 2026-04-11
 
 - feat: add dynamic quest usage nudges via context hook

package/README.md

@@ -1,6 +1,6 @@
 # pi-quests
 
-[![version 0.2.0](https://img.shields.io/badge/version-0.2.0-blue)](CHANGELOG.md)
+[![version 0.4.0](https://img.shields.io/badge/version-0.4.0-blue)](CHANGELOG.md)
 [![MIT license](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
 [![pi extension](https://img.shields.io/badge/pi-extension-purple)](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
 
@@ -47,6 +47,24 @@ Available /quests subcommands:
 ![Quests view](docs/assets/quests_view.png)
 
 
+## Configuration
+
+pi-quests reads configuration from pi's settings files. Global settings live at `~/.pi/agent/settings.json` and project overrides go in `.pi/settings.json`.
+
+```json
+{
+  "pi-quests": {
+    "ids": { "length": 2 },
+    "display": {
+      "pageSize": 10,
+      "progressBarMaxWidth": 24
+    }
+  }
+}
+```
+
+See [docs/configuration.md](docs/configuration.md) for the full options reference.
+
 ## Documentation
 
 | Doc | Description |
@@ -54,6 +72,7 @@ Available /quests subcommands:
 | [Pattern](docs/pattern.md) | "How do I...?" recipes for common workflows |
 | [Quests](docs/quests.md) | What are quests? |
 | [Reference](docs/reference.md) | Complete tool and command schemas, types |
+| [Configuration](docs/configuration.md) | Settings, overrides, and examples |
 | [Architecture](docs/architecture.md) | Module map, data flow diagrams, design decisions |
 | [Changelog](CHANGELOG.md) | Version history |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quests",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A quest-log for your pi. Keep your agent on track, one quest at a time.",
   "type": "module",
   "keywords": [

package/src/commands/handler.ts

@@ -1,5 +1,10 @@
 import { readFileSync } from "node:fs";
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
 import type { QuestAction, QuestLog } from "../quest/dataplane.js";
 import { QUEST_ACTIONS } from "../quest/types.js";
@@ -17,6 +22,7 @@ type MutatingCommand = Extract<
       | typeof QUEST_ACTIONS.update
       | typeof QUEST_ACTIONS.delete
       | typeof QUEST_ACTIONS.clear
+      | typeof QUEST_ACTIONS.reorder
       | typeof QUEST_ACTIONS.revert;
   }
 >["action"];
@@ -24,7 +30,11 @@ type MutatingCommand = Extract<
 const commandActionBuilders: {
   [K in MutatingCommand]: (parsed: Extract<ParsedArgs, { action: K }>) => QuestAction;
 } = {
-  [QUEST_ACTIONS.add]: (p) => ({ type: QUEST_ACTIONS.add, descriptions: p.descriptions }),
+  [QUEST_ACTIONS.add]: (p) => ({
+    type: QUEST_ACTIONS.add,
+    descriptions: p.descriptions,
+    parentId: p.parentId,
+  }),
   [QUEST_ACTIONS.toggle]: (p) => ({ type: QUEST_ACTIONS.toggle, id: p.id }),
   [QUEST_ACTIONS.update]: (p) => ({
     type: QUEST_ACTIONS.update,
@@ -32,15 +42,31 @@ const commandActionBuilders: {
     description: p.description,
   }),
   [QUEST_ACTIONS.delete]: (p) => ({ type: QUEST_ACTIONS.delete, id: p.id }),
-  [QUEST_ACTIONS.clear]: () => ({ type: QUEST_ACTIONS.clear }),
+  [QUEST_ACTIONS.clear]: (p) => ({ type: QUEST_ACTIONS.clear, all: p.all }),
+  [QUEST_ACTIONS.reorder]: (p) => ({
+    type: QUEST_ACTIONS.reorder,
+    id: p.id,
+    targetId: p.targetId,
+  }),
   [QUEST_ACTIONS.revert]: () => ({ type: QUEST_ACTIONS.revert }),
 };
 
-export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog) {
+export function openQuestList(
+  _pi: ExtensionAPI,
+  questLog: QuestLog,
+  config: ResolvedConfig,
+  ctx: ExtensionContext,
+): Promise<void> {
+  return ctx.ui.custom(
+    (_, theme, __, done) => new QuestListWidget(questLog, theme, () => done(undefined), config),
+  );
+}
+
+export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog, config: ResolvedConfig) {
   return async function handler(args: string, ctx: ExtensionCommandContext): Promise<void> {
     logger.debug("quests:cmd", "handler", { args, hasUI: ctx.hasUI });
 
-    const parsed = parseQuestArgs(args);
+    const parsed = parseQuestArgs(args, config.ids.length);
     if ("error" in parsed) {
       logger.debug("quests:cmd", "handler-error", { error: parsed.error });
       ctx.ui.notify(parsed.error, "error");
@@ -88,10 +114,7 @@ export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog) {
         }
 
         logger.debug("quests:cmd", "list-open-widget", { count: questLog.getAll().length });
-        await ctx.ui.custom(
-          (_, theme, __, done) =>
-            new QuestListWidget(questLog.getAll(), theme, () => done(undefined)),
-        );
+        await openQuestList(pi, questLog, config, ctx);
 
         logger.debug("quests:cmd", "list-widget-closed");
         return;
@@ -101,6 +124,7 @@ export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog) {
       case QUEST_ACTIONS.update:
       case QUEST_ACTIONS.delete:
       case QUEST_ACTIONS.clear:
+      case QUEST_ACTIONS.reorder:
       case QUEST_ACTIONS.revert: {
         const builder = commandActionBuilders[parsed.action];
         const action = builder(parsed as never);
@@ -114,13 +138,14 @@ export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog) {
         logger.debug("quests:cmd", "help");
 
         const lines = ["Available /quests subcommands:"];
-        lines.push("  add <description>  - Add a new quest");
+        lines.push("  add [--parent <id>] <description>  - Add a new quest or sub-quest");
         lines.push("  list               - List all quests");
         lines.push("  toggle <id>        - Toggle quest completion");
         lines.push("  delete <id>        - Delete a quest");
         lines.push("  update <id> <desc> - Update a quest description");
+        lines.push("  reorder <id> <targetId> - Reorder a quest before the target quest");
         lines.push("  revert             - Revert the last quest change");
-        lines.push("  clear              - Clear all quests");
+        lines.push("  clear [all]        - Clear completed quests, or optionally all quests");
         lines.push("  version            - Show version");
         lines.push("  changelog          - Show changelog");
         lines.push("  h, help            - Show this help message");

package/src/commands/parse-args.ts

@@ -2,12 +2,13 @@ import { logger } from "../logger.js";
 import { QUEST_ACTIONS } from "../quest/types.js";
 
 export type ParsedArgs =
-  | { action: typeof QUEST_ACTIONS.add; descriptions: string[] }
+  | { action: typeof QUEST_ACTIONS.add; descriptions: string[]; parentId?: string }
   | { action: typeof QUEST_ACTIONS.list }
-  | { action: typeof QUEST_ACTIONS.toggle; id: number }
-  | { action: typeof QUEST_ACTIONS.update; id: number; description: string }
-  | { action: typeof QUEST_ACTIONS.delete; id: number }
-  | { action: typeof QUEST_ACTIONS.clear }
+  | { action: typeof QUEST_ACTIONS.toggle; id: string }
+  | { action: typeof QUEST_ACTIONS.update; id: string; description: string }
+  | { action: typeof QUEST_ACTIONS.delete; id: string }
+  | { action: typeof QUEST_ACTIONS.clear; all?: boolean }
+  | { action: typeof QUEST_ACTIONS.reorder; id: string; targetId: string }
   | { action: typeof QUEST_ACTIONS.revert }
   | { action: "help" }
   | { action: "version" }
@@ -17,7 +18,7 @@ export type ParsedArgs =
 /**
  * Parse user input from the /quests command into structured arguments.
  */
-export function parseQuestArgs(args: string): ParsedArgs {
+export function parseQuestArgs(args: string, idLength = 2): ParsedArgs {
   logger.debug("quests:cmd", "parse-args", { args });
   const tokens = args.trim().split(/\s+/).filter(Boolean);
 
@@ -36,43 +37,72 @@ export function parseQuestArgs(args: string): ParsedArgs {
 
   // Quest actions without arguments
   if (command === QUEST_ACTIONS.list) return { action: QUEST_ACTIONS.list };
-  if (command === QUEST_ACTIONS.clear) return { action: QUEST_ACTIONS.clear };
+  if (command === QUEST_ACTIONS.clear) return parseClearArgs(rest);
   if (command === QUEST_ACTIONS.revert) return { action: QUEST_ACTIONS.revert };
 
   // Quest actions with arguments
-  if (command === QUEST_ACTIONS.add) return parseAddArgs(rest);
-  if (command === QUEST_ACTIONS.toggle) return parseIdAction(QUEST_ACTIONS.toggle, rest);
-  if (command === QUEST_ACTIONS.delete) return parseIdAction(QUEST_ACTIONS.delete, rest);
-  if (command === QUEST_ACTIONS.update) return parseUpdateArgs(rest);
+  if (command === QUEST_ACTIONS.add) return parseAddArgs(rest, idLength);
+  if (command === QUEST_ACTIONS.toggle) return parseIdAction(QUEST_ACTIONS.toggle, rest, idLength);
+  if (command === QUEST_ACTIONS.delete) return parseIdAction(QUEST_ACTIONS.delete, rest, idLength);
+  if (command === QUEST_ACTIONS.update) return parseUpdateArgs(rest, idLength);
+  if (command === QUEST_ACTIONS.reorder) return parseReorderArgs(rest, idLength);
 
   return { error: `Unknown subcommand: ${command}. Use /quests help to see available commands.` };
 }
 
-function parseAddArgs(tokens: string[]): ParsedArgs {
-  const description = tokens.join(" ").trim();
-  if (!description) return { error: "Usage: /quests add <description>" };
+function parseAddArgs(tokens: string[], idLength: number): ParsedArgs {
+  let parentId: string | undefined;
+  let descTokens = tokens;
+  const pIdx = tokens.indexOf("--parent");
+  if (pIdx !== -1) {
+    const pid = tokens[pIdx + 1]?.toLowerCase() ?? "";
+    const pattern = new RegExp(`^[0-9a-f]{${idLength}}$`);
+    if (!pattern.test(pid)) return { error: "Usage: /quests add [--parent <id>] <description>" };
+    parentId = pid;
+    descTokens = tokens.slice(0, pIdx).concat(tokens.slice(pIdx + 2));
+  }
+  const description = descTokens.join(" ").trim();
+  if (!description) return { error: "Usage: /quests add [--parent <id>] <description>" };
 
-  return { action: QUEST_ACTIONS.add, descriptions: [description] };
+  return { action: QUEST_ACTIONS.add, descriptions: [description], parentId };
 }
 
 function parseIdAction(
   action: typeof QUEST_ACTIONS.toggle | typeof QUEST_ACTIONS.delete,
   tokens: string[],
+  idLength: number,
 ): ParsedArgs {
-  const idStr = tokens[0];
-  const id = idStr ? Number(idStr) : NaN;
-  if (Number.isNaN(id)) return { error: `Usage: /quests ${action} <id>` };
+  const id = tokens[0] ? tokens[0].toLowerCase() : "";
+  const pattern = new RegExp(`^[0-9a-f]{${idLength}}$`);
+  if (!pattern.test(id)) return { error: `Usage: /quests ${action} <id>` };
 
   return { action, id };
 }
 
-function parseUpdateArgs(tokens: string[]): ParsedArgs {
-  const idStr = tokens[0];
-  const id = idStr ? Number(idStr) : NaN;
-  if (Number.isNaN(id)) return { error: "Usage: /quests update <id> <description>" };
+function parseUpdateArgs(tokens: string[], idLength: number): ParsedArgs {
+  const id = tokens[0] ? tokens[0].toLowerCase() : "";
+  const pattern = new RegExp(`^[0-9a-f]{${idLength}}$`);
+  if (!pattern.test(id)) return { error: "Usage: /quests update <id> <description>" };
 
   const description = tokens.slice(1).join(" ").trim();
   if (!description) return { error: "Usage: /quests update <id> <description>" };
 
   return { action: QUEST_ACTIONS.update, id, description };
 }
+
+function parseClearArgs(tokens: string[]): ParsedArgs {
+  const all = tokens[0] === "all";
+  if (tokens.length > 0 && !all) return { error: "Usage: /quests clear [all]" };
+  return { action: QUEST_ACTIONS.clear, all };
+}
+
+function parseReorderArgs(tokens: string[], idLength: number): ParsedArgs {
+  const id = tokens[0] ? tokens[0].toLowerCase() : "";
+  const targetId = tokens[1] ? tokens[1].toLowerCase() : "";
+  const pattern = new RegExp(`^[0-9a-f]{${idLength}}$`);
+
+  if (!pattern.test(id) || !pattern.test(targetId))
+    return { error: "Usage: /quests reorder <id> <targetId>" };
+
+  return { action: QUEST_ACTIONS.reorder, id, targetId };
+}

package/src/config.ts

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+export interface ResolvedConfig {
+  ids: { length: number };
+  display: { pageSize: number; progressBarMaxWidth: number };
+  nudges: {
+    toolCallThreshold: number;
+    hintIntervalMinutes: number;
+    timeBasedToolCallThreshold: number;
+    zeroActiveToolCallThreshold: number;
+    staleProgressToolCallThreshold: number;
+    subQuestSuggestionToolCallThreshold: number;
+    complexTaskKeywords: string[];
+  };
+  validation: { fakeDonePattern: string };
+  shortcuts?: { openQuests?: string };
+}
+
+export const DEFAULT_COMPLEX_TASK_KEYWORDS = [
+  "implement",
+  "refactor",
+  "investigate",
+  "review",
+  "analyze",
+  "audit",
+  "plan",
+  "design",
+  "create",
+  "build",
+  "write",
+  "fix",
+] as const;
+
+export const DEFAULT_FAKE_DONE_PATTERN = String.raw`\s[-\u2013\u2014]\s*(DONE|COMPLETED|FINISHED)$|\s[([](DONE|COMPLETED|FINISHED)[)\]]$`;
+
+export const DEFAULT_CONFIG: ResolvedConfig = {
+  ids: { length: 2 },
+  display: { pageSize: 10, progressBarMaxWidth: 24 },
+  nudges: {
+    toolCallThreshold: 3,
+    hintIntervalMinutes: 8,
+    timeBasedToolCallThreshold: 3,
+    zeroActiveToolCallThreshold: 5,
+    staleProgressToolCallThreshold: 10,
+    subQuestSuggestionToolCallThreshold: 6,
+    complexTaskKeywords: [...DEFAULT_COMPLEX_TASK_KEYWORDS],
+  },
+  validation: { fakeDonePattern: DEFAULT_FAKE_DONE_PATTERN },
+  shortcuts: {},
+};
+
+function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === "object" &&
+      !Array.isArray(source[key]) &&
+      result[key] &&
+      typeof result[key] === "object" &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(
+        result[key] as Record<string, unknown>,
+        source[key] as Record<string, unknown>,
+      );
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+function loadSettings(cwd: string): Record<string, unknown> {
+  const settings: Record<string, unknown> = {};
+  const globalPath = join(getAgentDir(), "settings.json");
+  if (existsSync(globalPath)) {
+    try {
+      Object.assign(settings, JSON.parse(readFileSync(globalPath, "utf-8")));
+    } catch {
+      /* ignore */
+    }
+  }
+  const projectPath = join(cwd, ".pi", "settings.json");
+  if (existsSync(projectPath)) {
+    try {
+      const project = JSON.parse(readFileSync(projectPath, "utf-8")) as Record<string, unknown>;
+      if (project["pi-quests"] && typeof project["pi-quests"] === "object") {
+        const globalPiQuests =
+          settings["pi-quests"] && typeof settings["pi-quests"] === "object"
+            ? (settings["pi-quests"] as Record<string, unknown>)
+            : {};
+        settings["pi-quests"] = deepMerge(
+          globalPiQuests,
+          project["pi-quests"] as Record<string, unknown>,
+        );
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return settings;
+}
+
+export function getConfig(ctx: Pick<ExtensionContext, "cwd">): ResolvedConfig {
+  const settings = loadSettings(ctx.cwd);
+  const user = (settings["pi-quests"] ?? {}) as Partial<ResolvedConfig>;
+  return {
+    ids: { length: user.ids?.length ?? DEFAULT_CONFIG.ids.length },
+    display: {
+      pageSize: user.display?.pageSize ?? DEFAULT_CONFIG.display.pageSize,
+      progressBarMaxWidth:
+        user.display?.progressBarMaxWidth ?? DEFAULT_CONFIG.display.progressBarMaxWidth,
+    },
+    nudges: {
+      toolCallThreshold: user.nudges?.toolCallThreshold ?? DEFAULT_CONFIG.nudges.toolCallThreshold,
+      hintIntervalMinutes:
+        user.nudges?.hintIntervalMinutes ?? DEFAULT_CONFIG.nudges.hintIntervalMinutes,
+      timeBasedToolCallThreshold:
+        user.nudges?.timeBasedToolCallThreshold ?? DEFAULT_CONFIG.nudges.timeBasedToolCallThreshold,
+      zeroActiveToolCallThreshold:
+        user.nudges?.zeroActiveToolCallThreshold ??
+        DEFAULT_CONFIG.nudges.zeroActiveToolCallThreshold,
+      staleProgressToolCallThreshold:
+        user.nudges?.staleProgressToolCallThreshold ??
+        DEFAULT_CONFIG.nudges.staleProgressToolCallThreshold,
+      subQuestSuggestionToolCallThreshold:
+        user.nudges?.subQuestSuggestionToolCallThreshold ??
+        DEFAULT_CONFIG.nudges.subQuestSuggestionToolCallThreshold,
+      complexTaskKeywords: [
+        ...(user.nudges?.complexTaskKeywords ?? DEFAULT_CONFIG.nudges.complexTaskKeywords),
+      ],
+    },
+    validation: {
+      fakeDonePattern:
+        user.validation?.fakeDonePattern ?? DEFAULT_CONFIG.validation.fakeDonePattern,
+    },
+    shortcuts: {
+      openQuests: user.shortcuts?.openQuests,
+    },
+  };
+}

package/src/index.ts

@@ -1,6 +1,12 @@
+import type { UserMessage } from "@mariozechner/pi-ai";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { createQuestsHandler } from "./commands/handler.js";
+import type { KeyId } from "@mariozechner/pi-tui";
+import { createQuestsHandler, openQuestList } from "./commands/handler.js";
+import { DEFAULT_CONFIG, getConfig, type ResolvedConfig } from "./config.js";
+import { logger } from "./logger.js";
+import { QUEST_PROMPT_GATE, QUEST_PROMPT_REMINDER } from "./prompts.js";
 import { QuestLog } from "./quest/dataplane.js";
+import { formatQuestList } from "./quest/formatters.js";
 import { QuestUsageTracker } from "./quest/tracker.js";
 import { questChangelogRenderer } from "./renderers/changelog.js";
 import { registerQuestTool } from "./tools/handler.js";
@@ -16,10 +22,42 @@ import { registerQuestTool } from "./tools/handler.js";
  * - Provide rollback support to restore a previous snapshot.
  */
 export default function (pi: ExtensionAPI): void {
-  const questLog = new QuestLog();
-  const tracker = new QuestUsageTracker();
+  let questLog = new QuestLog();
+  let tracker = new QuestUsageTracker(DEFAULT_CONFIG);
+  let config: ResolvedConfig = DEFAULT_CONFIG;
+
+  const shortcutKey = getConfig({ cwd: process.cwd() }).shortcuts?.openQuests ?? "ctrl+shift+l";
+  logger.debug("quests:shortcut", "register", { key: shortcutKey });
+  pi.registerShortcut(shortcutKey as KeyId, {
+    description: "Open quest list",
+    handler: async (ctx) => {
+      logger.debug("quests:shortcut", "handler", { hasUI: ctx.hasUI });
+      if (!ctx.hasUI) {
+        logger.debug("quests:shortcut", "no-ui");
+        ctx.ui.notify("Interactive mode required", "error");
+        return;
+      }
+      logger.debug("quests:shortcut", "open", { questCount: questLog.getAll().length });
+      await openQuestList(pi, questLog, config, ctx);
+      logger.debug("quests:shortcut", "closed");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    config = getConfig(ctx);
+    questLog = new QuestLog(config);
+    tracker = new QuestUsageTracker(config);
+    questLog.reconstructFromSession(ctx);
+
+    registerQuestTool(pi, questLog, config);
+
+    const questsHandler = createQuestsHandler(pi, questLog, config);
+    pi.registerCommand("quests", {
+      description: "Quest commands: /quests [help] to see usage",
+      handler: questsHandler,
+    });
+  });
 
-  pi.on("session_start", async (_event, ctx) => questLog.reconstructFromSession(ctx));
   pi.on("session_tree", async (_event, ctx) => questLog.reconstructFromSession(ctx));
 
   pi.on("turn_start", async () => tracker.clearTurnNudge());
@@ -34,13 +72,27 @@ export default function (pi: ExtensionAPI): void {
       .map((m) => (typeof m.content === "string" ? m.content : ""))
       .join("\n");
 
-    const activeQuestCount = questLog.getAll().filter((q) => !q.done).length;
-    const nudge = tracker.getNudge(activeQuestCount, latestPrompt);
-    if (!nudge) return undefined;
+    const allQuests = questLog.getAll();
+    const activeQuests = allQuests.filter((q) => !q.done);
+    const activeQuestCount = activeQuests.length;
+    const activeTopLevel = activeQuests.filter((q) => !(q as { parentId?: string }).parentId);
+    const hasTopLevelQuestWithoutSubs = activeTopLevel.some(
+      (q) => !allQuests.some((sq) => (sq as { parentId?: string }).parentId === q.id),
+    );
+    const nudge = tracker.getNudge(activeQuestCount, latestPrompt, hasTopLevelQuestWithoutSubs);
+
+    const fakeDoneRegex = new RegExp(config.validation.fakeDonePattern, "i");
+    const fakeDone = questLog.getAll().find((q) => !q.done && fakeDoneRegex.test(q.description));
+    if (!nudge && !fakeDone) return undefined;
 
-    const reminder: import("@mariozechner/pi-ai").UserMessage = {
+    let content = nudge ?? "";
+    if (fakeDone) {
+      content += `\nQUEST REMINDER: Quest [${fakeDone.id}] has a completion marker appended to its description but is not toggled done. Use the toggle action to mark it done. NEVER append completion markers to descriptions via the update action.`;
+    }
+
+    const reminder: UserMessage = {
       role: "user",
-      content: nudge,
+      content: content.trim(),
       timestamp: Date.now(),
     };
     return { messages: [...event.messages, reminder] };
@@ -48,31 +100,19 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("before_agent_start", async (event) => {
     const quests = questLog.getAll();
-    const gate =
-      "# Quest Management\nBefore reading files, running commands, or making edits, ALWAYS ensure the current work is tracked as specific, actionable quests. ALWAYS break broad requests into concrete steps.\n\n";
-
-    let reminder =
-      "## Quest Management\nUse the quest tool VERY frequently to track tasks, plans, and progress throughout the conversation. It is critical that you toggle quests to done as soon as you complete them. NEVER batch up multiple tasks before marking them completed.\n\nNEVER create a single vague quest for broad requests. Analyze the user's intent and break it into specific, independent, actionable quests that each represent a concrete step.";
+    let reminder = QUEST_PROMPT_REMINDER.join("\n");
     if (quests.length > 0) {
       const remaining = quests.filter((q) => !q.done).length;
-      const list = quests
-        .map((q) => `#${q.id} [${q.done ? "x" : " "}] ${q.description}`)
-        .join("\n");
+      const list = formatQuestList(quests);
 
       reminder += `\n\nActive quests (${remaining}/${quests.length}):\n${list}`;
     }
 
-    return { systemPrompt: `${gate}${event.systemPrompt}\n\n${reminder}` };
+    return {
+      systemPrompt: `# Quest Management\n${QUEST_PROMPT_GATE}${event.systemPrompt}\n\n## Quest Management\n${reminder}. Before adding any independent quests, clear any previously completed quests from the log to keep it focused on current work.`,
+    };
   });
 
-  registerQuestTool(pi, questLog);
-
   // Register custom message renderers
   pi.registerMessageRenderer("quest-changelog", questChangelogRenderer);
-
-  // Register the top-level /quests command dispatcher.
-  pi.registerCommand("quests", {
-    description: "Quest commands: /quests [help] to see usage",
-    handler: createQuestsHandler(pi, questLog),
-  });
 }

package/src/prompts.ts

@@ -0,0 +1,19 @@
+export const QUEST_PROMPT_REMINDER = [
+  "Use the quest tool VERY frequently to track tasks, plans, and progress throughout the conversation.",
+  "Before reading files, running commands, or making edits, ensure the current work is tracked as specific, actionable quests.",
+  "Do not create a single vague quest for broad requests. Break them into concrete, independent steps.",
+  "When the user gives a plan or a list of tasks, add them as quests immediately.",
+  "When reading a skill file, implementation plan, or protocol document that contains numbered steps or checklists, add those steps as quests immediately so they are tracked, and reorder them as needed in the quest log.",
+  "It is critical that you toggle quests to done as soon as you complete them. Do NOT batch completions.",
+  "ALWAYS use the toggle action to mark a quest done. NEVER use the update action to append 'DONE', '- DONE', or any completion marker to a quest description.",
+  "ALWAYS use sub-quests to break down a complex quest into smaller steps. To create a sub-quest, use the `add` action and set `parentId` to the parent quest's hex ID. Use sub-quests for multi-step tasks, minion delegations, or when a quest has more than one distinct deliverable.",
+  "A parent quest cannot be toggled done until all of its sub-quests are completed. Sub-quests cannot be reordered independently.",
+  "Before delegating to a minion, add a quest for the delegated task.",
+  "As work evolves, use the reorder action to reflect changes in priority",
+  "For reorder, provide the targetId (the hex ID of the quest to insert before).",
+  "If you are unsure what to do next, use the list action to check active quests.",
+  "Always use the hex ID shown in brackets (e.g. 0a, ff, 44e1, f712a) for toggle, update, delete, and reorder actions.",
+] as const;
+
+export const QUEST_PROMPT_GATE =
+  "Before reading files, running commands, or making edits, ALWAYS ensure the current work is tracked as specific, actionable quests. ALWAYS break broad requests into concrete steps.";