@ritualai/cli 0.5.0 → 0.7.1

package/skills/claude-code/ritual/DESIGN.md

@@ -0,0 +1,35 @@
+# Ritual skill design notes
+
+This file is for humans reviewing or maintaining the Ritual skill. Runtime instructions live in `SKILL.md` and `references/*.md`.
+
+## Product intent
+
+Ritual helps coding agents avoid jumping straight into implementation when the feature depends on context the agent cannot infer on its own: strategic intent, constraints, prior decisions, trade-offs, and non-obvious scope boundaries.
+
+The workflow surfaces that context through targeted discovery questions, combines it with codebase signals and prior explorations, and produces a validated build brief before code is written.
+
+## Why split the skill
+
+The previous monolithic `SKILL.md` mixed runtime instructions with design rationale, fallback formulas, version history, and long branch handlers. That made it harder for an agent to follow the right path at runtime.
+
+The split version keeps:
+
+- `SKILL.md` as a dispatcher/control plane
+- `references/*` as runtime procedure files loaded only when needed
+- `DESIGN.md` as rationale and maintenance notes
+
+## Retired `/ritual recon`
+
+`/ritual recon` is intentionally not part of the vNext command surface. Its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and its repo-reading behavior is normal coding-agent behavior in plain English.
+
+## Context packet principle
+
+The coding agent should contribute local codebase understanding, but not decide final scope itself. After recon, it produces a `codebase_context_packet` containing facts, evidence, hypotheses, confidence, scope pressure, corrections, and open questions. MCP/tooling remains responsible for generating and ranking final sub-problems and scope.
+
+## Context pulse principle
+
+Context pulse answers: can a reasoning system act safely on this yet? The primary user-facing score is Reasoning Readiness; Context Debt is the inverse. Server-side scoring is canonical for new pulses. Fallback formulas are only for older MCP servers or error recovery.
+
+## Host assumptions
+
+Designed primarily for Claude Code-style coding-agent sessions with filesystem, git, shell, and MCP access. Adapt commands as needed for Cursor or other agents with equivalent tools.

package/skills/claude-code/ritual/SKILL.md

@@ -1,398 +1,71 @@
 ---
 name: ritual
-description: "Top-level Ritual workflow dispatcher. Use when the engineer wants to start, run, check, or accept a Ritual exploration. Subcommands today: `build` (free-form problem → accepted recommendations, end-to-end). More land as they're built."
-argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3')"
+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) before the agent 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
 ---
 
 # /ritual
 
-Top-level dispatcher for vNext Ritual workflows. The first whitespace-delimited token of the argument selects a subcommand; everything after is passed to that subcommand.
+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.
 
