Feature Request: Implementation Planning Workflow (IPW)

Type: Feature Request (FR)
Identifier: IPW (Implementation Planning Workflow)
Submitted: 2026-02-22
Submitted By: User
Priority: HIGH
Severity: HIGH
Status: COMPLETE
Last updated: 2026-04-02 — AC5 (retro wiring) and AC7 (validator script) completed; FR-042 acceptance criteria satisfied under E5:S01:T42.
Implementation Task: E5:S01:T42

Summary

Define and implement an Implementation Planning Workflow (IPW) – a formal workflow for creating planning documents (spec, test design, implementation plan) before task implementation. IPW ensures planning artifacts are produced consistently and integrate with the Implementation Cycle (spec + TDD). Critical: The task doc and plan doc must be bidirectionally wired – the task doc must reference the plan doc (Input, References), and the plan doc must reference the task doc (Host Task). Both links are mandatory; a plan doc is not complete without them. Planning must not be ad hoc; it must be a repeatable, traceable workflow.

Strategic consolidation: The former Implementation Cycle Workflow (ICW)—three-phase specification / test design / implementation planning under the ICW name—is merged into IPW. IPW (IPW or IPW E:S:T) is the canonical user-facing planning workflow. ICW-specific packaging (e.g. implementation-cycle-workflow, icw_handler.py, Cursor ICW trigger) must be deprecated, aliased to IPW, or documented as legacy so there is only one planning workflow to learn and maintain. RW remains canonical for release; implementation follows the Implementation Cycle (TDD, etc.) guided by IPW artifacts, not by a second parallel “planning” workflow brand.

Problem Statement

Current Situation:

Two overlapping concepts exist for the same intent: ICW (FR-040, framework workflow + handler + ICW trigger) and IPW (this FR)—both target structured planning before implementation, which splits documentation and cognitive load
Planning documents (spec/test/impl plans) are created informally and inconsistently
No defined workflow for when or how to create a plan doc
Plan docs are often created without being wired to their host task doc
Fundamental failure: Plan docs exist with no cross-reference in the task doc, and no link back – breaks traceability and discoverability
Implementation Cycle (Step 3: Spec & Test Creation) exists but lacks a formal planning workflow that produces a durable plan document

Root Causes:

No workflow or SoP for implementation planning
No enforcement of mandatory wiring at creation time
Planning is treated as optional or implicit rather than a first-class workflow
Gap between "ascertain spec, create tests" (Implementation Cycle) and producing a reusable plan document

Impact:

Orphaned plan docs (exist but not discoverable from task)
Inconsistent planning quality and completeness
Violates bidirectional wiring principle
Weakens traceability between planning and implementation
Implementation Cycle Step 3 lacks a clear planning artifact

Proposed Solution: Implementation Planning Workflow (IPW)

1. IPW Definition

IPW is the workflow for creating an implementation plan document before implementation begins. It sits between Task Creation (Implementation Cycle Step 2) and Specification & Test Creation (Step 3), and produces the planning artifact that guides Step 3 and Step 4.

IPW Trigger: User invokes IPW (or IPW ExxSxxTxx). This replaces the previous ad hoc instruction:

"Plan ExxSxxTxx: Define spec, design tests, plan impl"

It also replaces the ICW trigger for planning: users and docs should prefer IPW; ICW may remain temporarily as an alias but must not define a divergent planning process.

IPW Output: A plan document containing:

Specification – Functional and non-functional requirements, scope, boundaries
Test Design – Test categories, test cases, test data strategy
Implementation Plan – Phases, steps, dependency order, files to create/modify

2. Formalized IPW Steps (Ordered)

Step	Name	Description
0	Identify Host Task	Resolve E:S:T from user input or context; confirm task doc exists
1	Define Spec	Populate Spec section: Goal, Functional Requirements, Non-Functional (if applicable), Out of Scope
2	Design Tests	Populate Test Design: categories, test cases (TC/Name/Behavior), test data strategy
3	Plan Implementation	Populate Impl Plan: phases, steps, dependency order, files to create/modify
4	Create Plan Doc	Write plan doc using template; include header with Task ID, Host Task link
5	Wire to Host Task	Add plan doc to task doc Input and References; add Host Task in plan doc header
6	Validate	Confirm bidirectional wiring; confirm required sections present

Mandatory Bidirectional Wiring

Both directions MUST be wired – neither is optional.

