pi-quest

A quest journal for the Pi coding agent: every task gets a plan, an adversarial review, and a validation pass, so complex long-running work gets done — and checked — with almost no input from you.

pi-quest gives the agent a work ethic for big tasks. Instead of running straight at a request, it researches, writes a plan, has the plan reviewed, and only then touches code — then it validates what it built against the plan before calling the task done. State is stamped into the conversation and re-read before every reply, so quests survive compactions and restarts without any setup. That makes it possible to hand a low-cost model a long, complex task and get a supervised, verifiable result.

How a quest goes

One quest is active at a time. Every quest runs through three modes:

1. Drafting — the agent may write exactly one file: the draft plan (.pi/quest/future/<qid>.md). Research, reading, and test runs are never blocked. Every content-changing save fires a fresh adversarial reviewer; a PASS promotes to implementing automatically, a FAIL returns findings. You can reply go at any moment to promote immediately — approval is never required.
2. Implementing — the agent works unrestricted from the approved plan. Setbacks and surprises are recorded as amendments; nothing blocks. A change of scope is a new quest.
3. Validation — a validator checks the implementation against the plan and its amendments. A PASS archives the quest (a slim archive/<qid>.zip); a FAIL sends it back to implementing with findings.

Some quests ask for a verdict, not a change: open them with quest_update_state { "kind": "analysis" } and the deliverable is the quest's own ## Analysis section. A draft review PASS auto-claims straight to validation, the validator judges the analysis against a bounded extract of the research, and a FAIL returns the analysis to drafting for revision.

Large tasks split into sub-quests, each running the same three modes under its own quest id (nested up to the depth cap). Plans can be revised mid-way when reality contradicts them: each revision is re-reviewed, prior plans are kept in history, and a rejected revision snaps back to the last good plan. The validator judges plan moves too — the acceptance bar can't be quietly lowered to fit what was built.

Features

• Plan gate — drafting locks every write to the single draft file, so the agent thinks before it codes. Searches, inspections, and test runs flow freely.
• Adversarial review — every draft save boots an independent reviewer that returns PASS or FAIL with findings. A rebuttal with evidence reopens a question rather than arguing in circles.
• Analysis quests — { "kind": "analysis" } turns the quest into a research deliverable: a draft PASS skips implementation and goes straight to validation, the validator checks the analysis against the research transcript, and a FAIL returns it to drafting.
• Sub-quests — complex sub-tasks become full-lifecycle quests up to the depth cap. A failed child never fails its parent: the parent records, adjusts, and continues.
• Durability without setup — quest state lives in the transcript as snapshots, re-read before every reply. Quests survive compaction and restarts; missing state recovers itself automatically.
• Asks that never block — when the agent needs a human decision it records a recommended default, waits a minute, and proceeds on absence. A late answer still applies whenever it arrives.
• Full-screen plan viewer — [^Q] floats the active quest's plan; the status bar shows the current phase and qid at all times.
• External editor — opens the plan in your configured editor (falls back to $EDITOR).
• Idle boot — a fresh session starts idle. Nothing takes over until you describe a request (which opens a quest) or run /quest. With several known quests, /quest lets you pick one.

Installation

pi install npm:@tty-pt/pi-quest

/reload picks up changes. Developing locally: drop the folder into .pi/extensions/pi-quest/ and restart pi.

Usage

Engine usage — commands for the user:

| Command | Effect | |---------|--------| | /quest | Pick a quest when idle, or show the active quest. No argument resumes the newest / presents known quests for selection. | | /quest <qid\|name> | Resume a named quest or drafting phase directly. | | /quests | List all quests with their phases and the active marker. | | /quest-del [qid] | Archive (kill) the current or named quest. Only you can abandon a quest this way. |

Keyboard — the agent's own shortcuts:

| Key | Effect | |-----|--------| | [^Q] | Open the active quest's plan in a floating, near-fullscreen viewer | | External editor | Open the active quest's plan in the external editor (planEditor or $EDITOR) |

The plan viewer

| Key | Effect | |-----|--------| | ↑ / k / ↓ / j | Scroll one line | | PgUp / PgDn / Space | Scroll one page | | Ctrl+U / Ctrl+D | Scroll half a page | | Home / g, End / G | Jump to top / bottom | | Enter, Esc, q | Close the viewer |

The viewer is view-only and best-effort — the draft file stays the source of truth.

The status bar

The footer shows the active quest dimmed, with an [F2] hint, and flashes bright for a few seconds right after the agent saves a draft change:

| Style | Format | Default | |-------|--------|---------| | icon | 📝 <qid> [F2] | yes | | text | drafting <qid> [F2] | |

Phase icons can be any of: 💤 idle · 🔍 provisional · 📝 drafting · 🔨 implementing · 🧪 validating · 📦 archived.

Configuration

All settings are optional and live in .pi/settings.json under "pi-quest":

{
  "pi-quest": {
    "askTimeoutMs": 60000,
    "depthCap": 3,
    "draftThresholds": { "requirements": 2, "evidence": 7 },
    "bindings": { "reviewRunner": { "tool": "subagent" } },
    "statusStyle": "icon",
    "autoArchive": true
  }
}

| Setting | Values | Default | Effect | |---------|--------|---------|--------| | askTimeoutMs | number (ms) | 60000 | How long quest_ask_human waits before proceeding with its recommended default. | | depthCap | number | 3 | How deep sub-quests may nest. | | draftThresholds.requirements | number | 2 | Minimum requirements the draft reviewer demands before passing. | | draftThresholds.evidence | number | 7 | Minimum evidence items (used when below the requirements bar). | | bindings.reviewRunner.tool | tool name | subagent | Sub-agent tool that runs reviewers/validators isolated (falls back to the user path). | | statusStyle | icon / text | icon | How the active quest renders in the status bar. | | autoArchive | true / false | true | Whether a validation PASS concludes and archives the quest automatically; when false, the agent archives manually. |

Workspace on disk

Under .pi/quest/ in the project:

future/<qid>.md     the quest document — one file for the whole life (draft plan, then the editable plan+## Status doc through implementing and validating)
.staging/<qid>/     ephemeral archive staging, removed after zipping (never surfaced, never read back)
archive/<qid>.zip   slim archive of each finished quest (agent doc + rendered view + manifest)

Every quest — draft or active — is identified by a short alphanumeric quest id (qid). The conversation transcript is the source of truth; these files are views.

The agent's tools

Six tools the main agent uses on your behalf:

| Tool | What it does | |------|--------------| | quest_update_state | The write path: records findings, drafts, amendments, next action, completion claims. | | quest_subquest | Spawns a linked sub-quest for a complex sub-task. | | quest_archive | Finishes a quest as complete or failed. Abandoning is user-only (/quest-del). | | quest_recover | Rebuilds quest state from the transcript, including earlier sessions. Runs automatically when state is missing. | | quest_rebut | Answers a review with evidence; a successful rebuttal reopens the question. | | quest_ask_human | Asks you with a recommended default and a timeout — never blocks. |

Requirements

• The Pi coding agent.
• pi-vcc with its compaction override enabled, so compacting is deterministic and never touches the snapshots quest state lives in.
• A sub-agent extension is optional. Without one, reviews and validations degrade to asking you: the plan is presented, a go promotes, and completion is accepted on your confirmation — the quest never stalls for a missing extension.