plan_prompt.py 3.2 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071
  1. """``/plan`` — build the plan-mode prompt: a saved markdown implementation plan, no execution.
  2. A first-class built-in with no engine and no model-tool footprint: every surface
  3. feeds :func:`build_plan_prompt` to the agent as a normal turn (like ``/learn``),
  4. so system prompt and history stay untouched (prompt-cache safe).
  5. """
  6. from __future__ import annotations
  7. # Ground rules + authoring craft (writing-craft adapted from obra/superpowers).
  8. _PLAN_MODE_RULES = """\
  9. For this turn, you are in PLAN MODE — planning only.
  10. - Do not implement code.
  11. - Do not edit project files except the plan markdown file itself.
  12. - Do not run mutating terminal commands, commit, push, or perform external
  13. actions.
  14. - You may inspect the repo or other context with read-only commands/tools
  15. when needed.
  16. - Your deliverable is a markdown plan saved inside the active workspace under
  17. `.hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md` (create the directory if
  18. needed; Hermes file tools are backend-aware, so this relative path keeps
  19. the plan with the workspace on local, docker, ssh, modal, and daytona
  20. backends). If the runtime provides a specific target path, use that exact
  21. path instead.
  22. """
  23. _PLAN_CRAFT = """\
  24. Write the plan for an implementer with zero context for the codebase and
  25. questionable taste. A good plan makes implementation obvious — if someone has
  26. to guess, the plan is incomplete.
  27. Structure (include the sections that are relevant):
  28. - Goal — one sentence.
  29. - Current context / assumptions.
  30. - Architecture / proposed approach — 2-3 sentences.
  31. - Step-by-step tasks. Each task is bite-sized (2-5 minutes of focused work),
  32. names exact file paths (`src/models/user.py`, not "the model file"),
  33. includes complete copy-pasteable code where code is needed, and exact
  34. commands with expected output for verification.
  35. - Tests / validation — for code tasks, follow the TDD cycle per task: write
  36. the failing test, run it to verify failure, implement minimally, run to
  37. verify pass, commit.
  38. - Risks, tradeoffs, and open questions.
  39. Principles: DRY, YAGNI, TDD, frequent commits. Avoid vague tasks ("add
  40. authentication"), incomplete code ("add validation here"), and unverifiable
  41. steps ("test it works" — instead: the exact command and its expected output).
  42. Interaction style:
  43. - If the request is clear enough, write the plan directly.
  44. - If it is genuinely underspecified, ask a brief clarifying question instead
  45. of guessing.
  46. - After saving the plan, reply briefly with what you planned and the saved
  47. path, and offer to execute it (e.g. via subagent-driven development) —
  48. but do not start executing in this turn.
  49. """
  50. def build_plan_prompt(task: str = "") -> str:
  51. """Build the plan-mode prompt; empty *task* asks the agent to infer it from conversation context.
  52. See #36821.
  53. """
  54. task = (task or "").strip()
  55. task_block = f"Task to plan:\n{task}\n" if task else (
  56. "No explicit task was given with /plan — infer the task from the "
  57. "current conversation context (the thing we have been discussing "
  58. "or working toward). If the conversation does not imply a task, ask a brief clarifying question.\n"
  59. )
  60. return "[/plan — plan mode]\n\n" + _PLAN_MODE_RULES + "\n" + task_block + "\n" + _PLAN_CRAFT