quest-loop 0.1.0

package/skills/protocol/references/contract-spec.md

@@ -0,0 +1,197 @@
+# Quest record format specification
+
+This is the byte-level contract for quest records. The `quest` CLI is the
+single write path — records are only created and mutated through it, in both
+backends. Everything here round-trips through `lib/contract.mjs`.
+
+## Store layout (local backend)
+
+```
+.quests/
+├── config.json        # backend selection + defaults
+├── quests/            # one file per quest: NNN-slug.md
+├── amendments.md      # numbered protocol amendments (always local)
+└── runs.ndjson        # runner journal (always local, gitignore-able)
+```
+
+`NNN` is the zero-padded quest id (`001`, `002`, …). `slug` is derived from the
+title: lowercase, `[a-z0-9-]`, max 40 chars.
+
+## config.json
+
+```json
+{
+  "backend": "local",
+  "github": { "repo": "owner/name" },
+  "defaults": {
+    "worker": "claude",
+    "claude": { "model": "opus", "effort": "xhigh" },
+    "codex": { "model": "gpt-5.5", "reasoning_effort": "medium" },
+    "max_iterations": 8,
+    "priority": "p2"
+  },
+  "notify": { "command": "" }
+}
+```
+
+Resolution order: `QUEST_DIR` env (points at a `.quests/` dir) →
+`QUEST_BACKEND` env (overrides backend only) → nearest `.quests/config.json`
+walking up from cwd. Not found → every command except `init` exits `3`.
+
+## Frontmatter (strict YAML subset)
+
+Only two shapes are legal: `key: scalar` and `key: [a, b, c]` (inline list).
+No nesting, no multi-line values, no quotes-with-escapes. Optional keys are
+**omitted entirely**, never `null`. The parser rejects anything else with a
+precise error (exit 5) — there is no best-effort mode.
+
+```yaml
+---
+id: 12
+title: Add --json output to the list command
+status: todo
+priority: p2
+worker: claude
+model: inherit
+max_iterations: 8
+parent: 3
+depends_on: [10, 11]
+created: 2026-07-07T12:00:00Z
+updated: 2026-07-07T14:00:00Z
+---
+```
+
+| Field | Required | Values |
+|---|---|---|
+| `id` | yes | positive integer, store-assigned |
+| `title` | yes | plain string |
+| `status` | yes | `todo \| in_progress \| blocked \| complete \| cancelled` |
+| `priority` | yes | `p0 \| p1 \| p2` |
+| `worker` | yes | `claude \| codex` |
+| `model` | yes | verbatim model string passed to the worker, or `inherit` (use config default) |
+| `effort` | no | reasoning effort passed to the worker (e.g. `xhigh`); omitted = config default |
+| `max_iterations` | yes | positive integer (counts runner **sessions**) |
+| `max_cost` | no | USD number; omitted = uncapped |
+| `parent` | no | quest id (epic linking; children derived by scanning) |
+| `depends_on` | no | list of quest ids (wave ordering) |
+| `created` / `updated` | yes | UTC ISO-8601 `…Z` |
+
+## Body sections (canonical order)
+
+`## Objective`, `## Done when`, `## Validation loop` are lint-required; the
+rest are optional but keep this order when present.
+
+```markdown
+# {title}
+
+## Objective
+One concrete outcome, at most 3 sentences. This is the anchor — it may be
+compatibly expanded, never redefined.
+
+## Done when
+- [ ] Each item independently checkable, with evidence.
+- [ ] Adjectives are not evidence; commands and observable outcomes are.
+
+## Validation loop
+```bash
+<exact commands the executor runs each iteration>
+```
+
+## Constraints
+- Hard guardrails that must hold along the way.
+
+## Milestones
+- [ ] M1 — discrete testable unit
+- [ ] M2 — …
+
+## Context
+Pointers: files + symbols (never bare line numbers), docs, related quests.
+
+## Out of scope
+- Explicit exclusions.
+
+## Checkpoints
+(append-only; written by `quest checkpoint` only)
+```
+
+## Checkpoint block
+
+Identical bytes in both backends (local: appended under `## Checkpoints`;
+GitHub: an issue comment). The HTML marker makes discovery deterministic.
+
+```markdown
+<!-- quest:checkpoint -->
+### 2026-07-07T14:32:00Z — quest_status: in_progress
+- iteration: 2
+- pr: https://github.com/owner/repo/pull/12
+- head_sha: abc1234
+- changed: M2 done — one line per milestone touched
+- validation_summary: `npm test` → 42 passed, 0 failed; `quest lint 12` → exit 0
+- failed_approaches: tried X; failed because Y
+- compatible_expansion: added done-when item Z because …
+
+Optional free-form note.
+```
+
+- `quest_status` ∈ `in_progress | complete | blocked` — the only legal values.
+- `iteration` required; `pr`, `head_sha`, `failed_approaches`,
+  `compatible_expansion` optional.
+- `validation_summary` required. When `quest_status: complete`, lint requires
+  at least one backticked command in it (commands, not adjectives).
+- A checkpoint's `quest_status` drives the store `status` transition:
+  `in_progress → in_progress`, `complete → complete`, `blocked → blocked`.
+
+## Status transitions
+
+```
+todo → in_progress            (quest start, or first checkpoint)
+in_progress → complete        (checkpoint quest_status: complete)
+in_progress → blocked         (checkpoint quest_status: blocked)
+blocked → in_progress         (new checkpoint quest_status: in_progress)
+todo|in_progress|blocked → cancelled   (quest cancel --reason)
+```
+
+Any other transition is illegal (exit 5). `complete` and `cancelled` are
+terminal.
+
+## GitHub backend mapping
+
+| Concept | Local | GitHub (`gh` only) |
+|---|---|---|
+| record | `quests/NNN-slug.md` | issue; body = same body sections |
+| orchestration metadata | frontmatter | `<!-- quest:meta -->` HTML block at top of body (same `key: value` lines) |
+| id | frontmatter `id` | issue number |
+| status | frontmatter | labels `quest:todo\|in-progress\|blocked\|complete\|cancelled` (+ marker label `quest`); issue state mirrored (complete → closed-completed, cancelled → closed-not-planned) |
+| priority | frontmatter | labels `quest-p0\|p1\|p2` |
+| checkpoint | appended section | issue comment, identical bytes |
+| parent/child | child `parent:` | child meta `parent:` + epic body `## Children` task list (`- [ ] #12`) |
+| config, amendments, runs | `.quests/` | still `.quests/` local — only records live remotely |
+
+Fail-honest: every `gh` failure surfaces gh's own stderr and exits `6`. There
+is no fallback from `github` to `local`.
+
+## Worker final-report schema
+
+Headless workers end each session with a final message conforming to
+`schemas/final-report.schema.json`:
+
+```json
+{
+  "quest_status": "in_progress | complete | blocked",
+  "checkpoint_recorded": true,
+  "evidence_summary": "one line citing the decisive command + result"
+}
+```
+
+## CLI exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 2 | usage error (bad flags/arguments) |
+| 3 | no quest store found / config invalid |
+| 4 | quest not found |
+| 5 | contract violation (lint failure, malformed record, illegal transition, missing checkpoint fields) |
+| 6 | backend unavailable (gh missing, unauthenticated, network) |
+
+Runner (`quest-run`) adds: `10` ended blocked · `11` budget exhausted.

