Waypoint™

Waypoint™ Execute Engine Specification

1. Purpose

The Execute Engine performs authorized work from an approved Execution Plan through humans, AI agents, agent teams, automations, and external systems.

Execution is not limited to writing code. It may create software, configure infrastructure, transform data, perform migrations, produce documentation, invoke operational processes, or perform other project work.

The Execute Engine answers:

What approved work is executable now, who or what should perform it, how should it be performed safely, and what evidence proves that it was completed correctly?

2. Inputs

The Execute Engine consumes:

  • approved Execution Plan and plan version;
  • execution authorization scope;
  • work hierarchy and dependencies;
  • stream definitions;
  • required capabilities;
  • worker recommendations/constraints;
  • acceptance criteria;
  • required tests and evidence;
  • environment/tool requirements;
  • policy and gate requirements;
  • delivery-unit associations.

Runtime context may include:

  • current work state;
  • available workers;
  • worker capacity;
  • active assignments;
  • external system state;
  • cost/budget state;
  • retries/failures;
  • current project priorities;
  • approved plan changes.

3. Outputs

Execution produces:

  • work assignments;
  • execution runs;
  • worker instructions/context packages;
  • produced artifacts;
  • test and validation results;
  • evidence;
  • actual effort/duration/cost where available;
  • defects and discovered work;
  • exceptions and escalations;
  • updated work state;
  • audit events;
  • delivery-ready units.

4. Core responsibilities

The Execute Engine shall:

  1. determine executable work;
  2. allocate or match workers;
  3. reserve work to prevent collisions;
  4. create bounded execution context;
  5. dispatch work;
  6. track worker/run lifecycle;
  7. coordinate parallel streams;
  8. enforce dependencies and gates;
  9. monitor progress and heartbeats;
  10. collect artifacts and evidence;
  11. invoke validation/testing;
  12. detect failure, stall, conflict, and drift;
  13. retry, recover, reassign, or escalate according to policy;
  14. create defects/discovered work when appropriate;
  15. synchronize operational work systems;
  16. capture actuals for planning/reporting;
  17. determine delivery readiness;
  18. preserve a complete execution audit trail.

5. Execution readiness

A work item may be selected only when all applicable readiness conditions are satisfied:

  • belongs to an approved plan/version;
  • lies within authorized execution scope;
  • is not complete, cancelled, superseded, or on hold;
  • predecessor dependencies are satisfied;
  • required artifacts/inputs exist;
  • required approvals/gates are satisfied;
  • target environment is available;
  • required capabilities can be fulfilled;
  • required tools/credentials are authorized;
  • concurrency and exclusivity constraints permit work;
  • no active reservation already owns the item;
  • budget/cost policy permits execution.

Readiness must be evaluated from Waypoint™ lifecycle state, not solely from Jira status.

6. Pull and push execution

Waypoint™ should support both models.

6.1 Pull

An available worker requests the next executable work compatible with its capabilities and permissions.

Useful for autonomous agents and scalable worker pools.

6.2 Push

The Control Plane assigns a specific work item to a selected worker.

Useful for:

  • humans;
  • specialist agents;
  • constrained environments;
  • urgent/recovery work;
  • work requiring explicit assignment.

Both models must use the same reservation and authorization controls.

7. Reservation and concurrency

Before dispatch, Waypoint™ should create a durable reservation/lease.

A reservation should include:

  • work item;
  • worker;
  • execution run;
  • lease start/expiration;
  • resources/workspaces reserved;
  • exclusivity constraints;
  • recovery metadata.

Reservations prevent duplicate execution and resource collisions.

Leases should be renewable through heartbeat/activity. Expired leases trigger reconciliation before reassignment.

8. Execution context package

Workers should receive bounded context sufficient to perform the assigned work without independently redesigning the project.

A context package may contain:

  • work objective;
  • acceptance criteria;
  • source requirements;
  • relevant design decisions;
  • dependencies and predecessor outputs;
  • expected artifacts;
  • repository/resource/environment references;
  • branch/workspace instructions;
  • testing/validation requirements;
  • documentation requirements;
  • allowed tools;
  • prohibited actions;
  • permissions;
  • escalation instructions;
  • reporting/update contract.

Context should be tailored to the work item and worker to reduce noise and unnecessary data exposure.

9. Worker lifecycle

A generic lifecycle may include:

available
→ reserved
→ preparing
→ running
→ validating
→ completed

Exceptional states may include:

waiting
blocked
stalled
failed
cancel_requested
cancelled
recovery
escalated

Worker state and work-item state are separate.

A worker may fail while the work remains resumable.

10. Parallel streams

Execution should maximize safe parallelism while honoring:

  • dependencies;
  • resource collisions;
  • repository/file overlap;
  • environment exclusivity;
  • database/schema conflicts;
  • reviewer capacity;
  • rate limits;
  • cost limits;
  • delivery sequencing.

The scheduler should be able to reason about multiple workers per stream and workers spanning multiple streams over time.

11. Workspace isolation

Execution environments should be isolated appropriately for the project domain.

Software work may use:

  • Git worktrees;
  • containers;
  • ephemeral development environments;
  • dedicated branches.

Infrastructure work may use:

  • isolated state/workspaces;
  • preview/planning environments;
  • subscriptions/resource groups/accounts.

Data work may use:

  • schemas/databases/workspaces;
  • development datasets;
  • isolated pipeline environments.

The domain model should represent an execution workspace generically.

12. Source-control execution pattern

For Git-based development, Waypoint™ should support configurable branch policies.

A common policy may be:

feature → preview → main

