pi-quests 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-04-17
+
+- fix: system prompt was too weak
+- chore: add more roadmap items
+
+## [0.6.1] - 2026-04-17
+
+- fix: make quest prompt injection static and cache-friendly with `nudges.enable` and `display.showStatus` toggles
+
 ## [0.6.0] - 2026-04-17
 
 - feat: add footer quest progress indicator with configurable icon

package/README.md

@@ -1,6 +1,6 @@
 # pi-quests
 
-[![version 0.6.0](https://img.shields.io/badge/version-0.6.0-blue)](CHANGELOG.md)
+[![version 0.6.2](https://img.shields.io/badge/version-0.6.2-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.6.0",
+  "version": "0.6.2",
   "description": "A quest-log for your pi. Keep your agent on track, one quest at a time.",
   "type": "module",
   "keywords": [

package/src/config.ts

@@ -5,8 +5,9 @@ import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 export interface ResolvedConfig {
   ids: { length: number };
-  display: { pageSize: number; progressBarMaxWidth: number; icon: string };
+  display: { pageSize: number; progressBarMaxWidth: number; icon: string; showStatus: boolean };
   nudges: {
+    enable: boolean;
     toolCallThreshold: number;
     hintIntervalMinutes: number;
     timeBasedToolCallThreshold: number;
@@ -35,8 +36,9 @@ export const DEFAULT_FAKE_DONE_PATTERN = String.raw`\s[-\u2013\u2014]\s*(DONE|CO
 
 export const DEFAULT_CONFIG: ResolvedConfig = {
   ids: { length: 2 },
-  display: { pageSize: 10, progressBarMaxWidth: 24, icon: "󰣏" },
+  display: { pageSize: 10, progressBarMaxWidth: 24, icon: "󰣏", showStatus: true },
   nudges: {
+    enable: true,
     toolCallThreshold: 8,
     hintIntervalMinutes: 4,
     timeBasedToolCallThreshold: 8,
@@ -115,8 +117,10 @@ export function getConfig(ctx: Pick<ExtensionContext, "cwd">): ResolvedConfig {
       progressBarMaxWidth:
         user.display?.progressBarMaxWidth ?? DEFAULT_CONFIG.display.progressBarMaxWidth,
       icon: user.display?.icon ?? DEFAULT_CONFIG.display.icon,
+      showStatus: user.display?.showStatus ?? DEFAULT_CONFIG.display.showStatus,
     },
     nudges: {
+      enable: user.nudges?.enable ?? DEFAULT_CONFIG.nudges.enable,
       toolCallThreshold: user.nudges?.toolCallThreshold ?? DEFAULT_CONFIG.nudges.toolCallThreshold,
       hintIntervalMinutes:
         user.nudges?.hintIntervalMinutes ?? DEFAULT_CONFIG.nudges.hintIntervalMinutes,

package/src/index.ts

@@ -6,7 +6,6 @@ import { DEFAULT_CONFIG, getConfig, type ResolvedConfig } from "./config.js";
 import { logger } from "./logger.js";
 import { QUEST_PROMPT_GATE } 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 { QuestStatusWidget } from "./renderers/status.js";
@@ -22,11 +21,20 @@ import { registerQuestTool } from "./tools/handler.js";
  * - Snapshot relevant session state at each quest milestone.
  * - Provide rollback support to restore a previous snapshot.
  */
+const NO_QUESTS_REMINDER =
+  "No active quests. Use the learn_quests tool to understand how to use quests and use quests to track this task. DO THIS NOW and acknowledge it.";
+
+const FAKE_DONE_REMINDER =
+  "QUEST REMINDER: A quest has a completion marker appended to its description but is not toggled done. Use the list action to find it, then toggle it done. NEVER append completion markers via update.";
+
 export default function (pi: ExtensionAPI): void {
   let questLog = new QuestLog();
   let tracker = new QuestUsageTracker(DEFAULT_CONFIG);
   let config: ResolvedConfig = DEFAULT_CONFIG;
-  let statusWidget = new QuestStatusWidget(DEFAULT_CONFIG.display.icon);
+  let statusWidget = new QuestStatusWidget(
+    DEFAULT_CONFIG.display.icon,
+    DEFAULT_CONFIG.display.showStatus,
+  );
 
   const shortcutKey = getConfig({ cwd: process.cwd() }).shortcuts?.openQuests ?? "ctrl+shift+l";
   logger.debug("quests:shortcut", "register", { key: shortcutKey });
@@ -49,8 +57,9 @@ export default function (pi: ExtensionAPI): void {
     config = getConfig(ctx);
     questLog = new QuestLog(config);
     tracker = new QuestUsageTracker(config);
-    statusWidget = new QuestStatusWidget(config.display.icon);
+    statusWidget = new QuestStatusWidget(config.display.icon, config.display.showStatus);
     questLog.reconstructFromSession(ctx);
+    if (questLog.getAll().length > 0) tracker.markQuestToolUsed();
     statusWidget.update(questLog, ctx.ui, ctx.ui.theme);
 
     registerQuestTool(pi, questLog, config);
@@ -66,6 +75,7 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("session_tree", async (_event, ctx) => {
     questLog.reconstructFromSession(ctx);
+    if (questLog.getAll().length > 0) tracker.markQuestToolUsed();
     statusWidget.update(questLog, ctx.ui, ctx.ui.theme);
   });
 
@@ -79,6 +89,7 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("context", async (event) => {
+    if (!config.nudges.enable) return undefined;
     const latestPrompt = event.messages
       .filter((m) => m.role === "user")
       .map((m) => (typeof m.content === "string" ? m.content : ""))
@@ -91,44 +102,32 @@ export default function (pi: ExtensionAPI): void {
     const hasTopLevelQuestWithoutSubs = activeTopLevel.some(
       (q) => !allQuests.some((step) => (step as { parentId?: string }).parentId === q.id),
     );
-    const nudge = tracker.getNudge(
-      activeQuestCount,
-      allQuests,
-      latestPrompt,
-      hasTopLevelQuestWithoutSubs,
-    );
+    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;
 
-    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 parts: string[] = [];
+    if (nudge) parts.push(nudge);
+    if (fakeDone) parts.push(FAKE_DONE_REMINDER);
 
     const reminder: UserMessage = {
       role: "user",
-      content: content.trim(),
+      content: parts.join("\n"),
       timestamp: Date.now(),
     };
     return { messages: [...event.messages, reminder] };
   });
 
   pi.on("before_agent_start", async (event) => {
-    const quests = questLog.getAll();
-    let reminder = "";
-    if (quests.length > 0) {
-      const remaining = quests.filter((q) => !q.done).length;
-      const list = formatQuestList(quests);
-      reminder = `Active quests (${remaining}/${quests.length}):\n${list}\n\nKeep quest progress updated as you work.`;
-    } else {
-      reminder =
-        "No active quests. Use the quest tool to track your work. Use action: 'skill' for usage documentation.";
-    }
+    if (questLog.getAll().length === 0)
+      return {
+        systemPrompt: `${event.systemPrompt}\n\nUse quests to track this task. DO THIS now and acknowledge it.`,
+      };
 
     return {
-      systemPrompt: `# Quest Management\n${QUEST_PROMPT_GATE}${event.systemPrompt}\n\n## Quest Management\n${reminder}`,
+      systemPrompt: `# Quest Management\n${QUEST_PROMPT_GATE}${event.systemPrompt}\n\n## Quest Management\n${NO_QUESTS_REMINDER}`,
     };
   });
 

package/src/prompts/skill.md

@@ -5,56 +5,53 @@ description: Quest management best practices for the pi-quests extension. Use wh
 
 # 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
+This skill provides guidelines and best practices for using the quest management system in the pi-quests extension. It covers the core actions available for managing quests, recommended workflows for common use cases, and important rules to follow for effective task tracking and progress management.
+
+## Action Reference
+
+| Action | Required Params | Behavior |
+|--------|----------------|----------|
+| `add` | `descriptions[]` | Create top-level quests. Batch multiple descriptions in one call. |
+| `split` | `id`, `descriptions[]` | Break a quest into steps under it. Alias: `add_step`. |
+| `list` | — | View all quests and steps. |
+| `toggle` | `id` | Flip done status. Blocked if parent has incomplete steps. |
+| `update` | `id`, `description` | Change description. |
+| `delete` | `id` | Remove a quest. Blocked if parent has incomplete steps. Cascade-deletes done steps of a done parent. |
+| `clear` | — | Remove completed quests. `all: true` removes everything. |
+| `reorder` | `id`, `targetId` | Move a top-level quest before `targetId`. Steps cannot be reordered. |
+| `reparent` | `id`, `parentId?` | Demote to step under `parentId`, or promote to top-level if `parentId` omitted. |
+| `revert` | — | Undo the most recent mutating action. One level only. |
+| `rules` / `skill` | — | Return this document. |
+
+## Workflows
+
+### Multi-step task
+1. `add` top-level quests for the overall goal
+2. `split` them into steps for each deliverable
+3. Execute steps sequentially, `toggle` each done as you finish
+4. `add` other top-level quests for other related work of this goal
+4. `toggle` the parent done only after all steps are complete
+
+### Delegation
+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.
+### Cleanup
+- `clear` completed quests before adding unrelated work. Keeps the log focused.
 
-## Gotchas
+## Rules
 
-- 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.
+- ALWAYS use quests for any work that involves multiple turns.
+- NEVER try to nest steps. Only top-level quests can be parents.
+- NEVER mark a parent as done if they have incomplete steps.
+- NEVER delete a quest with incomplete steps.
+- Use revert if you make a mistake to undo an action.
+- ALWAYS use the hex ID, never the positional number when referring to quests in actions.
+- ALWAYS Use `toggle` for done states. NEVER use `update` to append "DONE" or any completion marker to a description.
+- If a parent toggle is blocked, check that all its steps are done first.

package/src/quest/tracker.ts

@@ -1,20 +1,8 @@
 import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
-import type { Quest } from "./types.js";
 
 const ACKNOWLEDGEMENT = "Update your quest status before continuing.";
 
-function formatActiveQuests(allQuests: Quest[], limit = 3): string {
-  const active = allQuests.filter((q) => !q.done);
-  if (active.length === 0) return "";
-
-  const shown = active.slice(0, limit);
-  const lines = shown.map((q) => `  [${q.id}]: ${q.description}`);
-  if (active.length > limit) lines.push(`  ... and ${active.length - limit} more`);
-
-  return `\nActive quests:\n${lines.join("\n")}`;
-}
-
 type NudgeCandidate = { index: number; message: string };
 
 export class QuestUsageTracker {
@@ -43,9 +31,17 @@ export class QuestUsageTracker {
     this.nudgedThisTurn = false;
   }
 
+  get hasUsedQuestTool(): boolean {
+    return this.hasEverUsedQuestTool;
+  }
+
+  markQuestToolUsed(): void {
+    this.hasEverUsedQuestTool = true;
+    this.lastQuestToolTime = Date.now();
+  }
+
   getNudge(
     activeQuestCount: number,
-    allQuests: Quest[],
     latestPrompt?: string,
     hasTopLevelQuestWithoutSubs?: boolean,
   ): string | undefined {
@@ -67,7 +63,6 @@ export class QuestUsageTracker {
 
     const eligible = this.getEligibleNudges(
       activeQuestCount,
-      allQuests,
       latestPrompt,
       hasTopLevelQuestWithoutSubs,
     );
@@ -101,7 +96,6 @@ export class QuestUsageTracker {
 
   private getEligibleNudges(
     activeQuestCount: number,
-    allQuests: Quest[],
     latestPrompt?: string,
     hasTopLevelQuestWithoutSubs?: boolean,
   ): NudgeCandidate[] {
@@ -111,7 +105,7 @@ export class QuestUsageTracker {
     if (this.totalToolCalls >= this.config.nudges.toolCallThreshold && !this.hasEverUsedQuestTool) {
       candidates.push({
         index: 0,
-        message: `QUEST REMINDER: You have made ${this.totalToolCalls} tool calls but have NEVER used the quest tool this session. USE the quest tool to initialize tracking and break your work into concrete steps. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: You have made multiple tool calls but have NEVER used the quest tool this session. USE the quest tool to initialize tracking and break your work into concrete steps. ${ACKNOWLEDGEMENT}`,
       });
     }
 
@@ -119,7 +113,7 @@ export class QuestUsageTracker {
     if (activeQuestCount === 0 && latestPrompt && this.isComplexPrompt(latestPrompt)) {
       candidates.push({
         index: 1,
-        message: `QUEST REMINDER: Your latest prompt is a complex task, but there are 0 active quests. USE the quest tool to break this into concrete, trackable steps. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: Your latest prompt looks like a complex task, but there are 0 active quests. USE the quest tool to break it into concrete, trackable steps. ${ACKNOWLEDGEMENT}`,
       });
     }
 
@@ -130,10 +124,9 @@ export class QuestUsageTracker {
       this.consecutiveNonQuestToolCalls >= this.config.nudges.timeBasedToolCallThreshold &&
       Date.now() - this.lastQuestToolTime >= this.config.nudges.hintIntervalMinutes * 60 * 1000
     ) {
-      const questContext = formatActiveQuests(allQuests);
       candidates.push({
         index: 2,
-        message: `QUEST REMINDER: It has been a while since your last quest tool use and ${this.consecutiveNonQuestToolCalls} tools have been called since then. ALIGN on quest status before continuing.${questContext} ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: It has been a while since your last quest tool use and many tools have been called since then. ALIGN on quest status before continuing. ${ACKNOWLEDGEMENT}`,
       });
     }
 
@@ -144,7 +137,7 @@ export class QuestUsageTracker {
     ) {
       candidates.push({
         index: 3,
-        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and there are 0 active quests. TRACK your work with specific, actionable quests. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: You have made several consecutive tool calls without using the quest tool and there are 0 active quests. TRACK your work with specific, actionable quests. ${ACKNOWLEDGEMENT}`,
       });
     }
 
@@ -157,7 +150,7 @@ export class QuestUsageTracker {
     ) {
       candidates.push({
         index: 4,
-        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and have active top-level quests without steps. Consider the quest complexity and use the \`split\` action to break them into smaller steps and track progress. ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: You have made several consecutive tool calls without using the quest tool and have active top-level quests without steps. Consider whether decomposing them with the \`split\` action would help track progress. ${ACKNOWLEDGEMENT}`,
       });
     }
 
@@ -168,10 +161,9 @@ export class QuestUsageTracker {
       this.lastQuestToolTime > 0 &&
       Date.now() - this.lastQuestToolTime >= this.config.nudges.hintIntervalMinutes * 60 * 1000
     ) {
-      const questContext = formatActiveQuests(allQuests);
       candidates.push({
         index: 5,
-        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool despite having active quests. UPDATE your quest progress to reflect current status.${questContext} ${ACKNOWLEDGEMENT}`,
+        message: `QUEST REMINDER: You have made many consecutive tool calls without using the quest tool despite having active quests. UPDATE your quest progress to reflect current status. ${ACKNOWLEDGEMENT}`,
       });
     }
 

package/src/renderers/status.ts

@@ -5,13 +5,18 @@ export class QuestStatusWidget {
   private readonly key = "pi-quests";
   private readonly barWidth = 5;
 
-  constructor(private readonly icon: string) {}
+  constructor(
+    private readonly icon: string,
+    private readonly enabled: boolean = true,
+  ) {}
 
   update(
     questLog: QuestLog,
     ui: { setStatus(key: string, text: string | undefined): void },
     theme: Theme,
   ): void {
+    if (!this.enabled) return;
+
     const all = questLog.getAll();
     const total = all.length;
     const done = all.filter((q) => q.done).length;

package/src/tools/handler.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { Static } from "@sinclair/typebox";
+import { type Static, Type } from "@sinclair/typebox";
 import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
 import { QUEST_PROMPT_GATE, QUEST_PROMPT_REMINDER } from "../prompts.js";
@@ -106,7 +106,7 @@ function runTool(
     ? questLog.getAll()
     : result.quest
       ? [result.quest]
-      : undefined;
+      : [];
 
   return makeToolResult(result.message, questLog, displayQuests);
 }
@@ -132,10 +132,10 @@ export function registerQuestTool(
     label: "Quest",
     description:
       "Manage the session quest log and retrieve the complete quest system documentation. " +
-      "Use this VERY frequently to track tasks, plans, and progress. " +
       "When you need to understand quests, steps, rules, or best practices, use action: 'skill' or action: 'rules'.",
     promptSnippet:
-      "Manage quests and steps, or retrieve quest rules and best practices via skill/rules",
+      "Manage quests and steps, or retrieve quest rules and best practices via skill/rules. " +
+      "Use this VERY frequently to track tasks, plans, and progress. ",
     promptGuidelines: [QUEST_PROMPT_GATE, ...QUEST_PROMPT_REMINDER],
     parameters: createQuestParams(config.ids.length),
     execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>
@@ -143,4 +143,24 @@ export function registerQuestTool(
     renderCall: renderQuestCall,
     renderResult: renderQuestResult(config),
   });
+
+  pi.registerTool({
+    name: "learn_quests",
+    label: "Learn Quests",
+    description: "Learn about the quest system and how to use it effectively.",
+    promptSnippet: "Use this tool to learn about the quest system and how to use it effectively.",
+    promptGuidelines: [
+      "Use this tool when on a session to understand how and when to use quests.",
+      "ALWAYS run this tool when on a new session before starting any work.",
+    ],
+    parameters: Type.Object(
+      {},
+      { description: "No parameters required for learning about quests" },
+    ),
+    execute: async (_toolCallId, _params, _signal, _onUpdate, _ctx) =>
+      questToolExecute(questLog, "learn_quests", { action: QUEST_ACTIONS.skill }),
+    renderCall: (_args, theme, context) =>
+      renderQuestCall({ action: QUEST_ACTIONS.skill }, theme, context),
+    renderResult: renderQuestResult(config),
+  });
 }