@ritualai/cli 0.8.1 → 0.8.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +38 -9
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/skills/claude-code/ritual/.ritual-bundle.json +2 -2
- package/skills/claude-code/ritual/references/build-flow.md +30 -39
- package/skills/codex/ritual/.ritual-bundle.json +2 -2
- package/skills/codex/ritual/references/build-flow.md +30 -39
- package/skills/cursor/ritual/.ritual-bundle.json +2 -2
- package/skills/cursor/ritual/references/build-flow.md +30 -39
- package/skills/gemini/ritual/.ritual-bundle.json +2 -2
- package/skills/gemini/ritual/references/build-flow.md +30 -39
- package/skills/kiro/ritual/.ritual-bundle.json +2 -2
- package/skills/kiro/ritual/references/build-flow.md +30 -39
- package/skills/vscode/ritual/.ritual-bundle.json +2 -2
- package/skills/vscode/ritual/references/build-flow.md +30 -39
package/dist/index.js
CHANGED
|
@@ -32,33 +32,62 @@ program
|
|
|
32
32
|
.description('Ritual CLI — connect AI coding agents to Ritual Cloud. ' +
|
|
33
33
|
'Scaffold skills, register MCP servers, manage sessions.')
|
|
34
34
|
.version((0, package_info_1.readPackageVersionSafe)());
|
|
35
|
+
/**
|
|
36
|
+
* Maintainer-only flags only register when RITUAL_INTERNAL=1 is set in
|
|
37
|
+
* the environment. The public npm install never sets it, so end users:
|
|
38
|
+
*
|
|
39
|
+
* - Don't see internal flags in `ritual <cmd> --help`
|
|
40
|
+
* - Get `error: unknown option '--<flag>'` if they discover them another way
|
|
41
|
+
*
|
|
42
|
+
* Why this exists: pre-0.8.2, internal flags carried an `[internal]` text
|
|
43
|
+
* marker in their description but were still discoverable in --help. The
|
|
44
|
+
* marker was advisory; this is enforcement. Caught by the user 2026-05-21
|
|
45
|
+
* after the v0.8.0 release notes inadvertently advertised `--re-onboard`
|
|
46
|
+
* (a demo-iteration helper) as if it were a public feature. Same fix
|
|
47
|
+
* shape covers `--dev` (which had the marker but was still in --help).
|
|
48
|
+
*
|
|
49
|
+
* Maintainer use: `RITUAL_INTERNAL=1 ritual init --re-onboard --dev`.
|
|
50
|
+
* The demo-loop helper `scripts/dev/start-ritual-mock-mcp.sh` exports
|
|
51
|
+
* RITUAL_INTERNAL=1 so maintainers running the local mock-mode loop
|
|
52
|
+
* don't have to remember the env var. Same for `apps/cli/CONTRIBUTING.md`
|
|
53
|
+
* dev-iteration setup.
|
|
54
|
+
*/
|
|
55
|
+
const IS_INTERNAL_BUILD = process.env.RITUAL_INTERNAL === '1';
|
|
56
|
+
function internalOption(cmd, flag, desc) {
|
|
57
|
+
if (IS_INTERNAL_BUILD) {
|
|
58
|
+
return cmd.option(flag, desc);
|
|
59
|
+
}
|
|
60
|
+
return cmd;
|
|
61
|
+
}
|
|
35
62
|
// `init` is the headline command: scaffold + register against every
|
|
36
63
|
// detected agent. Listed first so `ritual --help` surfaces it.
|
|
37
|
-
program
|
|
64
|
+
const initCmd = program
|
|
38
65
|
.command('init')
|
|
39
66
|
.description('Scaffold Ritual skills + register MCP server with every detected AI coding agent')
|
|
40
67
|
.option('--agent <id>', 'Restrict to one agent (e.g. claude-code, cursor, kiro)')
|
|
41
68
|
.option('--list', 'List known agents and exit')
|
|
42
69
|
.option('--issuer <url>', 'OIDC issuer for the lazy-auth flow (defaults to prod or RITUAL_KEYCLOAK_URL env)')
|
|
43
70
|
.option('--client-id <id>', 'OIDC client id (defaults to "ritual-cli")')
|
|
44
|
-
.option('--dev', '[internal] shortcut for --issuer https://auth.dev.ritualapp.cloud/realms/ritual')
|
|
45
71
|
.option('--no-workspace', 'Skip the "create a workspace for this repo?" prompt. Useful for CI or when you want to bind a workspace by hand later.')
|
|
46
72
|
.option('--switch-account', 'Force a fresh sign-in even if you already have valid local credentials. Uses OIDC prompt=login so Keycloak ignores its SSO cookie. Atomic — your previous session is restored if anything fails.')
|
|
47
73
|
.option('--yes', 'Skip interactive confirmation prompts (required for --switch-account in non-TTY mode).')
|
|
48
74
|
.option('--skills-only', 'Refresh ONLY the bundled skill files in this project; skip auth, PAT minting, workspace binding, and MCP registration. Use after `npm i -g @ritualai/cli@latest` to pull the newest SKILL bundle into an already-initialized repo.')
|
|
49
75
|
.option('--persona <slug>', 'Persona for /ritual build defaults (e.g. backend-services, frontend-web). Skips the interactive picker in the onboarding flow.')
|
|
50
|
-
.option('--
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
76
|
+
.option('-v, --verbose', 'Verbose post-setup output: PAT details, per-agent status table, skill install paths, and the detailed verify-then-restart next-steps block. Default is a compact "Ready to ship" CTA box.');
|
|
77
|
+
// Maintainer-only — registered only when RITUAL_INTERNAL=1.
|
|
78
|
+
internalOption(initCmd, '--dev', 'Shortcut for --issuer https://auth.dev.ritualapp.cloud/realms/ritual (maintainer testing against the Ritual dev environment).');
|
|
79
|
+
internalOption(initCmd, '--re-onboard', 'Re-run the FTUE onboarding screens (persona picker + workspace + build-flow explainer) even if they\'ve been shown on this machine. Used by maintainers iterating on screen designs.');
|
|
80
|
+
initCmd.action(init_1.initCommand);
|
|
81
|
+
const loginCmd = program
|
|
54
82
|
.command('login')
|
|
55
83
|
.description('Authenticate with Ritual via your browser')
|
|
56
84
|
.option('--issuer <url>', 'OIDC issuer (defaults to https://auth.ritualapp.cloud/realms/ritual or RITUAL_KEYCLOAK_URL env)')
|
|
57
85
|
.option('--client-id <id>', 'OIDC client id (defaults to "ritual-cli" or RITUAL_KEYCLOAK_CLIENT_ID env)')
|
|
58
|
-
.option('--dev', '[internal] shortcut for --issuer https://auth.dev.ritualapp.cloud/realms/ritual')
|
|
59
86
|
.option('--switch-account', 'Force a fresh sign-in even if you already have valid local credentials. Uses OIDC prompt=login so Keycloak ignores its SSO cookie.')
|
|
60
|
-
.option('--yes', 'Skip interactive confirmation prompts (required for --switch-account in non-TTY mode).')
|
|
61
|
-
|
|
87
|
+
.option('--yes', 'Skip interactive confirmation prompts (required for --switch-account in non-TTY mode).');
|
|
88
|
+
// Maintainer-only — registered only when RITUAL_INTERNAL=1.
|
|
89
|
+
internalOption(loginCmd, '--dev', 'Shortcut for --issuer https://auth.dev.ritualapp.cloud/realms/ritual (maintainer testing against the Ritual dev environment).');
|
|
90
|
+
loginCmd.action(login_1.loginCommand);
|
|
62
91
|
program
|
|
63
92
|
.command('logout')
|
|
64
93
|
.description('Clear local credentials. With --all, also end the Keycloak browser SSO session.')
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAEA,yCAAoC;AACpC,4CAAgD;AAChD,8CAAkD;AAClD,8CAAkD;AAClD,gDAAoD;AACpD,0CAA8C;AAC9C,8CAAkD;AAClD,oEAAoE;AACpE,kEAAkE;AAClE,kEAAkE;AAClE,oEAAoE;AACpE,iEAAiE;AACjE,iEAAiE;AACjE,6BAA6B;AAC7B,8CAAkD;AAClD,4CAAsD;AACtD,qDAA4D;AAC5D,kEAAkE;AAClE,oEAAoE;AACpE,+DAA+D;AAC/D,iEAAiE;AACjE,oEAAoE;AACpE,oEAAoE;AACpE,oCAAoC;AACpC,qEAAqE;AAErE,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO;KACL,IAAI,CAAC,QAAQ,CAAC;KACd,WAAW,CACX,yDAAyD;IACxD,yDAAyD,CAC1D;KACA,OAAO,CAAC,IAAA,qCAAsB,GAAE,CAAC,CAAC;AAEpC,oEAAoE;AACpE,+DAA+D;AAC/D,OAAO;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ritualai/cli",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.3",
|
|
4
4
|
"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.",
|
|
5
5
|
"private": false,
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -45,7 +45,7 @@ When **not** to use:
|
|
|
45
45
|
|
|
46
46
|
Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
|
|
47
47
|
|
|
48
|
-
**Pauses are not optional even in auto-mode
|
|
48
|
+
**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
|
|
49
49
|
|
|
50
50
|
---
|
|
51
51
|
|
|
@@ -53,15 +53,29 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
|
|
|
53
53
|
|
|
54
54
|
Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
|
|
55
55
|
|
|
56
|
-
#### Step 0 —
|
|
56
|
+
#### Step 0 — Auto-mode heads-up (informational, NOT a pause)
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
> **Changed 2026-05-21.** Pre-0.8.3 this was a blocking pause: the agent asked the user to confirm they were not in auto-mode and waited for a `1`/`2` reply before proceeding. That broke FTUE: a brand-new user running their first `/ritual build` hit a meta-question about a Claude Code TUI setting before they had any context for what Ritual does. Friction without value. Worse, no reliable programmatic signal exists for "is the agent in auto-mode" — every coding agent represents the state differently, the MCP request carries no mode flag, and the SKILL itself admitted "I can't read your Claude Code TUI footer from here." So the pause was theatre: it forced the user to assert something the agent had no way to verify.
|
|
59
|
+
>
|
|
60
|
+
> The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
|
|
61
|
+
|
|
62
|
+
The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
66
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
67
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
68
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
69
|
+
back to "default").
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That's it. No menu. No required reply. Just inform.
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
**Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
|
|
63
77
|
|
|
64
|
-
| Agent |
|
|
78
|
+
| Agent | Where the mode shows up |
|
|
65
79
|
|---|---|
|
|
66
80
|
| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
|
|
67
81
|
| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
|
|
@@ -69,38 +83,7 @@ How to detect (per-agent):
|
|
|
69
83
|
| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
|
|
70
84
|
| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
|
|
71
85
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**If auto-mode is on (or you're uncertain), surface this before Step 1:**
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
Heads up — looks like your coding agent is in auto-mode for this session.
|
|
78
|
-
|
|
79
|
-
Ritual's build flow needs ~5 real decisions from you across the next
|
|
80
|
-
20–30 minutes:
|
|
81
|
-
· which workspace to use
|
|
82
|
-
· how to scope the problem
|
|
83
|
-
· which discovery questions matter for your case
|
|
84
|
-
· which recommendations to accept
|
|
85
|
-
· whether the build brief is ready to implement
|
|
86
|
-
|
|
87
|
-
Auto-mode tends to speed past these. The output will look like a
|
|
88
|
-
normal Ritual exploration but won't actually reflect your input —
|
|
89
|
-
the recommendations will be plausible-but-not-yours.
|
|
90
|
-
|
|
91
|
-
──────────────────────────────────────────────────────────────────
|
|
92
|
-
Recommended: turn off auto-mode before continuing.
|
|
93
|
-
· Claude Code: Shift+Tab to cycle back to "default"
|
|
94
|
-
· Other agents: see your agent's settings or CLI flag
|
|
95
|
-
──────────────────────────────────────────────────────────────────
|
|
96
|
-
|
|
97
|
-
1. Pause — I'll turn off auto-mode, then say "go"
|
|
98
|
-
2. Continue anyway (I want speed over alignment for this run)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
|
|
102
|
-
|
|
103
|
-
Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
|
|
86
|
+
The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
|
|
104
87
|
|
|
105
88
|
#### Step 1 — Pick a workspace
|
|
106
89
|
|
|
@@ -108,8 +91,10 @@ Resolution order:
|
|
|
108
91
|
|
|
109
92
|
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. Use it without pausing.
|
|
110
93
|
|
|
111
|
-
User-visible:
|
|
94
|
+
User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
|
|
112
95
|
|
|
96
|
+
> Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
|
|
97
|
+
>
|
|
113
98
|
> Using workspace: **{workspaceName}** from `.ritual/config.json`.
|
|
114
99
|
> Override with `workspace: list`.
|
|
115
100
|
|
|
@@ -160,6 +145,12 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
|
|
|
160
145
|
Ritual build
|
|
161
146
|
● Context ○ Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
|
|
162
147
|
|
|
148
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
149
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
150
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
151
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
152
|
+
back to "default").
|
|
153
|
+
|
|
163
154
|
Using workspace: {workspaceName}.
|
|
164
155
|
|
|
165
156
|
No Ritual history here yet.
|
|
@@ -45,7 +45,7 @@ When **not** to use:
|
|
|
45
45
|
|
|
46
46
|
Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
|
|
47
47
|
|
|
48
|
-
**Pauses are not optional even in auto-mode
|
|
48
|
+
**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
|
|
49
49
|
|
|
50
50
|
---
|
|
51
51
|
|
|
@@ -53,15 +53,29 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
|
|
|
53
53
|
|
|
54
54
|
Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
|
|
55
55
|
|
|
56
|
-
#### Step 0 —
|
|
56
|
+
#### Step 0 — Auto-mode heads-up (informational, NOT a pause)
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
> **Changed 2026-05-21.** Pre-0.8.3 this was a blocking pause: the agent asked the user to confirm they were not in auto-mode and waited for a `1`/`2` reply before proceeding. That broke FTUE: a brand-new user running their first `/ritual build` hit a meta-question about a Claude Code TUI setting before they had any context for what Ritual does. Friction without value. Worse, no reliable programmatic signal exists for "is the agent in auto-mode" — every coding agent represents the state differently, the MCP request carries no mode flag, and the SKILL itself admitted "I can't read your Claude Code TUI footer from here." So the pause was theatre: it forced the user to assert something the agent had no way to verify.
|
|
59
|
+
>
|
|
60
|
+
> The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
|
|
61
|
+
|
|
62
|
+
The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
66
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
67
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
68
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
69
|
+
back to "default").
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That's it. No menu. No required reply. Just inform.
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
**Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
|
|
63
77
|
|
|
64
|
-
| Agent |
|
|
78
|
+
| Agent | Where the mode shows up |
|
|
65
79
|
|---|---|
|
|
66
80
|
| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
|
|
67
81
|
| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
|
|
@@ -69,38 +83,7 @@ How to detect (per-agent):
|
|
|
69
83
|
| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
|
|
70
84
|
| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
|
|
71
85
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**If auto-mode is on (or you're uncertain), surface this before Step 1:**
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
Heads up — looks like your coding agent is in auto-mode for this session.
|
|
78
|
-
|
|
79
|
-
Ritual's build flow needs ~5 real decisions from you across the next
|
|
80
|
-
20–30 minutes:
|
|
81
|
-
· which workspace to use
|
|
82
|
-
· how to scope the problem
|
|
83
|
-
· which discovery questions matter for your case
|
|
84
|
-
· which recommendations to accept
|
|
85
|
-
· whether the build brief is ready to implement
|
|
86
|
-
|
|
87
|
-
Auto-mode tends to speed past these. The output will look like a
|
|
88
|
-
normal Ritual exploration but won't actually reflect your input —
|
|
89
|
-
the recommendations will be plausible-but-not-yours.
|
|
90
|
-
|
|
91
|
-
──────────────────────────────────────────────────────────────────
|
|
92
|
-
Recommended: turn off auto-mode before continuing.
|
|
93
|
-
· Claude Code: Shift+Tab to cycle back to "default"
|
|
94
|
-
· Other agents: see your agent's settings or CLI flag
|
|
95
|
-
──────────────────────────────────────────────────────────────────
|
|
96
|
-
|
|
97
|
-
1. Pause — I'll turn off auto-mode, then say "go"
|
|
98
|
-
2. Continue anyway (I want speed over alignment for this run)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
|
|
102
|
-
|
|
103
|
-
Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
|
|
86
|
+
The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
|
|
104
87
|
|
|
105
88
|
#### Step 1 — Pick a workspace
|
|
106
89
|
|
|
@@ -108,8 +91,10 @@ Resolution order:
|
|
|
108
91
|
|
|
109
92
|
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. Use it without pausing.
|
|
110
93
|
|
|
111
|
-
User-visible:
|
|
94
|
+
User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
|
|
112
95
|
|
|
96
|
+
> Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
|
|
97
|
+
>
|
|
113
98
|
> Using workspace: **{workspaceName}** from `.ritual/config.json`.
|
|
114
99
|
> Override with `workspace: list`.
|
|
115
100
|
|
|
@@ -160,6 +145,12 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
|
|
|
160
145
|
Ritual build
|
|
161
146
|
● Context ○ Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
|
|
162
147
|
|
|
148
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
149
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
150
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
151
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
152
|
+
back to "default").
|
|
153
|
+
|
|
163
154
|
Using workspace: {workspaceName}.
|
|
164
155
|
|
|
165
156
|
No Ritual history here yet.
|
|
@@ -45,7 +45,7 @@ When **not** to use:
|
|
|
45
45
|
|
|
46
46
|
Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
|
|
47
47
|
|
|
48
|
-
**Pauses are not optional even in auto-mode
|
|
48
|
+
**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
|
|
49
49
|
|
|
50
50
|
---
|
|
51
51
|
|
|
@@ -53,15 +53,29 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
|
|
|
53
53
|
|
|
54
54
|
Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
|
|
55
55
|
|
|
56
|
-
#### Step 0 —
|
|
56
|
+
#### Step 0 — Auto-mode heads-up (informational, NOT a pause)
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
> **Changed 2026-05-21.** Pre-0.8.3 this was a blocking pause: the agent asked the user to confirm they were not in auto-mode and waited for a `1`/`2` reply before proceeding. That broke FTUE: a brand-new user running their first `/ritual build` hit a meta-question about a Claude Code TUI setting before they had any context for what Ritual does. Friction without value. Worse, no reliable programmatic signal exists for "is the agent in auto-mode" — every coding agent represents the state differently, the MCP request carries no mode flag, and the SKILL itself admitted "I can't read your Claude Code TUI footer from here." So the pause was theatre: it forced the user to assert something the agent had no way to verify.
|
|
59
|
+
>
|
|
60
|
+
> The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
|
|
61
|
+
|
|
62
|
+
The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
66
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
67
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
68
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
69
|
+
back to "default").
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That's it. No menu. No required reply. Just inform.
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
**Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
|
|
63
77
|
|
|
64
|
-
| Agent |
|
|
78
|
+
| Agent | Where the mode shows up |
|
|
65
79
|
|---|---|
|
|
66
80
|
| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
|
|
67
81
|
| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
|
|
@@ -69,38 +83,7 @@ How to detect (per-agent):
|
|
|
69
83
|
| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
|
|
70
84
|
| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
|
|
71
85
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**If auto-mode is on (or you're uncertain), surface this before Step 1:**
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
Heads up — looks like your coding agent is in auto-mode for this session.
|
|
78
|
-
|
|
79
|
-
Ritual's build flow needs ~5 real decisions from you across the next
|
|
80
|
-
20–30 minutes:
|
|
81
|
-
· which workspace to use
|
|
82
|
-
· how to scope the problem
|
|
83
|
-
· which discovery questions matter for your case
|
|
84
|
-
· which recommendations to accept
|
|
85
|
-
· whether the build brief is ready to implement
|
|
86
|
-
|
|
87
|
-
Auto-mode tends to speed past these. The output will look like a
|
|
88
|
-
normal Ritual exploration but won't actually reflect your input —
|
|
89
|
-
the recommendations will be plausible-but-not-yours.
|
|
90
|
-
|
|
91
|
-
──────────────────────────────────────────────────────────────────
|
|
92
|
-
Recommended: turn off auto-mode before continuing.
|
|
93
|
-
· Claude Code: Shift+Tab to cycle back to "default"
|
|
94
|
-
· Other agents: see your agent's settings or CLI flag
|
|
95
|
-
──────────────────────────────────────────────────────────────────
|
|
96
|
-
|
|
97
|
-
1. Pause — I'll turn off auto-mode, then say "go"
|
|
98
|
-
2. Continue anyway (I want speed over alignment for this run)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
|
|
102
|
-
|
|
103
|
-
Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
|
|
86
|
+
The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
|
|
104
87
|
|
|
105
88
|
#### Step 1 — Pick a workspace
|
|
106
89
|
|
|
@@ -108,8 +91,10 @@ Resolution order:
|
|
|
108
91
|
|
|
109
92
|
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. Use it without pausing.
|
|
110
93
|
|
|
111
|
-
User-visible:
|
|
94
|
+
User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
|
|
112
95
|
|
|
96
|
+
> Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
|
|
97
|
+
>
|
|
113
98
|
> Using workspace: **{workspaceName}** from `.ritual/config.json`.
|
|
114
99
|
> Override with `workspace: list`.
|
|
115
100
|
|
|
@@ -160,6 +145,12 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
|
|
|
160
145
|
Ritual build
|
|
161
146
|
● Context ○ Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
|
|
162
147
|
|
|
148
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
149
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
150
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
151
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
152
|
+
back to "default").
|
|
153
|
+
|
|
163
154
|
Using workspace: {workspaceName}.
|
|
164
155
|
|
|
165
156
|
No Ritual history here yet.
|
|
@@ -45,7 +45,7 @@ When **not** to use:
|
|
|
45
45
|
|
|
46
46
|
Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
|
|
47
47
|
|
|
48
|
-
**Pauses are not optional even in auto-mode
|
|
48
|
+
**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
|
|
49
49
|
|
|
50
50
|
---
|
|
51
51
|
|
|
@@ -53,15 +53,29 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
|
|
|
53
53
|
|
|
54
54
|
Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
|
|
55
55
|
|
|
56
|
-
#### Step 0 —
|
|
56
|
+
#### Step 0 — Auto-mode heads-up (informational, NOT a pause)
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
> **Changed 2026-05-21.** Pre-0.8.3 this was a blocking pause: the agent asked the user to confirm they were not in auto-mode and waited for a `1`/`2` reply before proceeding. That broke FTUE: a brand-new user running their first `/ritual build` hit a meta-question about a Claude Code TUI setting before they had any context for what Ritual does. Friction without value. Worse, no reliable programmatic signal exists for "is the agent in auto-mode" — every coding agent represents the state differently, the MCP request carries no mode flag, and the SKILL itself admitted "I can't read your Claude Code TUI footer from here." So the pause was theatre: it forced the user to assert something the agent had no way to verify.
|
|
59
|
+
>
|
|
60
|
+
> The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
|
|
61
|
+
|
|
62
|
+
The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
66
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
67
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
68
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
69
|
+
back to "default").
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That's it. No menu. No required reply. Just inform.
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
**Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
|
|
63
77
|
|
|
64
|
-
| Agent |
|
|
78
|
+
| Agent | Where the mode shows up |
|
|
65
79
|
|---|---|
|
|
66
80
|
| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
|
|
67
81
|
| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
|
|
@@ -69,38 +83,7 @@ How to detect (per-agent):
|
|
|
69
83
|
| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
|
|
70
84
|
| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
|
|
71
85
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**If auto-mode is on (or you're uncertain), surface this before Step 1:**
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
Heads up — looks like your coding agent is in auto-mode for this session.
|
|
78
|
-
|
|
79
|
-
Ritual's build flow needs ~5 real decisions from you across the next
|
|
80
|
-
20–30 minutes:
|
|
81
|
-
· which workspace to use
|
|
82
|
-
· how to scope the problem
|
|
83
|
-
· which discovery questions matter for your case
|
|
84
|
-
· which recommendations to accept
|
|
85
|
-
· whether the build brief is ready to implement
|
|
86
|
-
|
|
87
|
-
Auto-mode tends to speed past these. The output will look like a
|
|
88
|
-
normal Ritual exploration but won't actually reflect your input —
|
|
89
|
-
the recommendations will be plausible-but-not-yours.
|
|
90
|
-
|
|
91
|
-
──────────────────────────────────────────────────────────────────
|
|
92
|
-
Recommended: turn off auto-mode before continuing.
|
|
93
|
-
· Claude Code: Shift+Tab to cycle back to "default"
|
|
94
|
-
· Other agents: see your agent's settings or CLI flag
|
|
95
|
-
──────────────────────────────────────────────────────────────────
|
|
96
|
-
|
|
97
|
-
1. Pause — I'll turn off auto-mode, then say "go"
|
|
98
|
-
2. Continue anyway (I want speed over alignment for this run)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
|
|
102
|
-
|
|
103
|
-
Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
|
|
86
|
+
The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
|
|
104
87
|
|
|
105
88
|
#### Step 1 — Pick a workspace
|
|
106
89
|
|
|
@@ -108,8 +91,10 @@ Resolution order:
|
|
|
108
91
|
|
|
109
92
|
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. Use it without pausing.
|
|
110
93
|
|
|
111
|
-
User-visible:
|
|
94
|
+
User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
|
|
112
95
|
|
|
96
|
+
> Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
|
|
97
|
+
>
|
|
113
98
|
> Using workspace: **{workspaceName}** from `.ritual/config.json`.
|
|
114
99
|
> Override with `workspace: list`.
|
|
115
100
|
|
|
@@ -160,6 +145,12 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
|
|
|
160
145
|
Ritual build
|
|
161
146
|
● Context ○ Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
|
|
162
147
|
|
|
148
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
149
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
150
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
151
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
152
|
+
back to "default").
|
|
153
|
+
|
|
163
154
|
Using workspace: {workspaceName}.
|
|
164
155
|
|
|
165
156
|
No Ritual history here yet.
|
|
@@ -45,7 +45,7 @@ When **not** to use:
|
|
|
45
45
|
|
|
46
46
|
Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
|
|
47
47
|
|
|
48
|
-
**Pauses are not optional even in auto-mode
|
|
48
|
+
**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
|
|
49
49
|
|
|
50
50
|
---
|
|
51
51
|
|
|
@@ -53,15 +53,29 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
|
|
|
53
53
|
|
|
54
54
|
Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
|
|
55
55
|
|
|
56
|
-
#### Step 0 —
|
|
56
|
+
#### Step 0 — Auto-mode heads-up (informational, NOT a pause)
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
> **Changed 2026-05-21.** Pre-0.8.3 this was a blocking pause: the agent asked the user to confirm they were not in auto-mode and waited for a `1`/`2` reply before proceeding. That broke FTUE: a brand-new user running their first `/ritual build` hit a meta-question about a Claude Code TUI setting before they had any context for what Ritual does. Friction without value. Worse, no reliable programmatic signal exists for "is the agent in auto-mode" — every coding agent represents the state differently, the MCP request carries no mode flag, and the SKILL itself admitted "I can't read your Claude Code TUI footer from here." So the pause was theatre: it forced the user to assert something the agent had no way to verify.
|
|
59
|
+
>
|
|
60
|
+
> The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
|
|
61
|
+
|
|
62
|
+
The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
66
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
67
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
68
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
69
|
+
back to "default").
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That's it. No menu. No required reply. Just inform.
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
**Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
|
|
63
77
|
|
|
64
|
-
| Agent |
|
|
78
|
+
| Agent | Where the mode shows up |
|
|
65
79
|
|---|---|
|
|
66
80
|
| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
|
|
67
81
|
| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
|
|
@@ -69,38 +83,7 @@ How to detect (per-agent):
|
|
|
69
83
|
| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
|
|
70
84
|
| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
|
|
71
85
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**If auto-mode is on (or you're uncertain), surface this before Step 1:**
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
Heads up — looks like your coding agent is in auto-mode for this session.
|
|
78
|
-
|
|
79
|
-
Ritual's build flow needs ~5 real decisions from you across the next
|
|
80
|
-
20–30 minutes:
|
|
81
|
-
· which workspace to use
|
|
82
|
-
· how to scope the problem
|
|
83
|
-
· which discovery questions matter for your case
|
|
84
|
-
· which recommendations to accept
|
|
85
|
-
· whether the build brief is ready to implement
|
|
86
|
-
|
|
87
|
-
Auto-mode tends to speed past these. The output will look like a
|
|
88
|
-
normal Ritual exploration but won't actually reflect your input —
|
|
89
|
-
the recommendations will be plausible-but-not-yours.
|
|
90
|
-
|
|
91
|
-
──────────────────────────────────────────────────────────────────
|
|
92
|
-
Recommended: turn off auto-mode before continuing.
|
|
93
|
-
· Claude Code: Shift+Tab to cycle back to "default"
|
|
94
|
-
· Other agents: see your agent's settings or CLI flag
|
|
95
|
-
──────────────────────────────────────────────────────────────────
|
|
96
|
-
|
|
97
|
-
1. Pause — I'll turn off auto-mode, then say "go"
|
|
98
|
-
2. Continue anyway (I want speed over alignment for this run)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
|
|
102
|
-
|
|
103
|
-
Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
|
|
86
|
+
The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
|
|
104
87
|
|
|
105
88
|
#### Step 1 — Pick a workspace
|
|
106
89
|
|
|
@@ -108,8 +91,10 @@ Resolution order:
|
|
|
108
91
|
|
|
109
92
|
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. Use it without pausing.
|
|
110
93
|
|
|
111
|
-
User-visible:
|
|
94
|
+
User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
|
|
112
95
|
|
|
96
|
+
> Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
|
|
97
|
+
>
|
|
113
98
|
> Using workspace: **{workspaceName}** from `.ritual/config.json`.
|
|
114
99
|
> Override with `workspace: list`.
|
|
115
100
|
|
|
@@ -160,6 +145,12 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
|
|
|
160
145
|
Ritual build
|
|
161
146
|
● Context ○ Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
|
|
162
147
|
|
|
148
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
149
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
150
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
151
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
152
|
+
back to "default").
|
|
153
|
+
|
|
163
154
|
Using workspace: {workspaceName}.
|
|
164
155
|
|
|
165
156
|
No Ritual history here yet.
|
|
@@ -45,7 +45,7 @@ When **not** to use:
|
|
|
45
45
|
|
|
46
46
|
Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
|
|
47
47
|
|
|
48
|
-
**Pauses are not optional even in auto-mode
|
|
48
|
+
**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
|
|
49
49
|
|
|
50
50
|
---
|
|
51
51
|
|
|
@@ -53,15 +53,29 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
|
|
|
53
53
|
|
|
54
54
|
Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
|
|
55
55
|
|
|
56
|
-
#### Step 0 —
|
|
56
|
+
#### Step 0 — Auto-mode heads-up (informational, NOT a pause)
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
> **Changed 2026-05-21.** Pre-0.8.3 this was a blocking pause: the agent asked the user to confirm they were not in auto-mode and waited for a `1`/`2` reply before proceeding. That broke FTUE: a brand-new user running their first `/ritual build` hit a meta-question about a Claude Code TUI setting before they had any context for what Ritual does. Friction without value. Worse, no reliable programmatic signal exists for "is the agent in auto-mode" — every coding agent represents the state differently, the MCP request carries no mode flag, and the SKILL itself admitted "I can't read your Claude Code TUI footer from here." So the pause was theatre: it forced the user to assert something the agent had no way to verify.
|
|
59
|
+
>
|
|
60
|
+
> The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
|
|
61
|
+
|
|
62
|
+
The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
66
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
67
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
68
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
69
|
+
back to "default").
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That's it. No menu. No required reply. Just inform.
|
|
59
73
|
|
|
60
|
-
|
|
74
|
+
Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
**Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
|
|
63
77
|
|
|
64
|
-
| Agent |
|
|
78
|
+
| Agent | Where the mode shows up |
|
|
65
79
|
|---|---|
|
|
66
80
|
| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
|
|
67
81
|
| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
|
|
@@ -69,38 +83,7 @@ How to detect (per-agent):
|
|
|
69
83
|
| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
|
|
70
84
|
| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
|
|
71
85
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**If auto-mode is on (or you're uncertain), surface this before Step 1:**
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
Heads up — looks like your coding agent is in auto-mode for this session.
|
|
78
|
-
|
|
79
|
-
Ritual's build flow needs ~5 real decisions from you across the next
|
|
80
|
-
20–30 minutes:
|
|
81
|
-
· which workspace to use
|
|
82
|
-
· how to scope the problem
|
|
83
|
-
· which discovery questions matter for your case
|
|
84
|
-
· which recommendations to accept
|
|
85
|
-
· whether the build brief is ready to implement
|
|
86
|
-
|
|
87
|
-
Auto-mode tends to speed past these. The output will look like a
|
|
88
|
-
normal Ritual exploration but won't actually reflect your input —
|
|
89
|
-
the recommendations will be plausible-but-not-yours.
|
|
90
|
-
|
|
91
|
-
──────────────────────────────────────────────────────────────────
|
|
92
|
-
Recommended: turn off auto-mode before continuing.
|
|
93
|
-
· Claude Code: Shift+Tab to cycle back to "default"
|
|
94
|
-
· Other agents: see your agent's settings or CLI flag
|
|
95
|
-
──────────────────────────────────────────────────────────────────
|
|
96
|
-
|
|
97
|
-
1. Pause — I'll turn off auto-mode, then say "go"
|
|
98
|
-
2. Continue anyway (I want speed over alignment for this run)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
|
|
102
|
-
|
|
103
|
-
Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
|
|
86
|
+
The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
|
|
104
87
|
|
|
105
88
|
#### Step 1 — Pick a workspace
|
|
106
89
|
|
|
@@ -108,8 +91,10 @@ Resolution order:
|
|
|
108
91
|
|
|
109
92
|
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. Use it without pausing.
|
|
110
93
|
|
|
111
|
-
User-visible:
|
|
94
|
+
User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
|
|
112
95
|
|
|
96
|
+
> Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
|
|
97
|
+
>
|
|
113
98
|
> Using workspace: **{workspaceName}** from `.ritual/config.json`.
|
|
114
99
|
> Override with `workspace: list`.
|
|
115
100
|
|
|
@@ -160,6 +145,12 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
|
|
|
160
145
|
Ritual build
|
|
161
146
|
● Context ○ Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
|
|
162
147
|
|
|
148
|
+
Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
|
|
149
|
+
scope, discovery picks, rec acceptance, implementation approval). If your
|
|
150
|
+
agent is in auto-accept / bypass-permissions mode, those pauses won't
|
|
151
|
+
actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
|
|
152
|
+
back to "default").
|
|
153
|
+
|
|
163
154
|
Using workspace: {workspaceName}.
|
|
164
155
|
|
|
165
156
|
No Ritual history here yet.
|