The executing worker should:

  • create/use the appropriate isolated workspace;
  • make bounded changes;
  • commit changes with traceability;
  • maintain required documentation;
  • run required validation;
  • create a detailed pull request;
  • respond to review feedback;
  • promote changes through authorized branches;
  • clean and prune temporary workspaces when complete.

The policy must be configurable and not embedded as a universal assumption.

13. Testing and validation

Testing is part of execution, not an optional afterthought.

Validation may include:

  • unit tests;
  • integration tests;
  • regression tests;
  • build validation;
  • lint/static analysis;
  • security checks;
  • infrastructure plan/policy checks;
  • data-quality tests;
  • reconciliation;
  • manual review;
  • documentation build;
  • environment smoke tests.

Each work item or delivery unit should declare required validation.

A work item cannot be considered complete until required validation and evidence are satisfied or an authorized exception exists.

14. Defects and discovered work

Execution will discover unplanned work.

Waypoint™ should distinguish:

  • defect in current work;
  • pre-existing defect;
  • missing requirement;
  • design deficiency;
  • technical task discovered during implementation;
  • external blocker.

The system should create or propose appropriate work while preserving provenance.

Material scope/design changes should not be silently absorbed into execution.

15. Failure and recovery

Execution must assume partial external success.

Every multi-step external operation should, where practical:

  1. persist intent/run state before mutation;
  2. use deterministic idempotency identifiers;
  3. perform the external action;
  4. persist returned identifiers/evidence;
  5. probe external state after ambiguous failure;
  6. reconcile successful side effects;
  7. resume only missing steps.

Examples include:

  • branch created but response lost;
  • PR created but persistence failed;
  • cloud resource deployed before timeout;
  • Jira updated but network call returned ambiguous failure.

Retries must not blindly repeat irreversible actions.

16. Stall detection

Waypoint™ should identify work that is not technically failed but is no longer progressing.

Signals may include:

  • missing heartbeat;
  • unchanged run state;
  • repeated tool failures;
  • no artifact progress;
  • worker waiting for unavailable input;
  • external job exceeding expected duration.

Policy may:

  • wait;
  • prompt the worker;
  • restart;
  • reassign;
  • escalate to a human;
  • return work to planning.

17. Human work

Humans are workers in the same execution model but require different interaction.

Waypoint™ should support:

  • human assignments;
  • due dates/priority;
  • clear work packages;
  • notification;
  • evidence submission;
  • approval/review tasks;
  • manual completion with required evidence;
  • reassignment/escalation.

Human work should participate in dependencies and forecasts exactly like autonomous work.

18. Agent teams and subagents

A worker assignment may be fulfilled by an agent team.

The parent agent/team remains accountable for:

  • decomposition within its authorized work boundary;
  • subagent coordination;
  • evidence aggregation;
  • policy compliance;
  • reporting status back to Waypoint™.

Subagents may not expand project scope or bypass permissions.

Waypoint™ should retain enough subexecution telemetry to audit meaningful actions without requiring every internal reasoning step.

19. Runtime replanning

The Execute Engine should feed actual conditions to Planning.

Triggers may include:

  • estimate variance;
  • newly discovered dependencies;
  • worker capacity changes;
  • repeated failure;
  • new defects;
  • external delays;
  • scope/design changes.

Execution should not rewrite the approved plan invisibly.

Minor assignment/scheduling adjustments may occur under policy; material plan changes require a new plan version or approval.

20. Adaptive execution and discovered work

Execute is responsible for surfacing structured discoveries and may automatically create and continue newly required work when policy permits.

For in-scope discoveries, Waypoint™ should be able to:

  • classify the discovery;
  • create the appropriate Task or Bug;
  • establish acceptance criteria and provenance;
  • estimate it;
  • establish dependencies;
  • place it into the appropriate stream and sprint/timebox;
  • synchronize it to Jira;
  • make it executable immediately when authorization, dependencies, capability, and capacity permit;
  • update forecast/actual reporting.

Material scope, architecture, security, cost, schedule, or delivery impact must raise the applicable gate rather than being silently absorbed.

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

21. Execution authorization and stop controls

Waypoint™ must support:

  • project pause;
  • stream pause;
  • worker pause;
  • work-item cancellation;
  • prevent-new-work mode;
  • emergency stop;
  • revoke execution authorization.

Stopping new dispatch should be distinguishable from terminating active external operations.

Destructive termination requires policy-aware handling and reconciliation.

22. Delivery readiness

A delivery unit becomes delivery-ready when:

  • required work is complete;
  • required tests/validation pass;
  • required reviews are complete;
  • required artifacts exist;
  • unresolved defects are within accepted policy;
  • delivery prerequisites are satisfied;
  • evidence is complete;
  • no blocking exception remains.

The Execute Engine then produces the delivery package consumed by the Delivery Engine.

23. Reporting requirements

Execution must expose reporting-ready data for:

  • active workers;
  • work queues;
  • stream progress;
  • throughput;
  • cycle time;
  • estimate versus actual;
  • worker utilization;
  • failures/retries;
  • blocked/stalled work;
  • test/quality results;
  • discovered defects;
  • cost where available;
  • delivery readiness.

The Control Plane reporting API is the primary reporting interface; Jira reporting is supplemental.

24. Initial completion criteria

The Execute Engine is sufficient for an initial end-to-end release when it can:

  1. identify executable work;
  2. match and reserve workers;
  3. dispatch bounded context;
  4. support parallel streams;
  5. track durable run state;
  6. execute at least one AI-worker integration;
  7. support human work;
  8. collect validation/evidence;
  9. recover safely from ambiguous external failure;
  10. synchronize work state with Jira;
  11. capture execution actuals;
  12. create/escalate discovered work;
  13. provide stop/pause controls;
  14. hand a validated delivery unit to Delivery.