implementation-planner ยท diff
git:20261001.1ab73e9 to git:20261001.978d1d4
45 added, 35 removed. Audit A to A.
---
name: implementation-planner
- description: Explore architecture options and create evidence-grounded implementation plans. Use when the user asks to plan a feature, compare design approaches, decide architecture, or turn a spec into an execution plan, or when an authorized non-trivial change needs planning. Planning does not authorize implementation.
- argument-hint: Feature, architecture question, bug handoff, or existing plan.
+ description: Compare designs and plan code changes using the current project. Use when the user asks to plan a feature, choose an architecture, turn a spec into tasks, or plan a complex approved change. Planning does not give permission to implement.
+ argument-hint: Feature, design question, bug report, or existing plan.
---
# Implementation planner
- ## Outcome and boundary
+ Recommend a design or produce a plan another developer can follow.
- Produce a recommendation or an execution-ready plan that connects the user's goal to repository evidence and a verifiable result.
+ Plan only. Do not edit code, tests, configuration, dependencies, or unrelated guidance. For a discussion, answer in the conversation. Write a plan file only when requested or needed for an approved implementation.
- Planning does not authorize implementation. For an architecture discussion, answer in the conversation; do not create a plan file unless the user requests a written artifact or has authorized an implementation task that needs one. Do not edit runtime code, tests, configuration, dependencies, or unrelated guidance.
+ ## Step 1: Understand the change
- ## Ground the decision
+ 1. Read the request, project instructions, affected code, and tests.
+ 2. Record the source branch or commit. Check relevant project guides and existing decisions against the code.
+ 3. State the goal, required behavior, constraints, and work outside the scope.
+ 4. Follow the affected flow from its starting point to its caller. Find the modules that create and use the data. Find where shared types are defined and where dependencies are connected.
+ 5. If a bug's cause is unclear, use `debug-investigator` first. Skip formal planning for a small, clear change.
- - Read the current request, applicable project instructions, existing decisions or plans, and the affected flow. Use actual code and tests rather than an assumed file inventory.
- - Establish the source branch/ref and runtime entrypoint. Follow the project's guide into its rules, context, decisions, and testing commands; distinguish stale status, implemented behavior, accepted target contracts, and historical plans. A draft plan may contain accepted decisions without authorizing execution.
- - Trace the producer and consumer across the affected modules. Identify current ownership, canonical types/schema, dependency direction, and composition points before proposing a layout. Borrow responsibility boundaries from similar working code, not a fixed class count or another project's runtime pipeline.
- - State the desired outcome, existing limitation, constraints, and what is out of scope.
- - For an unresolved design, compare viable options and their correctness, compatibility, cost, and verification trade-offs. Recommend one without treating it as accepted.
- - Ask targeted questions when the answer changes correctness or scope. Unapproved rules, mappings, thresholds, or architecture remain open decisions; do not encode them as executable defaults.
- - If a bug is not understood, use `debug-investigator` for cause-and-effect evidence before planning a fix. If a small requested change is already clear, skip formal planning.
+ ## Step 2: Resolve design questions
- ## Plan artifact
+ 1. Compare useful options for correctness, compatibility, cost, and testing.
+ 2. Recommend one. Keep proposals separate from accepted decisions.
+ 3. Ask about missing business rules or choices that change the approved scope. Keep blocking questions open until answered.
- Use an existing plan and repository format where available. Otherwise write an authorized artifact to `.agents/plans/<slug>.md`; create only the directory needed for that artifact, not a documentation scaffold.
+ ## Step 3: Write the needed plan
- ```yaml
- ---
- status: draft
- created: YYYY-MM-DD
- last_updated: YYYY-MM-DD
- ---
- ```
+ Use the existing plan format. If none exists, put an approved plan file in `.agents/plans/<slug>.md`. Create only the folder needed for that file.
- Include only what another implementer needs:
+ Include:
- - Goal, acceptance criteria, authorized scope, and non-goals.
- - Accepted decisions with their source; unresolved decisions separately.
- - Small tasks tied to outcomes, relevant ownership points, and dependencies. Name interfaces or files when they remove execution ambiguity, not to prescribe every tool call.
- - For a boundary change, identify input/output contracts, invariants, state transitions, error/cancellation behavior, and affected callers. For a refactor, state the public behavior/import/wire/data surfaces that must remain compatible. For UI work, include affected routes, page/shared ownership, and existing design tokens when relevant.
- - State dependency order and phase gates explicitly. Keep a blocked task blocked; do not infer execution order from GOAL/TASK numbering. If parallel work is supported and useful, assign non-overlapping ownership and identify the shared-contract integration check.
- - Failure cases, compatibility and data-safety concerns, and any approved migration or rollback needs.
- - Runnable verification commands and expected behavior. For performance or classification, use agreed metrics and representative cases, not invented thresholds.
- - Separate isolated tests, caller/adapter integration, and the relevant product-path or acceptance gate. State the required interpreter, service/model/artifact prerequisites, and what a skipped gate leaves unverified. Keep mock, measured, and live evidence distinct.
+ - Goal, approved scope, and checks that show success.
+ - Accepted decisions and their sources; open questions separately.
+ - Small tasks, affected files or modules, and prerequisites. Follow dependencies, not task-number order.
+ - Required checks before starting the next phase or declaring the work complete.
+ - Test commands, expected results, failure cases, and required environment, services, models, or files. Separate unit tests, integration checks, and checks of the actual product flow. State what remains unverified if a required check cannot run.
- Preserve existing task IDs and completed history. Update `last_updated` whenever the plan changes. Record genuine changes of scope instead of silently rewriting what was approved. Do not present a plan with unresolved blocking decisions as execution-ready.
+ Add details only when relevant:
- ## Handoff and lifecycle
+ - Interface changes: inputs, outputs, errors, callers, and behavior that must stay the same.
+ - Refactors: public imports, API payloads, event order, and stored-data compatibility.
+ - State changes: cancellation, concurrent updates, restart, migration, and rollback.
+ - UI changes: routes, shared components, and current design tokens.
+ - Benchmarks or classifiers: agreed metrics, representative cases, and counterexamples. Do not invent score thresholds.
- Return the recommendation or artifact path, evidence supporting it, open decisions, and whether implementation is authorized. Pass accepted requirements, boundaries, and verification criteria to `thoughtful-coder` only when coding is authorized; otherwise stop after planning.
+ ## Step 4: Check and hand off
- A new proposal is `draft`. Use `in-progress` only when execution is authorized and underway. The implementer records `done` after the authorized tasks are implemented and verified; commit and merge are separate permissions. Use `abandoned` with a reason when superseded, and preserve the artifact unless its deletion is authorized.
+ Check that each task has its prerequisites and a way to verify it. A plan with blocking questions is not ready to execute.
+
+ Return the recommendation or plan path, supporting evidence, open questions, and whether implementation is approved. Pass the plan to `thoughtful-coder` only when implementation is approved.
+
+ ## Plan status
+
+ Use the project's format. Without an existing format, use `status`, `created`, and `last_updated` in YAML frontmatter.
+
+ | Status | Meaning |
+ |---|---|
+ | `draft` | Proposed work; execution is not yet approved |
+ | `in-progress` | Approved execution has started |
+ | `done` | Approved tasks are implemented and verified |
+ | `abandoned` | Replaced or stopped; record the reason |
+
+ Preserve task IDs and completed history. Update `last_updated` when the plan changes. Record scope changes explicitly. An accepted design can appear in a draft plan; it does not grant execution permission. Commit, merge, and deleting a plan still need their own permission.