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

Plan Handoff

This file contains post-plan-writing instructions: document review, post-generation options, and issue creation. Load it after the plan file has been written and the confidence check (5.3.1-5.3.7) is complete.

5.3.8 Document Review

After the confidence check (and any deepening), run the document-review skill on the plan file. Pass the plan path as the argument. When this step is reached, it is mandatory — do not skip it because the confidence check already ran. The two tools catch different classes of issues.

The confidence check and document-review are complementary:

• The confidence check strengthens rationale, sequencing, risk treatment, and grounding
• Document-review checks coherence, feasibility, scope alignment, and surfaces role-specific issues

If document-review returns findings that were auto-applied, note them briefly when presenting handoff options. If residual P0/P1 findings were surfaced, mention them so the user can decide whether to address them before proceeding.

When document-review returns "Review complete", proceed to Final Checks.

Pipeline mode: If invoked from an automated workflow such as LFG, SLFG, or any disable-model-invocation context, run document-review with mode:headless and the plan path. Headless mode applies auto-fixes silently and returns structured findings without interactive prompts. Address any P0/P1 findings before returning control to the caller.

5.3.9 Final Checks and Cleanup

Before proceeding to post-generation options:

• Confirm the plan is stronger in specific ways, not merely longer
• Confirm the planning boundary is intact
• Confirm origin decisions were preserved when an origin document exists

If artifact-backed mode was used:

• Clean up the temporary scratch directory after the plan is safely updated
• If cleanup is not practical on the current platform, note where the artifacts were left

5.4 Post-Generation Options

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 (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 (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
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.

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:

  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
• 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

Issue Creation

When the user selects "Create Issue", detect their project tracker:

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 project_tracker: github:

   gh issue create --title "<type>: <title>" --body-file <plan_path>
   

3. If project_tracker: linear:

   linear issue create --title "<title>" --description "$(cat <plan_path>)"
   

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:

   • Proceed with the chosen tracker's command above
   • 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 using the platform's blocking question tool