plan

A short, structured plan written before any code, reviewed and approved as a contract. The agent maps the change before doing it. Scope creep becomes visible.

When to use it

• Any change touching more than three files.
• Refactors, migrations, public-API changes.
• Optional but worth it for smaller changes. A two-file change still benefits from a five-line plan.

What it produces

One file at .context/plans/<YYYY-MM-DD>-<slug>.md with non-negotiable sections:

• Intent: the why.
• Files touched: real list, not aspirational.
• Approach: two or three sentences. Not a design doc.
• Verification: real commands.
• Out of scope: at least two bullets. Always.
• Rollback, Risks, Notes.

Status moves draft → approved → in-progress → shipped. The file stays in the repo as context for future agents.

How it works

1. Understand the task. If it is vague, ask one focused question.
2. Read the relevant code. Map the actual files.
3. Draft. Fill each section. Approach is two or three sentences.
4. Show the plan; wait for approval. Approve, edit, or reject. Never code before approval.
5. Checkpoint commit. Record the hash. If the change goes sideways, you have a known-good state.
6. Implement, verifying as you go. If reality forces a change, update the plan first, get re-approval, then continue.
7. Mark shipped. Record the merge commit. Leave the file in place.
8. Prompt for ADRs. If the plan made a technology choice or rejected an alternative, offer adr. Never write one without asking.