@ritualai/cli 0.8.2 → 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/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/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.
|