Writing plans

Implementation Planning

Create the smallest plan that another capable agent can execute without rediscovering critical context.

Plan Contract

Capture:

• Goal and observable completion condition
• In-scope and out-of-scope boundaries
• Relevant repository instructions and responsibility boundaries
• Assumptions, dependencies, and irreversible decisions
• Ordered implementation steps with concrete files or components when known
• Validation mapped to each risky behavior or state transition
• Stop conditions and decisions that require user input

Each step should produce a reviewable increment. Split work only where a dependency, validation boundary, or independent deliverable justifies it.

Rules

• Inspect the repository before naming files or commands.
• Prefer repository-native tests and workflows over generic prescriptions.
• Do not force TDD, commits, worktrees, subagents, or a fixed plan directory.
• Do not write placeholders such as "add tests"; state what behavior must be proven.
• Keep implementation details proportional to risk. A small safe change may need only a short checklist.
• Save the plan only when the user requests an artifact or repository conventions require one; otherwise return it inline.

Output

1. Goal and acceptance
2. Scope and constraints
3. Ordered steps
4. Validation
5. Risks, stop conditions, and unresolved decisions