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:

Keyboard — the agent's own shortcuts:

The plan 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:

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,
    "judgeMode": "auto",
    "judgeUrl": "http://127.0.0.1:4242",
    "judgeModel": "qwen",
    "judgeFallback": "heuristic"
  }
}

Intelligent Quest Intent Detection (Jev System One)

When idle, pi-quest listens for new user requests to start a quest automatically. Instead of relying solely on brittle regexes or opening quests unconditionally on casual dialogue (such as "I spoke to my grandfather..." or memory recall questions), pi-quest uses an intelligent decision judge:

• Automatic Intent Classification: In "auto" or "systemone" mode, the judge submits a typed choice question (quest_intent) to determine whether the user wants to initiate software engineering work (quest) versus casual conversation or questions (conversation).
• Shared Infrastructure: If you already use pi-mm paired with local axil-auren, pi-quest automatically shares the local judge endpoint and settings with zero additional configuration.
• Fail-Open & Resilient: If the inference service is offline or restarting, pi-quest never disrupts your conversation: it cleanly degrades to local heuristics or skips according to judgeFallback.

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:

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.