@ritualai/cli 0.36.36 → 0.36.38

package/skills/vscode/ritual/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: ritual
-description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into plan mode before the agent writes code. Prefer this over jumping straight to implementation or plan mode when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
+description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into the agent's planning step before it writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: c082a0648fbd
-cli_version: 0.36.36
+stamp: ca720305a0e1
+cli_version: 0.36.38
 ---
 
 # /ritual
 
-Top-level dispatcher for Ritual coding-agent workflows. Designed primarily for Claude Code-style sessions with filesystem, git, shell, and MCP access; adapt commands as needed for Cursor or other agents with equivalent tools.
+Top-level dispatcher for Ritual coding-agent workflows. Works with any coding agent connected to the Ritual MCP — v0, Lovable, Cursor, Claude Code, Codex, Kiro, and others. Some steps use local capabilities (filesystem, git, shell) when your agent has them, and degrade gracefully to MCP-only when it doesn't.
+<!-- skill-options:no-gate-change: agent-neutral rewording + shell/git probes made conditional; no [USER PAUSE] gate or its offered options changed -->
 
 ## Always apply
 
 Before executing any subcommand, read and follow:
 
-- `references/cli-output-contract.md` — terminal output, vocabulary, readability, pause policy
+- `references/cli-output-contract.md` — agent output, vocabulary, readability, pause policy
 - `references/async-polling.md` — harness-safe polling and timeout recovery
 - `references/change-preflight.md` — restate + confirm before any free-text change/add tool call (refine sub-problems, reframe scope, add anti-goal); hard pause, even in auto-mode
 
@@ -76,10 +77,10 @@ Parse the first token of the argument:
 | `resume` | `references/resume-flow.md` | "Pick up where I left off." Lists in-flight explorations with state badges and jumps to the right step. |
 | `lineage` | `references/lineage-flow.md` | Paste a file path (or set of paths); see every prior exploration / decision / deferral that touched those files. |
 | `context-pulse` | `references/context-pulse-flow.md` | Score readiness / context debt for a feature ask or exploration. Can seed a `CONTEXT-<feature>.md` file with relevant codebase + KG context that `/ritual build` picks up automatically. Also surfaces inline during build so the user watches debt drop. |
-| `status` | `references/status-flow.md` | Read-only mirror of the `ritual status` terminal CLI command (CLI 0.7.14+) for users who want a quick run-progress check inside the agent session instead of in a separate terminal. Calls `mcp__ritual__get_agentic_run` + renders the same run-first layout the CLI uses. |
+| `status` | `references/status-flow.md` | Read-only mirror of the `ritual status` CLI command (CLI 0.7.14+) for a quick run-progress check inside the agent session. Calls `mcp__ritual__get_agentic_run` + renders the same run-first layout the CLI uses. (Most useful when your agent runs alongside the Ritual CLI; harmless elsewhere.) |
 | (anything else, OR no subcommand) | default to `build` and treat the entire argument as the problem statement | |
 
-The Ritual CLI surface is intentionally narrow: `build`, `lite`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
+The Ritual `/ritual` command surface is intentionally narrow: `build`, `lite`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
 
 
 ## Subcommand reference files
@@ -100,13 +101,13 @@ Additional runtime references:
 
 ## Routing behavior
 
