pi-quests 0.6.1 → 0.6.2

package/CHANGELOG.md

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

package/README.md

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

@@ -22,7 +22,7 @@ import { registerQuestTool } from "./tools/handler.js";
  * - Provide rollback support to restore a previous snapshot.
  */
 const NO_QUESTS_REMINDER =
-  "No active quests. Use the quest tool to track your work. Use action: 'skill' for usage documentation.";
+  "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.";
@@ -121,7 +121,11 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("before_agent_start", async (event) => {
-    if (tracker.hasUsedQuestTool) return undefined;
+    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${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/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),
+  });
 }