Waypoint™ Planning Engine Specification

1. Purpose

The Planning Engine transforms an approved Project Design Package into a realistic, dependency-aware, traceable, estimable, and governable Execution Plan.

Planning answers:

Given the approved solution, what work must occur, in what relationships and order, with what effort and capabilities, so the outcome can be executed and delivered?

2. Inputs

Required:

approved Project Design Package ID/version;
requirement inventory;
design artifacts;
constraints;
acceptance criteria;
delivery targets;
approval record.

Optional/contextual:

organization/project planning policies;
Jira configuration;
worker capability registry;
capacity;
calendars;
historical estimates/actuals;
reusable templates;
prior project patterns;
release constraints;
budgets/deadlines.

3. Outputs

The Planning Engine produces a versioned Execution Plan containing:

phases/releases;
epics/capabilities;
stories/work packages where useful;
executable tasks and bugs;
estimates;
dependencies;
streams;
priorities;
milestones;
sprints/timeboxes where applicable;
requirement/design traceability;
required worker capabilities;
performer type recommendations;
worker/team forecast;
concurrency constraints;
acceptance/test expectations;
required artifacts/evidence;
execution gates;
delivery units;
risks/assumptions introduced by planning.

It may then materialize the approved plan into Jira.

4. Planning principles

4.1 Plan from approved design

Planning does not substitute for Design. If decomposition requires inventing a consequential requirement or architecture choice, Planning should raise a design deficiency.

4.2 Executable leaf work

Leaf work items should be small and explicit enough for an authorized worker to execute without independently redesigning the project.

4.3 Estimate executable work

Every executable task should have an estimate or an explicit reason why it cannot yet be estimated.

Estimates should support scheduling and capacity decisions rather than create false precision.

4.4 Express capability requirements

Planning should describe the capabilities required to perform work.

Examples:

nextjs
typescript
sql-server
azure
fabric
terraform
security-review
technical-writing
manual-approval

A capability requirement is more durable than assigning a specific agent name during initial decomposition.

4.5 Separate plan from allocation

The plan may forecast workers and recommend allocations, but the work definition should survive reassignment.

4.6 Dependencies determine execution order

The hierarchy alone must not imply ordering. Dependencies should be explicit.

4.7 Preserve traceability

Every material planned item should trace to one or more:

requirements;
design decisions;
delivery requirements;
risk mitigations;
technical enablers with documented rationale.

5. Planning hierarchy

Waypoint™ should support configurable hierarchy, with a default model such as:

Project
└── Phase / Release
    └── Epic
        └── Story / Work Package (optional)
            └── Task / Bug

The internal domain must not depend on Jira's exact hierarchy.

5.1 Phase

A major implementation/delivery stage with a coherent outcome.

5.2 Release

A deliverable increment/version. A project may use phases, releases, or both depending on domain.

5.3 Epic

A significant capability or body of related work.

5.4 Story/work package

A user/business capability or cohesive implementation slice when useful.

5.5 Task

An executable unit of work.

5.6 Bug

A defect/remediation item. Bugs may arise during planning or execution and must participate in dependencies, estimates, streams, and allocation like other executable work.

6. Decomposition process

Planning should iteratively:

identify delivery outcomes/increments;
derive major capabilities;
identify enabling/foundation work;
decompose capabilities into executable work;
add test/validation/documentation/delivery work;
model dependencies;
identify streams;
estimate;
identify capability/performer requirements;
validate completeness against the Design Package;
identify schedule/capacity implications;
propose releases/sprints;
generate plan review.

The engine should critique its own plan before presenting it.

7. Completeness validation

The Planning Engine should check:

every requirement is covered, deferred, or explicitly excluded;
every delivery target has delivery work;
required testing/validation is planned;
security/governance requirements have implementation/review work;
architecture components have implementation/configuration work where needed;
integrations have build/configuration/test work;
documentation/handoff requirements are planned;
dependencies are acyclic or intentionally modeled;
leaf work is executable;
estimates exist;
performer/capability requirements exist;
no work silently expands approved scope.

8. Dependencies

Waypoint™ should support dependency types such as:

blocks / blocked by;
requires;
produces input for;
must precede;
environment prerequisite;
approval prerequisite;
test prerequisite;
delivery prerequisite.

Dependencies may exist across:

epics;
streams;
sprints;
phases/releases;
project boundaries where external dependencies are represented.

The plan should identify the critical path and major parallel opportunities.

9. Streams

Planning should group work into development/execution streams.

Streams are intended to support autonomous parallel work and reduce collisions.

A stream definition may include:

name;
purpose;
work membership;
capability profile;
repository/resource boundaries;
concurrency constraints;
expected worker count;
dependencies on other streams.

Jira labels such as stream:* may be used as a materialization pattern, but they are not the permanent internal representation.

10. Estimates

The Planning Engine should support configurable estimate units, such as:

hours;
ideal hours;
story points;
duration;
cost.

For autonomous execution, effort and elapsed duration should be distinguishable.

Estimate metadata should include:

estimate;
confidence;
basis/rationale where material;
performer assumptions;
historical calibration if available.

Actual execution data should later feed planning intelligence.

11. Performer and capability planning

