@ritualai/cli 0.7.16 → 0.8.0

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

@@ -121,7 +121,7 @@ Store `workspace_id` for the rest of the flow.
 
 If you created a new workspace, persist the binding to `.ritual/config.json` so future runs in this repo skip the workspace-selection prompt. Write it yourself if you have filesystem write access; otherwise show the user the JSON and have them save it.
 
-**`.ritual/config.json` is committed to the repo — it is shared, not per-user.** Same model as `.eslintrc.json` or `tsconfig.json`: it binds this codebase to a Ritual workspace + pins team-level defaults (workspaceId, defaultTemplateId). Everyone working on this repo wants the same values. Per-user state (PATs, auth tokens) lives in `~/.config/ritual/` and never in this file.
+**`.ritual/config.json` is committed to the repo — it is shared, not per-user.** Same model as `.eslintrc.json` or `tsconfig.json`: it binds this codebase to a Ritual workspace + pins team-level defaults (`workspaceId`, `personaSlug` — set by `ritual init`'s FTUE — or the legacy `defaultTemplateId`). Everyone working on this repo wants the same values. Per-user state (PATs, auth tokens) lives in `~/.config/ritual/` and never in this file.
 
 When you write the config, also write `.ritual/.gitignore` if it doesn't already exist so any future per-user state files in this directory get ignored while `config.json` itself stays tracked:
 
@@ -446,16 +446,48 @@ Templates shape the structure of considerations, the problem statement, and the
 
 Resolution order:
 
-1. **Project-pinned default (preferred).** Check `.ritual/config.json` for a `defaultTemplateId` field. If present, the project has a pinned team template — use it without pausing.
+1. **Persona-pinned default (preferred — FTUE-set).** Check `.ritual/config.json` for a `personaSlug` field. If present, that slug **is the template id** (Engineering template families are seeded with `schema.id === <slug>` — see `apps/cli/src/lib/persona-samples.ts`). Use it directly as `template_id` without calling `mcp__ritual__list_templates` and without pausing. This is the common case: the user picked a persona during `ritual init`'s FTUE, the slug was persisted to `.ritual/config.json`, and `/ritual build` should respect that pick.
 
-   User-visible:
+   **Frame this as a persona + scope-of-work confirmation, not a template confirmation.** "Template" is an internal noun the user hasn't seen — they picked a *persona* during FTUE and what they care about now is "is the persona right + what does that mean for this feature?" Use the `PERSONA_DISPLAY` table below to look up the friendly label from the slug.
 
-   > Template
-   > Using **{templateName}**, pinned in `.ritual/config.json`.
-   > Ritual will use this to turn the candidate into implementation-ready sub-problems, recommendations, and a build brief for the coding agent.
-   > Override anytime with `template: list` or `template: {name}`.
+   User-visible (one short pause that confirms persona + lists the scope sections, NOT a tool-call prompt):
+
+   > You're set up as **{personaLabel}**.
+   >
+   > For this feature, we'll work through: scope · non-goals · requirements · acceptance criteria · dependencies · metrics · open questions.
+   >
+   > Sound right? Reply `go` to continue, or `change role` to pick a different persona.
+
+   Do **NOT** call `mcp__ritual__list_templates` in this branch. It's wasted ceremony — both for latency (round-trip + LLM context bloat) and for UX (pre-FTUE this step was a real decision; with `personaSlug` already pinned it's a confirmation prompt the user can't meaningfully act on).
+
+   **`PERSONA_DISPLAY` lookup table** (slug → label, mirrors `apps/cli/src/lib/persona-samples.ts#PERSONA_SAMPLES`). If the slug isn't here (a custom or future persona), fall back to humanizing the slug (e.g. `frontend-web` → `Frontend Web`):
+
+   | slug | label |
+   | --- | --- |
+   | backend-services | Backend Services |
+   | frontend-web | Frontend Web |
+   | data-engineering | Data Engineering |
+   | ml-engineering | ML Engineering |
+   | platform-engineering | Platform Engineering |
+   | security-engineering | Security Engineering |
+   | developer-tooling | Developer Tooling |
+   | embedded-firmware | Embedded / Firmware |
+   | game-development | Game Development |
+   | smart-contracts | Smart Contracts |
+   | desktop-apps | Desktop Apps |
+   | qa-engineering | QA Engineering |
 
-2. **Pick a recommended default + offer alternatives.** If no `.ritual/config.json` pin exists, call `mcp__ritual__list_templates`. From the response, pick the first template matching this fallback chain:
+   **If user replies `change role`** (or `template: list`, retained as a power-user alias): fall through to Branch 3 (`list_templates`). Otherwise treat any non-empty reply that isn't a recognized override command as `go`.
+
+2. **Legacy template pin.** If `personaSlug` is missing but `.ritual/config.json` has the legacy `defaultTemplateId` field (older inits before FTUE), use that as `template_id` without pausing. Same confirmation shape as Branch 1, but the role name comes from the template — call `mcp__ritual__list_templates` ONCE to resolve the display name (the legacy pin gave us an id, not a label), then show:
+
+   > You're set up with **{templateName}**.
+   >
+   > For this feature, we'll work through: scope · non-goals · requirements · acceptance criteria · dependencies · metrics · open questions.
+   >
+   > Sound right? Reply `go` to continue, or `change role` to pick a different persona.
+
+3. **No pin — pick a recommended default + offer alternatives.** Only when neither `personaSlug` nor `defaultTemplateId` is set, call `mcp__ritual__list_templates`. From the response, pick the first template matching this fallback chain:
    - Name matches `/Feature Specification.*Agentic Coding/i` — canonical default for code-aware builds
    - Name matches `/Technical Detail PRD/i`
    - Name matches `/Engineering Spec|Technical (Detail|Spec)/i`
@@ -468,13 +500,13 @@ Resolution order:
    >
    > Reply `go`, `list`, or `template: {name}`.
 
-3. **If the user types `list`:** present a numbered menu of all SYSTEM-type templates. Skip CUSTOM templates by default to avoid menu sprawl unless the user gives a specific custom id/name. Each line: `{N}. {name} — {short description}`. Wait for a number selection.
+4. **If the user types `list`** (in any branch, override path): call `mcp__ritual__list_templates` if you haven't yet, then present a numbered menu of all SYSTEM-type templates. Skip CUSTOM templates by default to avoid menu sprawl unless the user gives a specific custom id/name. Each line: `{N}. {name} — {short description}`. Wait for a number selection.
 
-4. **If the user types `template: {name}` or picks one by name:** find the case-insensitive partial match in the template list. If ambiguous, show only the matching options and ask which one. If no match, show the SYSTEM template menu.
+5. **If the user types `template: {name}` or picks one by name:** call `mcp__ritual__list_templates` if you haven't yet, then find the case-insensitive partial match. If ambiguous, show only the matching options and ask which one. If no match, show the SYSTEM template menu.
 
-5. **Remember `template_id`.** It passes through every subsequent phase — `generate_considerations`, `refine_considerations`, `generate_problem_statement`, `refine_problem_statement`, and ultimately `create_exploration`. The API uses it to load template-specific anti-patterns + focus keywords into the LLM prompt, so it materially shapes output quality.
+6. **Remember `template_id`.** It passes through every subsequent phase — `generate_considerations`, `refine_considerations`, `generate_problem_statement`, `refine_problem_statement`, and ultimately `create_exploration`. The API uses it to load template-specific anti-patterns + focus keywords into the LLM prompt, so it materially shapes output quality.
 
-6. **Track role silently.** Infer `role` from the selected template and carry it forward for:
+7. **Track role silently.** Infer `role` from the selected template and carry it forward for:
    - recommendation tone
    - sibling exploration cap
    - Step 8 run-mode default
@@ -501,11 +533,15 @@ Resolution order:
 
    If the user corrects the role (e.g. "actually I'm building a PRD"), update internal role tracking. Do **not** re-pick the template unless the user explicitly asks to change it.
 
-7. **Suggest persistence only when useful.** If you picked a default from the template list and the user accepted with `go` rather than choosing a different one, suggest:
+8. **Suggest persistence only when useful.** If you got here via Branch 3 (no pinned default, you picked one from the list), AND the user accepted with `go` rather than picking a different one, suggest:
 
    > Want me to pin this template for future `/ritual build` runs in this repo? I can add `"defaultTemplateId": "{id}"` to `.ritual/config.json`.
 
-   If the user says yes, write the field while preserving existing keys. This is a TEAM pin — `.ritual/config.json` is committed to the repo per Step 1, so the whole team picks up the same default.
+   If the user says yes, write the field while preserving existing keys. Use the `defaultTemplateId` field (not `personaSlug`) when the user picked a template directly — `personaSlug` is reserved for the FTUE persona pick (where the slug semantically maps to one of the 12 Engineering personas). The SKILL reads `personaSlug` first, then `defaultTemplateId`, so either field works as a pin; the distinction is provenance.
+
+   This is a TEAM pin — `.ritual/config.json` is committed to the repo per Step 1, so the whole team picks up the same default.
+
+   **Do NOT suggest persistence in Branches 1 or 2** (persona-pinned or legacy-pinned). The pin already exists; offering to write it would be confusing.
 
 Proceed to Step 3 once a template is selected. No extra confirmation is required after a pinned template or an accepted default.
 
@@ -1061,6 +1097,7 @@ Call `mcp__ritual__create_exploration` with:
 - `workspace_id`
 - `name`
 - `problem_statement` (the scope from Step 5)
+- `template_id` — **REQUIRED.** Pass the same `template_id` used in Steps 4 and 5 (the one established in Step 2 from `personaSlug` / `defaultTemplateId` / picker). The exploration must carry this forward so downstream `start_agentic_run`, `get_recommendations`, and `generate_build_brief` load the right template-specific anti-patterns + focus keywords into the LLM prompts. Skipping `template_id` here silently falls back to the API default, which produces generic recs that don't match the persona's scope contract — the symptom is brief sections that don't align with what the user was promised at Step 2 ("For this feature, we'll work through: scope · non-goals · requirements …"). Always include it; the MCP tool accepts it (see `apps/mcp/src/mcp/tools/create-exploration.tool.ts:78`).
 - `agentic: false` — **do NOT** pass `agentic: true`. We want explicit per-step control so the user gets to pick discovery questions in Step 7. Auto-agentic skips that.
 
 Store `exploration_id`. Move the progress header from Scope to Discovery: