Planner Tool V1
Planner Tool V1
Objective
Define a standalone planner API that takes selected solutions and project scope, decomposes them into buildable work, and emits dependency-aware graphs that can be executed as real implementation programs.
This tool is not the research runtime and not the governance engine.
Its purpose is to:
- take selected solution packets
- identify implementation problems worth solving
- decompose work into bounded nodes
- model dependencies and workflow order
- emit machine-readable DAGs and execution packets
Role In The System
The intended split is:
evidence-search-toolexternal evidence retrievalmemory-toolreusable solved-case retrievalresearch-toolcandidate generation, evaluation, and recommendationplanner-toolimplementation decomposition and DAG generationgovernance-toolexecution gating, approval, and merge control
The planner turns chosen directions into buildable work. It does not decide which solution wins and it does not approve execution.
Canonical project-level model:
docs/node-based-project-plan-v1.md
Planner must route major work through problem nodes, node options, and execution units.
Hard Boundary With Governance
The planner owns:
- decomposition of selected solutions into work items
- dependency modeling
- conflict-domain declaration
- completion criteria declaration
- execution packet structure
The governance tool owns:
- legality of execution
- approval requirements
- validation requirements
- state transitions
- completion or merge readiness
Governance must not reconstruct plan structure from prose or invent missing planner fields. Planner must emit the machine-readable structure governance needs.
Core Principle
Large projects should be modeled as many bounded implementation problems with explicit dependencies, not one giant plan blob.
The planner must answer:
- what needs to be built
- in what order
- what can run in parallel
- what is blocked on what
- what artifacts prove completion
The planner ranks problem nodes, but it executes only execution units.
V1 Use Case
V1 should support:
- one selected solution or a small selected solution set
- one project scope packet
- decomposition into a DAG of implementation work
- generation of worker-ready execution packets
The initial planner should optimize for clarity and buildability, not perfect forecasting.
Non-Goals
V1 should not become:
- a full PM suite
- an autonomous executor
- a governance engine
- a massive project portfolio system
It should stay focused on turning selected solutions into executable work graphs.
End-To-End Flow
- accept
planning_request_packet - normalize selected solutions and scope constraints
- identify or import
problem_noderecords - rank problem nodes and choose a frontier
- generate or attach
node_optionrecords - select options and materialize
execution_unitrecords - detect dependencies and conflicts
- emit
implementation_graph_packet - materialize the chosen structural plan into execution-ready form
- emit worker-ready execution packets
API Surface
define_scope
Purpose:
- normalize the selected solution and implementation scope
Input:
planning_request_packet
Output:
normalized_scope_packetscope_validation_results
derive_work_items
Purpose:
- identify bounded implementation problems implied by the selected solution
Input:
normalized_scope_packet
Output:
work_item_packet[]
This API should evolve toward problem_node[].
build_dependency_graph
Purpose:
- create dependency-aware graph structure across work items
Input:
work_item_packet[]dependency_policy
Output:
implementation_graph_packet
materialize_execution_slices
Purpose:
- convert a chosen structural plan into an execution-ready plan with runnable slices
Input:
- chosen structural
implementation_graph_packet execution_materialization_policy
Output:
execution_ready_plan_packetexecution_packet[]
This API should consume execution_unit[] once the execution-unit contract is active.
emit_execution_packets
Purpose:
- project execution-ready slices into worker-usable execution packets
Input:
execution_ready_plan_packetexecution_policy
Output:
execution_packet[]
Primary Packets
planning_request_packet
Purpose:
- canonical planner input
Minimum fields:
request_idproject_idselected_solution_refsproject_goalscope_constraintsacceptance_targetsartifact_targets
Recommended optional fields:
deadlineteam_constraintspreferred_execution_ordernon_goals
Required upstream contract rule:
selected_solution_refsmust reference one or moreselected_solution_scopepackets- raw
research_recommendation_packetoutput is not a sufficient authoritative planner input by itself
work_item_packet
Purpose:
- one bounded implementation problem worth solving
Minimum fields:
work_item_idtitleproblem_statementgoalinputsoutputscompletion_criteriadependency_refsconflict_domains
implementation_graph_packet
Purpose:
- machine-readable project DAG
Minimum fields:
graph_idproject_idnodesedgesworkflow_groupsready_nodesblocked_nodes
execution_ready_plan_packet
Purpose:
- canonical planner-produced execution-ready handoff before governance
Minimum fields:
plan_idselected_solution_scope_refsource_structural_plan_refplan_readinessexecution_slicesmaterialization_policy_refmaterialization_warnings
execution_packet
Purpose:
- a planner-produced packet for one execution-ready build slice
Minimum fields:
execution_idwork_item_idgraph_idtask_summaryrequired_inputsexpected_outputsvalidation_targetsblocking_dependencies
Required upstream contract rule:
execution_packetmust be derived from anexecution_ready_plan_packet, not directly from a raw structuralimplementation_graph_packet
Recommended governance-facing fields:
declared_ready_inputsconflict_domainsrequired_approvalscompletion_evidence_requirementsrunnable_preconditions
Required Upstream Selection Contract
Before planning begins, research output must be converted into a canonical selected-solution contract.
The planner should therefore consume:
selected_solution_scope
through:
planning_request_packet
The planner must not become the place where recommendation ranking is reinterpreted into final selection authority.
Node Model
Each node should represent one bounded buildable problem.
V1 node properties:
- stable id
- clear goal
- explicit dependencies
- explicit conflict domains
- artifact outputs
- completion checks
- estimated parallelizability
Good node examples:
- define API schema for memory tool packets
- implement ranking engine normalization helpers
- add evidence packet assembler
- wire planner handoff packet generation
Bad node examples:
- build the whole planner
- make research better
- fix architecture generally
Edge Model
V1 edges should stay simple.
Supported edge relations:
depends_onblocksconflicts_withinforms
The critical relation is depends_on. The graph should remain a DAG for execution ordering.
Workflow Groups
The planner should cluster nodes into coarse workflows.
Recommended workflow groups:
contractsruntimeevaluationintegrationhardening
These are grouping aids, not authority boundaries.
Dependency Rules
The planner should infer dependencies from:
- artifact prerequisites
- API producer/consumer relationships
- validation order
- migration or rollout sequencing
- shared conflict domains
The planner should avoid inventing unnecessary dependencies. A DAG that is too dense destroys parallelism.
Parallelism Rules
A node is parallelizable only when:
- it has no unmet dependencies
- it does not collide on conflict domains
- it does not require the same exclusive artifact ownership
The planner should explicitly mark:
ready_nowblockedparallel_safereview_gated
Planner Outputs
The planner should emit:
- full implementation DAG
- topological order
- ready queue
- blocked queue
- execution packets
- unresolved ambiguity list
This makes the graph operational, not merely descriptive.
Runnable Contract
The planner must emit enough structure for governance to evaluate runnable state without re-planning the work.
At minimum, a planner-produced runnable contract should identify:
- unmet dependency refs
- required inputs
- exclusive conflict domains
- expected outputs
- validation targets
- completion evidence requirements
If governance has to infer these from free text, the planner output is incomplete.
Integration With Research Tool
The planner consumes:
- selected solution packets
- recommendation reasoning
- supporting artifacts
- open questions
It should not consume raw internal research search state by default.
Integration With Memory Tool
The planner may retrieve:
- prior DAG fragments
- reusable workflows
- reusable execution packet patterns
These should help decomposition but should not overwrite current project reality.
Integration With Governance Tool
The planner hands governance:
- graph packets
- execution packets
- completion criteria
- validation targets
The planner proposes work structure. Governance decides what is legal to run and merge.
Failure Modes To Avoid
- giant plan nodes that cannot be executed
- dense graphs with fake dependencies
- missing completion criteria
- planner outputs that require prose interpretation to act on
- planning becoming hidden governance
V1 Implementation Sequence
- define planner packet schemas
- implement scope normalization
- implement bounded work-item derivation
- implement dependency inference
- implement DAG emitter
- implement execution packet emitter
- integrate with governance-tool
V1 Exit Criteria
V1 is successful when:
- one selected solution can be decomposed into bounded work items
- the work items form a real DAG
- the planner can identify ready vs blocked work
- execution packets are specific enough for downstream implementation