@ritualai/cli 0.3.0

package/skills/codex/ritual/SKILL.md

@@ -0,0 +1,271 @@
+---
+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')"
+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.
+
+## 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 — 7 phases
+
+Each phase has explicit **[USER PAUSE]** points — never skip them.
+
+#### Phase 1 — Pick a workspace
+
+Call `mcp__ritual__list_workspaces`. Present as a numbered list (id, name).
+
+If the user only has one project workspace, confirm it directly: "I'll create this in *Acme Engineering*. Sound right?" — but still wait for **[USER PAUSE]**.
+
+Store `workspace_id`.
+
+#### Phase 2 — Generate sub-problems
+
+Call `mcp__ritual__generate_considerations` with:
+- `workspace_id`
+- `raw_input` (the problem from the slash-command argument or chat)
+- `template_id` (omit unless the user specified one)
+
+LLM call, ~5-10s. Returns 5-6 sub-problems — different framing axes the agent should investigate.
+
+**[USER PAUSE]** Present as a numbered list and ask which to include:
+
+> Sub-problems the system identified:
+>
+> 1. {sub-problem 1}
+> 2. {sub-problem 2}
+> ...
+>
+> Which should we factor into the scope? Pick any subset, or "all".
+
+Store the picked sub-problems (text strings — they'll go into `considerations[]` next call).
+
+#### Phase 3 — Generate scope
+
+Call `mcp__ritual__generate_problem_statement` with:
+- `workspace_id`
+- `raw_input`
+- `considerations` (the picks from Phase 2 — these are the sub-problems we just discussed)
+- `template_id` (same as Phase 2 if used)
+
+Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores.
+
+**[USER PAUSE]** Present and ask:
+
+> Here's the scope:
+>
+> > **{generated scope}**
+>
+> Looks good? Want to tighten / broaden / change the audience? Or "ship it" to lock it in.
+
+If refinement requested: regenerate with the refinement appended to `raw_input`. Iterate until accepted.
+
+Store the final scope as `problem_statement` for the next call.
+
+#### 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}
+
+### 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)?
+
+**Agentic run fails or stalls**: surface the error, offer retry or stop.
+
+**Discovery state ready=true with zero matters**: rare but possible if the LLM produced a malformed state. Retry by calling `suggest_discovery_questions` again.
+
+**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).
+
+### Tools used
+
+This subcommand exclusively uses vNext MCP tools, in the order they appear:
+
+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)
+
+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.
+
+### After this subcommand
+
+When `/ritual build` completes, the exploration is in COMPLETE state with accepted recommendations. Downstream:
+
+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
+
+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.
+
+---
+
+## /ritual run, /ritual status, /ritual recs
+
+Not yet built. When they are, add a `## /ritual <name>` section to this file and update the routing table at the top.
+
+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.
+
+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/cursor/ritual/SKILL.md

@@ -0,0 +1,271 @@
+---
+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')"
+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.
+
+## 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 — 7 phases
+
+Each phase has explicit **[USER PAUSE]** points — never skip them.
+
+#### Phase 1 — Pick a workspace
+
+Call `mcp__ritual__list_workspaces`. Present as a numbered list (id, name).
+
+If the user only has one project workspace, confirm it directly: "I'll create this in *Acme Engineering*. Sound right?" — but still wait for **[USER PAUSE]**.
+
+Store `workspace_id`.
+
+#### Phase 2 — Generate sub-problems
+
+Call `mcp__ritual__generate_considerations` with:
+- `workspace_id`
+- `raw_input` (the problem from the slash-command argument or chat)
+- `template_id` (omit unless the user specified one)
+
+LLM call, ~5-10s. Returns 5-6 sub-problems — different framing axes the agent should investigate.
+
+**[USER PAUSE]** Present as a numbered list and ask which to include:
+
+> Sub-problems the system identified:
+>
+> 1. {sub-problem 1}
+> 2. {sub-problem 2}
+> ...
+>
+> Which should we factor into the scope? Pick any subset, or "all".
+
+Store the picked sub-problems (text strings — they'll go into `considerations[]` next call).
+
+#### Phase 3 — Generate scope
+
+Call `mcp__ritual__generate_problem_statement` with:
+- `workspace_id`
+- `raw_input`
+- `considerations` (the picks from Phase 2 — these are the sub-problems we just discussed)
+- `template_id` (same as Phase 2 if used)
+
+Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores.
+
+**[USER PAUSE]** Present and ask:
+
+> Here's the scope:
+>
+> > **{generated scope}**
+>
+> Looks good? Want to tighten / broaden / change the audience? Or "ship it" to lock it in.
+
+If refinement requested: regenerate with the refinement appended to `raw_input`. Iterate until accepted.
+
+Store the final scope as `problem_statement` for the next call.
+
+#### 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}
+
+### 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)?
+
+**Agentic run fails or stalls**: surface the error, offer retry or stop.
+
+**Discovery state ready=true with zero matters**: rare but possible if the LLM produced a malformed state. Retry by calling `suggest_discovery_questions` again.
+
+**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).
+
+### Tools used
+
+This subcommand exclusively uses vNext MCP tools, in the order they appear:
+
+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)
+
+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.
+
+### After this subcommand
+
+When `/ritual build` completes, the exploration is in COMPLETE state with accepted recommendations. Downstream:
+
+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
+
+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.
+
+---
+
+## /ritual run, /ritual status, /ritual recs
+
+Not yet built. When they are, add a `## /ritual <name>` section to this file and update the routing table at the top.
+
+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.
+
+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."