-## Routing
-
-Parse the first token of the argument:
-
-| First token | Route to |
-|---|---|
-| `build` | the [build flow](#ritual-build) below |
-| (anything else, OR no subcommand) | default to `build` and treat the entire argument as the problem statement |
-
-Future subcommands (`run`, `status`, `recs`) will be added as their workflows are built. When you add a new subcommand, extend the routing table above and add a `## /ritual <subcommand>` section below.
-
----
-
-## /ritual build
-
-Walks the engineer from a free-form problem statement to vetted, accepted Ritual recommendations using the vNext MCP tool surface.
-
-Output: **an exploration in COMPLETE state with accepted recommendations**, suitable as input to downstream implementation skills.
-
-### 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:
-
-| User-facing term (the skill says) | Tool field name (the API uses) |
-|---|---|
-| **scope** | `problemStatement` |
-| **sub-problem** | `consideration` |
-| **matter** | `matter` (no rename — already the right word) |
-| **discovery question** | `question` |
-| **recommendation** | `recommendation` |
-
-When the user says "tighten the scope," call `generate_problem_statement(...)` with their refinement. When you tell the user "I picked these sub-problems," you mean the items you put in `considerations[]`. The tools don't change; only the language to the user does.
-
-### When to use
-
-- The user describes a problem they want explored ("we need to figure out X", "let's scope Y", "I want recommendations on Z")
-- The user wants the full pipeline — sub-problems → scope → discovery → recommendations — not just one step
-
-When **not** to use:
-- An exploration already exists with recommendations — fetch directly via `get_exploration` + `get_recommendations`
-- The user wants to *implement* a feature from existing recommendations — use `/ritual-builder-spec` (from `@ritual-ai/cli`)
-
-### Workflow — 9 phases (Phase 8 happens after the engineer ships the work)
-
-Each phase has explicit **[USER PAUSE]** points — never skip them.
-
-#### Phase 1 — Pick a workspace
-
-Resolution order:
-
-1. **Project-bound workspace (preferred).** Check for a `.ritual/config.json` at the project root (you can use the Read tool — the file is a small JSON with `workspaceId` + `workspaceName`). If it exists, that's the workspace this repo is bound to. Surface it to the user: "Using workspace **`{workspaceName}`** (bound to this repo). Sound right?" — wait for **[USER PAUSE]**.
-2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). Present as a numbered list (id, name). **[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]**
-
-Store `workspace_id` for the rest of the flow.
-
-If you created a new workspace, suggest the user run `ritual init` to persist the binding into `.ritual/config.json` for next time (or write it yourself if the user is in a Claude Code session that can edit files).
-
-#### Phase 1.5 — Code reconnaissance
-
-**Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
-
-Before generating considerations, do a structured scan of the codebase so the sub-problems land specific to *this* code, not generic. The legacy system shipped considerations that read like a textbook table of contents because it skipped this step; the difference between "Conversion Timing, Trust Signals, Recovery Paths" (generic) and "Leverage `apps/checkout/session.py` anonymous-checkout path vs. adding a new step in `CheckoutSessionMixin`" (codebase-specific) is whether you did Phase 1.5.
-
-Steps:
-
-1. **Read the README + top-level project structure.** Use `ls` / Glob to see top-level files (5–10 lines). Identify the language, framework, key directories.
-
-2. **Glob for relevance.** Derive patterns from the user's problem. Examples:
-   - User says "auth flow" → `**/auth/**`, `**/login*`, `**/user*`, `**/session*`
-   - User says "checkout" → `**/checkout/**`, `**/cart/**`, `**/order/**`, `**/payment*`
-   - User says "notifications" → `**/notif*`, `**/email/**`, `**/sms/**`, `**/push/**`
-   Cap at ~15 hits per pattern.
-
-3. **Skim 3–5 most-relevant files.** For each, read the first ~100 lines + scan for class/function names. Triangulate: "is the behavior we care about actually here, or does it call into somewhere else?"
-
-4. **Build a recon summary** — 5–10 lines, concrete file paths, key abstractions, observed constraints. Examples of GOOD summaries:
-
-   > Codebase recon (django-oscar, Django 5.0):
-   > - Booking flow lives in `apps/checkout/views.py` (`CheckoutSessionMixin` orchestrates the step chain)
-   > - Anonymous checkout already supported via `apps/checkout/session.py:CheckoutSessionData`
-   > - Account creation entry point: `apps/customer/forms.py:RegisterUserForm`
-   > - Strategy classes (`apps/partner/strategy.py`) are the conventional pluggability pattern
-   > - User-model split: `auth.User` is the Django auth user; `apps/customer/models.py:Customer` is the order-attached profile — they can be linked or anonymous
-
-5. **Surface to the user as a [USER PAUSE]**:
-
-   > Reading the codebase I see:
-   > <recon summary>
-   >
-   > Anything I'm missing about design intent or constraints I won't find by reading the code (e.g. business decisions, prod incidents, in-flight migrations)?
-
-   Wait for confirmation or additional context. The user's reply (if any) becomes part of the input to Phase 2.
-
-6. **Compose the augmented `raw_input` for Phase 2.** Concatenate:
-   - The user's original problem (verbatim, top)
-   - A `--- Codebase context ---` section with the recon summary
-   - The user's reply from step 5 if non-empty
-   - Phase 1.5 IS the difference between "generic considerations" and "considerations that name actual files and reference existing patterns". Don't skip the recon step. Don't compress the summary to one line.
-
-7. **Collect the `sources` array.** The file paths you read in step 3 — exactly as they appear in the repo (e.g. `"apps/checkout/views.py"`, NOT `"./apps/checkout/views.py"` or absolute paths). This list is passed alongside `raw_input` to `generate_considerations` and `generate_problem_statement` so the API can auto-inject **prior knowledge-graph context** for overlapping files. Keep the list focused — only files you actually read and consider load-bearing for this problem. 5–10 is the sweet spot; >20 dilutes the KG signal.
-
-**[USER PAUSE]** confirmation of recon is required before proceeding.
-
-#### Phase 2 — Generate sub-problems
-
-##### 2.1 First draft
-
-Call `mcp__ritual__generate_considerations` with:
-- `workspace_id`
-- `raw_input` (the user's problem + the Phase 1.5 codebase recon, concatenated as described above)
-- `template_id` (omit unless the user specified one)
-- `sources` (the file path list from Phase 1.5 step 7 — file-path strings only, e.g. `["apps/checkout/views.py", ...]`)
-
-LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the agent should investigate. Track each one as `{ text, version: 1 }` in your working memory.
-
-**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior team decisions shaped this draft.
-
-> Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
->  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) — 2 decisions, 1 deferral
->  - **"Payment-method routing"** (shipped 2026-03-22) — 4 decisions
->  - **"Session-data persistence"** (shipped 2026-02-08) — 1 decision
->
-> I factored those into the sub-problems below.
-
-If `implementationCount === 0`: don't mention the KG check (silent — would just be noise on a cold KG).
-
-**[USER PAUSE]** Present as a numbered list and ask which to include:
-
-> Sub-problems the system identified (v1):
->
-> 1. {sub-problem 1}
-> 2. {sub-problem 2}
-> ...
->
-> Which should we factor into the scope? Pick any subset, "all", or ask for a different framing (e.g. "make them more technical", "drop the measurement angle", "focus on enterprise").
-
-##### 2.2 Iteration loop
-
-If the user asks for a refinement (anything that isn't "all" / specific picks / "these are good"):
-
-Call `mcp__ritual__refine_considerations` with:
-- `workspace_id`, `raw_input`, `template_id`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
-- `change_prompt`: the user's request verbatim
-- `selected`: items from prior versions the user kept (track `{ text, from_version }`, send just `text`)
-- `dismissed`: items the user explicitly rejected
-- `session_id`: omitted on the first refinement; pass the `session_id` from the previous refine response on subsequent ones to chain context
-
-Track the new items as `{ text, version: N+1 }`. Present **alongside** the prior versions, not replacing them — the user can mix selections across versions.
-
-Loop until the user says "these are good" or picks a subset.
-
-**Critical**: never re-call `generate_considerations` for a refinement. That endpoint is stateless and re-rolls a fresh seed; you'll lose what the user just told you. The whole point of `refine_*` is the LLM sees the iteration context.
-
-Store the final picked sub-problems for Phase 3 — they go into `considerations[]`.
-
-#### Phase 3 — Generate scope
-
-##### 3.1 First draft
-
-Call `mcp__ritual__generate_problem_statement` with:
-- `workspace_id`
-- `raw_input` (same augmented version from Phase 2)
-- `considerations` (the picks from Phase 2)
-- `template_id` (same as Phase 2 if used)
-- `sources` (the same file-path list passed to generate_considerations — keeps the KG anchor consistent)
-
-Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores. Treat this as **v1** of the problem statement.
-
-If the response includes `kg_context_used` with `implementationCount > 0`, prepend a note to the scope presentation:
-
-> *(Grounded in {N} prior implementation{s}: {top match name}, …)*
+## Always apply
 
-**[USER PAUSE]** Present and ask:
+Before executing any subcommand, read and follow:
 
-> Here's the scope (v1):
->
-> > **{generated scope}**
->
-> Looks good? Want to tighten / broaden / change the audience / focus on a specific tier? Or "ship it" to lock it in.
+- `references/cli-output-contract.md` — terminal output, vocabulary, readability, pause policy
+- `references/async-polling.md` — harness-safe polling and timeout recovery
 
-##### 3.2 Iteration loop
+Do not reintroduce `/ritual recon`. Use plain-language repo inspection, `/ritual resume`, or `/ritual lineage` depending on intent.
 
-If the user asks for a refinement:
-
-Call `mcp__ritual__refine_problem_statement` with:
-- `workspace_id`, `raw_input`, `considerations`, `template_id`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
-- `previous_problem_statement`: the FULL TEXT of the current best draft (the v1 you just showed)
-- `change_prompt`: the user's request verbatim ("tighten and drop the audience clause")
-- `version`: optional label like `"v2"` — purely for telemetry
-- `session_id`: omitted on the first refinement; chain on subsequent ones
-
-The returned text becomes `v2`. Show it. The user can iterate v2 → v3 → ... by calling refine again with `previous_problem_statement` set to the latest draft.
-
-**Critical**: each refinement's `previous_problem_statement` is the LATEST draft, not the original v1. Otherwise the LLM keeps refining the same starting point and the user can't compose multiple refinements ("tighter, AND drop the audience clause, AND make it past-tense").
-
-When the user accepts ("ship it" / "looks good"), store the final text as `problem_statement` for Phase 4.
-
-#### Phase 4 — Create the exploration
-
-Generate a short name (≤60 chars) from the scope — typically the noun phrase, not the full HMW. E.g. "Reduce T2 customer churn in Q3" → name `T2 churn reduction (Q3)`.
-
-**[USER PAUSE]** "I'll create the exploration as **T2 churn reduction (Q3)**. Proceed?"
-
-Call `mcp__ritual__create_exploration` with:
-- `workspace_id`
-- `name`
-- `problem_statement` (the scope from Phase 3)
-- `agentic: false` — **do NOT** pass `agentic: true`. We want explicit per-step control so the user gets to pick discovery questions in Phase 5. Auto-agentic skips that.
-
-Store `exploration_id`. Show the URL:
-
-> Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
-
-#### Phase 5 — Discovery questions
-
-Longest phase because generation is async + the user picks per-matter.
-
-##### 5.1 — Kick off
-
-Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immediately with `task_id`. Tell the user:
-
-> Generating discovery questions for each matter… 30-120 seconds.
-
-##### 5.2 — Poll until ready
-
-Loop:
-- Call `mcp__ritual__get_discovery_state(exploration_id)`
-- If `ready: false`, wait 5 seconds, poll again
-- If `ready: true`, exit loop
-
-Don't poll faster than every 5 seconds. Update the user every ~30 seconds so they know you haven't stalled.
-
-##### 5.3 — Present matters and collect picks
-
-The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Walk through them **one matter at a time**:
-
-> **{matter.name}** — {matter.questions.length} discovery questions:
->
-> 1. {question 1}
-> 2. {question 2}
-> ...
->
-> Which should the agent investigate? Pick any subset, "all", or "skip" to skip this matter.
-
-**[USER PAUSE]** Wait per matter.
-
-##### 5.4 — Commit picks per-matter
-
-For each matter where the user picked at least one question, call `mcp__ritual__accept_discovery_questions` with:
-- `state_id` (from the discovery state)
-- `matter_id`
-- `question_ids[]` (the picks for THIS matter)
-
-This MUST be one call per matter — the API enforces per-matter atomicity. Don't bundle across matters.
-
-##### 5.5 — Optional: capture out-of-scope items
-
-If the user mentioned things they DON'T want investigated ("don't touch enterprise SSO", "skip pricing"), capture them as anti-goals.
-
-Call `mcp__ritual__set_anti_goals(exploration_id, [{ text, reason? }, ...])`.
-
-Skip silently if no anti-goals were mentioned.
-
-#### Phase 6 — Run the agentic pipeline
-
-Call `mcp__ritual__start_agentic_run` with:
-- `scope_type: 'exploration'`
-- `exploration_id`
-
-Returns `run_id`. Starts the full pipeline (sourcing → answers → recommendations) in the background. Typical runtime: 3-8 minutes.
-
-Poll `mcp__ritual__get_agentic_run(run_id)` every 15 seconds. Show progress when it changes:
-
-> Agentic run: {progress_pct}% — {current_step}
-
-When `status` is `COMPLETED`: continue to Phase 7.
-When `status` is `COMPLETED_WITH_ERRORS`: tell the user, but proceed — partial recommendations may still be useful.
-When `status` is `FAILED`: surface the error message, ask if they want to retry (`start_agentic_run` again with same exploration_id) or stop.
-
-If user wants to abort mid-flight: `mcp__ritual__cancel_agentic_run(run_id)`.
-
-#### Phase 7 — Review and accept recommendations
-
-Call `mcp__ritual__get_recommendations(exploration_id)`. Response is an array of recommendations with id, title, status, content, reasoning.
-
-**[USER PAUSE]** Present as a numbered list with title + 1-line summary:
-
-> {N} recommendations:
->
-> 1. **{title}** — {one-line from content}
-> 2. **{title}** — {one-line from content}
-> ...
->
-> Want detail on any of them? Or ready to accept the set?
-
-If detail requested: show full `content` and `reasoning_chain` (if present). Loop until done.
-
-When the user is ready:
-
-**[USER PAUSE]** "Accept all and mark the exploration complete?"
-
-If yes, call `mcp__ritual__accept_recommendations(exploration_id)`. Response includes counts (`promoted`, `alreadyApproved`, `skipped`, `transitionedToComplete`).
-
-Show the final state:
-
-> Done. {N} recommendations accepted. Exploration is now COMPLETE.
->
-> View at: https://dev.ritualapp.cloud/e/{exploration_id}
-
-#### Phase 8 — After shipping: close the loop with `sync_implementation`
-
-This phase happens *outside* the `/ritual build` chat — after the engineer has taken the accepted recommendations into their coding work and the implementation has actually landed (PR merged, etc.). The agent in that follow-up session should call `mcp__ritual__sync_implementation` to register what shipped, which decisions were made, and what was deliberately deferred.
-
-When sync_implementation succeeds, the response now includes:
-
-- `decisions: [{ decisionId, area, choice }, ...]` — IDs of every architectural decision logged
-- `deferrals: [{ deferralId, rbId, severity }, ...]` — IDs of every deferral
-- `decisionsCount`, `deferralsCount` — totals for the summary line
-- `webUrl` — clickable link to the exploration's implementation record in the web UI
-
-**Surface ALL of this to the user**, not just "ok logged." This is the visible signal that the loop closed. Format:
-
-> ✓ Logged implementation for **{exploration name}**
->   - {decisionsCount} decision{s} registered: {first 2 decisions, e.g. "auth: OAuth not SAML; data-model: tenant-scoped indexes"}
->   - {deferralsCount} deferral{s} registered: {first 1, e.g. "[major] Rate-limit per-tenant — out of scope for v1"}
->   - View: {webUrl}
->
-> Future `/ritual build` calls touching `{first 2 of filesChanged}` will now see this implementation in their priorContext block.
-
-The closing sentence is the most important one: it tells the user **what just happened in the system** in product-level terms. Without it, sync_implementation feels like a write-only black hole. With it, the user understands they just contributed to the workspace's memory.
-
-If they want to check the state at any time, point them at:
-
-> `ritual graph status` (in their CLI) — shows the workspace's current KG counts + recent implementations.
-
-### Failure modes & recovery
-
-**Discovery generation hangs (>5 min polling without `ready: true`)**: ask the user — wait longer? retry (`suggest_discovery_questions` again, new task)? or skip discovery entirely (proceed to Phase 6 without picked questions)?
+## Routing
 
-**Agentic run fails or stalls**: surface the error, offer retry or stop.
+Parse the first token of the argument:
 
-**Discovery state ready=true with zero matters**: rare but possible if the LLM produced a malformed state. Retry by calling `suggest_discovery_questions` again.
+| First token | Route to | One-liner |
+|---|---|---|
+| `build` | `references/build-flow.md` | Free-form problem → recommendations → build brief → code → sync. The full cycle. |
+| `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. |
+| (anything else, OR no subcommand) | default to `build` and treat the entire argument as the problem statement | |
 
-**LLM-cost / quota errors (HTTP 429)**: tell the user explicitly. Do NOT auto-retry — quota issues need a human decision (different model tier, wait, top up).
+The vNext CLI surface is intentionally **just these four**. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `status`, `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 "status of exp-Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired in this PR 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.)
 
-### Tools used
 
-This subcommand exclusively uses vNext MCP tools, in the order they appear:
+## Subcommand reference files
 
-1. `mcp__ritual__list_workspaces` (Phase 1)
-2. `mcp__ritual__generate_considerations` (Phase 2)
-3. `mcp__ritual__generate_problem_statement` (Phase 3)
-4. `mcp__ritual__create_exploration` (Phase 4)
-5. `mcp__ritual__suggest_discovery_questions` (Phase 5.1)
-6. `mcp__ritual__get_discovery_state` (Phase 5.2)
-7. `mcp__ritual__accept_discovery_questions` (Phase 5.4)
-8. `mcp__ritual__set_anti_goals` (Phase 5.5, optional)
-9. `mcp__ritual__start_agentic_run` (Phase 6)
-10. `mcp__ritual__get_agentic_run` (Phase 6 polling)
-11. `mcp__ritual__cancel_agentic_run` (Phase 6, only on user abort)
-12. `mcp__ritual__get_recommendations` (Phase 7)
-13. `mcp__ritual__accept_recommendations` (Phase 7)
+Load only the reference file needed for the selected subcommand:
 
-13 of the 19 vNext tools. The other 6 (`ping`, `get_exploration`, `list_templates`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`) are situational, not part of the linear build flow.
+| Subcommand | Runtime file |
+|---|---|
+| `build` | `references/build-flow.md` |
+| `resume` | `references/resume-flow.md` |
+| `lineage` | `references/lineage-flow.md` |
+| `context-pulse` | `references/context-pulse-flow.md` |
 
-### After this subcommand
+Additional runtime references:
 
-When `/ritual build` completes, the exploration is in COMPLETE state with accepted recommendations. Downstream:
+- `references/discovery-classification.md` — only when build question picking triggers scope classification
+- `references/scoring-fallback.md` — only if `mcp__ritual__score_context_pulse` is unavailable or errors
 
-1. `/ritual-builder-spec <feature description>` — generates a build brief from the recommendations + a codebase-grounded plan
-2. `/ritual-build <feature description>` (legacy variant from `@ritual-ai/cli`) — implements the plan, commits per logical unit, drafts a PR description
+## Routing behavior
 
-Naming overlap note: the legacy `/ritual-build` (in the public CLI package) is the *implementation* skill — feature description → committed code. This new `/ritual build` is the *exploration* skill — problem statement → accepted recommendations. Different scopes, similar names. Future cleanup may align them.
+- If the first token is one of the four subcommands, 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.
 
----
+## Asks that don't map to a subcommand
 
-## /ritual run, /ritual status, /ritual recs
+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:
 
-Not yet built. When they are, add a `## /ritual <name>` section to this file and update the routing table at the top.
+| User asks for… | Call this MCP tool |
+|---|---|
+| Status of one exploration | `mcp__ritual__get_exploration(exploration_id)` |
+| Status across many explorations | `mcp__ritual__list_explorations(workspace_id)` (returns state badges) |
+| The recommendations on an exploration | `mcp__ritual__get_recommendations(exploration_id)` |
+| 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` |
 
-Conceptual scope (when built):
-- `/ritual run <exploration_id>` — kick off agentic run on an existing exploration, poll, present recommendations. Subset of `build` starting at Phase 6.
-- `/ritual status <id>` — quick status check on an exploration or run. No interaction.
-- `/ritual recs <exploration_id>` — fetch + present recommendations. No interaction.
+This is intentional. Legacy exposed each of these as its own slash-command (`/ritual status`, `/ritual recs`, `/ritual run`) and the surface area ballooned without adding agent value. In vNext we keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`) and let the agent fluently call MCP tools for everything else. 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.
 
-For now, if the user asks for these, tell them politely: "That subcommand isn't built yet — for status, use `mcp__ritual__get_exploration` directly; for recs, use `mcp__ritual__get_recommendations` directly."

package/skills/claude-code/ritual/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: Ritual
+  short_description: Plan and build implementation-heavy changes with Ritual context, discovery, build briefs, lineage, and context-pulse scoring.
+  icon: 🪷
+  color: "#7C3AED"

package/skills/claude-code/ritual/references/async-polling.md

@@ -0,0 +1,26 @@
+# Async polling contract
+
+Use this for every long-running Ritual/MCP operation: discovery generation, agentic runs, requirement generation, build brief generation, and future async status surfaces.
+
+## Standard poll loop
+
+- Use a single `Bash sleep 5` per poll iteration.
+- Do not chain sleeps (`sleep 5; sleep 5`).
+- Do not use `sleep >= 30`.
+- Between polls, take a fresh turn: sleep, call status, decide continue/exit.
+- Print progress only when status/progress/current_step changes, or every ~3 polls (~15s).
+- Keep updates to one line unless an error occurs.
+
+## Long waits
+
+For genuinely long waits (>5 minutes), use the harness's `Monitor` tool with an `until <check>; do sleep 2; done` pattern rather than the standard poll loop.
+
+## Timeout recovery
+
+If a write/generate call times out locally but server-side work may still be running, do not blindly regenerate. Call the matching status tool first and poll:
+
+- `get_requirement_set_status` after requirement generation
+- `get_build_brief_status` after build brief generation
+- `get_agentic_run` after agentic run start/resume
+
+Regenerate only when status proves work did not start, failed, or the user explicitly requests a fresh roll.