pi-quests 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-14
+
+- feat: add reparent action to promote, demote, or move quests and steps with validation and revert support
+- feat: add rules and skill actions that return the built-in quest-management skill document
+- feat: add split action to break a quest into steps with add_step alias and command support
+- feat: rename sub-quest terminology to step across types, commands, docs, and prompts
+- feat: improve error messages with actionable recovery hints and refine nudge behavior
+
+## [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)

package/README.md

@@ -1,6 +1,6 @@
 # pi-quests
 
-[![version 0.3.0](https://img.shields.io/badge/version-0.3.0-blue)](CHANGELOG.md)
+[![version 0.5.0](https://img.shields.io/badge/version-0.5.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.3.0",
+  "version": "0.5.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";
@@ -13,11 +18,13 @@ type MutatingCommand = Extract<
   {
     action:
       | typeof QUEST_ACTIONS.add
+      | typeof QUEST_ACTIONS.split
       | typeof QUEST_ACTIONS.toggle
       | typeof QUEST_ACTIONS.update
       | typeof QUEST_ACTIONS.delete
       | typeof QUEST_ACTIONS.clear
       | typeof QUEST_ACTIONS.reorder
+      | typeof QUEST_ACTIONS.reparent
       | typeof QUEST_ACTIONS.revert;
   }
 >["action"];
@@ -25,7 +32,15 @@ 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,
+  }),
+  [QUEST_ACTIONS.split]: (p) => ({
+    type: QUEST_ACTIONS.split,
+    id: p.id,
+    descriptions: p.descriptions,
+  }),
   [QUEST_ACTIONS.toggle]: (p) => ({ type: QUEST_ACTIONS.toggle, id: p.id }),
   [QUEST_ACTIONS.update]: (p) => ({
     type: QUEST_ACTIONS.update,
@@ -37,16 +52,32 @@ const commandActionBuilders: {
   [QUEST_ACTIONS.reorder]: (p) => ({
     type: QUEST_ACTIONS.reorder,
     id: p.id,
-    targetIndex: p.targetIndex,
+    targetId: p.targetId,
+  }),
+  [QUEST_ACTIONS.reparent]: (p) => ({
+    type: QUEST_ACTIONS.reparent,
+    id: p.id,
+    parentId: p.parentId,
   }),
   [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");
@@ -94,20 +125,19 @@ 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;
       }
       case QUEST_ACTIONS.add:
+      case QUEST_ACTIONS.split:
       case QUEST_ACTIONS.toggle:
       case QUEST_ACTIONS.update:
       case QUEST_ACTIONS.delete:
       case QUEST_ACTIONS.clear:
       case QUEST_ACTIONS.reorder:
+      case QUEST_ACTIONS.reparent:
       case QUEST_ACTIONS.revert: {
         const builder = commandActionBuilders[parsed.action];
         const action = builder(parsed as never);
@@ -121,12 +151,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 <description>           - Add a new top-level quest");
+        lines.push("  add-step <id> <description> - Split a quest into a step");
         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> <idx> - Reorder a quest to index");
+        lines.push("  reparent <id> [parentId] - Reparent a quest/step (omit parentId to promote)");
+        lines.push("  reorder <id> <targetId> - Reorder a quest before the target quest");
         lines.push("  revert             - Revert the last quest change");
         lines.push("  clear [all]        - Clear completed quests, or optionally all quests");
         lines.push("  version            - Show version");

package/src/commands/parse-args.ts

@@ -3,13 +3,15 @@ import { QUEST_ACTIONS } from "../quest/types.js";
 
 export type ParsedArgs =
   | { action: typeof QUEST_ACTIONS.add; descriptions: string[] }
+  | { action: typeof QUEST_ACTIONS.split; id: string; descriptions: 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.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: number; targetIndex: number }
+  | { action: typeof QUEST_ACTIONS.reorder; id: string; targetId: string }
   | { action: typeof QUEST_ACTIONS.revert }
+  | { action: typeof QUEST_ACTIONS.reparent; id: string; parentId?: string }
   | { action: "help" }
   | { action: "version" }
   | { action: "changelog" }
@@ -18,7 +20,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);
 
@@ -42,10 +44,12 @@ export function parseQuestArgs(args: string): ParsedArgs {
 
   // 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.reorder) return parseReorderArgs(rest);
+  if (command === "add-step") return parseAddStepArgs(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);
+  if (command === QUEST_ACTIONS.reparent) return parseReparentArgs(rest, idLength);
 
   return { error: `Unknown subcommand: ${command}. Use /quests help to see available commands.` };
 }
@@ -57,21 +61,31 @@ function parseAddArgs(tokens: string[]): ParsedArgs {
   return { action: QUEST_ACTIONS.add, descriptions: [description] };
 }
 
+function parseAddStepArgs(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 add-step <id> <description>" };
+  const description = tokens.slice(1).join(" ").trim();
+  if (!description) return { error: "Usage: /quests add-step <id> <description>" };
+  return { action: QUEST_ACTIONS.split, id, descriptions: [description] };
+}
+
 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>" };
@@ -85,10 +99,25 @@ function parseClearArgs(tokens: string[]): ParsedArgs {
   return { action: QUEST_ACTIONS.clear, all };
 }
 
-function parseReorderArgs(tokens: string[]): ParsedArgs {
-  const id = Number(tokens[0]);
-  const targetIndex = Number(tokens[1]);
-  if (Number.isNaN(id) || Number.isNaN(targetIndex))
-    return { error: "Usage: /quests reorder <id> <index>" };
-  return { action: QUEST_ACTIONS.reorder, id, targetIndex };
+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 };
+}
+
+function parseReparentArgs(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 reparent <id> [parentId]" };
+
+  const parentId = tokens[1] ? tokens[1].toLowerCase() : undefined;
+  if (parentId && !pattern.test(parentId))
+    return { error: "Usage: /quests reparent <id> [parentId]" };
+
+  return { action: QUEST_ACTIONS.reparent, id, parentId };
 }

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;
+    stepSuggestionToolCallThreshold: 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: 8,
+    hintIntervalMinutes: 4,
+    timeBasedToolCallThreshold: 5,
+    zeroActiveToolCallThreshold: 8,
+    staleProgressToolCallThreshold: 16,
+    stepSuggestionToolCallThreshold: 10,
+    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,
+      stepSuggestionToolCallThreshold:
+        user.nudges?.stepSuggestionToolCallThreshold ??
+        DEFAULT_CONFIG.nudges.stepSuggestionToolCallThreshold,
+      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,8 +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";
@@ -18,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());
@@ -36,17 +72,22 @@ 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);
+    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((step) => (step as { parentId?: string }).parentId === q.id),
+    );
+    const nudge = tracker.getNudge(activeQuestCount, latestPrompt, hasTopLevelQuestWithoutSubs);
 
-    const fakeDoneRegex =
-      /\s[-–—]\s*(DONE|COMPLETED|FINISHED)$|\s[([](DONE|COMPLETED|FINISHED)[)\]]$/i;
+    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;
 
     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.`;
+      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 = {
@@ -59,14 +100,13 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("before_agent_start", async (event) => {
     const quests = questLog.getAll();
-    let reminder = QUEST_PROMPT_REMINDER.join("\n");
+    let reminder = "";
     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");
-
-      reminder += `\n\nActive quests (${remaining}/${quests.length}):\n${list}`;
+      const list = formatQuestList(quests);
+      reminder = `Active quests (${remaining}/${quests.length}):\n${list}\n\nKeep quest progress updated as you work.`;
+    } else {
+      reminder = `${QUEST_PROMPT_REMINDER.join("\n")}\n\nBefore adding any independent quests, clear any previously completed quests from the log to keep it focused on current work.`;
     }
 
     return {
@@ -74,14 +114,6 @@ export default function (pi: ExtensionAPI): void {
     };
   });
 
-  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/skill.md

@@ -0,0 +1,60 @@
+---
+name: quest-management
+description: Quest management best practices for the pi-quests extension. Use when the user asks about tracking tasks, managing quests, using the quest tool, or when you need guidance on how to structure session work into quests and steps.
+---
+
+# Quest Management
+
+## When to use quests
+
+Use the quest tool at the start of any non-trivial task. If the request involves multiple steps, files, tool calls, or minion delegation, track it with quests.
+
+## Capabilities
+
+| Action | Purpose |
+|--------|---------|
+| `add` | Create top-level quests |
+| `split` / `add_step` | Break a quest into steps under a parent |
+| `reparent` | Promote, demote, or move a quest/step via optional `parentId` |
+| `toggle` | Mark a quest or step done/undone |
+| `update` | Change a quest description |
+| `delete` | Remove a quest or step |
+| `clear` | Remove completed quests (or all with `all: true`) |
+| `reorder` | Change the priority order of top-level quests |
+| `revert` | Undo the most recent mutating action |
+| `list` | View all quests and steps |
+
+## Common patterns
+
+### Multi-step task workflow
+1. Add many top-level quests for the overall goal
+2. Split them into steps for each distinct deliverable
+3. Execute steps sequentially, toggling each done as you finish
+4. Toggle the parent quest done only after all steps are complete
+
+### Delegation workflow
+1. Add a quest for the delegated task
+2. Spawn the minion and assign the work
+3. Toggle the quest done when the minion returns successfully
+
+### Reparenting
+- Promote a step: `reparent <step-id>` (omit `parentId`)
+- Demote a quest: `reparent <quest-id> <parent-id>`
+- Move a step: `reparent <step-id> <new-parent-id>`
+
+## Rules
+
+- Steps cannot have nested steps. Only top-level quests can be parents.
+- A parent with incomplete steps cannot be toggled done or deleted.
+- Deleting a done parent cascade-deletes its done steps.
+- Revert only undoes the most recent mutating action.
+- Quest IDs are random hex strings shown in square brackets (e.g., `[01]`, `[a3f1]`).
+- Always use the hex ID for actions, never the positional number.
+
+## Gotchas
+
+- Use toggle for done states. NEVER use `update` to append "DONE", "- DONE", or any completion marker to a quest description.
+- IDs are hex, not positional. The list shows `#1 [01] ...`. Use `01` in tool calls, not `1`.
+- Steps cannot be reordered independently. Use `reorder` on top-level quests only.
+- Clear completed quests before adding unrelated work. This keeps the log focused and reduces context noise.
+- Parent blocked?: If you cannot toggle a parent done, check that all its steps are toggled done first.

package/src/prompts.ts

@@ -1,3 +1,13 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export function getQuestSkillDocument(): string {
+  return readFileSync(join(__dirname, "prompts", "skill.md"), "utf-8");
+}
+
 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.",
@@ -6,10 +16,14 @@ export const QUEST_PROMPT_REMINDER = [
   "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.",
-  "As work evolves, use the reorder action to reflect changes in priority or sequencing.",
+  "ALWAYS use steps to break down a complex quest into smaller steps. To create a step, use the `split` action with the parent quest's hex ID. Use steps 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 steps are completed. Steps cannot be reordered independently.",
   "Before delegating to a minion, add a quest for the delegated task.",
-  "For reorder, targetIndex is 0-based (array index), not a 1-based position. If the user says 'move quest to position 5', use targetIndex 4.",
+  "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.",
+  "When you need to understand the quest system, rules, or best practices, use the quest tool with action: 'skill' or action: 'rules' rather than reading documentation files.",
 ] as const;
 
 export const QUEST_PROMPT_GATE =