-- If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and follow it.
-- If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement.
-- If the user asks for retired or unsupported subcommands, answer in plain English and call the relevant MCP tool directly when appropriate; do not expand the slash-command surface.
+- If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and **immediately execute its ON ENTRY block — your next tool call is that flow's first tool call, not a clarifying question of your own.**
+- If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement (still run `build`'s ON ENTRY block — do not pause to ask your own scoping questions first).
+- If the user asks for retired or unsupported subcommands, answer in plain English and call the relevant MCP tool directly when appropriate; do not expand the `/ritual` command surface.
 
 ## Asks that don't map to a subcommand
 
-When the user says things like *"what's the status of exp-X?"*, *"show me the recs on exp-Y"*, or *"kick off the agentic run on exp-Z"* — those don't need a dedicated slash-command. Just call the MCP tool directly:
+When the user says things like *"what's the status of exp-X?"*, *"show me the recs on exp-Y"*, or *"kick off the agentic run on exp-Z"* — those don't need a dedicated command. Just call the MCP tool directly:
 
 | User asks for… | Call this MCP tool |
 |---|---|
@@ -116,15 +117,18 @@ When the user says things like *"what's the status of exp-X?"*, *"show me the re
 | Kick off / re-run the agentic pipeline | `mcp__ritual__start_agentic_run(exploration_id, …)` |
 | Did anyone implement something on these files? | `mcp__ritual__query_knowledge_graph(sources=[…])` — same plumbing as `/ritual lineage` |
 
-This is intentional. Legacy exposed each of these as its own slash-command (`/ritual recs`, `/ritual run`, etc.) and the surface area ballooned without adding agent value. We keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror) and let the agent fluently call MCP tools for everything else. Note: `/ritual status` is the one deliberate exception — it exists as a thin SKILL mirror of the terminal CLI command so users who want an in-chat status check don't have to context-switch to a separate terminal. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+This is intentional. Legacy exposed each of these as its own command (`/ritual recs`, `/ritual run`, etc.) and the surface area ballooned without adding agent value. We keep the commands narrow (`build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror) and let the agent fluently call MCP tools for everything else. Note: `/ritual status` is the one deliberate exception — it exists as a thin SKILL mirror of the `ritual status` CLI command so users who want an in-chat status check don't have to switch surfaces. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
 
 ---
 
 ## Before this skill is installed — bootstrap context
 
-This SKILL only governs behavior **after** `ritual init` has run and the
-`/ritual` skill has been copied into the agent's skills directory. Before
-that, the agent has no Ritual-specific instructions in scope.
+This SKILL only governs behavior **after** it has been installed into the
+agent's skills directory. The canonical install path is the Ritual CLI
+(`ritual init` copies the skill in); agents without a CLI install it their own
+way — e.g. uploading the skill bundle directly (v0, Lovable). Either way, before
+the skill is in scope the agent has no Ritual-specific instructions; the runtime
+behavior below is identical once it is.
 
 If you are reading this file by browsing the repo, or as part of a
 post-mortem on why a user's "set up Ritual MCP" request went sideways:

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]**
@@ -457,7 +483,7 @@ Steps:
    - For `ready` or `in_flight` states, jump directly to Step 10 (build brief generation).
    - For `awaiting_admin`, jump to Step 9 (review + `proceed`). Only an admin can move it forward; collaborators see the recs and proceed only if they're explicitly authorized to implement ahead.
    - For `implemented_ahead`, surface the situation to the user and ask what to do — typically the admin reconciles by either approving the recs post-hoc (no code change needed) or updating the recs to match shipped reality.
-   - **For `done` or `in_flight` — branch-existence sanity check FIRST.** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
+   - **For `done` or `in_flight` — branch-existence sanity check FIRST (when your agent can run shell + git).** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* **If your agent can't run shell/git** (v0, Lovable, browser-only agents), skip this probe and the footprint probe below, treat the KG state badge as truth, and tell the user you couldn't cross-check it against local git. The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
 
      ```bash
      # If implementationRecord.branch is set:
@@ -476,7 +502,7 @@ Steps:
 
      Don't paint 3-4 options ("treat as done / treat as fresh / inspect the KG row / something else") — one decisive proposal with a yes/no/correct-me escape hatch. If yes: jump to Step 10 (build brief). If no/correct-me: take the user's input as ground truth and update the next move accordingly.
 
-   - **For `ready` or `in_flight` — implementation footprint check FIRST.** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
+   - **For `ready` or `in_flight` — implementation footprint check FIRST (when your agent can run shell + git; otherwise skip — see the guard above).** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
 
      ```bash
      git log --all --grep="Ritual-Exploration: ${exploration_id}" --oneline 2>/dev/null
@@ -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/cli-output-contract.md

@@ -1,8 +1,8 @@
-# CLI output contract
+# Agent output contract
 
 ### Developer-facing output contract
 
