@ritualai/cli 0.36.37 → 0.36.39

package/skills/vscode/ritual/references/build-flow.md

@@ -4,6 +4,31 @@ Walks the engineer from a free-form problem statement to vetted, accepted Ritual
 
 Output: a fully-closed loop — **exploration in COMPLETE state, recommendations accepted (or explicitly handed off to an admin), build brief generated, code implemented, and `sync_implementation` called to register the result in the knowledge graph**. The engineer stays in the driver's seat through concise status updates and explicit pauses only at real decision gates.
 
+### ON ENTRY — do this FIRST, then stay on the pipeline (load-bearing)
+<!-- skill-options:no-gate-change: entry-point + planning-phase trigger — names the existing Step 0.7 first action and the existing pre-brief pipeline; adds no pause gate or options -->
+
+The instant `/ritual build` is selected (including the no-subcommand default that treats the whole ask as the scope), your **next tool call** is the Step 0.7 **Job gate**: call `classify_work_item` with the user's ask, then render that gate. Everything between here and Step 0.7 — the vocabulary map, the build rail, the runtime contracts — is reference you apply *while* running the flow; it is **not** a reason to delay that first tool call.
+
+**The pipeline — you are in the PLANNING phase until the build brief is accepted.** It runs as the six build-rail stages below, **in order**. **Advance through the numbered Steps exactly as written — do not skip ahead or reorder them.** The exact tool sequence lives in the Steps; follow them, don't reconstruct it from memory.
+
+```
+Job (classify) -> Scope -> Discovery -> Recommendations -> Build brief (Step 10) | Implementation (Step 11+)
+[------------------------------- planning phase -------------------------------] [---- implementation ----]
+```
+
+**`create_exploration` is the END of Scope, not the start.** Scope = sub-problems (Step 4) → problem frame (Step 5) → `create_exploration` (Step 6). Creating the exploration before the sub-problems and frame exist forces a confusing backtrack — don't. After `classify_work_item` returns, render the Job gate, pick/create the workspace (Step 1), then do Steps 4 → 5 → 6 → 7 in order.
+
+**The most common failures: (a) freelancing your own questions before classify, and (b) jumping ahead — creating the exploration or touching discovery before Scope is built. Do the next numbered Step; nothing else.**
+
+**Forbidden for EVERY turn of the planning phase — not just the first (hard violations):**
+
+- Inventing your own clarifying / scoping / "which option did you mean" questions, or using your agent's own question or prompt UI to gather scope. Scope is captured ONLY inside the flow, via `generate_problem_statement` (Step 4). The flow's own gates (Job gate, discovery, rec review) are the only pauses.
+- Running ANY **implementation-phase** tooling before the build brief is generated and accepted (Step 10): file writes/edits, package installs, component/scaffold generators, design-asset generators, todo/task lists. (Examples by agent — v0: `GenerateDesignInspiration`, `TodoManager`, `shadcn add`; Cursor/Claude/etc. have equivalents.) Pulling implementation forward is a hard violation. These resume — and are expected — at **Step 11**.
+- Reading repo files, `.ritual/config.json`, or calling `list_workspaces` before the Job gate is confirmed (Step 0.7). (Code-recon *reads* are fine later, at their step inside the planning phase; this only forbids them up front.)
+- Emitting an empty, "let me think…", or narration-only turn with no tool call (e.g. "I'll start the build flow", "Let me gather context first"). Start the next step; don't announce it.
+
+"Proceed with your best judgment" / "no clarification needed" does **not** mean skip the flow — it means run the flow with sane defaults and pause only at the real pause gates.
+
 ### Vocabulary mapping (engineer-tone)
 
 The Ritual data model uses product-research terminology. This skill translates to engineer-natural terms when speaking to the user. The underlying API still uses original names — keep this table mental when you read tool inputs / outputs:
@@ -288,11 +313,12 @@ Resolution order:
 
    <!-- skill-options:no-gate-change: adds explainer prose to the existing workspace-pick gate; options and pause unchanged -->
 
-   > This repo isn't connected to a workspace yet.
-   > A workspace keeps the context and reasoning Ritual needs for future runs.
-   >
-   > Where should Ritual save this run?
+   > A **workspace** is where Ritual keeps the context, decisions, and reasoning for related work — so future runs build on this one instead of starting cold. You're not in one yet.
    > {numbered list}
