@ritualai/cli 0.36.36 → 0.36.37

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: 622a0cff45d0
+cli_version: 0.36.37
 ---
 
 # /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
@@ -102,11 +103,11 @@ Additional runtime references:
 
 - 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 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

@@ -457,7 +457,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 +476,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

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: 41c0a8e8e2f22f6c -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -549,7 +549,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 +568,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

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`).