package/skills/protocol/references/protocol.md

@@ -0,0 +1,93 @@
+# The quest loop protocol
+
+This is the base protocol every quest execution follows. Local amendments (mined
+from retros, see `/quest:retro`) live in `.quests/amendments.md` and extend this
+document — read both. `quest protocol` prints them together.
+
+## Vocabulary
+
+- A **quest** is a goal contract: one Objective, evidence-checkable "Done when"
+  conditions, a Validation loop of exact commands, Constraints, and optional
+  Milestones. The record format is defined in [contract-spec.md](./contract-spec.md).
+- **Store status** (record lifecycle): `todo | in_progress | blocked | complete | cancelled`.
+- **quest_status** (checkpoint verdict, the only vocabulary allowed in
+  checkpoints): `in_progress | complete | blocked`.
+- A **checkpoint** is an evidence-citing progress entry appended to the quest
+  record via `quest checkpoint`. Checkpoints are the resume artifact: a fresh
+  session with zero prior context must be able to continue the quest from the
+  record and its checkpoints alone.
+
+## The loop
+
+Each iteration:
+
+1. **Orient.** Read the full quest record (`quest show <id>`), the protocol
+   (`quest protocol`), all prior checkpoints, and the referenced files. Check
+   recent history (`git log --oneline -5`). Re-verify every reference cited in
+   the record — cite **symbol + file** (`resolveConfig` in `lib/config.mjs`),
+   never bare line numbers, which rot within hours. If a cited reference is
+   stale, post the correction in your first checkpoint.
+2. **One milestone per iteration.** Pick the smallest unfinished milestone and
+   implement it end-to-end. If the quest has no milestones, treat the whole
+   Objective as one milestone.
+3. **Verify with the stated validation loop.** Run the quest's Validation loop
+   commands exactly as written. **Never silently substitute a different check**
+   for a stated one — if an equivalent check must be used, name the
+   substitution and why in the checkpoint.
+4. **Commit green, never red.** Commit the verified milestone with a clear
+   message. Do not commit failing states.
+5. **Checkpoint.** Record progress via `quest checkpoint` using the canonical
+   fields (see contract-spec). `validation_summary` cites exact commands and
+   their observed results — commands, not adjectives. Floor: at least one
+   checkpoint at completion, plus one at any blocker; per-milestone checkpoints
+   when a quest has more than 4 milestones.
+6. **Evaluate stop conditions.**
+   - `complete` — every "Done when" item is enumerated as
+     **Done / Blocked / Cancelled** with its evidence, and no new TODOs or
+     follow-up work remain inside this quest (file a new quest instead).
+   - `blocked` — (a) two consecutive iterations failing on the same error,
+     (b) a decision only a human can make, or (c) an unsatisfiable "Done when"
+     — name the exact discrepancy and the corrected anchor; **never improvise
+     a replacement**. Record the blocker precisely and stop.
+   - **Budget** — respect `max_iterations` (and cost caps where enforced); if
+     exceeded, checkpoint `blocked` with the reason and stop.
+
+## Scope fence
+
+Implement exactly and only the Objective. Scope may **compatibly expand**
+(additions that serve the same Objective) with explicit rationale recorded via
+`quest edit --rationale` or a `compatible_expansion` checkpoint field. The
+Objective and existing "Done when" anchors are never rewritten. Adjacent
+improvements go into new quests.
+
+## Honesty rules
+
+- Never edit or delete existing tests to make them pass.
+- Never hide failures behind fallbacks or fake success states; surface the real
+  error and fail loudly.
+- Report outcomes faithfully: failing checks are reported as failing, skipped
+  steps as skipped.
+
+## Review disposition
+
+Every external review finding (human or automated) gets an explicit disposition
+before the work merges: **fixed**, **follow-up quest filed** (linked), or
+**rejected with reason**. Unreplied findings are protocol violations.
+
+## Orchestrator rulings
+
+When reviewing a finished iteration or run, the orchestrator rules one of:
+
+- **accept** — the checkpoint's evidence actually satisfies the Done-when items
+  it claims (quote the commands; never accept adjectives).
+- **iterate-with-feedback** — send the specific gap back to the executor.
+- **split** — the quest was bigger than it looked; decompose via `/quest:plan`.
+- **escalate-to-human** — human-only decisions are surfaced verbatim, never
+  guessed.
+
+## Sizing
+
+- **Small** — one quest, worked inline in the current session.
+- **Medium** — one quest dispatched to an executor (subagent or headless run).
+- **Large** — an epic (parent quest) with child quests in dependency waves via
+  `depends_on`; orchestrate wave by wave.