+   >
+   > Where should this run live? (pick one, or I'll create a new workspace for you)
+
+   (Repo-agnostic on purpose: don't say "this repo" — agents like v0 have no repo. If there are NO existing workspaces, skip the list and just say *"Ritual will set up a workspace for this — a workspace keeps the context for related work. I'll name it `{name}`; sound good?"* and create it.)
 
    **[USER PAUSE]** for selection.
 3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[USER PAUSE]**
@@ -594,12 +620,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:
@@ -1303,7 +1329,7 @@ Longest phase because generation is async + the user picks per-Area. (Internally
 **Picking is a deliberate step-through, not a bulk action (load-bearing):** the user going Area by Area and choosing the questions that matter IS the value of discovery — that per-question judgment shapes the whole downstream chain. So **nudge the user to step through and pick**; don't lead with bulk shortcuts.
 - **Nudge to step through.** Walk the user Area-by-Area (drop into Area 1, `next`/`prev`) and invite deliberate picks per Area, with `show more` to expand an Area. The framing is "which of these should we dig into?", not "want all of them?".
 - **Floor (HARD): at least 6 questions** across any Areas — below this, do NOT commit or proceed (tell them how many more to pick and keep them in the picker). There is NO "skip discovery" path — the agentic run needs a real question set to develop answers against. **Good coverage (SOFT): 15–20 questions** — nudge toward it on the Summary, but never block once ≥6. **No upper cap** — picking many (or all) is a legitimate explicit choice, never a default or fallback. (Uncovered scope is handled downstream when recommendations + requirements are generated and audited, so a thin set is the failure mode to prevent.)
-- **The default is the suggested 12 on screen, never "all."** The landing shows exactly what `proceed` commits. An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12 the user is looking at** — never silently accept everything.
+- **The default is the suggested 12, never "all."** `proceed` commits exactly that suggested set (not every generated question). An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12** — never silently accept everything. (The landing summarizes rather than lists them; `expert` is the path to read/adjust the set before committing.)
 - **Taking all IS allowed — but only as an explicit user choice, never the default or a fallback.** If the user genuinely says "take all" / "all of them", honor it and commit them; that's a legitimate choice, not an error. Just never *offer* "I'll take all" as the default, and never auto-fall-back to it. (Worth mentioning once, not as a gate: every accepted question is answered individually in the agentic run, so accepting all of them across every Area means many more questions to answer and a much longer run — but it's the user's call.)
 
 **Forbidden behaviors:**
@@ -1367,31 +1393,19 @@ The user always confirms; nothing is committed without their reply.
 
 ###### 7.3.1 — First render: the suggested-12 landing (the default)
 
-Render ALL 12 suggested questions IN FULL, grouped by Area — never truncate, elide, or "(… N more)" this list; the whole point is that the user reads exactly what one word will commit. Full phase rail on this message (we just entered Discovery).
+Render the **compact landing**: one summary line (counts + that the 12 most impactful were identified) and the action bar. Do NOT list the questions here — the full set is inspected on demand via `expert` (the Area walk). Keeping this terse is deliberate; the earlier "render all 12 in full" landing was too verbose. Full phase rail on this message (we just entered Discovery).
 
 ```text
 Ritual build
 ✓ Job  ✓ Scope  ● Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
-Discovery questions ready — {M} generated across {N} areas.
-
-These 12 questions target the tradeoffs and unknowns most likely to change the plan.
-
-{Area name 1}
-  ✓ 1. {question, full text, wrapped readably}
-  ✓ 2. {question}
-
-{Area name 2}
-  ✓ 3. {question}
-  ✓ 4. {question}
-
-{…every suggested question, grouped by Area, all 12 visible…}
+We've generated {M} discovery questions across {N} areas and identified the 12 most impactful questions.
 
-Reply `proceed` to use these 12, `expert` to adjust, or `pause`.
+Reply `proceed` to generate answers and recommendations for these questions, `expert` to inspect and adjust the question set, or `pause`.
 ```
 
 Branch on reply:
-- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the 12 on screen via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. The ambiguous-reply rule is now structurally safe: what gets accepted is exactly what the user is looking at.
+- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the suggested 12 via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. Ambiguous replies (`ok`/`go`) map here. The questions aren't listed at this landing by design — a user who wants to read or change them before committing uses `expert`.
 - **`expert`**: enter the Area walk below with the suggested 12 **pre-selected** (`picked so far: 12`, ✓ on each suggested row). Numbers TOGGLE in expert mode — typing a selected question's number unselects it.
 - **`pause`**: stop here; nothing committed.
 

package/skills/vscode/ritual/references/lite-flow.md

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 41c0a8e8e2f22f6c -->
+<!-- source-sha: 294b970c48a237b5 -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -96,6 +96,31 @@ Walks the engineer from a free-form problem statement to vetted, accepted Ritual
 
 Output: a fully-closed loop — **exploration in COMPLETE state, recommendations accepted (or explicitly handed off to an admin), build brief generated, code implemented, and `sync_implementation` called to register the result in the knowledge graph**. The engineer stays in the driver's seat through concise status updates and explicit pauses only at real decision gates.
 
+### ON ENTRY — do this FIRST, then stay on the pipeline (load-bearing)
+<!-- skill-options:no-gate-change: entry-point + planning-phase trigger — names the existing Step 0.7 first action and the existing pre-brief pipeline; adds no pause gate or options -->
+
+The instant `/ritual build` is selected (including the no-subcommand default that treats the whole ask as the scope), your **next tool call** is the Step 0.7 **Job gate**: call `classify_work_item` with the user's ask, then render that gate. Everything between here and Step 0.7 — the vocabulary map, the build rail, the runtime contracts — is reference you apply *while* running the flow; it is **not** a reason to delay that first tool call.
+
+**The pipeline — you are in the PLANNING phase until the build brief is accepted.** It runs as the six build-rail stages below, **in order**. **Advance through the numbered Steps exactly as written — do not skip ahead or reorder them.** The exact tool sequence lives in the Steps; follow them, don't reconstruct it from memory.
+
+```
+Job (classify) -> Scope -> Discovery -> Recommendations -> Build brief (Step 10) | Implementation (Step 11+)
+[------------------------------- planning phase -------------------------------] [---- implementation ----]
+```
+
+**`create_exploration` is the END of Scope, not the start.** Scope = sub-problems (Step 4) → problem frame (Step 5) → `create_exploration` (Step 6). Creating the exploration before the sub-problems and frame exist forces a confusing backtrack — don't. After `classify_work_item` returns, render the Job gate, pick/create the workspace (Step 1), then do Steps 4 → 5 → 6 → 7 in order.
+
+**The most common failures: (a) freelancing your own questions before classify, and (b) jumping ahead — creating the exploration or touching discovery before Scope is built. Do the next numbered Step; nothing else.**
+
+**Forbidden for EVERY turn of the planning phase — not just the first (hard violations):**
+
+- Inventing your own clarifying / scoping / "which option did you mean" questions, or using your agent's own question or prompt UI to gather scope. Scope is captured ONLY inside the flow, via `generate_problem_statement` (Step 4). The flow's own gates (Job gate, discovery, rec review) are the only pauses.
+- Running ANY **implementation-phase** tooling before the build brief is generated and accepted (Step 10): file writes/edits, package installs, component/scaffold generators, design-asset generators, todo/task lists. (Examples by agent — v0: `GenerateDesignInspiration`, `TodoManager`, `shadcn add`; Cursor/Claude/etc. have equivalents.) Pulling implementation forward is a hard violation. These resume — and are expected — at **Step 11**.
+- Reading repo files, `.ritual/config.json`, or calling `list_workspaces` before the Job gate is confirmed (Step 0.7). (Code-recon *reads* are fine later, at their step inside the planning phase; this only forbids them up front.)
+- Emitting an empty, "let me think…", or narration-only turn with no tool call (e.g. "I'll start the build flow", "Let me gather context first"). Start the next step; don't announce it.
+
+"Proceed with your best judgment" / "no clarification needed" does **not** mean skip the flow — it means run the flow with sane defaults and pause only at the real pause gates.
+
 ### Vocabulary mapping (engineer-tone)
 
 The Ritual data model uses product-research terminology. This skill translates to engineer-natural terms when speaking to the user. The underlying API still uses original names — keep this table mental when you read tool inputs / outputs:
@@ -380,11 +405,12 @@ Resolution order:
 
    <!-- skill-options:no-gate-change: adds explainer prose to the existing workspace-pick gate; options and pause unchanged -->
 
-   > This repo isn't connected to a workspace yet.
-   > A workspace keeps the context and reasoning Ritual needs for future runs.
-   >
-   > Where should Ritual save this run?
+   > A **workspace** is where Ritual keeps the context, decisions, and reasoning for related work — so future runs build on this one instead of starting cold. You're not in one yet.
    > {numbered list}
+   >
+   > Where should this run live? (pick one, or I'll create a new workspace for you)
+
+   (Repo-agnostic on purpose: don't say "this repo" — agents like v0 have no repo. If there are NO existing workspaces, skip the list and just say *"Ritual will set up a workspace for this — a workspace keeps the context for related work. I'll name it `{name}`; sound good?"* and create it.)
 
    **[LITE AUTO — no pause; auto-pick the recommended default]** for selection.
 3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[LITE AUTO — no pause; auto-pick the recommended default]**
@@ -686,12 +712,12 @@ Steps:
 <!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
    f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
 
+      <!-- skill-options:no-gate-change: prose-only copy tightening of the discover/next-job/skip descriptions; option tokens + gate unchanged -->
       ```text
-      You picked #{k}. The other {M} — want to keep any going?
-        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
-                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
-        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
-        • `skip`             — drop them (default)
+      You picked #{k}. For the rest:
+        • `discover <nums>`  — explore unpicked option(s) in parallel; returns a build brief, no code.
+        • `next-job <nums>`  — save as future work.
+        • `skip`             — drop them. Default.
       ```
 
       Resolve the reply, then continue to Step 2 for the picked candidate:
@@ -1367,7 +1393,7 @@ Longest phase because generation is async + the user picks per-Area. (Internally
 **Picking is a deliberate step-through, not a bulk action (load-bearing):** the user going Area by Area and choosing the questions that matter IS the value of discovery — that per-question judgment shapes the whole downstream chain. So **nudge the user to step through and pick**; don't lead with bulk shortcuts.
 - **Nudge to step through.** Walk the user Area-by-Area (drop into Area 1, `next`/`prev`) and invite deliberate picks per Area, with `show more` to expand an Area. The framing is "which of these should we dig into?", not "want all of them?".
 - **Floor (HARD): at least 6 questions** across any Areas — below this, do NOT commit or proceed (tell them how many more to pick and keep them in the picker). There is NO "skip discovery" path — the agentic run needs a real question set to develop answers against. **Good coverage (SOFT): 15–20 questions** — nudge toward it on the Summary, but never block once ≥6. **No upper cap** — picking many (or all) is a legitimate explicit choice, never a default or fallback. (Uncovered scope is handled downstream when recommendations + requirements are generated and audited, so a thin set is the failure mode to prevent.)
-- **The default is the suggested 12 on screen, never "all."** The landing shows exactly what `proceed` commits. An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12 the user is looking at** — never silently accept everything.
+- **The default is the suggested 12, never "all."** `proceed` commits exactly that suggested set (not every generated question). An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12** — never silently accept everything. (The landing summarizes rather than lists them; `expert` is the path to read/adjust the set before committing.)
 - **Taking all IS allowed — but only as an explicit user choice, never the default or a fallback.** If the user genuinely says "take all" / "all of them", honor it and commit them; that's a legitimate choice, not an error. Just never *offer* "I'll take all" as the default, and never auto-fall-back to it. (Worth mentioning once, not as a gate: every accepted question is answered individually in the agentic run, so accepting all of them across every Area means many more questions to answer and a much longer run — but it's the user's call.)
 
 **Forbidden behaviors:**
@@ -1431,31 +1457,19 @@ The user always confirms; nothing is committed without their reply.
 
 ###### 7.3.1 — First render: the suggested-12 landing (the default)
 
-Render ALL 12 suggested questions IN FULL, grouped by Area — never truncate, elide, or "(… N more)" this list; the whole point is that the user reads exactly what one word will commit. Full phase rail on this message (we just entered Discovery).
+Render the **compact landing**: one summary line (counts + that the 12 most impactful were identified) and the action bar. Do NOT list the questions here — the full set is inspected on demand via `expert` (the Area walk). Keeping this terse is deliberate; the earlier "render all 12 in full" landing was too verbose. Full phase rail on this message (we just entered Discovery).
 
 ```text
 Ritual build
 ✓ Job  ✓ Scope  ● Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
-Discovery questions ready — {M} generated across {N} areas.
-
-These 12 questions target the tradeoffs and unknowns most likely to change the plan.
-
-{Area name 1}
-  ✓ 1. {question, full text, wrapped readably}
-  ✓ 2. {question}
-
-{Area name 2}
-  ✓ 3. {question}
-  ✓ 4. {question}
-
-{…every suggested question, grouped by Area, all 12 visible…}
+We've generated {M} discovery questions across {N} areas and identified the 12 most impactful questions.
 
-Reply `proceed` to use these 12, `expert` to adjust, or `pause`.
+Reply `proceed` to generate answers and recommendations for these questions, `expert` to inspect and adjust the question set, or `pause`.
 ```
 
 Branch on reply:
-- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the 12 on screen via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. The ambiguous-reply rule is now structurally safe: what gets accepted is exactly what the user is looking at.
+- **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the suggested 12 via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. Ambiguous replies (`ok`/`go`) map here. The questions aren't listed at this landing by design — a user who wants to read or change them before committing uses `expert`.
 - **`expert`**: enter the Area walk below with the suggested 12 **pre-selected** (`picked so far: 12`, ✓ on each suggested row). Numbers TOGGLE in expert mode — typing a selected question's number unselects it.
 - **`pause`**: stop here; nothing committed.