writing-plans

name	writing-plans
description	Consult when multi-round implementation, context compaction, or worker handoff requires a durable execution contract.

Writing Durable Plans

Purpose

A plan is a durable execution contract for work that spans multiple rounds, context compaction, or handoff between the main agent and workers. It preserves what a future implementer cannot safely reconstruct from a task title alone:

• user intent and the real product, business, or operational behavior;
• architecture and module relationships;
• exact constraints, interfaces, values, compatibility boundaries, and files;
• necessary technical and code details;
• dependency and construction order;
• semantic acceptance scenarios, evidence, and readback;
• repository-operation preferences; and
• recovery state needed to resume after interruption.

Assume the implementer is capable but starts with no conversation context. Give them enough specific information to construct and verify the intended result, not a generic principles document or a micro-step transcript.

Ground the contract

1. Read the applicable request, stable specifications, repository instructions, relevant implementation, tests, and current repository state.
2. Record stable requirements by reference rather than copying entire specs. Repeat only the exact values, interfaces, compatibility rules, decisions, or code detail that the worker needs at the point of construction.
3. Map the architecture: which modules own which behavior, how data or control crosses their boundaries, and why the construction order follows from those relationships.
4. Inspect current context for commit, push, branch, and worktree preferences. When a preference is absent and changes execution, ask once; never push without clear authority.

Preserve decisions and open boundaries

A negative compatibility boundary is not a positive architecture decision. For example, a rule that an unapproved remote sink must not be introduced does not approve a local file, in-memory store, injected sink, or any other substitute.

When storage, sink, failure strategy, source layout, ownership, or another construction choice lacks evidence, record it as an open decision or blocker. State what evidence or approval resolves it and keep dependent work conditional. A fresh worker must not treat an inference as an approved decision merely because the plan names a compatibility boundary.

Save plans to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md unless the project or user specifies another durable location.

Task boundaries

Organize tasks around independently meaningful, testable deliverables. A task may include setup, implementation, tests, documentation, and review when they form one product or operational outcome. Split when a later task depends on a distinct accepted behavior, not to force every action into a short time box.

Use red-green testing when it discriminates the behavior being changed. Compilation, linting, and unit tests are support signals, not the complete acceptance claim. Every task must derive semantic acceptance from its real product, business, or operational scenario:

• frontend work verifies the rendered visual state and the relevant interaction;
• persistence work verifies save, restart or reload, and readback;
• API, CLI, and automation work exercises meaningful arguments, failure paths, and the resulting state; and
• migrations or compatibility work verifies the promised boundary against a representative existing consumer or artifact.

Routine code that a competent worker can infer does not belong in the plan. Do include code snippets, signatures, schemas, commands, or exact values where an incorrect inference would change behavior, compatibility, construction order, or acceptance evidence.

Plan document header

Every durable plan begins with:

# [Feature Name] Implementation Plan

**Goal:** [User-visible or operational outcome.]

**Stable references:** [Specs, decisions, instructions, and repository state
that the plan relies on.]

**Repository operations:** [Known commit/push/branch/worktree preference, or
the one decision still requiring user input.]

**Recovery state:** [What a worker should read first after context compaction,
which completed deliverables are trusted, and which evidence remains to gather.]

Task template

Use this structure for each deliverable. Fill every field with task-specific information; omit only fields that truly do not apply and explain why.

### Task N: [Meaningful deliverable]

**Project meaning:** Why this task exists in the product or operation, including
the user-visible or operational problem it resolves.

**Architecture relationship:** Which modules, ownership boundaries, or data and
control flows this changes, and how it fits the surrounding system.

**Technical contract:**
- Files: Create/modify/delete exact paths.
- Interfaces and values: exact signatures, schemas, names, configuration
  values, compatibility conditions, and error behavior.
- Constraints: stable references plus the task-specific detail that must not be
  inferred differently.

**Dependencies:** What must already be accepted, what this task unblocks, and
the required construction order.

**Implementation notes:** The non-routine technical decisions, code excerpts,
commands, or data shapes needed to construct this deliverable correctly. Link
to stable specifications for routine detail instead of duplicating it.

**Semantic acceptance:**
- Scenario: a real product, business, or operational use case.
- Evidence: exact test, command, rendered state, persisted readback, or other
  artifact to inspect.
- Pass/fail: what the observed result means, including relevant negative or
  compatibility cases.

**Recovery checkpoint:** What state, artifacts, and next decision a fresh worker
needs to resume this task after context compaction or a failed attempt.

Self-review

Before presenting the plan, verify that it preserves the intended semantics:

1. Every user requirement and stable constraint maps to a task or an explicit out-of-scope decision.
2. Interfaces, exact values, compatibility boundaries, and dependency order are consistent across tasks.
3. Each task has a real semantic acceptance scenario rather than only red-green, compilation, lint, or unit-test evidence.
4. A fresh worker can resume from the recovery state without rereading the original conversation, while routine code and duplicated specification prose stay out of the document.
5. Repository-operation preferences are recorded or the remaining choice is ready to ask once.
6. Negative constraints have not been converted into unapproved positive design choices; unresolved storage, sink, failure, or layout decisions remain visible as decisions or blockers for the next worker.

Execution handoff

After saving a plan, always ask the user to choose between Subagent-Driven Development (SDD) and inline execution. State the agent's recommendation first, grounded in task complexity, main-session context, isolation needs, cost, and continuity; the user makes the final choice.

Use this handoff shape:

Plan saved to <path>. I recommend [SDD or inline] because [complexity/context/isolation/cost/continuity rationale].

Choose one: SDD (fresh worker per bounded deliverable with review and durable handoff) or inline (this session implements the plan while keeping its recovery checkpoints current).

If the user chooses SDD, use subagent-driven-development. If the user chooses inline execution, use executing-plans. Do not silently choose the mode for them.