quest-loop 0.1.0

package/lib/workers.mjs

@@ -0,0 +1,372 @@
+// Worker adapters for the headless runner. BOTH the Claude and Codex adapters
+// live here. Each exposes the shared interface the runner drives generically:
+//
+//   buildInvocation(questRecord, config, opts) -> { cmd, args, env, prompt, artifactsFile? }
+//   parseResult(stdout, artifacts)             -> { session_id?, cost_usd?, tokens?, events? }
+//
+// plus a higher-level `runSession(ctx)` that composes those two into one runner
+// iteration (a single worker SESSION). Codex's session additionally owns the
+// native-goal correction + same-session continuation resumes; Claude's is a
+// single non-interactive `claude -p` call in native /goal mode.
+//
+// Design invariants:
+// - Adapters never touch the quest store directly. They only shape and parse
+//   worker invocations; the runner owns all `quest` CLI reads/writes.
+// - USD cost is only ever reported when the worker reports it (Claude's
+//   total_cost_usd). Codex cost stays token-only — never fabricated.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+// Non-interactive backstop injected into the Claude system prompt. A headless
+// worker must never block on input; a human-only decision becomes a blocked
+// checkpoint and a stop, which the runner then observes.
+const CLAUDE_APPEND_SYSTEM_PROMPT =
+  "Non-interactive headless run: never wait for input or ask a question. " +
+  "If a decision can only be made by a human, checkpoint the quest with " +
+  "quest_status blocked (via `quest checkpoint`) stating the decision needed, then stop.";
+
+// The machine-generated, conversation-verifiable stopping condition shared by
+// both workers. `runStartIso` makes it verifiable: only a checkpoint newer than
+// the run start satisfies it, so a stale prior checkpoint can't be mistaken for
+// progress.
+function stoppingCondition(id, runStartIso) {
+  return (
+    "the output of `quest show " +
+    id +
+    " --json` shown in this conversation contains a NEW checkpoint (timestamp after " +
+    runStartIso +
+    ") with quest_status complete or blocked"
+  );
+}
+
+function workInstructions(id) {
+  return (
+    "Work quest " +
+    id +
+    " per the /quest:work skill. The quest store is in this directory. " +
+    "End every iteration by running quest show " +
+    id +
+    "."
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Shared parse helpers
+// ---------------------------------------------------------------------------
+
+function tryParseJson(text) {
+  if (!text) return undefined;
+  const trimmed = text.trim();
+  if (!trimmed) return undefined;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // Fall back to the last non-empty line (streamed multi-object stdout).
+    const lines = trimmed.split("\n").filter((l) => l.trim());
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        return JSON.parse(lines[i]);
+      } catch {
+        /* keep scanning upward */
+      }
+    }
+    return undefined;
+  }
+}
+
+function parseJsonl(text) {
+  if (!text) return [];
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+function sumTokens(usage) {
+  if (!usage || typeof usage !== "object") return undefined;
+  const input = num(usage.input_tokens) ?? num(usage.prompt_tokens) ?? 0;
+  const output = num(usage.output_tokens) ?? num(usage.completion_tokens) ?? 0;
+  const total = num(usage.total_tokens);
+  if (total !== undefined) return total;
+  const sum = input + output;
+  return sum > 0 ? sum : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Claude adapter
+// ---------------------------------------------------------------------------
+
+export const claude = {
+  name: "claude",
+
+  buildInvocation(questRecord, config, opts) {
+    const { id } = opts;
+    const prompt =
+      "/goal " +
+      stoppingCondition(id, opts.runStartIso) +
+      "\n" +
+      workInstructions(id);
+    const args = [
+      "-p",
+      prompt,
+      "--plugin-dir",
+      opts.pluginRoot,
+      "--model",
+      opts.model,
+      "--output-format",
+      "json",
+      "--permission-mode",
+      "acceptEdits",
+      "--allowedTools",
+      "Bash,Read,Edit,Write,Glob,Grep,Skill",
+      "--append-system-prompt",
+      CLAUDE_APPEND_SYSTEM_PROMPT,
+    ];
+    if (opts.resumeSessionId) args.push("--resume", opts.resumeSessionId);
+    // Effort is passed via env: CLAUDE_EFFORT is observed-supported; no stable
+    // documented flag at this CLI version, so env is the deliberate seam.
+    // PATH prepends the plugin's bin/ so the worker's Bash can reach the `quest`
+    // CLI to record checkpoints (Claude Code does not guarantee plugin bins on
+    // the child's PATH); QUEST_DIR is added by the runner so records stay central.
+    const basePath = opts.env?.PATH ?? "";
+    const env = {
+      PATH: `${join(opts.pluginRoot, "bin")}:${basePath}`,
+      ...(opts.effort ? { CLAUDE_EFFORT: String(opts.effort) } : {}),
+    };
+    return { cmd: "claude", args, env, prompt };
+  },
+
+  parseResult(stdout /* , artifacts */) {
+    const obj = tryParseJson(stdout);
+    if (!obj) return {};
+    return {
+      session_id: typeof obj.session_id === "string" ? obj.session_id : undefined,
+      cost_usd: num(obj.total_cost_usd),
+      tokens: sumTokens(obj.usage),
+    };
+  },
+
+  // One Claude session = one `claude -p` call in native /goal mode.
+  async runSession(ctx) {
+    const inv = this.buildInvocation(ctx.questRecord, ctx.config, ctx.opts);
+    const { stdout } = await ctx.spawn(inv);
+    const res = this.parseResult(stdout, {});
+    return { ...res, invocations: [inv], sawGoal: true };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Codex adapter
+// ---------------------------------------------------------------------------
+
+const CODEX_MAX_RESUMES = 3;
+
+// Legal `codex exec --sandbox` modes and the default. workspace-write (the
+// default) write-protects `.git`, so a codex worker under it CANNOT `git commit`
+// (the index.lock write fails — confirmed empirically in quest 8's walkthrough).
+// Commit-requiring quests must explicitly opt into danger-full-access via the
+// runner's --codex-sandbox flag (or config defaults.codex.sandbox). The runner
+// validates the resolved value; buildInvocation only consumes it.
+export const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access"];
+export const DEFAULT_CODEX_SANDBOX = "workspace-write";
+
+function codexArtifactsFile() {
+  return join(tmpdir(), `quest-run-codex-${randomUUID()}.json`);
+}
+
+// Recognise an ACTUAL create_goal tool invocation in the codex `--json` event
+// stream — not prose that merely mentions it. Only tool/function/mcp-call event
+// items count, so a narrated "I will create_goal…" is correctly treated as
+// missing and triggers the corrective resume.
+function isToolCallItem(item) {
+  if (!item || typeof item !== "object") return false;
+  const t = String(item.type || "");
+  return /tool_call|function_call|mcp|tool_use|command/i.test(t);
+}
+
+function toolCallName(item) {
+  return String(item?.tool || item?.name || item?.tool_name || item?.function?.name || "");
+}
+
+export function codexUsedCreateGoal(events) {
+  for (const e of events) {
+    // Newer shape: { type: "item.*", item: {...} }
+    if (e && e.item && isToolCallItem(e.item) && toolCallName(e.item).includes("create_goal")) return true;
+    // Legacy shape: { msg: { type, ... } } / flat tool-call event.
+    if (e && e.msg && isToolCallItem(e.msg) && toolCallName(e.msg).includes("create_goal")) return true;
+    if (isToolCallItem(e) && toolCallName(e).includes("create_goal")) return true;
+  }
+  return false;
+}
+
+function codexSessionId(events) {
+  for (const e of events) {
+    const id =
+      e?.session_id ||
+      e?.thread_id ||
+      e?.item?.thread_id ||
+      e?.session?.id ||
+      e?.thread?.id ||
+      (e?.msg && (e.msg.session_id || e.msg.thread_id));
+    if (typeof id === "string" && id) return id;
+  }
+  return undefined;
+}
+
+function codexTokens(events) {
+  let tokens;
+  for (const e of events) {
+    const usage = e?.usage || e?.item?.usage || e?.msg?.usage || (e?.type === "token_count" ? e : undefined);
+    const t = sumTokens(usage);
+    if (t !== undefined) tokens = t; // last usage event wins (running total)
+  }
+  return tokens;
+}
+
+const CODEX_CREATE_GOAL_CORRECTION = (id) =>
+  "You did not invoke the create_goal tool — you narrated it instead. Call the create_goal tool now " +
+  "(a real tool call, not prose) with the stopping condition, verify with get_goal, then continue working quest " +
+  id +
+  " per /quest:work.";
+
+export const codex = {
+  name: "codex",
+
+  buildInvocation(questRecord, config, opts) {
+    const { id } = opts;
+    const prompt =
+      "First step: Create a goal for this thread using the create_goal tool (not as prose) with this exact " +
+      "stopping condition: " +
+      stoppingCondition(id, opts.runStartIso) +
+      '. Verify with get_goal. Only call update_goal(status="complete") AFTER `quest checkpoint` succeeded.' +
+      "\n" +
+      workInstructions(id);
+    const artifactsFile = codexArtifactsFile();
+    const args = [
+      "exec",
+      prompt,
+      "--json",
+      "-m",
+      opts.model,
+      "-C",
+      opts.cwd,
+      "--sandbox",
+      opts.codexSandbox ?? DEFAULT_CODEX_SANDBOX,
+      "--skip-git-repo-check",
+      "-o",
+      artifactsFile,
+      "--output-schema",
+      opts.schemaPath,
+    ];
+    if (opts.effort) args.push("-c", `model_reasoning_effort=${opts.effort}`);
+    // Prepend the plugin's bin/ so the `quest` CLI resolves inside the sandbox.
+    const basePath = opts.env?.PATH ?? "";
+    const env = { PATH: `${join(opts.pluginRoot, "bin")}:${basePath}` };
+    return { cmd: "codex", args, env, prompt, artifactsFile };
+  },
+
+  // Build a `codex exec resume` invocation for the corrective/continuation
+  // segments. `sessionArg` is "--last" or a concrete session/thread id.
+  buildResume(questRecord, config, opts, sessionArg, text) {
+    const artifactsFile = codexArtifactsFile();
+    const args = ["exec", "resume"];
+    if (sessionArg === "--last") args.push("--last");
+    else args.push(sessionArg);
+    args.push(text, "--json", "-C", opts.cwd, "--skip-git-repo-check", "-o", artifactsFile, "--output-schema", opts.schemaPath);
+    if (opts.effort) args.push("-c", `model_reasoning_effort=${opts.effort}`);
+    const basePath = opts.env?.PATH ?? "";
+    const env = { PATH: `${join(opts.pluginRoot, "bin")}:${basePath}` };
+    return { cmd: "codex", args, env, prompt: text, artifactsFile };
+  },
+
+  parseResult(stdout, artifacts = {}) {
+    const events = parseJsonl(stdout);
+    return {
+      session_id: codexSessionId(events),
+      cost_usd: undefined, // codex reports no USD — never fabricated
+      tokens: codexTokens(events),
+      events,
+      lastMessage: artifacts.lastMessage,
+    };
+  },
+
+  readArtifacts(inv) {
+    if (!inv.artifactsFile) return {};
+    try {
+      return { lastMessage: readFileSync(inv.artifactsFile, "utf8") };
+    } catch {
+      return {};
+    }
+  },
+
+  // One Codex iteration: initial segment, then (if create_goal was narrated
+  // rather than invoked) exactly one corrective resume, then same-session
+  // continuation resumes while the stopping condition is unmet — capped at
+  // CODEX_MAX_RESUMES total resume segments per iteration.
+  async runSession(ctx) {
+    const { questRecord, config, opts } = ctx;
+    const invocations = [];
+    let cost, tokens, sessionId;
+    let resumes = 0;
+    let correctiveResume = false;
+
+    const runSegment = async (inv) => {
+      invocations.push(inv);
+      const { stdout } = await ctx.spawn(inv);
+      const res = this.parseResult(stdout, this.readArtifacts(inv));
+      if (res.session_id) sessionId = res.session_id;
+      if (res.tokens !== undefined) tokens = res.tokens;
+      if (res.cost_usd !== undefined) cost = res.cost_usd;
+      return res;
+    };
+
+    // Initial segment.
+    const first = await runSegment(this.buildInvocation(questRecord, config, opts));
+    let sawGoal = codexUsedCreateGoal(first.events || []);
+
+    // Corrective resume: create_goal was narrated, not invoked.
+    if (!sawGoal) {
+      correctiveResume = true;
+      resumes += 1;
+      const corr = this.buildResume(questRecord, config, opts, "--last", CODEX_CREATE_GOAL_CORRECTION(opts.id));
+      const cres = await runSegment(corr);
+      if (codexUsedCreateGoal(cres.events || [])) sawGoal = true;
+    }
+
+    // Same-session continuation while the stopping condition is unmet.
+    while (resumes < CODEX_MAX_RESUMES) {
+      const state = await ctx.readState();
+      const newCheckpoint = (state?.checkpoints?.length ?? 0) > ctx.checkpointsBefore;
+      if (newCheckpoint) break; // condition met — the outer loop will observe it
+      resumes += 1;
+      const arg = sessionId || "--last";
+      const text =
+        `The stopping condition is not yet met: no new checkpoint since ${opts.runStartIso}. ` +
+        `Continue working quest ${opts.id}.`;
+      await runSegment(this.buildResume(questRecord, config, opts, arg, text));
+    }
+
+    return { session_id: sessionId, cost_usd: cost, tokens, invocations, sawGoal, correctiveResume, resumes };
+  },
+};
+
+export function getAdapter(worker) {
+  if (worker === "codex") return codex;
+  if (worker === "claude") return claude;
+  throw new Error(`unknown worker "${worker}" (expected claude or codex)`);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "quest-loop",
+  "version": "0.1.0",
+  "description": "Goal-loop engineering for coding agents: quest contracts, iterative execution with evidence checkpoints, Claude + Codex workers. Ships the `quest` store CLI and the `quest-run` headless runner.",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "bin": {
+    "quest": "./bin/quest",
+    "quest-run": "./bin/quest-run"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "schemas/",
+    "skills/",
+    "agents/",
+    "hooks/",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check:parity": "node scripts/check-agent-parity.mjs",
+    "check:hygiene": "node scripts/check-hygiene.mjs",
+    "check:manifests": "node scripts/validate-manifests.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robertsreberski/quest.git"
+  },
+  "homepage": "https://github.com/robertsreberski/quest",
+  "bugs": "https://github.com/robertsreberski/quest/issues",
+  "keywords": ["goal-loop", "agents", "orchestration", "workflow", "planning", "checkpoints", "claude", "codex", "cli"],
+  "author": "Robert Sreberski",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/schemas/final-report.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Quest worker final report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["quest_status", "checkpoint_recorded", "evidence_summary"],
+  "properties": {
+    "quest_status": {
+      "type": "string",
+      "enum": ["in_progress", "complete", "blocked"],
+      "description": "The quest_status of the checkpoint this session recorded."
+    },
+    "checkpoint_recorded": {
+      "type": "boolean",
+      "description": "True only if `quest checkpoint` was actually run and succeeded this session."
+    },
+    "evidence_summary": {
+      "type": "string",
+      "description": "One line citing the decisive command and its observed result."
+    }
+  }
+}

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: orchestrate
+description: Run the quest loop as orchestrator — dispatch workers on ready quests, verify checkpoints, rule on results, manage waves. Use when asked to orchestrate quests, run an epic, or drive multiple quests to completion.
+argument-hint: "[epic-id]"
+---
+
+# Orchestrate quests
+
+**What this does:** drives quests through workers and rules on the evidence —
+you are the loop engineer, not the implementer.
+**Use when:** more than one quest is in play, or a quest is dispatched rather
+than worked inline.
+**Input:** optionally an epic id to scope to; otherwise the whole store.
+**What you get:** quests moved to complete/blocked with verified checkpoint
+trails, and escalations only where a human ruling is genuinely needed.
+
+## The cycle
+
+1. **Adopt state** (especially at session start):
+   ```bash
+   quest list --ready --json   # the dispatch queue (deps met, priority order)
+   quest runs --active         # headless runners that outlived prior sessions
+   ```
+2. **Dispatch** each ready quest per its record:
+   - `worker: claude` → spawn the `quest-executor` subagent with the record's
+     `model`/`effort` as the dispatch override; prompt = "Work quest <id> per
+     /quest:work."
+   - `worker: codex`, parallel batches, or anything long-running → run
+     `quest-run <id>` in **background Bash** and keep working; you'll be
+     notified when it exits. Parallel file-disjoint quests:
+     `quest-run --ready --parallel 3` (add `--isolate worktree` when they touch
+     the same files).
+3. **Verify before you believe:** when a worker stops, run
+   `quest show <id> --json`. A stop WITHOUT a new checkpoint is a protocol
+   violation — redispatch with exactly that instruction. Never accept a chat
+   summary in place of a recorded checkpoint.
+4. **Review before accepting complete:** for non-trivial quests, spawn
+   `quest-reviewer` on the diff + checkpoint evidence. Every finding gets a
+   disposition: fixed / follow-up quest filed / rejected-with-reason.
+5. **Rule** (quote evidence, never adjectives):
+   - **accept** — the validation_summary's commands actually discharge the
+     Done-when items.
+   - **iterate-with-feedback** — send the specific gap back (continue the
+     subagent, or `quest-run <id> --continue-session`).
+   - **split** — bigger than it looked → `/quest:plan` to decompose; cancel or
+     re-parent the original honestly.
+   - **escalate-to-human** — surface human-only decisions verbatim. Never
+     guess a ruling the human should make.
+6. **Wave done?** When `quest list --ready` empties and nothing is in flight:
+   run `/quest:retro` before starting the next wave.
+
+## Autonomous waves
+
+For an unattended wave, pin your own session to the outcome with a native goal:
+
+```
+/goal every quest in this wave shows complete or blocked in `quest list --json` output
+```
+
+The harness then keeps you cycling until the wave is genuinely done.
+
+## Worked example
+
+```bash
+quest list --ready --json     # → [{"id":12,"worker":"claude"…},{"id":13,"worker":"codex"…}]
+# 12 → dispatch quest-executor subagent (model/effort from the record)
+# 13 → background Bash: quest-run 13
+# …executor stops →
+quest show 12 --json          # new checkpoint? quest_status? evidence?
+# reviewer on 12's diff → findings dispositioned → accept
+```
+
+**Next:** contracts weak? `/quest:plan` to fix them first. Wave finished?
+`/quest:retro`. Vocabulary and stop rules: `/quest:protocol`.

package/skills/orchestrate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Orchestrate Quests"
+  short_description: "Dispatch workers on ready quests, verify checkpoints, rule on evidence"
+  default_prompt: "Use $orchestrate to drive the ready quests to completion."

package/skills/plan/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: plan
+description: Turn an idea, feature request, or bug into quest contracts. Use when planning work as quests, decomposing a large ask into an epic with waves, or when asked to "create a quest" for something.
+argument-hint: "<the ask>"
+---
+
+# Plan work as quests
+
+**What this does:** decomposes an ask into one or more quest contracts —
+Objective, evidence-checkable Done-when, exact Validation loop — written via
+`quest create`.
+**Use when:** turning any ask into executable, verifiable units of work.
+**Input:** the ask, plus whatever code/context you need to read to size it.
+**What you get:** lint-clean quest record(s) an executor can run with zero
+extra context.
+
+## Size it first
+
+| Size | Shape | Rule of thumb |
+|---|---|---|
+| Small | 1 quest, work it inline now | one sitting, one validation run |
+| Medium | 1 quest, dispatch an executor | needs iterations, fits one Objective |
+| Large | epic parent + child quests in waves | multiple objectives; order via `depends_on` |
+
+For epics: create the parent first, then children with `--parent <id>` and
+`--depends-on` expressing the real order. `quest list --ready` becomes the
+dispatch queue — that is the whole wave mechanic.
+
+## Author the contract
+
+Every field earns its place:
+
+- **Objective** (≤3 sentences): one concrete outcome. It is the anchor — it
+  will never be rewritten, so don't bury multiple outcomes in it.
+- **Done when**: each item independently checkable WITH EVIDENCE. Write the
+  check into the item ("`npm test` passes including new theme tests"), not a
+  vibe ("works well").
+- **Validation loop**: the exact commands the executor runs every iteration.
+  If you can't state them, the quest isn't ready to dispatch.
+- **Constraints**: what must hold along the way (not a wish list).
+- **Milestones**: discrete testable units for anything beyond one sitting.
+- **Context**: files + symbols (`resolveConfig` in `lib/config.mjs`), related
+  quests. NEVER bare line numbers — they rot.
+- **Out of scope**: the adjacent work you are explicitly not doing.
+- `--worker` / `--model` / `--effort` / `--max-iterations`: match the tier to
+  the difficulty; the defaults come from `.quests/config.json`.
+
+**Anti-patterns** (lint catches some, you catch the rest): adjective done-whens
+("fast", "clean"); validation loops that are prose, not commands; objectives
+hiding three objectives; context by line number; budgets so big they never bind.
+
+## Worked example
+
+```bash
+quest create --title "Add dark mode to settings" \
+  --objective "The settings page offers a dark theme that persists across reloads." \
+  --done-when "toggling theme switches the UI and survives reload" \
+  --done-when "\`npm test\` passes including new theme tests" \
+  --validation "npm test" \
+  --constraint "no new dependencies" \
+  --milestone "theme toggle renders and switches CSS variables" \
+  --milestone "choice persists via localStorage" \
+  --context "Settings page: src/settings/Page.tsx; theme tokens: src/theme.ts" \
+  --out-of-scope "system-preference auto-detection"
+quest lint 12   # always, before dispatch
+```
+
+**Next:** dispatch with `/quest:orchestrate` (or work it yourself via
+`/quest:work <id>`). Rules and vocabulary: `/quest:protocol`.

package/skills/plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan Quests"
+  short_description: "Turn an ask into evidence-checkable quest contracts"
+  default_prompt: "Use $plan to decompose this ask into quest contracts via `quest create`."

package/skills/protocol/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: protocol
+description: The quest loop rules, checkpoint format, and vocabulary. Use when you need the protocol itself — stop conditions, checkpoint fields, status enums, scope-fence rules — or when judging whether a quest was worked correctly.
+---
+
+# The quest protocol
+
+**What this does:** gives you the canonical rules every quest execution follows.
+**Use when:** working, orchestrating, reviewing, or planning quests and you need
+the exact rule — don't paraphrase from memory.
+**Input:** none.
+**What you get:** the base protocol + this store's local amendments.
+
+## Read it
+
+- [references/protocol.md](references/protocol.md) — the loop: orient → one
+  milestone → verify with stated commands → commit green → checkpoint →
+  stop conditions (`complete` needs every Done-when enumerated with evidence;
+  `blocked` beats improvising), scope fence, honesty rules, rulings, sizing.
+- [references/contract-spec.md](references/contract-spec.md) — the record
+  format: frontmatter fields, body sections, checkpoint bytes, GitHub mapping,
+  exit codes.
+
+In a store, prefer the CLI — it appends the store's own amendments:
+
+```bash
+quest protocol
+```
+
+## The vocabulary that matters most
+
+- Store status: `todo | in_progress | blocked | complete | cancelled`.
+- Checkpoint verdict (`quest_status`): `in_progress | complete | blocked` — the
+  ONLY legal checkpoint vocabulary.
+- A `complete` checkpoint cites backticked commands in `validation_summary`
+  and enumerates every Done-when item as Done / Blocked / Cancelled.
+
+**Next:** plan with `/quest:plan`, execute with `/quest:work`, drive with
+`/quest:orchestrate`, improve with `/quest:retro`.

package/skills/protocol/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Quest Protocol"
+  short_description: "The quest loop rules, checkpoint format, and vocabulary"
+  default_prompt: "Use $protocol to look up the exact quest loop rule before acting."