fix(ce-plan, ce-brainstorm): reliable interactive handoff menus (#575)

plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md

@@ -6,7 +6,7 @@ This content is loaded when Phase 4 begins — after the requirements document i
 
 #### 4.1 Present Next-Step Options
 
-Present next steps using the platform's blocking question tool when available (see Interaction Rules in the main skill). Otherwise present numbered options in chat and end the turn.
+Present the options using the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the numbered options in chat and wait for the user's reply before proceeding.
 
 If `Resolve Before Planning` contains any items:
 - Ask the blocking questions now, one at a time, by default
@@ -18,15 +18,15 @@ If `Resolve Before Planning` contains any items:
 
 **Question when blocking questions remain and user wants to pause:** "Brainstorm paused. Planning is blocked until the remaining questions are resolved. What would you like to do next?"
 
-Present only the options that apply:
+Present only the options that apply, keeping the total at 4 or fewer:
-- **Proceed to planning (Recommended)** - Run `/ce:plan` for structured implementation planning
-- **Proceed directly to work** - Only offer this when scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain
-- **Run additional document review** - Offer this only when a requirements document exists. Runs another pass for further refinement
-- **Ask more questions** - Continue clarifying scope, preferences, or edge cases
-- **Share to Proof** - Offer this only when a requirements document exists
-- **Done for now** - Return later
 
-If the direct-to-work gate is not satisfied, omit that option entirely.
+- **Proceed to planning (Recommended)** - Move to `/ce:plan` for structured implementation planning. Shown only when `Resolve Before Planning` is empty.
+- **Proceed directly to work** - Skip planning and move to `/ce:work`; suited to lightweight, well-defined changes. Shown only when `Resolve Before Planning` is empty **and** scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain (the "direct-to-work gate").
+- **Continue the brainstorm** - Answer more clarifying questions to tighten scope, edge cases, and preferences. Always shown.
+- **View & share in Proof** - Open the requirements doc in Proof to read, comment, collaborate, and share a link. Shown only when a requirements document exists **and** the direct-to-work gate is not satisfied (when both conditions collide, `Proceed directly to work` takes priority and Proof becomes reachable via free-form request).
+- **Done for now** - Pause; the requirements doc is saved and can be resumed later. Always shown.
+
+**Surface additional document review contextually, not as a menu fixture:** When the prior document-review pass surfaced residual P0/P1 findings that the user has not addressed, mention them adjacent to the menu and offer another review pass in prose (e.g., "Document review flagged 2 P1 findings you may want to address — want me to run another pass?"). Do not add it to the option list.
 
 #### 4.2 Handle the Selected Option
 
@@ -38,7 +38,9 @@ Immediately run `/ce:plan` in the current session. Pass the requirements documen
 
 Immediately run `/ce:work` in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first.
 
-**If user selects "Share to Proof":**
+**If user selects "Continue the brainstorm":** Return to Phase 1.3 (Collaborative Dialogue) and continue asking the user clarifying questions one at a time to further refine scope, edge cases, constraints, and preferences. Continue until the user is satisfied, then return to Phase 4. Do not show the closing summary yet.
+
+**If user selects "View & share in Proof":**
 
 ```bash
 CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md)
@@ -53,13 +55,11 @@ Display the URL prominently: `View & collaborate in Proof: <PROOF_URL>`
 
 If the curl fails, skip silently. Then return to the Phase 4 options.
 
-**If user selects "Ask more questions":** Return to Phase 1.3 (Collaborative Dialogue) and continue asking the user questions one at a time to further refine the design. Probe deeper into edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4. Do not show the closing summary yet.
+**If the user asks to run another document review** (either from the contextual prompt when P0/P1 findings remain, or by free-form request):
 
-**If user selects "Run additional document review":**
+Load the `document-review` skill and apply it to the requirements document for another pass. When document-review returns "Review complete", return to the normal Phase 4 options and present only the options that still apply. Do not show the closing summary yet.
 
-Load the `document-review` skill and apply it to the requirements document for another pass.
+**If user selects "Done for now":** Display the closing summary (see 4.3) and end the turn.
-
-When document-review returns "Review complete", return to the normal Phase 4 options and present only the options that still apply. Do not show the closing summary yet.
 
 #### 4.3 Closing Summary
 

plugins/compound-engineering/skills/ce-brainstorm/references/universal-brainstorming.md

@@ -48,5 +48,5 @@ When the conversation has enough material to narrow — reflect back what you've
 **Then offer next steps** using the platform's question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini):
 - **Create a plan** → hand off to `/ce:plan` with the decided goal and constraints
 - **Save summary to disk** → write the summary as a markdown file in the current working directory
-- **Share to Proof** → load the `proof` skill to create a shareable web link for others to review
+- **View & share in Proof** → load the `proof` skill to open the summary in Proof for reading, collaborating, and sharing a link
 - **Done** → the conversation was the value, no artifact needed

plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md

@@ -31,22 +31,22 @@ If artifact-backed mode was used:
 
 **Pipeline mode:** If invoked from an automated workflow such as LFG, SLFG, or any `disable-model-invocation` context, skip the interactive menu below and return control to the caller immediately. The plan file has already been written, the confidence check has already run, and document-review has already run — the caller (e.g., lfg, slfg) determines the next step.
 
-After document-review completes, present the options using the platform's blocking question tool when available (see Interaction Method). Otherwise present numbered options in chat and wait for the user's reply before proceeding.
+After document-review completes, present the options using the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the numbered options in chat and wait for the user's reply before proceeding.
 
 **Question:** "Plan ready at `docs/plans/YYYY-MM-DD-NNN-<type>-<name>-plan.md`. What would you like to do next?"
 
 **Options:**
-1. **Start `/ce:work`** - Begin implementing this plan in the current environment (recommended)
+1. **Start `/ce:work`** (recommended) - Begin implementing this plan in the current session
-2. **Open plan in editor** - Open the plan file for review
+2. **Create Issue** - Create a tracked issue from this plan in your configured issue tracker (GitHub or Linear)
-3. **Run additional document review** - Another pass for further refinement
+3. **View & share in Proof** - Open the plan in Proof to read, comment, collaborate, and share a link
-4. **Share to Proof** - Upload the plan for collaborative review and sharing
+4. **Done for now** - Pause; the plan file is saved and can be resumed later
-5. **Start `/ce:work` in another session** - Begin implementing in a separate agent session when the current platform supports it
+
-6. **Create Issue** - Create an issue in the configured tracker
+**Surface additional document review contextually, not as a menu fixture:** When the prior document-review pass surfaced residual P0/P1 findings that the user has not addressed, mention them adjacent to the menu and offer another review pass in prose (e.g., "Document review flagged 2 P1 findings you may want to address — want me to run another pass before you pick?"). Do not add it to the option list.
 
 Based on selection:
-- **Open plan in editor** -> Open `docs/plans/<plan_filename>.md` using the current platform's file-open or editor mechanism (e.g., `open` on macOS, `xdg-open` on Linux, or the IDE's file-open API)
+- **Start `/ce:work`** -> Call `/ce:work` with the plan path
-- **Run additional document review** -> Load the `document-review` skill with the plan path for another pass
+- **Create Issue** -> Follow the Issue Creation section below
-- **Share to Proof** -> Upload the plan:
+- **View & share in Proof** -> Upload the plan:
   ```bash
   CONTENT=$(cat docs/plans/<plan_filename>.md)
   TITLE="Plan: <plan title from frontmatter>"
@@ -56,32 +56,34 @@ Based on selection:
   PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
   ```
   Display `View & collaborate in Proof: <PROOF_URL>` if successful, then return to the options
-- **`/ce:work`** -> Call `/ce:work` with the plan path
+- **Done for now** -> Display a brief confirmation that the plan file is saved and end the turn
-- **`/ce:work` in another session** -> If the current platform supports launching a separate agent session, start `/ce:work` with the plan path there. Otherwise, explain the limitation briefly and offer to run `/ce:work` in the current session instead.
+- **If the user asks for another document review** (either from the contextual prompt when P0/P1 findings remain, or by free-form request) -> Load the `document-review` skill with the plan path for another pass, then return to the options
-- **Create Issue** -> Follow the Issue Creation section below
 - **Other** -> Accept free text for revisions and loop back to options
 
 ## Issue Creation
 
-When the user selects "Create Issue", detect their project tracker from `AGENTS.md` or, if needed for compatibility, `CLAUDE.md`:
+When the user selects "Create Issue", detect their project tracker:
 
-1. Look for `project_tracker: github` or `project_tracker: linear`
+1. Read `AGENTS.md` (or `CLAUDE.md` for compatibility) at the repo root and look for `project_tracker: github` or `project_tracker: linear`.
-2. If GitHub:
+2. If `project_tracker: github`:
 
    ```bash
    gh issue create --title "<type>: <title>" --body-file <plan_path>
    ```
 
-3. If Linear:
+3. If `project_tracker: linear`:
 
    ```bash
    linear issue create --title "<title>" --description "$(cat <plan_path>)"
    ```
 
-4. If no tracker is configured:
+4. If no tracker is configured, ask the user which tracker they use with the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, ask in chat and wait for the reply. Options: `GitHub`, `Linear`, `Skip`. Then:
-   - Ask which tracker they use using the platform's blocking question tool when available (see Interaction Method)
+   - Proceed with the chosen tracker's command above
-   - Suggest adding the tracker to `AGENTS.md` for future runs
+   - Offer to persist the choice by adding `project_tracker: <value>` to `AGENTS.md`, where `<value>` is the lowercase tracker key (`github` or `linear`) — not the display label — so future runs match the detector in step 1 and skip this prompt
+   - If `Skip`, return to the options without creating an issue
+
+5. If the detected tracker's CLI is not installed or not authenticated, surface a clear error (e.g., "`gh` CLI not found — install it or create the issue manually") and return to the options.
 
 After issue creation:
 - Display the issue URL
-- Ask whether to proceed to `/ce:work`
+- Ask whether to proceed to `/ce:work` using the platform's blocking question tool

tests/pipeline-review-contract.test.ts

@@ -284,9 +284,11 @@ describe("ce:brainstorm review contract", () => {
     expect(content).toContain("`references/requirements-capture.md`")
     expect(content).toContain("`references/handoff.md`")
 
-    // Handoff option is for additional passes, not the first review (now in extracted reference)
+    // Additional review passes are surfaced contextually (not as a menu fixture) and still
+    // route through the document-review skill when requested
     const handoff = await readRepoFile("plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md")
-    expect(handoff).toContain("**Run additional document review**")
+    expect(handoff).toContain("Surface additional document review contextually")
+    expect(handoff).toContain("Load the `document-review` skill")
     expect(handoff).not.toContain("**Review and refine**")
   })
 })
@@ -339,10 +341,12 @@ describe("ce:plan review contract", () => {
     const content = await readRepoFile("plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md")
 
     // ce:work is recommended (review already happened)
-    expect(content).toContain("**Start `/ce:work`** - Begin implementing this plan in the current environment (recommended)")
+    expect(content).toContain("**Start `/ce:work`** (recommended) - Begin implementing this plan in the current session")
 
-    // Document review option is for additional passes
+    // Additional review passes are surfaced contextually (not as a menu fixture) and still
-    expect(content).toContain("**Run additional document review**")
+    // route through the document-review skill when requested
+    expect(content).toContain("Surface additional document review contextually")
+    expect(content).toContain("Load the `document-review` skill")
 
     // No conditional ordering based on plan depth (review already ran)
     expect(content).not.toContain("**Options when document-review is recommended:**")