feat(proof, ce-brainstorm, ce-plan, ce-ideate): HITL review-loop mode (#580)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

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

@@ -38,7 +38,7 @@ After document-review completes, present the options using the platform's blocki
 **Options:**
 1. **Start `/ce:work`** (recommended) - Begin implementing this plan in the current session
 2. **Create Issue** - Create a tracked issue from this plan in your configured issue tracker (GitHub or Linear)
-3. **View & share in Proof** - Open the plan in Proof to read, comment, collaborate, and share a link
+3. **Open in Proof (web app) — review and comment to iterate with the agent** - Open the doc in Every's Proof editor, iterate with the agent via comments, or copy a link to share with others
 4. **Done for now** - Pause; the plan file is saved and can be resumed later
 
 **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.
@@ -46,16 +46,21 @@ After document-review completes, present the options using the platform's blocki
 Based on selection:
 - **Start `/ce:work`** -> Call `/ce:work` with the plan path
 - **Create Issue** -> Follow the Issue Creation section below
-- **View & share in Proof** -> Upload the plan:
-  ```bash
-  CONTENT=$(cat docs/plans/<plan_filename>.md)
-  TITLE="Plan: <plan title from frontmatter>"
-  RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
-    -H "Content-Type: application/json" \
-    -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
-  PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
-  ```
-  Display `View & collaborate in Proof: <PROOF_URL>` if successful, then return to the options
+- **Open in Proof (web app) — review and comment to iterate with the agent** -> Load the `proof` skill in HITL-review mode with:
+  - source file: `docs/plans/<plan_filename>.md`
+  - doc title: `Plan: <plan title from frontmatter>`
+  - identity: `ai:compound-engineering` / `Compound Engineering`
+  - recommended next step: `/ce:work` (shown in the proof skill's final terminal output)
+
+  Follow `references/hitl-review.md` in the proof skill. It uploads the plan, prompts the user for review in Proof's web UI, ingests each thread by reading it fresh and replying in-thread, applies agreed edits as tracked suggestions, and syncs the final markdown back to the plan file atomically on proceed.
+
+  When the proof skill returns:
+  - `status: proceeded` with `localSynced: true` -> the plan on disk now reflects the review. Re-run `document-review` on the updated plan before re-rendering the menu — HITL can materially rewrite the plan body, so the prior document-review pass no longer covers the current file and section 5.3.8 requires a review before any handoff option is offered. Then return to the post-generation options with the refreshed residual findings.
+  - `status: proceeded` with `localSynced: false` -> the reviewed version lives in Proof at `docUrl` but the local copy is stale. Offer to pull the Proof doc to `localPath` using the proof skill's Pull workflow. If the pull happened, re-run `document-review` on the pulled file before re-rendering the options (same 5.3.8 rationale — the local plan was materially updated by the pull). If the pull was declined, include a one-line note above the menu that `<localPath>` is stale vs. Proof — otherwise `Start /ce:work` or `Create Issue` will silently use the pre-review copy.
+  - `status: done_for_now` -> the plan on disk may be stale if the user edited in Proof before leaving. Offer to pull the Proof doc to `localPath` so the local plan file stays in sync. If the pull happened, re-run `document-review` on the pulled file before re-rendering the options (same 5.3.8 rationale). If the pull was declined, include the stale-local note above the menu. `done_for_now` means the user stopped the HITL loop — it does not mean they ended the whole plan session; they may still want to start work or create an issue.
+  - `status: aborted` -> fall back to the options without changes.
+
+  If the initial upload fails (network error, Proof API down), retry once after a short wait. If it still fails, tell the user the upload didn't succeed and briefly explain why, then return to the options — don't leave them wondering why the option did nothing.
 - **Done for now** -> Display a brief confirmation that the plan file is saved and end the turn
 - **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
 - **Other** -> Accept free text for revisions and loop back to options

plugins/compound-engineering/skills/ce-plan/references/universal-planning.md

@@ -93,6 +93,8 @@ Example: A date night plan should present 2-3 restaurant options, 2-3 activity o
 
 After structuring the plan, ask the user how they want to receive it using the platform's question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat.
 
+**Question:** "Plan ready. How would you like to receive it?"
+
 **Options:**
 
 1. **Save to disk** — Write the plan as a markdown file. Ask where:
@@ -103,8 +105,8 @@ After structuring the plan, ask the user how they want to receive it using the p
    - Use filename convention: `YYYY-MM-DD-<descriptive-name>-plan.md`
    - Start the document with a `# Title` heading, followed by `Created: YYYY-MM-DD` on the next line. No YAML frontmatter.
 
-2. **Share to Proof** — View the plan on the web and get a shareable link. Load the `proof` skill to create and share the document. Useful for sharing with others who aren't in the terminal.
+2. **Open in Proof (web app) — review and comment to iterate with the agent** — Open the doc in Every's Proof editor, iterate with the agent via comments, or copy a link to share with others. Load the `proof` skill to create and open the document.
 
-3. **Both** — Save to disk and share to Proof.
+3. **Save to disk AND open in Proof** — Do both: write the markdown file to disk and open the doc in Proof for review.
 
 Do not offer `/ce:work` (software-only) or issue creation (not applicable to non-software plans).