Waypoint™ should use a generalized performer model rather than a simple human versus ai distinction.

A planned work item may specify:

Performer category

human required;
AI eligible;
automation;
external system;
mixed;
unspecified/allocator decides.

Required capabilities

one or more capability identifiers.

Review requirements

independent human review;
peer agent review;
automated validation;
domain approver.

Execution constraints

tool;
environment;
permission;
data access;
location/network;
concurrency/exclusivity.

12. Allocation forecast

Planning should estimate how the project could be staffed/executed.

The forecast may recommend:

number of workers/agents;
worker teams;
likely parallelism;
stream assignments;
sprint assignments;
reviewer load;
expected bottlenecks;
capacity shortfalls.

This is a forecast until execution is authorized and workers are actually reserved/assigned.

Many agents may work in one sprint. One agent may work across multiple sprints. The model must remain N:N.

13. Sprints and timeboxes

Sprints are planning/execution timeboxes, not the fundamental unit of work organization.

Waypoint™ should:

support sprint-based projects;
support non-sprint projects;
create reviewable chunks;
consider dependency readiness;
consider worker capacity;
consider reviewer capacity;
avoid filling a sprint with work that cannot become executable;
allow multiple streams per sprint.

For AI-heavy work, human review capacity may be a more important constraint than agent compute capacity.

14. Jira materialization

Once the plan is approved, the Planning Engine may create/update Jira.

The Jira adapter should support:

hierarchy creation;
descriptions;
labels;
estimates;
sprints;
links/dependencies;
requirement/design references;
performer/capability metadata;
plan version metadata;
reconciliation.

14.1 Jira is not the canonical plan

Waypoint™ must retain its own Execution Plan representation.

Jira is a synchronized operational projection.

14.2 Reconciliation

Reconciliation should:

detect drift;
distinguish intentional external changes from stale projections;
avoid destructive correction without policy;
preserve audit history;
allow approved synchronization in either permitted direction.

15. Plan review

Before Jira materialization/execution, the owner should be able to review the plan at multiple levels.

The review should summarize:

phases/releases;
major epics;
total estimated effort;
expected duration/range;
critical path;
streams;
proposed worker/agent footprint;
human work;
reviewer load;
major dependencies;
risks;
unresolved planning assumptions;
delivery sequence;
requirement coverage.

The user should be able to drill into detailed work without reading every task to understand the plan.

16. Plan Gate

Possible decisions:

approve;
approve a bounded increment;
request replanning;
change priorities;
change worker/capacity assumptions;
return to Design;
hold/cancel.

Approval identifies the exact Execution Plan version.

Only approved scope becomes execution-authorized.

17. Dynamic replanning

Execution will invalidate forecasts.

The Planning Engine must support replanning based on:

actual duration;
worker failure/unavailability;
newly discovered work;
bugs;
blocked external dependencies;
changed requirements;
delivery failure;
capacity changes.

Replanning must preserve:

completed work;
historical estimates;
actuals;
prior plan versions;
approval history;
traceability.

Waypoint™ should identify the impact of the proposed replan before applying it.

18. Relationship to allocation and Execute

The Planning Engine determines:

what work exists;
what it depends on;
what capabilities it requires;
how it can be grouped;
estimates and forecasts.

The Execute Engine/Control Plane determines at runtime:

what is currently executable;
which authorized worker should pull it;
whether capacity is available;
whether concurrency constraints allow it;
when to retry/reassign/escalate.

This boundary prevents a static plan from becoming an inflexible dispatcher.

19. Required planning capability areas

The implementation should provide or evolve the following capability areas:

hierarchy generation and validation;
plan schemas;
sprint/timebox planning;
issue/work intelligence;
backlog intelligence;
capacity intelligence;
hierarchy reconciliation;
bulk Jira operations;
worker execution-package generation;
next-executable selection;
reporting-domain integration;
durable run/audit foundations.

These capabilities should conform to Waypoint™'s domain contracts and remain decoupled from Jira-specific representations wherever practical.

20. Adaptive plan maintenance

The approved Execution Plan is the baseline, not a frozen operational snapshot. During execution, Waypoint™ may discover in-scope Tasks, Bugs, dependencies, validation work, estimate changes, and scheduling changes.

Planning must support controlled amendments that:

preserve the approved baseline;
maintain a current execution plan;
incorporate automatically dispositioned discovered work;
recalculate dependencies, estimates, capacity, sprints/timeboxes, streams, and forecasts;
continuously reconcile authorized work with Jira when configured;
create a new plan version or gate when policy thresholds are exceeded;
retain provenance and audit for every material plan mutation.

Detailed behavior is defined in 14-Adaptive-Execution-and-Continuous-Replanning.md.

21. Planning Engine completion criteria

The Planning Engine is complete enough for an initial end-to-end Waypoint™ release when it can:

consume an approved Project Design Package;
produce a versioned Execution Plan;
decompose work to executable leaves;
estimate executable work;
represent dependencies;
create parallel streams;
express performer/capability needs;
forecast allocation/capacity;
produce a meaningful Plan Gate review;
materialize an approved plan in Jira;
preserve requirement/design traceability;
expose executable-plan data to the Execute Engine;
support controlled replanning.