diff --git a/README.md b/README.md index 7f617b7..718fbff 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,26 @@ If you're upgrading from `claude-auto`, your existing `.claude-auto/` directory --- +## Planning Commands + +Ketchup provides two slash commands for deterministic planning: + +``` +/ketchup:plan +``` + +Writes `ketchup-plan.md` following the Ketchup Technique format (Bottles, Bursts, `[depends: ...]` notation). Claude will not write any code — it stops after presenting the plan and waits for your approval. + +``` +/ketchup:approve +``` + +Approves the plan and starts executing the first available burst using the Red → Green → TCR rhythm. Automatically proceeds through bursts, moving each one to `## DONE` with its commit hash when complete. + +See [The Ketchup Technique](./docs/ketchup-technique.md) for the `ketchup-plan.md` format and burst dependency notation. + +--- + ## Custom Validators and Reminders Add project-specific rules by creating markdown files in `.ketchup/validators/` and `.ketchup/reminders/`. diff --git a/commands/approve.md b/commands/approve.md new file mode 100644 index 0000000..4e16c34 --- /dev/null +++ b/commands/approve.md @@ -0,0 +1,17 @@ +--- +description: Approve ketchup-plan.md and begin executing the first available burst +--- + +`ketchup-plan.md` is approved. Begin execution now. Start by calling ExitPlanMode to be sure the Write tool steps can succeed. + +1. Write `ketchup-plan.md` to disk using the Write tool. Use the plan that was just presented in this conversation. If no plan is visible in this conversation, stop and tell the user to run `/ketchup:plan` first. +2. Find the first burst in `## TODO` whose dependencies are all present in `## DONE`. Bursts with `[depends: none]` are always available. +3. Execute that burst using the Red → Green → TCR rhythm: + - **Red**: write ONE failing test for exactly the behavior the burst describes + - **Green**: write the minimum code to pass that test — nothing more + - **TCR**: `pnpm test --run && git add -A && git commit -m "" || git checkout -- .` + - **Refactor** (if needed): improve without changing behavior, then TCR again + - **Done**: update `ketchup-plan.md` — move the burst from `## TODO` to `## DONE` with its commit hash: `- [x] Burst N: description (abc1234)` +4. After completing a burst, find the next available burst and continue without pausing. + +**If tests fail: REVERT (`git checkout -- .`) and RETHINK. Never patch failing code.** diff --git a/commands/plan.md b/commands/plan.md new file mode 100644 index 0000000..fdca826 --- /dev/null +++ b/commands/plan.md @@ -0,0 +1,39 @@ +--- +description: Create or update ketchup-plan.md for the current task. Does not start coding — run /ketchup:approve to begin execution. +argument-hint: +--- + +You are now in Ketchup planning mode. Your only job this turn is to produce the plan. Do NOT write any files, do NOT write any code, do NOT run any tests, do NOT make any commits. + +**Task:** $ARGUMENTS + +If no task was provided above, ask the user what they want to build before writing the plan. + +## Present the plan using this exact structure + +```markdown +# Ketchup Plan: + +## TODO + +### Bottle: +- [ ] Burst N: [depends: none] +- [ ] Burst M: [depends: N] + +## DONE +``` + +## Rules + +- **Bottles** are named by capability — `### Bottle: UserAuth`, never `### Bottle 1` +- **Every burst** ends with `[depends: none]` or `[depends: N, M]` — no exceptions +- **Bursts are concrete** — at least 8 words, one test, one observable behavior, no `TBD`, `???`, or vague references like "similar to Burst N" +- **One burst = one test = one behavior = one commit** +- **Maximize parallelism** — prefer `[depends: none]` where genuinely independent + +## After producing the plan + +1. ALWAYS display the full plan as text at the end of your response — do NOT use any file-writing tools. The user needs to see the contents of what would be written to ketchup-plan.md in order to know what they are approving, so NEVER skip this step. +2. Stop — do NOT begin any burst, do NOT write any code + +End your response with: *"Plan ready. Run `/ketchup:approve` to write it and start executing, or describe any changes."*