writing-plans

Writing Plans

Create a durable plan only when it materially improves execution or recovery. Plans are source-of-truth artifacts, not mandatory ceremony.

Plan Threshold

Use this module when at least one is true:

• the user explicitly requests a durable implementation plan;
• execution has several dependent steps or independent subsystems;
• risk, migration, coordination, or compaction recovery requires locked decisions;
• another agent must execute without product or architecture guesswork.

Fast localized work and chat-only planning skip .workflow/. An explicit no-edits/read-only boundary blocks plan artifacts unless the user separately authorizes a durable plan.

Planning Does Not Expand Context

A plan is not permission to map or preemptively harden. Every task must trace to stated behavior, observed failure, or normal-path risk. Cut only work outside acceptance, normal flow, integrity/security, and compatibility; minimal means behavior-complete, not partial. Reuse the working set; don't rediscover after create, reflection, or compaction.

Create Or Resume

Use workflow_plan_create, workflow_plan_update, workflow_plan_artifact_write, and workflow_handoff_write when available. Manual .workflow/ writes are fallback only. Resume an unfinished matching run; do not reopen completed work by default.

Read references/plan-schema.md when creating a run, defining chunks/tasks, or writing a plan handoff. Do not load it for a chat-only plan.

Plan Contract

The plan must lock decisions that execution cannot safely infer:

• exact goal, success criteria, scope, and non-goals;
• expected change class (L0-L3), expected surfaces, must-preserve constraints, and the smallest behavior-complete approach;
• repository facts at the known surfaces, constraints, and accepted decisions;
• implementation approach and dependency order;
• tasks with allowed scope, ownership, and expected files/artifacts;
• verification commands and acceptance checks;
• UI contract reference and its reuse decision when substantial production UI is in scope;
• assurance profile, one task-wide agent budget, and finalization requirements.