# Create Implementation Plan > Use when an approved engineering spec must become a deeply researched, dependency-ordered implementation plan before a human engineer or coding agent changes code - Skill: `cipradu/create-implementation-plan` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add cipradu/create-implementation-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/cipradu/create-implementation-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: cipradu (https://skillmd.com/u/cipradu) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cipradu/create-implementation-plan --- # Create Implementation Plan ## When to Use Use when an approved engineering spec, requirements artifact, or accepted change contract must become an implementation plan before code changes. Trigger on requests to create, write, validate, review, or decompose an implementation plan; convert a spec into tasks; prepare work for a coding agent; sequence brownfield changes; plan greenfield implementation after technology choices are known; or recover from a plan that is too vague, ungrounded, unreviewed, or unsafe. ## Do Not Use Do not use when neither an approved/current spec nor an accepted implementation contract exists, when planning cannot change the next action, or when the plan warrant is absent. Do not use for direct coding, quick factual answers, commit execution, project-management roadmaps, or generic task lists. Do not use this skill to run diagnosis, product ideation, strategy, engineering spec creation, architecture decision, documentation authoring, browser/device testing, runtime polish, setup repair, worktree creation, implementation, commits, pushes, PRs, CI watching, tracker filing, publishing, shipping, or release communication. Those workflows may provide source evidence or downstream consumers; they do not become planning mechanics. ## Iron Law **No warrant, no accepted implementation truth, no plan.** A plan is valid only when durable sequencing can make execution safer and its selected form resolves a named uncertainty or acceptance gap that can change the next action. A compact Standard plan uses only the bounded contract below. A full plan additionally requires its deeper decomposition, research, discovery, and task-graph controls to be individually warranted and passed; checkpoint cadence and independent plan review remain separate decisions. If a required gate fails, do not substitute the other form or expand ceremony by habit. Emit a blocked planning packet with the missing evidence and next required action, or return new concrete escalation evidence to the orchestrator. ## Core Concept **Implementation reasoning, not implementation code.** The plan must tell a capable executor exactly how to think and proceed: what exists, what must change, why each change is necessary, what it depends on, what it can break, which library/version/pattern applies, what rules constrain it, what proves completion, and when to stop. It must not pre-write function bodies, invent spec truth, or hide uncertainty inside confident prose. Planning is deeper than spec authoring. The spec defines required truth. The plan re-reads that truth at implementation depth and tests it against real code, rules, ADRs, dependencies, runtime contracts, libraries, available skills, and likely blast radius. ## Artifact Boundary | Artifact | Defines | Does not define | | ------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Engineering spec | required behavior, constraints, invariants, acceptance evidence, authority, risk at spec depth | implementation sequence, task dependency graph, file edit plan | | Implementation plan | evidence-grounded execution strategy, units/tasks, dependencies, impact, research, verification, review gates | new product truth, unapproved scope, implementation code | | Execution work | actual code, tests, migrations, docs, commits | changing the spec or plan silently | The plan may reject or return a spec for revision when codebase evidence, library reality, rules, or ADRs show the spec is incomplete, contradictory, impossible, unsafe, or already satisfied by a smaller change. A valid completed plan that is later judged unnecessary remains valid historical work. Preserve it and, when useful, mark it superseded or non-operative. Delete it only with explicit user authority or an existing retention rule that names the artifact class and deletion condition. ## Plan Warrant And Form Selection Consume the orchestrator assurance decision before planning. A plan is warranted only for multiple dependent units, real ordering constraints, multiple coordinated executors whose work needs durable sequencing, shared mutable state, migration or rollout, material rollback concerns, or a boundary that must be crossed safely. Multiple files, one coherent deliverable, or use of one delegated executor alone is insufficient. Consume the accepted scope envelope: `Outcome`, `Non-goals`, `Target boundary`, `Acceptance proof`, and `Expansion or re-plan triggers`. Planning may order and constrain accepted work; it must not add behavior, capability, compatibility, files, tests, artifacts, or phases merely to make execution comprehensive or future-ready. Require every proposed unit, capability, abstraction, file, test, artifact, compatibility path, and checkpoint to trace to the accepted outcome, a current named risk or invariant, a required compatibility obligation, or cleanup directly caused by the change. Remove an untraceable item. If current implementation evidence makes expansion necessary, return the concrete evidence to the orchestrator or `create-engineering-spec` skill instead of silently revising the plan boundary. Approved requirements, scope, deliverables, acceptance criteria, and plan commitments must not be amended to justify implementation deviations. Internal reclassification, research findings, review advice, and `amend` or `supersede` freshness labels do not grant user approval. Stop dependent work for the needed user decision before changing governing commitments; keep status/evidence updates separate and preserve existing authority for in-scope implementation decisions and repairs. Mention and record discovered issues under the `project-rules` discovery contract; unrelated items remain deferred rather than becoming plan units. Name the uncertainty or acceptance gap the plan can resolve and how its result changes the next action. If planning cannot change the next action, stop and reference the accepted implementation contract. If `Plan warranted: no`, do not create a plan merely because this skill was invoked; preserve any valid completed plan and return to the recorded route. Use the compact Standard form when the sequencing need is bounded and deeper research, source redecomposition, discovery, or task-graph analysis cannot change the plan. The compact minimum is: the linked spec or accepted implementation contract; exact reason planning is warranted; objective and boundaries; current evidence for affected surfaces; dependent units and order; relevant verification and state identity; re-plan triggers; and review decision. Do not perform generic research or full source redecomposition, ask a generic TDD-preference question, construct unwarranted checkpoints, or require independent plan review without separate named warrants. Select checkpoint cadence and independent review separately; either may apply to a compact plan when its own warrant passes. Use the full form only when its deeper planning controls are individually warranted. Preserve spec coverage, source and authority traceability, current codebase evidence, dependency ordering, verification, and rollback/recovery at the depth justified by those warrants. Select checkpoint cadence and independent artifact review independently from the plan form. This skill may challenge insufficient intake, but it may escalate only by returning newly discovered concrete evidence, the affected consequence or gate, and the changed next action for an updated orchestrator decision. Skill or agent preference, artifact type, file count, delegation, or generic uncertainty cannot silently reclassify the task. ## Mandatory Sequence Run the common warrant gate first, then only the selected form. Do not make compact mean the full internal workflow with fewer headings. | Path | Required method | Completion condition | | ---- | --------------- | -------------------- | | Common | Confirm the plan warrant, name the gap, select compact or full form, and select a verification posture from the affected behavior and seam | planning can change the next action, or it stops without creating an artifact | | Compact Standard | Validate the linked spec or accepted implementation contract; inspect only current affected surfaces; define dependent units/order, relevant verification/state identity, re-plan triggers, and review decision | every compact field is supported without generic research, full source redecomposition, generic TDD questioning, or unwarranted checkpoints/review | | Full | Run Steps 1–13 below only for the individually warranted full-form branch | every warranted full-form gate passes or the plan remains blocked | | Output | Use the matching compact, full, or blocked form in [Plan Output](references/plan-output.md) | the artifact contains only the selected form and preserves its evidence identity | ## Step 1 — Pair With Spec And Classify Plan State A full plan must start from a specific approved/current spec. A compact Standard plan may start from that spec or an accepted implementation contract as defined by the form-selection gate. Canonical specs live under: ```text docs/specs/YYYY-MM-DD_HH-mm_{slug}_spec.md ``` Canonical plans live under: ```text docs/plans/YYYY-MM-DD_HH-mm_{same-spec-slug}_plan.md ``` Use local plan-creation time, 24-hour, with leading zeroes. Do not use seconds. Do not use colons in filenames. The plan must reuse the exact slug segment from the paired spec filename; do not invent a new plan slug. If the user provides a spec path, read that exact path only if it matches `docs/specs/YYYY-MM-DD_HH-mm_{slug}_spec.md`. If a provided spec path is non-canonical, block and request the canonical spec path; do not derive a plan slug or plan filename from a non-canonical spec filename. Otherwise search `docs/specs/` first. Match by slug, title, requirement IDs, feature name, domain terms, status, and linked artifacts. Only use a spec that is approved and current. If no clear match exists in `docs/specs/`, then search other repository spec, requirements, design, ADR, docs, issue, or plan locations for a pointer to the canonical spec. If exactly one plausible approved and current canonical spec match is found, use it and cite the path. If multiple plausible specs exist, ask one blocking question with the recommended default. If no clear approved and current canonical spec match exists, use the blocked packet in [Plan Output](references/plan-output.md#blocked-planning-packet) with `Blocking gate: missing approved and current canonical spec`. Any user decision discovered during planning must preserve a decision-evidence packet before routing or asking: the user-visible situation and consequence; why no safe authorized default exists; the exact plan truth, requirement, or dependent work blocked; unaffected work; the recommended resolution; the exact source artifact or plan behavior approval would change; its material effect; its material cost and risk; what happens if no change is made; materially distinct alternatives only when they exist; and supporting evidence or limits. If the active agent is user-facing, translate the packet through the harness decision-readiness gate. Otherwise return it to the orchestrator. Do not lead with spec IDs, paths, settings, APIs, or implementation terms, present choices with the same practical result, or claim the whole implementation is blocked when only one planning branch is blocked. Recommended blocking question when no spec is found: ```text I cannot create an implementation plan without the approved spec. I searched docs/specs/ and did not find a clear match. Where is the spec file? Recommended default: create or provide a spec under docs/specs/YYYY-MM-DD_HH-mm_{slug}_spec.md. ``` Do not create `UNIT-001: find the spec`. Spec discovery is a prerequisite, not an implementation task. If the user asks to revise, validate, execute, or continue an existing plan, first pair that plan back to its linked canonical spec and classify the existing plan before drafting or accepting any units: - `current`: linked spec, upstream sources, rules, ADRs, current code evidence, verification commands, review status, and unit graph still align; - `amend`: paths, commands, examples, or narrow evidence changed, but spec truth, unit graph, risk tier, approach, TDD posture, and acceptance evidence still hold; - `supersede`: requirements, architecture, dependency order, TDD posture, library reality, risk tier, acceptance evidence, or plan-level approach changed materially; - `blocked`: authority conflicts, stale linked spec, missing review state, contradictory current code/spec/ADR/rules, or ambiguous active-plan responsibility prevents safe planning or execution. Do not follow whichever artifact looks newest. Current code is evidence, not automatic authority; approved specs, ADRs, public contracts, security rules, compliance constraints, and repository instructions may require code to change. When multiple plans, specs, ADRs, issues, research notes, docs, or review packets cover the same surface, identify the active canonical source, superseded precursors, overlapping guidance, inbound references, and unresolved contradictions. Preserve stable unit IDs and valid evidence during amendments; re-evaluate the independent-review warrant after material changes and rerun review only when its trigger passes. Do not revise a plan only to update timestamps, leave review breadcrumbs, restyle prose, or reflect cosmetic movement. Plan revisions must improve execution safety, traceability, verification, source alignment, or reviewability. ## Step 2 — Decompose The Spec And Upstream Sources Re-read the spec as an implementation planner. Build a decomposition table before any task list. For every spec item, extract: - source ID and exact requirement or constraint; - required behavior or invariant; - acceptance evidence promised by the spec; - implementation implications; - data, API, UI, workflow, protocol, runtime, security, operational, or migration surfaces affected; - rules, ADRs, skills, standards, or libraries likely involved; - upstream source authority class: approved spec truth, linked constraint, context, evidence lead, deferred-to-planning research, explicit non-scope, or blocker; - open questions or contradictions; - whether the item is in scope, out of scope, already satisfied, or requires the canonical blocked packet. Every normative spec item must later map to at least one plan unit, verification item, explicit no-op/already-satisfied finding, or explicitly deferred item. If an item cannot be mapped safely, the full plan is not valid; use the blocked packet in [Plan Output](references/plan-output.md#blocked-planning-packet). Missing mapping invalidates the plan. Classify upstream artifacts by authority before using them: - Approved spec or accepted change contract constrains implementation. - Linked PRDs, requirements docs, strategy docs, brainstorms, ideation artifacts, feedback bundles, issues, reviews, prior learnings, and reports may provide constraints, context, source evidence, source IDs, non-goals, examples, or research leads only when the approved spec adopts or links them. - Ideation artifacts, ranked ideas, PR comments, screenshots, transcripts, Slack notes, branch names, commit messages, generated findings, and old learnings are not implementation authority by themselves. - Feedback-derived sources must preserve observed facts, inferences, confirmed requirements, and suspected source mappings separately. If an upstream artifact contains `Resolve Before Planning`, unresolved planning blockers, or equivalent blocking language, do not turn the item into an implementation unit. Each item must become an approved decision, explicit non-normative assumption, deferred-to-planning research question, non-scope item, re-plan trigger, or blocked packet entry before the task graph exists. For failure-derived specs, capture symptom, reproduction status, environment differences, causal chain, verified assumptions, failed hypotheses, proposed fix status, and recommended regression evidence. If root cause or causal chain is still unresolved and the plan depends on it, route to diagnosis or emit the blocked packet instead of planning a symptom workaround. ## Step 3 — Inventory Rules, ADRs, Skills, and Prior Artifacts Before codebase or library research, inventory the constraints and reusable knowledge sources that change how planning should work. Check: - repository instructions and rules; - ADRs and prior technical decisions; - existing specs, plans, research notes, audits, dependency maps, and design docs; - searchable prior-learning stores when present, such as `docs/solutions/`, pattern docs, troubleshooting records, incident notes, conventions, and workflow learnings; - available project/installed skills for the relevant stack, language, database, framework, testing approach, security, observability, migrations, or domain; - available specialist agents for codebase research, rules discovery, library research, planning, or plan review. Use relevant skills before planning the affected units. If a skill exists for the stack or concern, load it or hand it to the relevant worker. If no skill exists, use authoritative docs and record that no skill was available. Prior learnings can inform research questions, known failure modes, existing patterns/reuse, rejected paths, quality constraints, and re-plan triggers. They do not outrank current approved specs, rules, ADRs, source code, public contracts, or current external docs. If a prior learning appears stale, contradicted, overlapping, or superseded, record the maintenance need for the owning documentation, pattern, ADR, or continuity workflow; do not mutate adjacent artifacts as a side effect of planning. When prior-learning docs use metadata or frontmatter, search likely title, tag, module, component, problem type, and category fields before broad full-text reading; then fully read only likely relevant matches. Completion condition: the plan can cite which rules/ADRs/skills/artifacts were applied, which were irrelevant, and which were missing but required. ## Step 4 — Classify Mode, Executor, and Risk There are only two implementation modes. | Mode | Test | Required discovery | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Brownfield | any existing repository, platform, contract, runtime, data model, dependency, process, consumer, or prior implementation owns part of the work | codebase/system discovery for every affected spec item | | Greenfield | no existing system owns the implementation surface | technology and library/version research for every chosen stack element | A new component inside an existing platform is brownfield first. If the spec's technology choices are missing for greenfield work, the spec is incomplete; block and return to spec authoring instead of choosing a stack in the plan. Declare executor mode: - **Human** — plan for a capable engineer and reviewer. - **AI Agent** — plan for a coding agent with bounded files, explicit context, re-plan triggers, and the recorded independent-review decision. - **Hybrid** — default to AI Agent rigor when an AI will execute any unit. For AI Agent or Hybrid plans, record workspace and isolation assumptions. State whether execution assumes the current checkout, an existing isolated workspace, or a separate workspace to be prepared by the implementing agent or `git-branch` skill before edits. The plan may name isolation requirements and shared-resource conflicts; it must not create worktrees, branches, or git state. Declare risk tier: - **Standard** — normal multi-step implementation. - **High Assurance** — irreversible, regulated, security/privacy-sensitive, data-integrity-sensitive, operationally risky, migration-heavy, cross-system, protocol/state-machine, or audit-relevant work. Do not encode domain-specific rules in the skill. Use the tier to increase evidence and review requirements. ## Step 5 — Select TDD And Verification Posture TDD can change the task graph, verification design, review criteria, and executor instructions. Select the posture from the affected behavior, available seam, accepted constraints, and evidence needs before unit planning. Use [TDD Planning](references/tdd-planning.md) when the user, spec, project rules, or accepted plan constraints explicitly require TDD, test-first implementation, red-green-refactor, regression-test-first bug fixing, or TDD-style implementation. If the user explicitly rejects TDD, do not force it. The plan must still assign a concrete verification posture to every unit and must explain why TDD is not being used where behavior changes are present. When TDD is unspecified, do not ask a generic preference question. Select and explain `TDD_REQUIRED`, `CHARACTERIZATION_FIRST`, `ACCEPTANCE_FIRST`, `PROPERTY_OR_METAMORPHIC`, `TEST_AFTER_WITH_REASON`, or `NO_AUTOMATED_TEST_FEASIBLE` from the actual behavior seam. If the artifact has no meaningful behavior seam, or the answer cannot change units, order, verification, or review, select the appropriate non-TDD posture and continue. Ask one blocking TDD question only when explicit sources conflict or two materially different valid postures remain after inspection and the answer will change the plan. State the recommended posture, evidence, and exact plan consequence. Explicit TDD requests and genuinely material TDD decisions remain supported through [TDD Planning](references/tdd-planning.md). A request to “use TDD” while omitting per-unit red/green details, behavior seams, or independent verification requirements is contradictory. Keep TDD details or choose a non-TDD verification posture with a reason. If the user insists on both, ask one blocking question: “Should I keep TDD with the required per-unit evidence, or switch this plan to non-TDD verification postures? Recommended default: keep TDD evidence for behavior-changing units with clear seams.” ## Step 6 — Plan Research Research is not generic browsing. It is derived from spec decomposition and mode. For each spec item and affected unit, write research questions that answer: - what current code, tests, configs, schemas, migrations, services, routes, jobs, consumers, and docs own this behavior; - what existing implementation can be reused, extended, configured, or fixed; - what rules/ADRs constrain the implementation; - what external libraries, versions, standards, protocols, APIs, or runtime behaviors are required; - which skills or specialist agents should be used; - what evidence proves the answer is sufficient. Library research must be version-specific. “Use TanStack” or “use Zod” is not enough. The plan must know the package, project version, relevant API/pattern, accepted usage style, gotchas, and source. If version cannot be determined, block or make version discovery an explicit prerequisite before planning dependent units. Resolve external research before discovery is treated as complete: 1. **Honor explicit external signals.** If the user, spec, linked PRD, issue, or prior artifact asks for outside input such as official docs, best practices, current behavior, alternatives, competitor/prior-art comparison, "what should we borrow", or named external references, external research is required unless the user explicitly opted out. Improvement words such as "improve", "strengthen", or "make better" do not trigger external research by themselves. 2. **Classify the research intent.** Use `implementation-guidance` when the technology or approach is settled and the question is how to build it correctly. Use `landscape/option-discovery` when the plan depends on external options, prior art, provider/library choice, or comparative approaches. Use `mixed` only when discovery must happen first and implementation guidance depends on the chosen shortlist. 3. **Use implicit signals when there is no explicit request.** Lean toward external research when the topic is high risk, the relevant codebase pattern is absent or thin, fewer than three direct local examples exist, only adjacent-domain examples exist, the user is exploring unfamiliar territory, the technology layer is absent, or an unsettled external option materially shapes a decision. Skip external research when strong current local patterns exist, the user already fixed the intended shape, and outside context would not change a plan decision. 4. **Narrow instead of skipping when local choice is settled.** If an explicit external request exists but the project already has a settled library, framework, or pattern, research current docs, pitfalls, and version-specific constraints for the settled choice instead of surveying alternatives. 5. **Record unavailable research honestly.** If requested external research cannot run because tools, access, or sources are unavailable, do not present the plan as externally grounded. Record the gap as an assumption, open question, blocker, or re-plan trigger according to risk. External findings must land where they change a choice: smallest-safe-path rationale, task graph, key technical decision, rejected path, risk, verification, approval gate, or re-plan trigger. Do not pad the plan with detached research notes. Mark whether an external finding was load-bearing. ## Step 7 — Run Mode-Specific Discovery ### Brownfield Discovery Gate For every affected spec item, inspect or delegate codebase/system discovery. Required evidence: - current implementation status: `ALREADY_IMPLEMENTED`, `PARTIAL`, `NOT_STARTED`, or `CONFLICTS_WITH_SPEC`; - exact repo-relative files, modules, tests, schemas, migrations, configs, routes, jobs, services, consumers, and docs read; - relevant patterns to follow; - anti-patterns to avoid; - reusable imports, utilities, schemas, services, or test helpers; - downstream callers, contracts, and blast radius; - hidden coupling, state, data integrity, migration, security, operational, or compatibility risks; - whether a smaller existing-code change satisfies the spec. If any affected area is not inspected, do not plan implementation units for it. Use the blocked packet in [Plan Output](references/plan-output.md#blocked-planning-packet) with `Blocking gate: brownfield discovery incomplete`. For behavior-bearing brownfield work, check applicable interaction chains: callbacks, middleware, events, persisted state before external calls, alternate interfaces exposing the same behavior, and layered error-handling or retry strategies. For branch, patch, review-fix, or existing-diff planning contexts, changed files can seed discovery, but approved spec mapping remains the authority. For runtime-bound work, identify launch source, repo/app root, command or runtime args, URL/port, route/screen, required environment, logs, screenshot/browser evidence, and process cleanup only when those facts affect verification or handoff. ### Greenfield Discovery Gate For greenfield work, the spec must already define the stack and material technology decisions. Research implementation-depth facts for each selected technology: - package names and versions to use; - current official docs or authoritative sources; - recommended patterns for the specific use case; - unacceptable patterns and version-specific gotchas; - integration order, generated artifacts, config, tests, deployment, and operational constraints; - required project skills or specialist agents. If the spec did not choose the stack or the technology choice is contradicted by research, block and return the spec for revision. ## Conditional Planning Facets Use these facets only when the paired spec or discovered implementation surface makes them load-bearing. Do not add every facet to every plan. - **Load-bearing decisions:** Record pinned choices, rationale, rejected alternatives, source evidence, affected units, and ADR-candidate status in the plan output. If no material plan-level decision exists beyond direct spec decomposition, say so. - **Optimization or comparison:** Define baseline, primary metric or rubric, hard gates, diagnostics, measurement source, immutable fixtures/examples, noise policy, dependency approvals, candidate/hypothesis units, and stopping or re-plan criteria before execution. - **Reporting or observability:** Name source systems, event definitions, instrumentation status, query shape, source conflicts, freshness/comparison windows, read-only access, credential non-capture, expensive-query skip behavior, privacy checks, generated artifact lifecycle, and scheduling responsibility. - **External provider or generated output:** Distinguish core behavior from optional enhancement, structured output contract from brittle parsing, credential handling, provider state detection, fallback semantics, hidden/internal fields, and mutation boundary. - **Agent, skill, prompt, MCP/tool, plugin, command, hook, or workflow surface:** Cover action parity, context parity, shared workspace assumptions, tool/request granularity, approval and human-only boundaries, lifecycle/failure recovery, observability, generated artifacts, and agent-native verification. - **Refactor or simplification:** Preserve behavior, errors, side effects, ordering, validation, authorization, escaping, sanitization, accessibility, cleanup, and safety checks. Success is not fewer lines; it is reduced duplication, clearer reuse, lower complexity risk, or less unnecessary work with preserved behavior. - **Verification environment:** For simulators, browsers, devices, cloud services, MCP servers, credentials, external systems, or human-only checks, include a preflight, known automation limits, manual evidence fallback, cleanup expectation, and re-plan trigger if the verifier is unavailable or cannot observe the required behavior. - **Long-running or many-scenario verification:** The plan may require a durable execution-owned report artifact as evidence, but the plan itself must not become progress tracking. ## Step 8 — Choose the Smallest Safe Path Before task decomposition, decide whether the spec is satisfied by: 1. no code change because behavior already exists; 2. configuration or rule/documentation alignment; 3. one local fix; 4. extension of existing code; 5. new unit inside existing architecture; 6. broader refactor or migration. Prefer the smallest path that satisfies the spec and preserves rules/ADRs. Evidence that smaller paths fail can justify a proposal to rebuild, add dependencies, create abstractions, or broaden scope; it cannot authorize changing approved scope. Obtain the needed user decision before amending governing commitments or planning the expanded work as approved. Record rejected paths with cause/effect reasoning: what would happen if chosen, what would break or remain unsolved, and why it was rejected. Reject paths that improve a proxy while weakening the real requirement, such as changing fixtures, narrowing inputs, weakening compatibility, bypassing auth, altering public outputs, skipping validation, or hiding missing data. For bug fixes, prefer the root-cause correction over downstream symptom handling and require the plan to explain how the change interrupts the causal chain. ## Step 9 — Build the Task Graph Break work into bite-sized implementation units only after the previous gates pass. Many tasks are acceptable when the dependency graph requires them. Fewer vague tasks are not better. Each unit must be independently understandable and use stable IDs such as `UNIT-001`; never renumber existing units during revision. Assign checkpoint IDs only when `Review cadence: checkpoints` has a separate named warrant. With `none` or `single_final`, do not construct intermediate checkpoints. When a checkpoint exists, independent review is required before crossing it, and within-checkpoint progression is allowed only when the plan explicitly states it is safe and the completed unit's required verification passed. The plan must expose the facts a coordinator needs to choose a runtime execution batch without making that choice prematurely. For each unit, identify any batch affinity with other units from shared implementation context or coherent verification, and identify exclusions from dependencies, checkpoints, shared state, isolation, or incompatible proof boundaries. The coordinator authorizes the exact batch from the current execution cursor. The plan never grants blanket authority to implement every remaining unit and never fixes batch size from unit, file, time, token, or cost counts. When `Review cadence: checkpoints` is warranted, define checkpoints by the named acceptance risk and change coupling, not convenience. Consider a checkpoint before a public-contract, security, data/persistence, migration, permission, generated-artifact, release/deploy, irreversible, high-blast-radius, or cross-responsibility boundary only when review there can change the next action. Reject per-unit review explosion and unwarranted checkpoints; one final review is sufficient when no intermediate result can change execution. A document-producing unit does not establish one of those boundaries merely because its ADR, spec, plan, README, reader-facing docs, progress note, scratch note, or other prose describes high-consequence implementation. Do not place an implementation-review checkpoint after a document-only unit or assign it deep review or fresh validation. Place any warranted checkpoint at the later unit that actually changes or crosses the executable public-contract, security, data, migration, permission, generated-artifact, release/deploy, irreversible, high-blast-radius, or surface spanning multiple responsibilities. A prose-formatted agent, skill, rule, prompt, hook, executable configuration, schema, or generated contract is a control or executable artifact, not document-only. Each unit must include: - spec requirements covered; - scope trace: the accepted outcome, current named risk or invariant, required compatibility obligation, or change-caused cleanup that justifies the unit and every proposed target file, test, abstraction, artifact, or compatibility path; - review cadence and checkpoint ID/crossing state when checkpoints are warranted, otherwise `none` or `single_final` with reason; - cause: why this unit exists; - effect: what exists after completion; - current evidence: files/docs/research proving current state; - target boundary: repo-relative files/surfaces intended to change; - non-target boundary: related surfaces that must not change; - existing patterns/reuse: imports, utilities, schemas, services, tests, or examples to reuse; - quality constraints: local patterns to preserve, duplication or complexity risks, abstraction/dependency justification, domain naming consistency, and cleanup/refactor non-goals; - library/version guidance: exact package/version/pattern/source when relevant; - test posture: selected posture and rationale; - execution note: the intended execution posture, such as test-first, characterization-first, acceptance-first, migration-first, config-only, or inspection-only; - approach logic: detailed implementation reasoning without code; - technical design: optional high-level sketch, state model, protocol outline, or diagram description when prose alone would leave the approach ambiguous; - dependencies: prior units, external decisions, data prerequisites, migrations, or approvals; - batch affinity: other units that could share one coherent executor return and the evidence-based reason, or `none`; - batch exclusions: units or boundaries that cannot share a batch because of dependency, checkpoint, shared-state, isolation, or verification constraints; - implementation-time unknowns that are non-blocking, with resolution method and re-plan trigger; blockers must stop the plan before unit drafting; - workspace/isolation requirement and shared-resource conflicts; - blast radius: what can break and why; - test scenarios: specific input/action/expected outcome cases for behavior-bearing units, including happy path, edge case, error/failure path, integration chain, external leg, and true end state when applicable; use `Test expectation: none — ` only for non-behavioral units; - verification: command/check, input/action, expected outcome, spec IDs covered; - reviewer focus: what the reviewer must inspect; - approval or re-plan triggers. Parallelism is allowed only when units do not share files, state, migrations, data contracts, invariants, test fixtures, generated artifacts, ports, locks, database files, exclusive devices, stateful services, or unresolved decisions. Otherwise sequence them or require isolated workspaces. ## Step 10 — Define Verification, Approval, and Re-Plan Rules Every unit must have concrete verification. “Add tests,” “run the suite,” or “verify behavior” is incomplete unless the command/check, expected result, and covered spec IDs are named. If the evidence cannot be a command, define inspection, analysis, demonstration, screenshot, log, audit, or review evidence and explain why no command applies. Manual, screenshot, log, demo, or audit evidence is acceptable only when it is mapped to spec IDs, names the observer or reviewer role, explains the automation limit, and records residual risk. It is not a substitute for automated checks when a reliable behavior seam exists. When TDD is enabled for a unit, verification must follow [TDD Planning](references/tdd-planning.md): behavior-facing seam, one red-capable test, minimal implementation, green verification, refactor after green, and independent verification for spec-critical or high-risk behavior. Same-agent TDD is a feedback loop, not independent proof. Define review checkpoint gates and approval gates separately. Review checkpoints control when independent implementation review is required. Approval gates control user authorization for high-risk surfaces such as data contracts, migrations, external APIs, auth, secrets, permissions, audit trails, production rollout, generated artifacts, CI/CD, dependency additions, and scope changes. Record the independent review decision separately from unit verification. When cadence is `checkpoints`, include a Review Checkpoint Summary naming each checkpoint, units covered, crossing rule, independent-review requirement, within-checkpoint progression rule, required verification, and re-plan triggers. When cadence is `none` or `single_final`, record that decision and reason without constructing intermediate checkpoints. For AI Agent or Hybrid mode, define re-plan triggers. Execution must stop when: - a needed file/surface is outside the declared boundary; - codebase evidence contradicts the plan; - a library/API behaves differently from the researched source; - verification fails for a non-trivial reason; - a new dependency, data contract, migration, or approval need appears; - a planned key technical decision, public interface, high-level design shape, or acceptance evidence becomes invalid; - implementation would change spec truth or broaden scope; - …(truncated)