Rework the plan template for a coding agent, and drop the handoff prompt

Merged
CH
15d ago
+687-1222

Summary

  • Why: the old template had 26 fields copied from design-review templates written for human reviewers. The plan's reader is a coding agent that can explore the repo itself. Behavior was written four times (rules, invariants, scenarios, acceptance examples), and the handoff prompt repeated the whole document, which Copy already takes.

  • New template (packages/hosted/src/plan-template.ts):

    • Goal (problem, outcome)
    • Scope (included, excluded, constraints)
    • Rules: each a one-line statement with Given/When/Then examples
    • Implementation: change map, contracts written as code, patterns to follow, and an optional order
    • Decisions
    • Verification
    • Left to the agent
    • Open questions
    • Data and migration (optional)
    • Assumptions

    An optional field is left out of the body while null. A core field reads "Unanswered".

  • Removed:

    • The handoff prompt, together with users, current behavior, relevant code, terminology, the three quality fields, risks, compatibility, rollout, approach, and steps.
    • An update_plan call that names handoffPrompt is now refused.

  • Reset:

    • Migration 0053_plan_template_reset.sql clears every plan's fields, body and assumptions.
    • plan-store.ts now formats an empty body as the untouched template when it reads it, and a new plan no longer stores a formatted body.
    • Saved conversations are kept.

  • Instructions (brain-host/planning.ts): only the changes the new template needs. The notetaker's handoff line is removed, and its list of whole-sent lists now names rules. The planning model's goal no longer says the plan "can be turned into a prompt". Field guidance lives in the schema's descriptions, which the notetaker already sees.

  • Sources: GitHub Spec Kit, OpenAI ExecPlans, Anthropic's Claude Code guidance, Google's agent program repair study, the SWE-Bench Pro interface block, and Example Mapping. The rationale is in docs/PLANNING.md under "The fixed template".

Evidence

  • ./scripts/check.sh: exit 0.
  • pnpm --filter @luke/web test:store: 585 passed on real Postgres, which applies the new migration.
  • test:agent could not run here: it needs DATABASE_URL, and it fails the same way on the base branch.
  • New tests, each failing without the change (hosted-plans.test.ts):
    • an optional field stays out of the body until it is set, and leaves again when cleared;
    • a handoffPrompt key is refused;
    • rule and example text cannot open a section.
  • The existing template tests now use the new shape.
  • Golden: update-plan-tool-input.json, recorded with LUKE_UPDATE_FIXTURES=1. It changes only because the schema changed.
  • CI could not verify the Plans tab. The panel now draws the new sections, and the fixture plan in planning-fixture.ts changed. ./scripts/verify.sh was not run, because this work was done on Linux. It needs a Mac run before this lands.

šŸ¤– Generated with Claude Code

Open workspace in Conductor