package/skills/retro/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: retro
+description: Mine finished quest traces into numbered protocol amendments. Use when a quest or wave just finished, when the same failure appeared twice, or when asked to run a retrospective.
+---
+
+# Retro — turn traces into amendments
+
+**What this does:** examines what actually happened (checkpoints, diffs, review
+threads) and encodes the deltas as numbered amendments future sessions read.
+**Use when:** a wave completed, a quest went sideways, or evidence contradicts
+the current protocol.
+**Input:** the finished quests' records and their surrounding artifacts.
+**What you get:** `.quests/amendments.md` entries served to every future orient
+via `quest protocol` — the loop that improves the loop.
+
+## Procedure
+
+1. **Gather evidence:**
+   ```bash
+   quest list --status complete --json && quest list --status blocked --json
+   quest show <id>            # read the checkpoint trails, not your memory
+   git log --oneline -20
+   ```
+2. **Mine for deltas** — ask, with evidence:
+   - Where did a stated check get silently substituted?
+   - What blocked twice for the same reason? What reference had rotted?
+   - Which checkpoint could a fresh session NOT have resumed from?
+   - Where did vocabulary drift (statuses invented, fields skipped)?
+   - What did a reviewer catch that the validation loop should have?
+3. **Write amendments** — imperative, numbered, each citing its evidence:
+   ```bash
+   quest amend --text "State the expected test count in validation_summary — quest 12's 'tests pass' hid three skipped tests (checkpoint 2026-07-07T14:32Z)."
+   ```
+   One behavioral change per amendment. No platitudes — if it doesn't change
+   what the next executor does, it's not an amendment.
+4. **Record what worked** as a "keep doing" amendment when a practice earned
+   its keep (evidence included) — protocols erode when only failures get ink.
+5. **Nothing to amend?** Say so explicitly: an honest "no deltas this wave"
+   entry beats silence.
+
+## Worked example
+
+```bash
+quest show 12   # blocked twice on the same flaky test before anyone noticed
+quest amend --text "Treat a test that fails twice in one quest as a blocker to escalate, not to retry — quest 12 burned 3 iterations rerunning a flaky suite (checkpoints 3–5)."
+quest protocol  # confirm the amendment now rides along
+```
+
+**Next:** amendments feed every future `/quest:work` orient automatically.
+Start the next wave with `/quest:orchestrate`.

