quest-loop 0.1.0 → 0.3.2

package/skills/protocol/SKILL.md

@@ -35,5 +35,5 @@ quest protocol
 - 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`.
+**Next:** plan with `$quest:plan`, execute with `$quest:work`, drive with
+`$quest:orchestrate`, improve with `$quest:retro`.

package/skills/protocol/agents/openai.yaml

@@ -1,4 +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."
+  default_prompt: "Use $quest:protocol to look up the exact quest loop rule before acting."

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

@@ -72,7 +72,7 @@ updated: 2026-07-07T14:00:00Z
 | `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) |
+| `parent` | no | quest id (epic linking; children derived by scanning). A quest with children is an epic: excluded from `--ready` until every child is terminal (complete/cancelled), and closed by the orchestrator inline — never dispatched to a worker |
 | `depends_on` | no | list of quest ids (wave ordering) |
 | `created` / `updated` | yes | UTC ISO-8601 `…Z` |
 
@@ -135,7 +135,11 @@ Optional free-form note.
 
 - `quest_status` ∈ `in_progress | complete | blocked` — the only legal values.
 - `iteration` required; `pr`, `head_sha`, `failed_approaches`,
-  `compatible_expansion` optional.
+  `compatible_expansion`, `reopen_reason` optional.
+- `reopen_reason` is written only by `quest reopen`: it records why a `complete`
+  quest was legally sent back into the loop (`quest_status: in_progress`), so a
+  fresh session can see why a once-complete quest is in progress again. Old
+  parsers ignore it — `parseCheckpoints` accepts any `- key: value` line.
 - `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:
@@ -149,10 +153,15 @@ 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)
+complete → in_progress        (quest reopen --reason ONLY — never a checkpoint)
 ```
 
-Any other transition is illegal (exit 5). `complete` and `cancelled` are
-terminal.
+Any other transition is illegal (exit 5). `cancelled` is fully terminal.
+`complete` is terminal for **checkpoints** — a stray checkpoint can never
+resurrect it — but the `quest reopen <id> --reason` verb provides the one
+audited path back into the loop, flipping `complete → in_progress` and appending
+a checkpoint carrying `reopen_reason`. This is a separate `assertReopen` path in
+`lib/contract.mjs`, deliberately not part of the checkpoint transition table.
 
 ## GitHub backend mapping
 
@@ -161,7 +170,7 @@ terminal.
 | 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) |
+| status | frontmatter | labels `quest:todo\|in-progress\|blocked\|complete\|cancelled` (+ marker label `quest`); issue state mirrored (complete → closed-completed, cancelled → closed-not-planned, reopen → issue reopened + label swapped back to `quest:in-progress`) |
 | 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`) |

package/skills/protocol/references/protocol.md

@@ -1,7 +1,7 @@
 # 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
+from retros, see `$quest:retro`) live in `.quests/amendments.md` and extend this
 document — read both. `quest protocol` prints them together.
 
 ## Vocabulary
@@ -44,7 +44,11 @@ Each iteration:
 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).
+     follow-up work remain inside this quest (file a new quest instead). If a
+     completed quest is later found defective, the one legal way back into the
+     loop is `quest reopen <id> --reason` (flips `complete → in_progress`,
+     appends an audited `reopen_reason` checkpoint) — never hand-edit a terminal
+     status line. `cancelled` stays fully terminal.
    - `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
@@ -81,7 +85,7 @@ 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`.
+- **split** — the quest was bigger than it looked; decompose via `$quest:plan`.
 - **escalate-to-human** — human-only decisions are surfaced verbatim, never
   guessed.
 
@@ -90,4 +94,8 @@ When reviewing a finished iteration or run, the orchestrator rules one of:
 - **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.
+  `depends_on`; orchestrate wave by wave. The epic itself is never dispatched to
+  a worker: it is gated out of `--ready` while any child is non-terminal, and
+  once the children are done the orchestrator closes it inline (verify children,
+  run the epic validation loop, checkpoint). Keep the epic contract
+  integration-level; its milestones must not mirror the children 1:1.

package/skills/retro/SKILL.md

@@ -46,5 +46,5 @@ quest amend --text "Treat a test that fails twice in one quest as a blocker to e
 quest protocol  # confirm the amendment now rides along
 ```
 
