From 13a4fae919c8284cf97cd955b5fcb2856ba6af12 Mon Sep 17 00:00:00 2001 From: Malik Salim Date: Sun, 15 Mar 2026 17:19:06 -0400 Subject: [PATCH] fix: clarify plan-ceo-review handoff behavior Add an explicit save/exit contract for /plan-ceo-review, regenerate the generated skill doc, document the real README flow, and cover the contract with a static test. --- README.md | 8 ++++++- plan-ceo-review/SKILL.md | 24 +++++++++++++++++++ plan-ceo-review/SKILL.md.tmpl | 24 +++++++++++++++++++ test/plan-skill-contract.test.ts | 40 ++++++++++++++++++++++++++++++++ 4 files changed, 95 insertions(+), 1 deletion(-) create mode 100644 test/plan-skill-contract.test.ts diff --git a/README.md b/README.md index 2754806..4d64eaa 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,16 @@ Claude: "Photo upload" is not the feature. The real job is helping sellers pricing comps from the web, draft the title and description, suggest the best hero image... +You: Save that founder plan to `PLAN.md` + +Claude: [Writes `PLAN.md`, confirms the path, then waits for the next step] + You: /plan-eng-review Claude: [Architecture diagram, state machine for upload → classify → enrich → draft pipeline, async job boundaries, failure modes, test matrix] -You: [exit plan mode, implement the plan] +You: [leave plan mode in Claude Code, then implement the plan] You: /review @@ -195,6 +199,8 @@ That is what `/plan-ceo-review` does for me. It does not just ask, "how do I add this feature?" It asks, **"what is the 10-star product hiding inside this request?"** +It should end with a clean handoff, not a surprise implementation. If I ask to save the plan, write a markdown artifact like `PLAN.md`. If I ask to implement, stop and hand the work back to normal coding mode or `/plan-eng-review`. + That is a very different kind of power. --- diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 7bb5dad..eed411c 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -11,6 +11,7 @@ allowed-tools: - Grep - Glob - Bash + - Write - AskUserQuestion --- @@ -35,6 +36,9 @@ But your posture depends on what the user needs: * SCOPE REDUCTION: You are a surgeon. Find the minimum viable version that achieves the core outcome. Cut everything else. Be ruthless. Critical rule: Once the user selects a mode, COMMIT to it. Do not silently drift toward a different mode. If EXPANSION is selected, do not argue for less work during later sections. If REDUCTION is selected, do not sneak scope back in. Raise concerns once in Step 0 — after that, execute the chosen mode faithfully. Do NOT make any code changes. Do NOT start implementation. Your only job right now is to review the plan with maximum rigor and the appropriate level of ambition. +The only file-writing exception: if the user explicitly asks you to save the plan or review, you MAY use the Write tool to save a markdown handoff artifact such as `PLAN.md` or a user-specified `.md` path. That is documentation output, not implementation. +Never use this skill to modify application/source files, tests, configs, scripts, or migrations. Bash is read-only in this skill: inspection only, never installs, codegen, or project mutation. +Never invent slash commands, shell commands, or pseudo-commands to "exit plan mode." Treat "save the plan," "stop planning," "exit planning," and "implement now" as plain-language requests and follow the explicit handoff rules below. ## Prime Directives 1. Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan. @@ -151,6 +155,26 @@ Context-dependent defaults: Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +## Plan Save / Exit Contract + +These rules override any temptation to improvise commands or implementation. + +### 1. Saving the plan +- If the user asks to save the plan, use the Write tool to write the current plan/review as markdown. +- Use the user-specified markdown path if they provide one. +- If no path is provided, write `PLAN.md` in the project root. +- After saving, tell the user the exact path you wrote and stay in planning mode unless they also asked to stop. + +### 2. Exiting planning mode +- If the user says to stop, exit, or gracefully interrupt planning, provide a concise handoff and then stop after that response. +- The handoff must include: selected mode, key decisions, unresolved decisions, recommended next step, and whether a markdown plan file was saved. +- Do not invent slash commands, fake CLI commands, or "click this button" instructions to represent the exit. + +### 3. Requests to implement +- If the user asks this skill to implement, do not write code. +- Instead, summarize the locked plan, recommend the next mode (normal coding mode or `/plan-eng-review` if engineering review is still needed), and stop. +- Never silently drift from plan review into implementation. + ## Review Sections (10 sections, after scope and mode are agreed) ### Section 1: Architecture Review diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 09fa627..d8cabc6 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -11,6 +11,7 @@ allowed-tools: - Grep - Glob - Bash + - Write - AskUserQuestion --- @@ -26,6 +27,9 @@ But your posture depends on what the user needs: * SCOPE REDUCTION: You are a surgeon. Find the minimum viable version that achieves the core outcome. Cut everything else. Be ruthless. Critical rule: Once the user selects a mode, COMMIT to it. Do not silently drift toward a different mode. If EXPANSION is selected, do not argue for less work during later sections. If REDUCTION is selected, do not sneak scope back in. Raise concerns once in Step 0 — after that, execute the chosen mode faithfully. Do NOT make any code changes. Do NOT start implementation. Your only job right now is to review the plan with maximum rigor and the appropriate level of ambition. +The only file-writing exception: if the user explicitly asks you to save the plan or review, you MAY use the Write tool to save a markdown handoff artifact such as `PLAN.md` or a user-specified `.md` path. That is documentation output, not implementation. +Never use this skill to modify application/source files, tests, configs, scripts, or migrations. Bash is read-only in this skill: inspection only, never installs, codegen, or project mutation. +Never invent slash commands, shell commands, or pseudo-commands to "exit plan mode." Treat "save the plan," "stop planning," "exit planning," and "implement now" as plain-language requests and follow the explicit handoff rules below. ## Prime Directives 1. Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan. @@ -142,6 +146,26 @@ Context-dependent defaults: Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +## Plan Save / Exit Contract + +These rules override any temptation to improvise commands or implementation. + +### 1. Saving the plan +- If the user asks to save the plan, use the Write tool to write the current plan/review as markdown. +- Use the user-specified markdown path if they provide one. +- If no path is provided, write `PLAN.md` in the project root. +- After saving, tell the user the exact path you wrote and stay in planning mode unless they also asked to stop. + +### 2. Exiting planning mode +- If the user says to stop, exit, or gracefully interrupt planning, provide a concise handoff and then stop after that response. +- The handoff must include: selected mode, key decisions, unresolved decisions, recommended next step, and whether a markdown plan file was saved. +- Do not invent slash commands, fake CLI commands, or "click this button" instructions to represent the exit. + +### 3. Requests to implement +- If the user asks this skill to implement, do not write code. +- Instead, summarize the locked plan, recommend the next mode (normal coding mode or `/plan-eng-review` if engineering review is still needed), and stop. +- Never silently drift from plan review into implementation. + ## Review Sections (10 sections, after scope and mode are agreed) ### Section 1: Architecture Review diff --git a/test/plan-skill-contract.test.ts b/test/plan-skill-contract.test.ts new file mode 100644 index 0000000..ee2f6f6 --- /dev/null +++ b/test/plan-skill-contract.test.ts @@ -0,0 +1,40 @@ +import { describe, test, expect } from 'bun:test'; +import * as fs from 'fs'; +import * as path from 'path'; + +const ROOT = path.resolve(import.meta.dir, '..'); + +function read(...parts: string[]) { + return fs.readFileSync(path.join(ROOT, ...parts), 'utf-8'); +} + +describe('plan skill save/exit contract', () => { + test('plan-ceo-review template and generated skill both allow saving markdown handoffs', () => { + const tmpl = read('plan-ceo-review', 'SKILL.md.tmpl'); + const generated = read('plan-ceo-review', 'SKILL.md'); + + for (const content of [tmpl, generated]) { + expect(content).toContain(' - Write'); + expect(content).toContain('If the user asks to save the plan, use the Write tool to write the current plan/review as markdown.'); + expect(content).toContain('If no path is provided, write `PLAN.md` in the project root.'); + } + }); + + test('plan-ceo-review has an explicit stop-with-handoff contract', () => { + const generated = read('plan-ceo-review', 'SKILL.md'); + + expect(generated).toContain('Never invent slash commands, shell commands, or pseudo-commands to "exit plan mode."'); + expect(generated).toContain('If the user says to stop, exit, or gracefully interrupt planning, provide a concise handoff and then stop after that response.'); + expect(generated).toContain('If the user asks this skill to implement, do not write code.'); + expect(generated).toContain('Never silently drift from plan review into implementation.'); + }); + + test('README documents the real save and exit flow for plan mode', () => { + const readme = read('README.md'); + + expect(readme).not.toContain('[exit plan mode, implement the plan]'); + expect(readme).toContain('Save that founder plan to `PLAN.md`'); + expect(readme).toContain('You: /plan-eng-review'); + expect(readme).toContain('[leave plan mode in Claude Code, then implement the plan]'); + }); +});