package/skills/retro/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Quest Retro"
+  short_description: "Mine finished quest traces into numbered protocol amendments"
+  default_prompt: "Use $retro to turn this wave's traces into protocol amendments."

package/skills/work/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: work
+description: Execute one quest iteratively to a checkpointed stop. Use when asked to work a quest by id, when dispatched as a quest executor, or when resuming a quest a previous session left in_progress or blocked.
+argument-hint: "<quest-id>"
+---
+
+# Work a quest
+
+**What this does:** runs the quest loop on ONE quest — iterate in small verified
+increments until the quest is `complete` or honestly `blocked`.
+**Use when:** you were given a quest id to execute (by a human or an orchestrator).
+**Input:** a quest id; the record is the whole spec — no other context is assumed.
+**What you get:** working, committed changes plus a checkpoint trail any fresh
+session can resume from.
+
+## The iteration
+
+1. **Orient** (every session, no exceptions):
+   ```bash
+   quest show <id> --json     # the contract + prior checkpoints
+   quest protocol             # the rules + this store's amendments
+   git log --oneline -5
+   ```
+   If the quest is `todo`, run `quest start <id>`. Re-verify every file/symbol
+   reference cited in the record; if one is stale, say so in your first checkpoint.
+2. **Pick the smallest unfinished milestone** (or the whole Objective if there
+   are none) and implement it end-to-end.
+3. **Verify with the quest's stated Validation loop** — run those commands
+   exactly. If you must substitute an equivalent check, name the substitution
+   and why in the checkpoint. Never invent a friendlier check.
+4. **Commit green, never red.**
+5. **Checkpoint** — the only way progress exists:
+   ```bash
+   quest checkpoint <id> --status in_progress \
+     --summary "M2 done — <one line per milestone touched>" \
+     --validation "\`npm test\` → 42 passed, 0 failed"
+   ```
+6. **Check stop conditions** (see `/quest:protocol` for the full rules):
+   - All Done-when items hold with evidence → final checkpoint with
+     `--status complete`, whose `--note` enumerates EVERY Done-when item as
+     Done / Blocked / Cancelled with its evidence.
+   - Same error two iterations in a row, a human-only decision, or an
+     unsatisfiable Done-when → `--status blocked` naming the exact blocker.
+     Blocked is a good stop; improvising past it is not.
+   - Budget (`max_iterations`) exceeded → blocked with reason.
+   Otherwise: loop to step 2.
+7. **End every session by displaying the state** — run `quest show <id>` so the
+   recorded checkpoint is visible in the conversation (goal-mode evaluators and
+   orchestrators verify from it).
+
+## Scope fence
+
+Implement exactly and only the Objective. Additions that serve the same
+objective go through `quest edit <id> --add-done-when … --rationale …`.
+Adjacent improvements: note them for a NEW quest; never fold them in.
+
+## Worked example
+
+```bash
+quest show 12 --json          # objective: "settings page offers dark mode…"
+quest start 12
+# …implement milestone M1, then:
+npm test                      # the quest's stated validation loop
+git commit -m "feat: dark mode toggle (quest 12, M1)"
+quest checkpoint 12 --status in_progress \
+  --summary "M1 — theme toggle renders and switches CSS vars" \
+  --validation "\`npm test\` → 38 passed"
+quest show 12
+```
+
+**Next:** finished or blocked → the orchestrator (or human) rules on your
+checkpoint — see `/quest:orchestrate`. Learned something protocol-worthy →
+mention it so `/quest:retro` can turn it into an amendment.

package/skills/work/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Work a Quest"
+  short_description: "Execute one quest iteratively to a checkpointed stop"
+  default_prompt: "Use $work to execute quest <id> per the quest protocol, ending in a recorded checkpoint."