-**Next:** amendments feed every future `/quest:work` orient automatically.
-Start the next wave with `/quest:orchestrate`.
+**Next:** amendments feed every future `$quest:work` orient automatically.
+Start the next wave with `$quest:orchestrate`.

package/skills/retro/agents/openai.yaml

@@ -1,4 +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."
+  default_prompt: "Use $quest:retro to turn this wave's traces into protocol amendments."

package/skills/setup/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: setup
+description: Use when setting up, validating, updating, or troubleshooting Quest's native Codex or Claude plugin integration.
+argument-hint: "[doctor|install-agents|init]"
+---
+
+# Set up Quest native agents
+
+Use this for Codex or Claude integration work, not for ordinary quest execution.
+
+## Project Init
+
+`quest init` creates `.quests/` and, by default, installs project-scoped native
+agent templates for both providers:
+
+- `.codex/agents/quest-executor.toml`
+- `.codex/agents/quest-reviewer.toml`
+- `.claude/agents/quest-executor.md`
+- `.claude/agents/quest-reviewer.md`
+
+Use `quest init --no-agents` when you only want the quest store. If an existing
+project template conflicts, init fails before creating `.quests/`; inspect the
+file, run the explicit provider install command with `--force` only when you
+intend replacement, then rerun `quest init`.
+
+Project-scoped agent templates install at the Git repository root. For a nested
+quest store, use `quest init --no-agents` in the nested directory and set
+`QUEST_DIR` for agents launched from elsewhere, or initialize from the repo root.
+
+## Doctor
+
+Check the installed Codex-facing state from the actual Codex surfaces:
+
+```bash
+quest codex doctor
+```
+
+This verifies the Codex CLI, `quest` binary on PATH, `multi_agent` and `goals`
+feature flags, installed `quest@quest` plugin version, hook parser health,
+duplicate/stale Quest skill roots, and whether the `quest-executor` plus
+`quest-reviewer` native-agent templates are installed and current. Runtime
+dispatch still happens from the parent Codex session via native subagent tools;
+use `quest-run --codex-goal-mode require` only as the headless fallback.
+
+Check the installed Claude-facing state from the actual Claude surfaces:
+
+```bash
+quest claude doctor
+```
+
+## Install Native Agents
+
+Install the Codex custom agents for this repository:
+
+```bash
+quest codex install-agents --scope project
+```
+
+Install the Claude custom agents for this repository:
+
+```bash
+quest claude install-agents --scope project
+```
+
+Use user scope only when you want the agents available everywhere:
+
+```bash
+quest codex install-agents --scope user
+quest claude install-agents --scope user
+```
+
+If an existing file conflicts, inspect it first. Use `--force` only when you
+intend to replace that custom agent with Quest's bundled definition. Symlinked
+agent directories or files are refused rather than overwritten.
+
+## Update Installed Plugin
+
+Codex installs from marketplace snapshots. After updating or releasing Quest,
+refresh and reinstall, then start a new Codex thread:
+
+```bash
+codex plugin marketplace upgrade quest
+codex plugin add quest@quest
+quest codex doctor
+```
+
+If hooks changed, review/trust the updated hook definitions in Codex when
+prompted, then re-run:
+
+```bash
+codex debug prompt-input "noop"
+```

package/skills/setup/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Quest Setup"
+  short_description: "Validate and install Quest's native Codex integration"
+  default_prompt: "Use $quest:setup to validate Quest's Codex plugin install."
+
+policy:
+  allow_implicit_invocation: false

package/skills/work/SKILL.md

@@ -35,7 +35,7 @@ session can resume from.
      --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):
+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.
@@ -69,5 +69,5 @@ 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.
+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

@@ -1,4 +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."
+  default_prompt: "Use $quest:work to execute quest <id> per the quest protocol, ending in a recorded checkpoint."