90 lines
6.0 KiB
Markdown
90 lines
6.0 KiB
Markdown
# 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:
|
|
```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
|
|
- **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`:
|
|
|
|
```bash
|
|
gh issue create --title "<type>: <title>" --body-file <plan_path>
|
|
```
|
|
|
|
3. If `project_tracker: linear`:
|
|
|
|
```bash
|
|
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
|