pi-quests 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [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`

package/README.md

@@ -1,6 +1,6 @@
 # pi-quests
 
-[![version 0.4.0](https://img.shields.io/badge/version-0.4.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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quests",
-  "version": "0.4.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

@@ -18,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"];
@@ -33,7 +35,11 @@ const commandActionBuilders: {
   [QUEST_ACTIONS.add]: (p) => ({
     type: QUEST_ACTIONS.add,
     descriptions: p.descriptions,
-    parentId: p.parentId,
+  }),
+  [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) => ({
@@ -48,6 +54,11 @@ const commandActionBuilders: {
     id: p.id,
     targetId: p.targetId,
   }),
+  [QUEST_ACTIONS.reparent]: (p) => ({
+    type: QUEST_ACTIONS.reparent,
+    id: p.id,
+    parentId: p.parentId,
+  }),
   [QUEST_ACTIONS.revert]: () => ({ type: QUEST_ACTIONS.revert }),
 };
 
@@ -120,11 +131,13 @@ export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog, config
         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);
@@ -138,11 +151,13 @@ export function createQuestsHandler(pi: ExtensionAPI, questLog: QuestLog, config
         logger.debug("quests:cmd", "help");
 
         const lines = ["Available /quests subcommands:"];
-        lines.push("  add [--parent <id>] <description>  - Add a new quest or sub-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("  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");

package/src/commands/parse-args.ts

@@ -2,7 +2,8 @@ import { logger } from "../logger.js";
 import { QUEST_ACTIONS } from "../quest/types.js";
 
 export type ParsedArgs =
-  | { action: typeof QUEST_ACTIONS.add; descriptions: string[]; parentId?: string }
+  | { 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: string }
   | { action: typeof QUEST_ACTIONS.update; id: string; description: string }
@@ -10,6 +11,7 @@ export type ParsedArgs =
   | { action: typeof QUEST_ACTIONS.clear; all?: boolean }
   | { 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" }
@@ -41,30 +43,31 @@ export function parseQuestArgs(args: string, idLength = 2): ParsedArgs {
   if (command === QUEST_ACTIONS.revert) return { action: QUEST_ACTIONS.revert };
 
   // Quest actions with arguments
-  if (command === QUEST_ACTIONS.add) return parseAddArgs(rest, idLength);
+  if (command === QUEST_ACTIONS.add) return parseAddArgs(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.` };
 }
 
-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>" };
+function parseAddArgs(tokens: string[]): ParsedArgs {
+  const description = tokens.join(" ").trim();
+  if (!description) return { error: "Usage: /quests add <description>" };
+
+  return { action: QUEST_ACTIONS.add, descriptions: [description] };
+}
 
-  return { action: QUEST_ACTIONS.add, descriptions: [description], parentId };
+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(
@@ -106,3 +109,15 @@ function parseReorderArgs(tokens: string[], idLength: number): ParsedArgs {
 
   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

@@ -12,7 +12,7 @@ export interface ResolvedConfig {
     timeBasedToolCallThreshold: number;
     zeroActiveToolCallThreshold: number;
     staleProgressToolCallThreshold: number;
-    subQuestSuggestionToolCallThreshold: number;
+    stepSuggestionToolCallThreshold: number;
     complexTaskKeywords: string[];
   };
   validation: { fakeDonePattern: string };
@@ -40,12 +40,12 @@ 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,
+    toolCallThreshold: 8,
+    hintIntervalMinutes: 4,
+    timeBasedToolCallThreshold: 5,
+    zeroActiveToolCallThreshold: 8,
+    staleProgressToolCallThreshold: 16,
+    stepSuggestionToolCallThreshold: 10,
     complexTaskKeywords: [...DEFAULT_COMPLEX_TASK_KEYWORDS],
   },
   validation: { fakeDonePattern: DEFAULT_FAKE_DONE_PATTERN },
@@ -130,9 +130,9 @@ export function getConfig(ctx: Pick<ExtensionContext, "cwd">): ResolvedConfig {
       staleProgressToolCallThreshold:
         user.nudges?.staleProgressToolCallThreshold ??
         DEFAULT_CONFIG.nudges.staleProgressToolCallThreshold,
-      subQuestSuggestionToolCallThreshold:
-        user.nudges?.subQuestSuggestionToolCallThreshold ??
-        DEFAULT_CONFIG.nudges.subQuestSuggestionToolCallThreshold,
+      stepSuggestionToolCallThreshold:
+        user.nudges?.stepSuggestionToolCallThreshold ??
+        DEFAULT_CONFIG.nudges.stepSuggestionToolCallThreshold,
       complexTaskKeywords: [
         ...(user.nudges?.complexTaskKeywords ?? DEFAULT_CONFIG.nudges.complexTaskKeywords),
       ],

package/src/index.ts

@@ -77,7 +77,7 @@ export default function (pi: ExtensionAPI): void {
     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),
+      (q) => !allQuests.some((step) => (step as { parentId?: string }).parentId === q.id),
     );
     const nudge = tracker.getNudge(activeQuestCount, latestPrompt, hasTopLevelQuestWithoutSubs);
 
@@ -100,16 +100,17 @@ 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 = formatQuestList(quests);
-
-      reminder += `\n\nActive quests (${remaining}/${quests.length}):\n${list}`;
+      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 {
-      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.`,
+      systemPrompt: `# Quest Management\n${QUEST_PROMPT_GATE}${event.systemPrompt}\n\n## Quest Management\n${reminder}`,
     };
   });
 

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,13 +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.",
-  "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.",
+  "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.",
   "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 =