Direction	Where	What to add
Task doc → Plan doc	Task doc Input	Link to plan doc (e.g. `[T07-planning-spec-tests-impl.md](T07-planning-spec-tests-impl.md)`)
Task doc → Plan doc	Task doc References	Same link
Plan doc → Task doc	Plan doc header	`Host Task: [T07-migrate-embedded-tasks-to-discrete-documents.md](T07-migrate-embedded-tasks-to-discrete-documents.md) (E4:S11:T07)`

Task doc must link to plan doc – Otherwise the plan is orphaned; developers cannot discover it from the task.
Plan doc must link to task doc – Otherwise the plan lacks context; the host task cannot be identified.
Wiring is atomic: both directions are completed in the same session. A plan doc is not complete until both links exist.

3. Plan Doc Template (Proposed)

Header (required):

Task title (E{epic}:S{story}:T{task} – Planning: Spec, Tests, Implementation Plan)
Host Task: relative path to the host task doc (E{epic}:S{story}:T{task}) — link to the task markdown file (bidirectional wiring)
Status
Planning doc created date

Sections (required):

Specification – Goal, Functional Requirements (table: ID/Requirement/Source), Non-Functional (optional), Out of Scope
Test Design – Test Categories (table), Test Cases (table: TC/Name/Behavior), Test Data Strategy
Implementation Plan – Phases (table: Step/Action/Deliverable), Dependency Order, Files to Create/Modify
Success/Verification Criteria (optional but recommended)

4. Analysis of Past Planning Docs

Examples analyzed: T07-planning-spec-tests-impl.md, T01-planning-spec-tests-impl.md, PIR-workflow-planning.md, migration-plan-embedded-to-discrete-tasks.md

Good practice (T07, T01):

Consistent 3-section structure (Spec, Test Design, Impl Plan)
Functional requirements table with IDs and sources
Test cases table with TC, Name, Behavior
Implementation phases with step/action/deliverable
Dependency order diagram
Out of scope explicitly stated
Script interfaces (T07), Files to create/modify

Bad practice / gaps:

T01 initially lacked Host Task link (unwired)
PIR-workflow-planning uses different structure (Executive Summary, Workflow Scope) – more design doc than spec/test/impl
Migration-plan has TBD placeholders; analysis sections not aligned with spec/test/impl pattern
No standard template enforced; structure varies

Proposed canonical structure: Adopt T07/T01 pattern as baseline; add mandatory Host Task in header; require Verification/Success Criteria section.

5. IPW Integration with Implementation Cycle

Implementation Cycle Step	IPW Relationship
Step 2: Task Creation	Host task must exist before IPW
Step 3a: Ascertain Specification	Plan doc Spec section captures this
Step 3b: Create Tests	Plan doc Test Design guides this
Step 4: Implementation	Plan doc Impl Plan guides this
Step 5: RW	Unchanged

IPW produces the plan document that formalizes and persists the output of "ascertain spec" and guides "create tests" and "implementation."

6. IPW Deliverables

IPW SoP or Workflow Doc – Step-by-step workflow with checklist
Plan Doc Template – Required structure (Spec, Test Design, Impl Plan, Host Task)
Wiring Rules – Mandatory bidirectional wiring, validation
Integration – Reference from Implementation Cycle SoP, .cursorrules, create-rule/create-skill
ICW deprecation / alias package – See §7

7. Consolidation with ICW (Implementation Cycle Workflow)

Aspect	Before	After (target state)
Canonical planning brand	ICW + IPW (overlapping)	IPW only
User / agent trigger	`ICW` and informal “plan task X”	`IPW` / `IPW E:S:T` (required); `ICW` = deprecated or thin alias
Artifacts	ICW templates / `docs/implementation-cycles/*` ad hoc + IPW plan doc	One durable plan doc per host task, bidirectionally wired (IPW); legacy ICW paths may redirect or merge
Task binding	FR-048 / `icw_handler` task-id rules	Same mandatory E:S:T binding applies to IPW sessions
Framework package	`implementation-cycle-workflow`, `icw_handler.py`, registry ICW	Document as legacy or adapter; eventually fold useful mechanics into IPW tooling or stub with “use IPW” guidance
Release / implementation	RW + Implementation Cycle	Unchanged — IPW does not replace RW or TDD

Rationale: One planning workflow reduces cognitive load and duplicate docs. ICW’s planning responsibilities (spec → test design → impl plan, planning-mode agent guidance) are the same scope as IPW; ICW as a separate product is redundant.

Use Cases

