@ritualai/cli 0.3.0

package/dist/lib/oidc.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefreshTokenError = void 0;
+exports.performLoginFlow = performLoginFlow;
+exports.refreshTokens = refreshTokens;
+exports.decodeJwtPayloadUnsafe = decodeJwtPayloadUnsafe;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const node_url_1 = require("node:url");
+const base64url = (buf) => buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+function generatePkce() {
+    const verifier = base64url((0, node_crypto_1.randomBytes)(32));
+    const challenge = base64url((0, node_crypto_1.createHash)('sha256').update(verifier).digest());
+    return { verifier, challenge };
+}
+/**
+ * Spin up a one-shot loopback server on a random port. Resolves with
+ * the captured `?code=...&state=...` query params from the OAuth
+ * redirect. Rejects on timeout (default 5 min) or error response.
+ */
+function awaitAuthorizationRedirect(timeoutMs = 5 * 60 * 1000) {
+    let port = 0;
+    let serverRef;
+    const promise = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            serverRef.close();
+            reject(new Error('Login timed out — no callback received within 5 minutes'));
+        }, timeoutMs);
+        const server = (0, node_http_1.createServer)((req, res) => {
+            if (!req.url) {
+                res.writeHead(400).end();
+                return;
+            }
+            const url = new node_url_1.URL(req.url, `http://127.0.0.1:${port}`);
+            if (url.pathname !== '/' && url.pathname !== '/callback') {
+                res.writeHead(404).end();
+                return;
+            }
+            const code = url.searchParams.get('code');
+            const state = url.searchParams.get('state');
+            const errorParam = url.searchParams.get('error');
+            if (errorParam) {
+                const description = url.searchParams.get('error_description') ?? '';
+                res.writeHead(400, { 'Content-Type': 'text/html' }).end(htmlPage('Sign-in failed', `<p style="color:#dc2626">${escapeHtml(errorParam)}: ${escapeHtml(description)}</p>`));
+                clearTimeout(timer);
+                serverRef.close();
+                reject(new Error(`OAuth error: ${errorParam}: ${description}`));
+                return;
+            }
+            if (!code || !state) {
+                res.writeHead(400).end('Missing code or state');
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' }).end(htmlPage('Sign-in complete', `<p>You can close this tab and return to your terminal.</p>`));
+            clearTimeout(timer);
+            serverRef.close();
+            resolve({ code, state });
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (typeof addr === 'object' && addr) {
+                port = addr.port;
+            }
+            else {
+                clearTimeout(timer);
+                server.close();
+                reject(new Error('Failed to bind loopback server'));
+            }
+        });
+        serverRef = server;
+    });
+    // Caller needs port for the redirect URI; resolve via wrapper that
+    // settles synchronously after listen completes.
+    return { server: serverRef, port, promise };
+}
+/**
+ * Run the full Auth Code + PKCE flow. Opens the user's browser to
+ * Keycloak; resolves with a TokenSet. Caller is responsible for
+ * persisting it (see lib/config.ts).
+ */
+async function performLoginFlow(cfg, openBrowser, log) {
+    const { verifier, challenge } = generatePkce();
+    const state = base64url((0, node_crypto_1.randomBytes)(16));
+    // Bind loopback server FIRST so we know which port to put in the
+    // redirect URI before sending the user off to Keycloak.
+    const { server, promise } = awaitAuthorizationRedirect();
+    // Wait one tick for `listen()` to populate the port.
+    await new Promise((r) => setImmediate(r));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    if (!port)
+        throw new Error('Failed to bind loopback server');
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    // Build the authorize URL.
+    const authorizeUrl = new node_url_1.URL(`${cfg.issuer}/protocol/openid-connect/auth`);
+    authorizeUrl.searchParams.set('response_type', 'code');
+    authorizeUrl.searchParams.set('client_id', cfg.clientId);
+    authorizeUrl.searchParams.set('redirect_uri', redirectUri);
+    authorizeUrl.searchParams.set('scope', cfg.scope);
+    authorizeUrl.searchParams.set('state', state);
+    authorizeUrl.searchParams.set('code_challenge', challenge);
+    authorizeUrl.searchParams.set('code_challenge_method', 'S256');
+    log(`Opening browser to ${cfg.issuer.replace(/^https?:\/\//, '')}…`);
+    log(`If the browser doesn't open, visit:\n  ${authorizeUrl.toString()}\n`);
+    await openBrowser(authorizeUrl.toString()).catch(() => {
+        /* if `open` fails the user can copy-paste */
+    });
+    // Wait for the redirect back to localhost.
+    const result = await promise;
+    if (result.state !== state) {
+        throw new Error('OAuth state mismatch — possible CSRF attack. Aborting login. Please try again.');
+    }
+    // Exchange code for token.
+    const tokenUrl = `${cfg.issuer}/protocol/openid-connect/token`;
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: cfg.clientId,
+        code: result.code,
+        redirect_uri: redirectUri,
+        code_verifier: verifier,
+    });
+    const res = await fetch(tokenUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Token exchange failed: HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const tokenSet = (await res.json());
+    return tokenSet;
+}
+/**
+ * Exchange a refresh token for a fresh access token (and usually a
+ * fresh refresh token too — Keycloak rotates them by default).
+ *
+ * Spec: RFC 6749 §6 (Refreshing an Access Token).
+ *
+ * Throws if the refresh token is expired/revoked — caller should
+ * fall back to `performLoginFlow()` to get the user re-auth'd in
+ * the browser.
+ */
+async function refreshTokens(cfg, refreshToken) {
+    const tokenUrl = `${cfg.issuer}/protocol/openid-connect/token`;
+    const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: cfg.clientId,
+        refresh_token: refreshToken,
+    });
+    const res = await fetch(tokenUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        // 400 invalid_grant is the canonical "refresh token expired or
+        // revoked" response — surface a typed error so the caller can
+        // trigger a fresh `performLoginFlow()` cleanly.
+        throw new RefreshTokenError(`Refresh failed: HTTP ${res.status}: ${text.slice(0, 200)}`, res.status);
+    }
+    return (await res.json());
+}
+/**
+ * Thrown by `refreshTokens()` when Keycloak rejects the refresh
+ * token. Carries the HTTP status so callers can distinguish a
+ * permanent failure (400 invalid_grant → re-login required) from
+ * a transient one (5xx → retry maybe).
+ */
+class RefreshTokenError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'RefreshTokenError';
+    }
+}
+exports.RefreshTokenError = RefreshTokenError;
+/**
+ * Decode a JWT's payload WITHOUT verifying its signature. The CLI
+ * validates by way of acquiring the token from Keycloak directly over
+ * TLS, then trusts the payload for display only ("logged in as
+ * alice@example.com"). For any actual authorization decision, call
+ * the API which verifies the signature against JWKS.
+ */
+function decodeJwtPayloadUnsafe(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// ─── small html helpers for the loopback browser response ──────────────────
+function htmlPage(title, body) {
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${escapeHtml(title)}</title>
+<style>body{font-family:system-ui,sans-serif;max-width:480px;margin:64px auto;padding:0 24px;color:#111}
+h1{font-size:18px;font-weight:600;margin:0 0 8px}p{margin:8px 0;color:#555}</style></head>
+<body><h1>${escapeHtml(title)}</h1>${body}</body></html>`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+//# sourceMappingURL=oidc.js.map

package/dist/lib/oidc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.js","sourceRoot":"","sources":["../../src/lib/oidc.ts"],"names":[],"mappings":"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"}

package/dist/lib/pat-store.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mintAgentPat = mintAgentPat;
+exports.defaultAgentTokenName = defaultAgentTokenName;
+const node_os_1 = require("node:os");
+const api_client_1 = require("./api-client");
+async function mintAgentPat(opts) {
+    const name = opts.nameOverride ?? defaultAgentTokenName();
+    let response;
+    try {
+        response = await opts.api.post('/auth/tokens', {
+            name,
+            scopes: opts.scopes ?? ['admin'],
+            // undefined → service-layer default; null → no expiry.
+            expiresInDays: opts.expiresInDays ?? 365,
+        });
+    }
+    catch (err) {
+        if (err instanceof api_client_1.ApiError && err.status === 409) {
+            // Active-token cap hit. Re-surface with a hint about the
+            // management UI so the user can revoke an old one.
+            throw new Error('Personal access token limit reached. Revoke an old token at ' +
+                'https://app.ritualapp.cloud/settings/tokens and re-run `ritual init`.');
+        }
+        throw err;
+    }
+    return {
+        plaintextToken: response.plaintextToken,
+        id: response.token.id,
+        name: response.token.name,
+        expiresAt: response.token.expiresAt,
+    };
+}
+/**
+ * `Ritual CLI — <hostname>`, truncated to fit the API's 80-char limit
+ * on token names. Real hostnames are typically 10-30 chars so this is
+ * defensive.
+ */
+function defaultAgentTokenName() {
+    const host = (0, node_os_1.hostname)() || 'unknown-host';
+    const full = `Ritual CLI — ${host}`;
+    return full.length > 80 ? full.slice(0, 77) + '...' : full;
+}
+//# sourceMappingURL=pat-store.js.map

package/dist/lib/pat-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pat-store.js","sourceRoot":"","sources":["../../src/lib/pat-store.ts"],"names":[],"mappings":";;AAoEA,oCA6BC;AAOD,sDAIC;AA5GD,qCAAmC;AACnC,6CAAmD;AAmE5C,KAAK,UAAU,YAAY,CAAC,IAAoB;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,EAAE,CAAC;IAE1D,IAAI,QAA2B,CAAC;IAChC,IAAI,CAAC;QACJ,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAoB,cAAc,EAAE;YACjE,IAAI;YACJ,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC;YAChC,uDAAuD;YACvD,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,GAAG;SACxC,CAAC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,GAAG,YAAY,qBAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACnD,yDAAyD;YACzD,mDAAmD;YACnD,MAAM,IAAI,KAAK,CACd,8DAA8D;gBAC7D,uEAAuE,CACxE,CAAC;QACH,CAAC;QACD,MAAM,GAAG,CAAC;IACX,CAAC;IAED,OAAO;QACN,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE;QACrB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI;QACzB,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS;KACnC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB;IACpC,MAAM,IAAI,GAAG,IAAA,kBAAQ,GAAE,IAAI,cAAc,CAAC;IAC1C,MAAM,IAAI,GAAG,gBAAgB,IAAI,EAAE,CAAC;IACpC,OAAO,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC"}

package/dist/lib/skill-copy.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPackageRoot = getPackageRoot;
+exports.copySkillsForProvider = copySkillsForProvider;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Resolve the npm package root (where the `skills/` bundle lives).
+ *
+ * At runtime, this file compiles to `dist/lib/skill-copy.js`. Package
+ * root is two `..` up from there.
+ *
+ * For dev (running via tsx from source), `__dirname` is `src/lib`, so
+ * the same `../..` walk lands at the package root. Same answer either
+ * way — no special-casing needed.
+ */
+function getPackageRoot() {
+    return (0, node_path_1.resolve)(__dirname, '..', '..');
+}
+/**
+ * Copy every skill bundled for `provider` into the project.
+ *
+ * `projectDir` is usually `process.cwd()` but parameterized so tests
+ * can write to a temp directory.
+ */
+function copySkillsForProvider(provider, projectDir, packageRoot = getPackageRoot()) {
+    const sourceBase = (0, node_path_1.join)(packageRoot, provider.packageSkillDir);
+    if (!(0, node_fs_1.existsSync)(sourceBase)) {
+        return {
+            provider,
+            copied: 0,
+            reason: `package missing ${provider.packageSkillDir}/ — try reinstalling @ritualai/cli`,
+        };
+    }
+    const skillDirs = (0, node_fs_1.readdirSync)(sourceBase, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    if (skillDirs.length === 0) {
+        return {
+            provider,
+            copied: 0,
+            reason: 'no skills found in package bundle',
+        };
+    }
+    const targetBase = (0, node_path_1.join)(projectDir, provider.projectSkillDir);
+    for (const name of skillDirs) {
+        const src = (0, node_path_1.join)(sourceBase, name);
+        const dest = (0, node_path_1.join)(targetBase, name);
+        (0, node_fs_1.mkdirSync)(dest, { recursive: true });
+        // `force: true` overwrites; `recursive: true` walks the whole
+        // skill directory (covers SKILL.md + any sibling assets like
+        // nested examples/ or templates/).
+        (0, node_fs_1.cpSync)(src, dest, { recursive: true, force: true });
+    }
+    return { provider, copied: skillDirs.length };
+}
+//# sourceMappingURL=skill-copy.js.map

package/dist/lib/skill-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-copy.js","sourceRoot":"","sources":["../../src/lib/skill-copy.ts"],"names":[],"mappings":";;AA0CA,wCAEC;AAQD,sDAwCC;AA5FD,qCAAqE;AACrE,yCAA0C;AA+B1C;;;;;;;;;GASG;AACH,SAAgB,cAAc;IAC7B,OAAO,IAAA,mBAAO,EAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CACpC,QAAuB,EACvB,UAAkB,EAClB,cAAsB,cAAc,EAAE;IAEtC,MAAM,UAAU,GAAG,IAAA,gBAAI,EAAC,WAAW,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAE/D,IAAI,CAAC,IAAA,oBAAU,EAAC,UAAU,CAAC,EAAE,CAAC;QAC7B,OAAO;YACN,QAAQ;YACR,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,mBAAmB,QAAQ,CAAC,eAAe,oCAAoC;SACvF,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,IAAA,qBAAW,EAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAChE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAErB,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO;YACN,QAAQ;YACR,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,mCAAmC;SAC3C,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAA,gBAAI,EAAC,UAAU,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAE9D,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAA,gBAAI,EAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACpC,IAAA,mBAAS,EAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrC,8DAA8D;QAC9D,6DAA6D;QAC7D,mCAAmC;QACnC,IAAA,gBAAM,EAAC,GAAG,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@ritualai/cli",
+	"version": "0.3.0",
+	"description": "Ritual CLI — scaffold AI coding agent skills + register MCP servers. Connects Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code/Copilot, and Codex to Ritual Cloud.",
+	"private": false,
+	"license": "Apache-2.0",
+	"bin": {
+		"ritual": "./dist/index.js"
+	},
+	"main": "./dist/index.js",
+	"files": [
+		"dist",
+		"skills",
+		"README.md"
+	],
+	"scripts": {
+		"build:skills": "node scripts/build-skills.js",
+		"build:ts": "tsc -p tsconfig.json",
+		"build": "pnpm run build:skills && pnpm run build:ts",
+		"dev": "tsx src/index.ts",
+		"clean": "rm -rf dist skills",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "jest --passWithNoTests",
+		"prepublishOnly": "pnpm run clean && pnpm run build"
+	},
+	"dependencies": {
+		"commander": "^14.0.3",
+		"open": "^10.1.0"
+	},
+	"devDependencies": {
+		"@types/jest": "^29.5.0",
+		"@types/node": "^20.0.0",
+		"jest": "^29.7.0",
+		"ts-jest": "^29.1.0",
+		"tsx": "^4.19.0",
+		"typescript": "^5.0.0"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"keywords": [
+		"ritual",
+		"mcp",
+		"ai-coding-agent",
+		"claude-code",
+		"cursor",
+		"windsurf",
+		"kiro",
+		"gemini-cli",
+		"copilot",
+		"codex"
+	],
+	"jest": {
+		"preset": "ts-jest",
+		"testEnvironment": "node",
+		"roots": ["<rootDir>/src", "<rootDir>/test"],
+		"testMatch": ["**/?(*.)+(spec|test).ts"]
+	}
+}

package/skills/claude-code/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."