-This skill drives a CLI surface where the user reads every line. Optimize for a busy engineer who wants enough signal to trust the workflow without reading the agent's scratchpad.
+This skill drives an agent surface where the user reads every line of the agent's output. Optimize for a busy engineer who wants enough signal to trust the workflow without reading the agent's scratchpad.
 
 Maintain two layers throughout the flow:
 
@@ -18,7 +18,7 @@ Do **not** pass raw notes as the primary context to MCP generation tools. Raw no
 
 Default user-visible messages should be:
 - 3–7 bullets max, unless the user explicitly asks for detail
-- no more than one terminal screen
+- no more than one screen
 - focused on findings, constraints, next action, and specific signals
 - free of “I inferred…” / “that means I'll bias…” narration unless the inference changes a user-facing choice
 - free of raw file-by-file recon dumps unless requested
@@ -138,14 +138,14 @@ When in doubt, prefer one blank line over none. The cost of a tiny gap is unnoti
 
 | Surface | Rendering | When to use |
 |---|---|---|
-| **CLI / terminal** (current default) | Full two-line rail. `Ritual build` on line 1, `● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)` on line 2. | Terminal scrollback has no persistent UI — the rail IS the anchor. |
+| **CLI / terminal** (terminal agents — Claude Code, Cursor, Codex in a built-in terminal) | Full two-line rail. `Ritual build` on line 1, `● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)` on line 2. | Terminal scrollback has no persistent UI — the rail IS the anchor. |
 | **Mobile chat / narrow chat** | Compact one-line chip. `Ritual build · 2/6 Scope`. Optionally add a second line: `Done: Job, Scope · Next: Recommendations`. | Six-stage rail wraps and looks noisy inside chat bubbles. |
 | **Rich app with persistent stepper** | Single-line stage label. `Scope` (or `Phase: Scope`). The app's pinned stepper above the conversation is the primary anchor; messages just need the current label. At phase transitions, resume points, and major decision gates, include the compact mobile-style chip even in rich-app surface for transcript portability. | The persistent UI carries the anchor; redundant chrome in every bubble is noise. |
 
 **How the agent picks the surface:**
 
-- Default to **CLI / terminal** rendering. This SKILL exists primarily to drive CLI surfaces (Claude Code, Cursor, Codex, etc. in their built-in terminals).
-- If the host signals a non-terminal surface via context (mobile-app chat embedding, web-app chat UI, etc.), drop to the compact chip.
+- When your agent runs in a terminal (Claude Code, Cursor, Codex, etc. in their built-in terminals), default to **CLI / terminal** rendering.
+- When the surface is a chat UI rather than a terminal (web-app agents like v0/Lovable, mobile-app chat embedding, etc.), drop to the compact chip.
 - The rule is: **progress anchor is mandatory; exact visual rendering is surface-specific.** Do NOT force the full six-stage rail when it will wrap.
 
 **Applies to:**
@@ -282,15 +282,15 @@ The host app pins a stepper above the conversation; the message only carries the
 All `/ritual build` and `/ritual resume` top-level messages in `references/build-flow.md` anchor to this spec — when a stage transitions, the existing examples advance the marker per the canonical ordering. If you need to rename a stage in the future, update this table first; everything else follows.
 
 
-### CLI experience cheat-sheet
+### Agent experience cheat-sheet
 
-This skill drives a CLI surface where the user reads every line you print. Keep these tenets in mind — full doc at `documents/design/cli-experience-tenets.md`:
+This skill drives an agent surface where the user reads every line you print. Keep these tenets in mind — full doc at `documents/design/cli-experience-tenets.md`:
 
 - **Long artifacts (briefs, recon notes) → files, not terminal dumps.** The CLI summarizes; the file holds the detail. End every output with what the user can do next.
 - **Single recommended action + escape hatch > 3-option menu.** Lead with the best next step, give them a cheap "no, do this instead" out. Reserve 3-way branches for genuinely distinct intents (implement / refine / drill — yes; "generate brief / look at deferrals / something else" — no).
 - **Cite the specific signal**, not the abstract gesture. *"Recommended because RB-001 is blocking…"* beats *"based on prior workspace context."*
 - **Silence on no-data.** Don't print "Checked X — nothing." Just don't render the section.
