CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-05-02 11:45:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat: plan-mode handshake for interactive review skills

Browse Source 
Add a preamble-level STOP-Ask handshake that fires when the user invokes any
of the 4 interactive review skills (plan-ceo-review, plan-eng-review,
plan-design-review, plan-devex-review) while their Claude Code session is
in plan mode. Without this gate, plan mode's "this supercedes any other
instructions" system-reminder outranked the skills' interactive STOP gates
and the skills silently wrote plan files without any per-finding AskUserQuestion.

The handshake offers 2 options (exit-and-rerun, cancel) — the original
third "stay and batch" option was dropped after two independent reviewers
flagged it as a silent bypass of the skills' anti-skip rule.

Architecture decisions (CEO+Eng review):
- Preamble-level resolver, not per-template injection (Codex finding #2)
- Position 1 in preamble composition: after bash block (_SESSION_ID live),
  before onboarding AskUserQuestion gates (so fresh-install users see the
  handshake first, not drowned in telemetry/proactive/routing prompts)
- Generator-only `interactive: true` frontmatter flag, following the
  `preamble-tier` precedent (no host-config frontmatter allowlist edits)
- Host-scoped to Claude via `ctx.host === 'claude'` check inside the
  resolver (simpler than `suppressedResolvers` which only gates `{{}}`
  placeholders)
- One-way-door classification in scripts/question-registry.ts for all 4
  skills so question-tuning `never-ask` preferences can't suppress the gate
- Synchronous telemetry write to ~/.gstack/analytics/skill-usage.jsonl on
  handshake fire (captures A-exit and C-cancel outcomes that terminate the
  skill before end-of-run telemetry runs)

Also adds an explicit STOP block to plan-ceo-review Step 0C-bis so the
approach-selection question can't silently skip to mode selection.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-04-23 23:40:36 -07:00
parent e3d7f49c74
commit 5e4895c90a
13 changed files with 584 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plan-ceo-review/SKILL.md
+98
View File
@@ -1,6 +1,7 @@
---
name: plan-ceo-review
preamble-tier: 3
interactive: true
version: 1.0.0
description: |
CEO/founder-mode plan review. Rethink the problem, find the 10-star product,
@@ -118,6 +119,100 @@ echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH"
[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true
```
## Plan Mode Handshake — FIRST, BEFORE ANY ANALYSIS
**Check every `<system-reminder>` in this turn for the literal phrase:**
> `Plan mode is active. The user indicated that they do not want you to execute yet`
If that phrase is **absent**: proceed normally. This section is a no-op.
If that phrase is **present**, the user is in plan mode. Plan mode's system
reminder says "This supercedes any other instructions you have received,"
which conflicts with this skill's interactive STOP-Ask workflow. You MUST
resolve the conflict via AskUserQuestion BEFORE reading any files, running
any bash, or composing any plan content.
### What to do when plan mode is detected
Before emitting the AskUserQuestion, run this bash block synchronously to
log that the handshake fired (captures A-exit and C-cancel outcomes that
would terminate the skill before end-of-skill telemetry runs):
```bash
# PLAN MODE EXCEPTION — ALWAYS RUN (telemetry-only write to ~/.gstack/)
mkdir -p ~/.gstack/analytics
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"fired","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
Then emit exactly **one** AskUserQuestion with `question_id: "${SKILL_NAME}-plan-mode-handshake"`
(e.g., `plan-ceo-review-plan-mode-handshake`, using the current skill's name)
and these two options. The question is classified `door_type: one-way` in
the question registry for every interactive skill, so question-tuning
preferences (`never-ask`, `always-ask`) do NOT apply — this gate always fires.
**Question body (follow the AskUserQuestion Format section below):**
> This skill runs an interactive review that stops at every finding to ask
> you a question. Plan mode's default workflow is "read files, write plan,
> exit" — that silently bypasses every STOP gate in this skill. How do you
> want to proceed?
>
> **Recommendation: A** because this skill was designed for back-and-forth.
> Each scope call and each per-section finding needs your decision before it
> lands in the plan. Exiting plan mode and running the skill normally is the
> only path that preserves the interactive contract.
>
> *Note: options differ in kind (workflow shape), not coverage — no
> completeness score.*
>
> **A) Exit plan mode and run interactively (recommended)**
> ✅ Every STOP gate in this skill fires as designed — you approve each
> scope call, each per-section finding, each cross-model tension before any
> decision lands in the plan. No silent bypass.
> ✅ Matches the skill's documented workflow. Each AskUserQuestion has a
> clear recommendation, pros/cons, and net line you can skim in ~5 seconds.
> ❌ Two-step: press esc-esc to exit plan mode, then rerun
> `/plan-{skill-name}`. Slight context-switch friction, but the alternative
> is shipping a rubber-stamp review.
>
> **C) Cancel — I meant to run something else**
> ✅ Clean exit, no partial state, no plan file written, no findings
> recorded. Use this if you invoked the skill by mistake.
> ❌ No output at all — no review, no plan file. Fine if that's what you
> want; otherwise pick A.
>
> **Net.** Plan mode is incompatible with this skill's per-finding STOP
> gates. A is the right choice for any real review; C is the bail-out.
### Routing the user's answer
**If the user picks A (exit and rerun):**
1. Append the outcome to the telemetry log (synchronous, before ExitPlanMode):
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"A-exit","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Respond to the user: "Press **esc-esc** to exit plan mode, then rerun
`/{skill-name}`. The skill will run interactively with every STOP gate
firing as designed."
3. Call `ExitPlanMode` with an empty plan body (plan mode requires
turn-end via AskUserQuestion or ExitPlanMode; there is no plan to
approve, so ExitPlanMode with an empty message is the correct exit).
**If the user picks C (cancel):**
1. Append the outcome:
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"C-cancel","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Tell the user: "Cancelled. No plan written."
3. Call `ExitPlanMode` with an empty message noting the user cancelled.
**After the handshake completes (either A or C),** do NOT continue with the
rest of this skill's workflow. The handshake is terminal for this turn.
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not
auto-invoke skills based on conversation context. Only run skills the user explicitly
types (e.g., /qa, /ship). If you would have auto-invoked a skill, instead briefly say:
@@ -1410,6 +1505,9 @@ Rules:
Present these approach options via AskUserQuestion using the preamble's AskUserQuestion Format section: include RECOMMENDATION and `Completeness: N/10` on every option. These approaches differ in coverage (minimal viable vs ideal architecture), so completeness scoring applies directly.
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. Do NOT proceed to Step 0D or 0F until the user responds to 0C-bis. A "clearly winning approach" is still an approach decision and still needs explicit user approval before it lands in the plan.
**Reminder: Do NOT make any code changes. Review only.**
### 0D-prelude. Expansion Framing (shared by EXPANSION and SELECTIVE EXPANSION)
Every expansion proposal you generate in SCOPE EXPANSION or SELECTIVE EXPANSION mode follows this framing pattern:
plan-ceo-review/SKILL.md.tmpl
+4
View File
@@ -1,6 +1,7 @@
---
name: plan-ceo-review
preamble-tier: 3
interactive: true
version: 1.0.0
description: |
CEO/founder-mode plan review. Rethink the problem, find the 10-star product,
@@ -248,6 +249,9 @@ Rules:
Present these approach options via AskUserQuestion using the preamble's AskUserQuestion Format section: include RECOMMENDATION and `Completeness: N/10` on every option. These approaches differ in coverage (minimal viable vs ideal architecture), so completeness scoring applies directly.
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. Do NOT proceed to Step 0D or 0F until the user responds to 0C-bis. A "clearly winning approach" is still an approach decision and still needs explicit user approval before it lands in the plan.
**Reminder: Do NOT make any code changes. Review only.**
### 0D-prelude. Expansion Framing (shared by EXPANSION and SELECTIVE EXPANSION)
Every expansion proposal you generate in SCOPE EXPANSION or SELECTIVE EXPANSION mode follows this framing pattern:
plan-design-review/SKILL.md
+95
View File
@@ -1,6 +1,7 @@
---
name: plan-design-review
preamble-tier: 3
interactive: true
version: 2.0.0
description: |
Designer's eye plan review — interactive, like CEO and Eng review.
@@ -115,6 +116,100 @@ echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH"
[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true
```
## Plan Mode Handshake — FIRST, BEFORE ANY ANALYSIS
**Check every `<system-reminder>` in this turn for the literal phrase:**
> `Plan mode is active. The user indicated that they do not want you to execute yet`
If that phrase is **absent**: proceed normally. This section is a no-op.
If that phrase is **present**, the user is in plan mode. Plan mode's system
reminder says "This supercedes any other instructions you have received,"
which conflicts with this skill's interactive STOP-Ask workflow. You MUST
resolve the conflict via AskUserQuestion BEFORE reading any files, running
any bash, or composing any plan content.
### What to do when plan mode is detected
Before emitting the AskUserQuestion, run this bash block synchronously to
log that the handshake fired (captures A-exit and C-cancel outcomes that
would terminate the skill before end-of-skill telemetry runs):
```bash
# PLAN MODE EXCEPTION — ALWAYS RUN (telemetry-only write to ~/.gstack/)
mkdir -p ~/.gstack/analytics
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"fired","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
Then emit exactly **one** AskUserQuestion with `question_id: "${SKILL_NAME}-plan-mode-handshake"`
(e.g., `plan-ceo-review-plan-mode-handshake`, using the current skill's name)
and these two options. The question is classified `door_type: one-way` in
the question registry for every interactive skill, so question-tuning
preferences (`never-ask`, `always-ask`) do NOT apply — this gate always fires.
**Question body (follow the AskUserQuestion Format section below):**
> This skill runs an interactive review that stops at every finding to ask
> you a question. Plan mode's default workflow is "read files, write plan,
> exit" — that silently bypasses every STOP gate in this skill. How do you
> want to proceed?
>
> **Recommendation: A** because this skill was designed for back-and-forth.
> Each scope call and each per-section finding needs your decision before it
> lands in the plan. Exiting plan mode and running the skill normally is the
> only path that preserves the interactive contract.
>
> *Note: options differ in kind (workflow shape), not coverage — no
> completeness score.*
>
> **A) Exit plan mode and run interactively (recommended)**
> ✅ Every STOP gate in this skill fires as designed — you approve each
> scope call, each per-section finding, each cross-model tension before any
> decision lands in the plan. No silent bypass.
> ✅ Matches the skill's documented workflow. Each AskUserQuestion has a
> clear recommendation, pros/cons, and net line you can skim in ~5 seconds.
> ❌ Two-step: press esc-esc to exit plan mode, then rerun
> `/plan-{skill-name}`. Slight context-switch friction, but the alternative
> is shipping a rubber-stamp review.
>
> **C) Cancel — I meant to run something else**
> ✅ Clean exit, no partial state, no plan file written, no findings
> recorded. Use this if you invoked the skill by mistake.
> ❌ No output at all — no review, no plan file. Fine if that's what you
> want; otherwise pick A.
>
> **Net.** Plan mode is incompatible with this skill's per-finding STOP
> gates. A is the right choice for any real review; C is the bail-out.
### Routing the user's answer
**If the user picks A (exit and rerun):**
1. Append the outcome to the telemetry log (synchronous, before ExitPlanMode):
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"A-exit","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Respond to the user: "Press **esc-esc** to exit plan mode, then rerun
`/{skill-name}`. The skill will run interactively with every STOP gate
firing as designed."
3. Call `ExitPlanMode` with an empty plan body (plan mode requires
turn-end via AskUserQuestion or ExitPlanMode; there is no plan to
approve, so ExitPlanMode with an empty message is the correct exit).
**If the user picks C (cancel):**
1. Append the outcome:
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"C-cancel","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Tell the user: "Cancelled. No plan written."
3. Call `ExitPlanMode` with an empty message noting the user cancelled.
**After the handshake completes (either A or C),** do NOT continue with the
rest of this skill's workflow. The handshake is terminal for this turn.
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not
auto-invoke skills based on conversation context. Only run skills the user explicitly
types (e.g., /qa, /ship). If you would have auto-invoked a skill, instead briefly say:
plan-design-review/SKILL.md.tmpl
+1
View File
@@ -1,6 +1,7 @@
---
name: plan-design-review
preamble-tier: 3
interactive: true
version: 2.0.0
description: |
Designer's eye plan review — interactive, like CEO and Eng review.
plan-devex-review/SKILL.md
+95
View File
@@ -1,6 +1,7 @@
---
name: plan-devex-review
preamble-tier: 3
interactive: true
version: 2.0.0
description: |
Interactive developer experience plan review. Explores developer personas,
@@ -119,6 +120,100 @@ echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH"
[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true
```
## Plan Mode Handshake — FIRST, BEFORE ANY ANALYSIS
**Check every `<system-reminder>` in this turn for the literal phrase:**
> `Plan mode is active. The user indicated that they do not want you to execute yet`
If that phrase is **absent**: proceed normally. This section is a no-op.
If that phrase is **present**, the user is in plan mode. Plan mode's system
reminder says "This supercedes any other instructions you have received,"
which conflicts with this skill's interactive STOP-Ask workflow. You MUST
resolve the conflict via AskUserQuestion BEFORE reading any files, running
any bash, or composing any plan content.
### What to do when plan mode is detected
Before emitting the AskUserQuestion, run this bash block synchronously to
log that the handshake fired (captures A-exit and C-cancel outcomes that
would terminate the skill before end-of-skill telemetry runs):
```bash
# PLAN MODE EXCEPTION — ALWAYS RUN (telemetry-only write to ~/.gstack/)
mkdir -p ~/.gstack/analytics
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"fired","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
Then emit exactly **one** AskUserQuestion with `question_id: "${SKILL_NAME}-plan-mode-handshake"`
(e.g., `plan-ceo-review-plan-mode-handshake`, using the current skill's name)
and these two options. The question is classified `door_type: one-way` in
the question registry for every interactive skill, so question-tuning
preferences (`never-ask`, `always-ask`) do NOT apply — this gate always fires.
**Question body (follow the AskUserQuestion Format section below):**
> This skill runs an interactive review that stops at every finding to ask
> you a question. Plan mode's default workflow is "read files, write plan,
> exit" — that silently bypasses every STOP gate in this skill. How do you
> want to proceed?
>
> **Recommendation: A** because this skill was designed for back-and-forth.
> Each scope call and each per-section finding needs your decision before it
> lands in the plan. Exiting plan mode and running the skill normally is the
> only path that preserves the interactive contract.
>
> *Note: options differ in kind (workflow shape), not coverage — no
> completeness score.*
>
> **A) Exit plan mode and run interactively (recommended)**
> ✅ Every STOP gate in this skill fires as designed — you approve each
> scope call, each per-section finding, each cross-model tension before any
> decision lands in the plan. No silent bypass.
> ✅ Matches the skill's documented workflow. Each AskUserQuestion has a
> clear recommendation, pros/cons, and net line you can skim in ~5 seconds.
> ❌ Two-step: press esc-esc to exit plan mode, then rerun
> `/plan-{skill-name}`. Slight context-switch friction, but the alternative
> is shipping a rubber-stamp review.
>
> **C) Cancel — I meant to run something else**
> ✅ Clean exit, no partial state, no plan file written, no findings
> recorded. Use this if you invoked the skill by mistake.
> ❌ No output at all — no review, no plan file. Fine if that's what you
> want; otherwise pick A.
>
> **Net.** Plan mode is incompatible with this skill's per-finding STOP
> gates. A is the right choice for any real review; C is the bail-out.
### Routing the user's answer
**If the user picks A (exit and rerun):**
1. Append the outcome to the telemetry log (synchronous, before ExitPlanMode):
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"A-exit","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Respond to the user: "Press **esc-esc** to exit plan mode, then rerun
`/{skill-name}`. The skill will run interactively with every STOP gate
firing as designed."
3. Call `ExitPlanMode` with an empty plan body (plan mode requires
turn-end via AskUserQuestion or ExitPlanMode; there is no plan to
approve, so ExitPlanMode with an empty message is the correct exit).
**If the user picks C (cancel):**
1. Append the outcome:
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"C-cancel","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Tell the user: "Cancelled. No plan written."
3. Call `ExitPlanMode` with an empty message noting the user cancelled.
**After the handshake completes (either A or C),** do NOT continue with the
rest of this skill's workflow. The handshake is terminal for this turn.
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not
auto-invoke skills based on conversation context. Only run skills the user explicitly
types (e.g., /qa, /ship). If you would have auto-invoked a skill, instead briefly say:
plan-devex-review/SKILL.md.tmpl
+1
View File
@@ -1,6 +1,7 @@
---
name: plan-devex-review
preamble-tier: 3
interactive: true
version: 2.0.0
description: |
Interactive developer experience plan review. Explores developer personas,
plan-eng-review/SKILL.md
+95
View File
@@ -1,6 +1,7 @@
---
name: plan-eng-review
preamble-tier: 3
interactive: true
version: 1.0.0
description: |
Eng manager-mode plan review. Lock in the execution plan — architecture,
@@ -117,6 +118,100 @@ echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH"
[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true
```
## Plan Mode Handshake — FIRST, BEFORE ANY ANALYSIS
**Check every `<system-reminder>` in this turn for the literal phrase:**
> `Plan mode is active. The user indicated that they do not want you to execute yet`
If that phrase is **absent**: proceed normally. This section is a no-op.
If that phrase is **present**, the user is in plan mode. Plan mode's system
reminder says "This supercedes any other instructions you have received,"
which conflicts with this skill's interactive STOP-Ask workflow. You MUST
resolve the conflict via AskUserQuestion BEFORE reading any files, running
any bash, or composing any plan content.
### What to do when plan mode is detected
Before emitting the AskUserQuestion, run this bash block synchronously to
log that the handshake fired (captures A-exit and C-cancel outcomes that
would terminate the skill before end-of-skill telemetry runs):
```bash
# PLAN MODE EXCEPTION — ALWAYS RUN (telemetry-only write to ~/.gstack/)
mkdir -p ~/.gstack/analytics
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"fired","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
Then emit exactly **one** AskUserQuestion with `question_id: "${SKILL_NAME}-plan-mode-handshake"`
(e.g., `plan-ceo-review-plan-mode-handshake`, using the current skill's name)
and these two options. The question is classified `door_type: one-way` in
the question registry for every interactive skill, so question-tuning
preferences (`never-ask`, `always-ask`) do NOT apply — this gate always fires.
**Question body (follow the AskUserQuestion Format section below):**
> This skill runs an interactive review that stops at every finding to ask
> you a question. Plan mode's default workflow is "read files, write plan,
> exit" — that silently bypasses every STOP gate in this skill. How do you
> want to proceed?
>
> **Recommendation: A** because this skill was designed for back-and-forth.
> Each scope call and each per-section finding needs your decision before it
> lands in the plan. Exiting plan mode and running the skill normally is the
> only path that preserves the interactive contract.
>
> *Note: options differ in kind (workflow shape), not coverage — no
> completeness score.*
>
> **A) Exit plan mode and run interactively (recommended)**
> ✅ Every STOP gate in this skill fires as designed — you approve each
> scope call, each per-section finding, each cross-model tension before any
> decision lands in the plan. No silent bypass.
> ✅ Matches the skill's documented workflow. Each AskUserQuestion has a
> clear recommendation, pros/cons, and net line you can skim in ~5 seconds.
> ❌ Two-step: press esc-esc to exit plan mode, then rerun
> `/plan-{skill-name}`. Slight context-switch friction, but the alternative
> is shipping a rubber-stamp review.
>
> **C) Cancel — I meant to run something else**
> ✅ Clean exit, no partial state, no plan file written, no findings
> recorded. Use this if you invoked the skill by mistake.
> ❌ No output at all — no review, no plan file. Fine if that's what you
> want; otherwise pick A.
>
> **Net.** Plan mode is incompatible with this skill's per-finding STOP
> gates. A is the right choice for any real review; C is the bail-out.
### Routing the user's answer
**If the user picks A (exit and rerun):**
1. Append the outcome to the telemetry log (synchronous, before ExitPlanMode):
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"A-exit","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Respond to the user: "Press **esc-esc** to exit plan mode, then rerun
`/{skill-name}`. The skill will run interactively with every STOP gate
firing as designed."
3. Call `ExitPlanMode` with an empty plan body (plan mode requires
turn-end via AskUserQuestion or ExitPlanMode; there is no plan to
approve, so ExitPlanMode with an empty message is the correct exit).
**If the user picks C (cancel):**
1. Append the outcome:
```bash
echo '{"skill":"'"${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"C-cancel","branch":"'"${_BRANCH:-unknown}"'","session":"'"${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
```
2. Tell the user: "Cancelled. No plan written."
3. Call `ExitPlanMode` with an empty message noting the user cancelled.
**After the handshake completes (either A or C),** do NOT continue with the
rest of this skill's workflow. The handshake is terminal for this turn.
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not
auto-invoke skills based on conversation context. Only run skills the user explicitly
types (e.g., /qa, /ship). If you would have auto-invoked a skill, instead briefly say:
plan-eng-review/SKILL.md.tmpl
+1
View File
@@ -1,6 +1,7 @@
---
name: plan-eng-review
preamble-tier: 3
interactive: true
version: 1.0.0
description: |
Eng manager-mode plan review. Lock in the execution plan — architecture,
scripts/gen-skill-docs.ts
+5 -1
View File
@@ -425,7 +425,11 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath:
const tierMatch = tmplContent.match(/^preamble-tier:\s*(\d+)$/m);
const preambleTier = tierMatch ? parseInt(tierMatch[1], 10) : undefined;
const ctx: TemplateContext = { skillName, tmplPath, benefitsFrom, host, paths: HOST_PATHS[host], preambleTier, model: MODEL_ARG_VAL };
// Extract interactive flag from frontmatter (generator-only; controls plan-mode handshake inclusion)
const interactiveMatch = tmplContent.match(/^interactive:\s*(true|false)\s*$/m);
const interactive = interactiveMatch ? interactiveMatch[1] === 'true' : undefined;
const ctx: TemplateContext = { skillName, tmplPath, benefitsFrom, host, paths: HOST_PATHS[host], preambleTier, model: MODEL_ARG_VAL, interactive };
// Replace placeholders (supports parameterized: {{NAME:arg1:arg2}})
// Config-driven: suppressedResolvers return empty string for this host
scripts/question-registry.ts
+39
View File
@@ -261,6 +261,45 @@ export const QUESTIONS = {
description: "Approve the design doc, revise sections, or start over?",
},
// -----------------------------------------------------------------------
// Plan-mode handshake — fires at the top of any interactive review skill
// when the user is in plan mode. Safety-critical, always asked regardless
// of user's tuning preferences. See scripts/resolvers/preamble/generate-
// plan-mode-handshake.ts.
// -----------------------------------------------------------------------
'plan-ceo-review-plan-mode-handshake': {
id: 'plan-ceo-review-plan-mode-handshake',
skill: 'plan-ceo-review',
category: 'routing',
door_type: 'one-way',
options: ['exit-and-rerun', 'cancel'],
description: "Plan mode detected — exit and rerun interactively, or cancel?",
},
'plan-eng-review-plan-mode-handshake': {
id: 'plan-eng-review-plan-mode-handshake',
skill: 'plan-eng-review',
category: 'routing',
door_type: 'one-way',
options: ['exit-and-rerun', 'cancel'],
description: "Plan mode detected — exit and rerun interactively, or cancel?",
},
'plan-design-review-plan-mode-handshake': {
id: 'plan-design-review-plan-mode-handshake',
skill: 'plan-design-review',
category: 'routing',
door_type: 'one-way',
options: ['exit-and-rerun', 'cancel'],
description: "Plan mode detected — exit and rerun interactively, or cancel?",
},
'plan-devex-review-plan-mode-handshake': {
id: 'plan-devex-review-plan-mode-handshake',
skill: 'plan-devex-review',
category: 'routing',
door_type: 'one-way',
options: ['exit-and-rerun', 'cancel'],
description: "Plan mode detected — exit and rerun interactively, or cancel?",
},
// -----------------------------------------------------------------------
// /plan-ceo-review — scope & strategy
// -----------------------------------------------------------------------
scripts/resolvers/preamble.ts
+8
View File
@@ -22,6 +22,7 @@ import { generateQuestionTuning } from './question-tuning';
// Core bootstrap
import { generatePreambleBash } from './preamble/generate-preamble-bash';
import { generatePlanModeHandshake } from './preamble/generate-plan-mode-handshake';
import { generateUpgradeCheck } from './preamble/generate-upgrade-check';
import { generateCompletionStatus } from './preamble/generate-completion-status';
@@ -78,6 +79,13 @@ export function generatePreamble(ctx: TemplateContext): string {
}
const sections = [
generatePreambleBash(ctx),
// Plan-mode handshake at position 1: after bash (so _SESSION_ID / _BRANCH /
// _TEL env vars are live for the synchronous telemetry write) and before
// all onboarding AskUserQuestion gates (so fresh-install users in plan mode
// see the handshake first, not drowned in telemetry / proactive / routing
// prompts). Host-scoped to Claude + interactive-frontmatter-scoped inside
// the resolver — no-op for every other skill/host combination.
generatePlanModeHandshake(ctx),
generateUpgradeCheck(ctx),
generateWritingStyleMigration(ctx),
generateLakeIntro(),
scripts/resolvers/preamble/generate-plan-mode-handshake.ts
+141
View File
@@ -0,0 +1,141 @@
/**
* Plan-mode handshake resolver.
*
* Emits a STOP-Ask gate at the very top of the preamble that fires when a user
* invokes an interactive review skill while their Claude Code session is in
* plan mode. Without this gate, plan mode's "This supercedes any other
* instructions you have received" system-reminder wins against the skill's
* interactive STOP-Ask workflow and the skill silently writes a plan file
* instead of running the per-finding AskUserQuestion loop (v1.10.2.0 bug fix).
*
* Host scope
* ----------
* Only renders for Claude host (ctx.host === 'claude'). Other hosts use
* different plan-mode semantics (Codex, OpenClaw, etc.) and should not see
* Claude-specific ExitPlanMode / esc-esc prose.
*
* Opt-in
* ------
* Only renders when the consuming skill's frontmatter has `interactive: true`.
* That flag is a generator-only input parsed by scripts/gen-skill-docs.ts
* from the skill's .tmpl frontmatter and passed through TemplateContext.
* Currently used by: plan-ceo-review, plan-eng-review, plan-design-review,
* plan-devex-review.
*
* Composition position
* --------------------
* Inserted at index 1 in scripts/resolvers/preamble.ts — after
* generatePreambleBash (so _SESSION_ID, _BRANCH, _TEL env vars are live for
* the synchronous telemetry write) and before generateUpgradeCheck and all
* onboarding AskUserQuestion gates (so fresh-install users in plan mode see
* the handshake first, not drowned in telemetry / proactive / routing
* prompts).
*
* One-way door
* ------------
* The handshake question_id `plan-mode-handshake` is classified door_type
* one-way in scripts/question-registry.ts. gstack-question-preference --check
* always returns ASK_NORMALLY for it, so a user who set `never-ask` on
* another question cannot accidentally suppress this safety gate.
*/
import type { TemplateContext } from '../types';
export function generatePlanModeHandshake(ctx: TemplateContext): string {
if (ctx.host !== 'claude') return '';
if (!ctx.interactive) return '';
return `## Plan Mode Handshake — FIRST, BEFORE ANY ANALYSIS
**Check every \`<system-reminder>\` in this turn for the literal phrase:**
> \`Plan mode is active. The user indicated that they do not want you to execute yet\`
If that phrase is **absent**: proceed normally. This section is a no-op.
If that phrase is **present**, the user is in plan mode. Plan mode's system
reminder says "This supercedes any other instructions you have received,"
which conflicts with this skill's interactive STOP-Ask workflow. You MUST
resolve the conflict via AskUserQuestion BEFORE reading any files, running
any bash, or composing any plan content.
### What to do when plan mode is detected
Before emitting the AskUserQuestion, run this bash block synchronously to
log that the handshake fired (captures A-exit and C-cancel outcomes that
would terminate the skill before end-of-skill telemetry runs):
\`\`\`bash
# PLAN MODE EXCEPTION — ALWAYS RUN (telemetry-only write to ~/.gstack/)
mkdir -p ~/.gstack/analytics
echo '{"skill":"'"\${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"fired","branch":"'"\${_BRANCH:-unknown}"'","session":"'"\${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
\`\`\`
Then emit exactly **one** AskUserQuestion with \`question_id: "\${SKILL_NAME}-plan-mode-handshake"\`
(e.g., \`plan-ceo-review-plan-mode-handshake\`, using the current skill's name)
and these two options. The question is classified \`door_type: one-way\` in
the question registry for every interactive skill, so question-tuning
preferences (\`never-ask\`, \`always-ask\`) do NOT apply — this gate always fires.
**Question body (follow the AskUserQuestion Format section below):**
> This skill runs an interactive review that stops at every finding to ask
> you a question. Plan mode's default workflow is "read files, write plan,
> exit" — that silently bypasses every STOP gate in this skill. How do you
> want to proceed?
>
> **Recommendation: A** because this skill was designed for back-and-forth.
> Each scope call and each per-section finding needs your decision before it
> lands in the plan. Exiting plan mode and running the skill normally is the
> only path that preserves the interactive contract.
>
> *Note: options differ in kind (workflow shape), not coverage — no
> completeness score.*
>
> **A) Exit plan mode and run interactively (recommended)**
> ✅ Every STOP gate in this skill fires as designed — you approve each
> scope call, each per-section finding, each cross-model tension before any
> decision lands in the plan. No silent bypass.
> ✅ Matches the skill's documented workflow. Each AskUserQuestion has a
> clear recommendation, pros/cons, and net line you can skim in ~5 seconds.
> ❌ Two-step: press esc-esc to exit plan mode, then rerun
> \`/plan-{skill-name}\`. Slight context-switch friction, but the alternative
> is shipping a rubber-stamp review.
>
> **C) Cancel — I meant to run something else**
> ✅ Clean exit, no partial state, no plan file written, no findings
> recorded. Use this if you invoked the skill by mistake.
> ❌ No output at all — no review, no plan file. Fine if that's what you
> want; otherwise pick A.
>
> **Net.** Plan mode is incompatible with this skill's per-finding STOP
> gates. A is the right choice for any real review; C is the bail-out.
### Routing the user's answer
**If the user picks A (exit and rerun):**
1. Append the outcome to the telemetry log (synchronous, before ExitPlanMode):
\`\`\`bash
echo '{"skill":"'"\${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"A-exit","branch":"'"\${_BRANCH:-unknown}"'","session":"'"\${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
\`\`\`
2. Respond to the user: "Press **esc-esc** to exit plan mode, then rerun
\`/{skill-name}\`. The skill will run interactively with every STOP gate
firing as designed."
3. Call \`ExitPlanMode\` with an empty plan body (plan mode requires
turn-end via AskUserQuestion or ExitPlanMode; there is no plan to
approve, so ExitPlanMode with an empty message is the correct exit).
**If the user picks C (cancel):**
1. Append the outcome:
\`\`\`bash
echo '{"skill":"'"\${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"C-cancel","branch":"'"\${_BRANCH:-unknown}"'","session":"'"\${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
\`\`\`
2. Tell the user: "Cancelled. No plan written."
3. Call \`ExitPlanMode\` with an empty message noting the user cancelled.
**After the handshake completes (either A or C),** do NOT continue with the
rest of this skill's workflow. The handshake is terminal for this turn.
`;
}
scripts/resolvers/types.ts
+1
View File
@@ -61,6 +61,7 @@ export interface TemplateContext {
paths: HostPaths;
preambleTier?: number; // 1-4, controls which preamble sections are included
model?: Model; // model family for behavioral overlay. Omitted/undefined → no overlay.
interactive?: boolean; // true → emit plan-mode handshake in preamble. Generator-only, not written to SKILL.md.
}
/** Resolver function signature. args is populated for parameterized placeholders like {{INVOKE_SKILL:name}}. */