Planning for E4:S11:T07: User requests plan → Agent runs IPW → Creates T07-planning-spec-tests-impl.md with spec, tests, impl → Wires to T07 task doc (Input, References) and adds Host Task in plan → Plan discoverable from task and vice versa
Starting implementation: Developer opens task doc → Sees plan doc in Input/References → Navigates to spec, test design, impl plan → Follows plan for Step 3 and 4
Validating planning completeness: Automated or manual check ensures no plan doc exists without task doc reference, and wiring is bidirectional
Cursor/Agent trigger: User types IPW or IPW E:S:T → Agent executes IPW workflow (replaces "Plan ExxSxxTxx: Define spec, design tests, plan impl" and supersedes ICW for that purpose)
Migrating from ICW: Maintainer renames or aliases ICW in .cursorrules to IPW, updates workflow-registry/README lines for ICW to point at IPW consolidation, and aligns FR-040 / FR-048 text to “planning via IPW” where appropriate

Requirements

Functional Requirements

Non-Functional Requirements

FR-042:NF01 - Traceability: Plan doc always discoverable from task doc and vice versa
FR-042:NF02 - Consistency: Aligns with bidirectional wiring principle
FR-042:NF03 - Repeatability: IPW is a clear, actionable, repeatable workflow
FR-042:NF04 - Single planning mental model: Adopters can rely on one named workflow (IPW) for pre-implementation artifacts

Acceptance Criteria

Scope Analysis

Problem Domain: Implementation Planning, Task Documentation, Workflow Design, Bidirectional Wiring
Affected Areas:

Documentation (IPW workflow, plan doc template)
Implementation Cycle SoP (integration)
Task Template (References/Input guidance)
Plan Doc Template (new or enhanced)
Validation (optional script)
Other: Cursor rules, create-rule/create-skill

Estimated Complexity:

Simple (1-3 days)
Medium (1 week)
Complex (2+ weeks)

Dependencies

Blocks:

Reliable plan doc discoverability
Formal planning before implementation
Bidirectional wiring for planning artifacts

Blocked By:

None

Related Work:

Implementation Cycle SoP: packages/frameworks/workflow mgt/KB/Documentation/Developer_Docs/vwmp/implementation-cycle-sop.md
FR-035: Task Template Cross-Wiring Section (bidirectional wiring)
FR-016: Kanban Granularity & Discrete Task Docs (3-tier structure)
E4:S11:T07: Incident that triggered this FR (plan doc created without wiring)
create-rule / create-skill: May extend to include IPW
FR-040 / E5:S01:T40: Implementation Cycle Workflow (ICW) — planning scope merged into IPW; legacy implementation remains historical
FR-048 / E5:S01:T48: ICW task identifier — binding applies to IPW planning sessions
BR-055 / E4:S14:T03: ICW presence in framework package (historical); consolidation docs should not reintroduce “two planning workflows”
E5:S01:T42: Repository anchor task for this FR (implementation + doc alignment)

References

packages/frameworks/workflow mgt/KB/Documentation/Developer_Docs/vwmp/implementation-planning-workflow-agent-execution.md – IPW agent execution
packages/frameworks/kanban/templates/PLAN_DOC_TEMPLATE.md – Plan doc template
packages/frameworks/workflow mgt/scripts/validation/validate_plan_wiring.py – AC7 validator
packages/frameworks/workflow mgt/KB/Documentation/Developer_Docs/vwmp/implementation-cycle-sop.md – Implementation Cycle
docs/project-management/kanban/epics/Epic-4/Story-011-kanban-granularity-discrete-task-docs/T07-planning-spec-tests-impl.md – Example plan doc (unwired)
docs/project-management/kanban/epics/Epic-4/Story-011-kanban-granularity-discrete-task-docs/T07-migrate-embedded-tasks-to-discrete-documents.md – Host task for T07
docs/project-management/kanban/epics/Epic-4/Story-014-kanban-framework-maintenance/T01-planning-spec-tests-impl.md – Example plan doc
packages/frameworks/kanban/templates/TASK_TEMPLATE.md – Task template
FR-035: Task Template Cross-Wiring Section

Summary​

Problem Statement​

Proposed Solution: Implementation Planning Workflow (IPW)​

1. IPW Definition​

2. Formalized IPW Steps (Ordered)​

Mandatory Bidirectional Wiring​

3. Plan Doc Template (Proposed)​

4. Analysis of Past Planning Docs​

5. IPW Integration with Implementation Cycle​

6. IPW Deliverables​

7. Consolidation with ICW (Implementation Cycle Workflow)​

Use Cases​

Requirements​

Functional Requirements​

Non-Functional Requirements​

Acceptance Criteria​

Scope Analysis​

Dependencies​

References​