-- **Sanity-check the world before trusting the DB.** When an `ImplementationRecord` asserts a branch/PR, verify it exists locally before treating the exploration as done (Step 1.5 step 5).
+- **Sanity-check the world before trusting the DB (when you can).** If your agent has shell + git, verify an `ImplementationRecord`'s asserted branch/PR exists locally before treating the exploration as done (Step 1.5 step 5). If it can't run git, treat the KG record as truth and say you couldn't verify it locally.
 - **Never commit to `main` / `master` from this workflow.** Step 11 creates a feature branch FIRST — no exceptions, no user-prompt offering "commit to trunk" as an option (Tenet #13).
 - **Attribute back to Ritual on outbound artifacts.** Commit-message trailers + PR body + generated-file headers carry the exploration link so future readers can trace the lineage without re-asking the agent (Tenet #14).
 - **Format dense CLI lists for scanning.** When an item has a title, explanation, rationale, and references, split those into labeled blocks with blank lines between items. Do not rely on terminal auto-wrap to make long prose readable.

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: d34e2df8a4177dbe -->
+<!-- source-sha: 251c9793521c8486 -->
 
 # /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]**
@@ -549,7 +575,7 @@ Steps:
    - For `ready` or `in_flight` states, jump directly to Step 10 (build brief generation).
    - For `awaiting_admin`, jump to Step 9 (review + `proceed`). Only an admin can move it forward; collaborators see the recs and proceed only if they're explicitly authorized to implement ahead.
    - For `implemented_ahead`, surface the situation to the user and ask what to do — typically the admin reconciles by either approving the recs post-hoc (no code change needed) or updating the recs to match shipped reality.
-   - **For `done` or `in_flight` — branch-existence sanity check FIRST.** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
+   - **For `done` or `in_flight` — branch-existence sanity check FIRST (when your agent can run shell + git).** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* **If your agent can't run shell/git** (v0, Lovable, browser-only agents), skip this probe and the footprint probe below, treat the KG state badge as truth, and tell the user you couldn't cross-check it against local git. The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
 
      ```bash
      # If implementationRecord.branch is set:
@@ -568,7 +594,7 @@ Steps:
 
      Don't paint 3-4 options ("treat as done / treat as fresh / inspect the KG row / something else") — one decisive proposal with a yes/no/correct-me escape hatch. If yes: jump to Step 10 (build brief). If no/correct-me: take the user's input as ground truth and update the next move accordingly.
 
-   - **For `ready` or `in_flight` — implementation footprint check FIRST.** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
+   - **For `ready` or `in_flight` — implementation footprint check FIRST (when your agent can run shell + git; otherwise skip — see the guard above).** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
 
      ```bash
      git log --all --grep="Ritual-Exploration: ${exploration_id}" --oneline 2>/dev/null
@@ -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.
 

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

@@ -142,6 +142,8 @@ Silence on no-data (CLI Tenet #6): if a state bucket is empty, don't render it.
 
 #### Step R3 — Branch-existence sanity check (`done` / `in_flight` only)
 
+> **Requires shell + git.** Steps R3 and R3.5 verify KG state against local git, so they only run on agents that can execute shell + `git`/`gh` (Claude Code, Codex, Cursor agent mode, …). **If your agent can't run shell/git** (v0, Lovable, browser-only agents), skip both probes entirely, treat the KG state badge as truth, and tell the user you couldn't cross-check it against local git history.
+
 Same as `/ritual build` Step 1.5 step 5's CLI Tenet #9 check. Before treating an exploration as ✓ done, verify the implementation record's branch / PR actually exists locally or remotely:
 
 ```bash
@@ -192,6 +194,7 @@ Cross-reference findings against the KG state:
 
 **Skip the probes when:**
 
+- **Your agent can't run shell + git** (see the R3 guard above) — skip entirely and treat the KG state as truth.
 - The exploration was just created in this same session — no time to have orphan commits.
 - The user just synced (the `done` / `in_flight` state badge was set within the last few minutes).
 - The exploration is in a state where the footprint check doesn't apply (`in_progress`, `awaiting_admin`, `implemented_ahead`).