Task: Create PLAN.md — An Implementation Plan

Task: Create PLAN.md — An Implementation Plan

Objective

Given a specification document and any available architecture or decision documents, produce a PLAN.md that an implementing agent can follow start-to-finish. The plan bridges "what to build" (the spec) and "how to build it" (the code) — it provides the sequence, the context, and the decisions needed to turn a spec into working software.

The defining discipline — and the commonest failure — is that every step inlines the context the implementer needs: types, signatures, behavioral rules, error variants, constants, and file paths are embedded directly in the step, not referenced by "see the spec" or "see the architecture doc." The implementing agent reads only PLAN.md. The commonest violation is leaving a step as a pointer to another document, or restating the spec at a summary level without concrete file paths and symbol citations — both produce plans that feel complete but force the implementer back into research mode.

Inputs

1. Specification document (required) — the source of truth for what to build (scope, interfaces, behavior, errors, tests). Typically SPEC.md for the work unit.
2. Architecture documents (optional) — ARCHITECTURE.md and related design artifacts describing system structure, conventions, and technology choices.
3. Decision documents (optional) — recorded architectural decisions with rationale (e.g., ADRs). Used to lock in choices without re-litigating them in the plan.
4. Existing codebase (auto-discovered — via Glob and Grep during Phase 1 Codebase Exploration) — read full method bodies, module structures, and test infrastructure; findings are what the plan's steps inline as concrete citations.

Workflow

Plan generation happens in three phases. The first two are research; the third is writing. Do not skip the research — a plan based on assumptions about the codebase instead of actual exploration will produce steps that duplicate existing utilities, violate conventions, or miss integration points.

Phase 1: Codebase Exploration

Before writing anything, launch subagents to deeply explore the existing codebase. This is not a file-listing exercise — subagents should read full method bodies, understand patterns, and map out how existing code actually works.

What to explore:

• Existing code related to the feature — data structures, patterns, conventions actually in use (not just file paths)
• Reusable utilities and abstractions — the plan should never propose building something that already exists in the codebase
• Similar features as implementation templates — how comparable things were built elsewhere, as a reference for consistency
• Integration points — where new code connects to existing code, what interfaces and contracts it must satisfy

Launch multiple exploration subagents in parallel when the scope spans different areas. Give each a focused search area (one explores existing patterns, another explores integration points, another explores test infrastructure). Subagent findings become the inlined context in the plan's steps. Record the commit hash exploration was verified against and include it in the plan overview so a reader can re-verify the citations.

Phase 2: Approach Analysis

After exploration, analyze the implementation approach before committing to a plan structure. This can be done via subagent or inline, depending on complexity.

Key questions to answer: