Epic: Subplan Spawning & Parallel Execution (v3.3.0) #8489

Open
opened 2026-04-13 20:08:47 +00:00 by HAL9000 · 2 comments
Owner

Metadata

  • Commit message: feat(plans): implement subplan spawning and parallel execution engine
  • Branch name: feat/v3.3.0-subplan-spawning-parallel-execution

Background and Context

As part of the v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints), the plan execution engine must be extended to support hierarchical plan composition. Currently, plans execute as flat, sequential step lists with no ability to delegate work to child plans.

This Epic covers the foundational capability of spawning subplans during the Execute phase of a parent plan. Subplans must be able to run in parallel, controlled by a max_parallel configuration parameter. The parent plan must track the status of all spawned subplans throughout their lifecycle (pending → running → complete/failed).

This is a prerequisite for the Three-Way Merge Epic (#8486 child) and is a direct blocker of the Legendary issue #8486.

This Epic BLOCKS Legendary #8486.

Expected Behavior

  • During the Execute phase, a plan step can spawn one or more child subplans.
  • Subplans are tracked by the parent plan with statuses: pending, running, complete, failed.
  • Subplans execute in parallel up to the max_parallel limit; additional subplans are queued.
  • Sequential execution is supported when max_parallel=1.
  • Parent plan does not advance past a spawning step until all spawned subplans have completed (or failed).
  • Subplan results are made available for downstream merge steps.

Acceptance Criteria

  • Plans spawn child subplans during the Execute phase
  • Subplan status tracking works (pending, running, complete, failed)
  • Sequential execution supported (max_parallel=1)
  • Parallel execution works with configurable max_parallel
  • Parent plan tracks all subplan statuses in real time
  • Subplan results are accessible to the parent plan after completion
  • Unit and integration tests cover spawning, parallel limits, and status tracking
  • Test coverage >= 97% for all new modules in this Epic

Subtasks

  • Design subplan spawning API (step type, lifecycle, result contract)
  • Implement SpawnSubplanStep step type in the plan execution engine
  • Implement subplan lifecycle management (pending → running → complete/failed)
  • Implement parallel execution scheduler with max_parallel concurrency control
  • Implement subplan queue for overflow beyond max_parallel
  • Implement parent plan subplan status registry and tracking
  • Expose subplan results to parent plan context for downstream steps
  • Write unit tests for subplan spawning and lifecycle
  • Write integration tests for parallel execution with various max_parallel values
  • Verify sequential execution (max_parallel=1) behaves correctly

Child Issues / Child Epics

Feature issues will be linked here as they are created.

  • Feature: SpawnSubplanStep implementation — TBD
  • Feature: Parallel execution scheduler with max_parallel — TBD
  • Feature: Parent plan subplan status tracking — TBD

Definition of Done

This Epic is closed when:

  1. All subtasks above are complete and checked off.
  2. All Acceptance Criteria are verified.
  3. Test coverage >= 97% for all new modules.
  4. This Epic is confirmed as unblocking the Three-Way Merge Epic and the Legendary #8486.

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## Metadata - **Commit message**: `feat(plans): implement subplan spawning and parallel execution engine` - **Branch name**: `feat/v3.3.0-subplan-spawning-parallel-execution` ## Background and Context As part of the v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints), the plan execution engine must be extended to support hierarchical plan composition. Currently, plans execute as flat, sequential step lists with no ability to delegate work to child plans. This Epic covers the foundational capability of spawning subplans during the Execute phase of a parent plan. Subplans must be able to run in parallel, controlled by a `max_parallel` configuration parameter. The parent plan must track the status of all spawned subplans throughout their lifecycle (pending → running → complete/failed). This is a prerequisite for the Three-Way Merge Epic (#8486 child) and is a direct blocker of the Legendary issue #8486. **This Epic BLOCKS Legendary #8486.** ## Expected Behavior - During the Execute phase, a plan step can spawn one or more child subplans. - Subplans are tracked by the parent plan with statuses: `pending`, `running`, `complete`, `failed`. - Subplans execute in parallel up to the `max_parallel` limit; additional subplans are queued. - Sequential execution is supported when `max_parallel=1`. - Parent plan does not advance past a spawning step until all spawned subplans have completed (or failed). - Subplan results are made available for downstream merge steps. ## Acceptance Criteria - [ ] Plans spawn child subplans during the Execute phase - [ ] Subplan status tracking works (pending, running, complete, failed) - [ ] Sequential execution supported (`max_parallel=1`) - [ ] Parallel execution works with configurable `max_parallel` - [ ] Parent plan tracks all subplan statuses in real time - [ ] Subplan results are accessible to the parent plan after completion - [ ] Unit and integration tests cover spawning, parallel limits, and status tracking - [ ] Test coverage >= 97% for all new modules in this Epic ## Subtasks - [ ] Design subplan spawning API (step type, lifecycle, result contract) - [ ] Implement `SpawnSubplanStep` step type in the plan execution engine - [ ] Implement subplan lifecycle management (pending → running → complete/failed) - [ ] Implement parallel execution scheduler with `max_parallel` concurrency control - [ ] Implement subplan queue for overflow beyond `max_parallel` - [ ] Implement parent plan subplan status registry and tracking - [ ] Expose subplan results to parent plan context for downstream steps - [ ] Write unit tests for subplan spawning and lifecycle - [ ] Write integration tests for parallel execution with various `max_parallel` values - [ ] Verify sequential execution (`max_parallel=1`) behaves correctly ## Child Issues / Child Epics > Feature issues will be linked here as they are created. - [ ] Feature: SpawnSubplanStep implementation — _TBD_ - [ ] Feature: Parallel execution scheduler with max_parallel — _TBD_ - [ ] Feature: Parent plan subplan status tracking — _TBD_ ## Definition of Done This Epic is closed when: 1. All subtasks above are complete and checked off. 2. All Acceptance Criteria are verified. 3. Test coverage >= 97% for all new modules. 4. This Epic is confirmed as unblocking the Three-Way Merge Epic and the Legendary #8486. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.3.0 milestone 2026-04-13 20:09:31 +00:00
Author
Owner

[AUTO-OWNR-3] Triage Decision

Status: Verified

MoSCoW: Must Have
Priority: Critical

Rationale: This Epic is a direct prerequisite for both the Three-Way Merge Epic (#8491) and the Legendary (#8486). The v3.3.0 milestone explicitly requires plans to spawn child subplans during execution and support parallel execution with configurable max_parallel. Without SpawnSubplanStep and the parallel execution scheduler, no downstream merge or checkpoint work can proceed. Priority/Critical is confirmed — this is the foundational execution engine change for v3.3.0.

Next Steps: Begin with the subplan spawning API design and SpawnSubplanStep implementation. Parallel execution scheduler with max_parallel concurrency control is the critical path item. Target ≥ 97% test coverage for all new modules before closing.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

## [AUTO-OWNR-3] Triage Decision **Status**: ✅ Verified **MoSCoW**: Must Have **Priority**: Critical **Rationale**: This Epic is a direct prerequisite for both the Three-Way Merge Epic (#8491) and the Legendary (#8486). The v3.3.0 milestone explicitly requires plans to spawn child subplans during execution and support parallel execution with configurable `max_parallel`. Without `SpawnSubplanStep` and the parallel execution scheduler, no downstream merge or checkpoint work can proceed. Priority/Critical is confirmed — this is the foundational execution engine change for v3.3.0. **Next Steps**: Begin with the subplan spawning API design and `SpawnSubplanStep` implementation. Parallel execution scheduler with `max_parallel` concurrency control is the critical path item. Target ≥ 97% test coverage for all new modules before closing. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

🧩 Child Issues Created for Epic #8489

The following child implementation issues have been created for this Epic. Each child issue blocks this Epic and is assigned to milestone v3.3.0.

# Issue Labels
1 #8549feat(plans): implement subplan spawning during plan execution Type/Feature · Priority/High · MoSCoW/Must have · State/Verified
2 #8550feat(plans): implement parallel subplan execution with configurable max_parallel Type/Feature · Priority/High · MoSCoW/Must have · State/Verified
3 #8551feat(plans): implement comprehensive subplan status tracking Type/Feature · Priority/High · MoSCoW/Must have · State/Verified

All three issues follow the CONTRIBUTING.md format with Metadata, Background and Context, Expected Behavior, Acceptance Criteria, Subtasks, and Definition of Done sections.


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## 🧩 Child Issues Created for Epic #8489 The following child implementation issues have been created for this Epic. Each child issue blocks this Epic and is assigned to milestone **v3.3.0**. | # | Issue | Labels | |---|---|---| | 1 | #8549 — `feat(plans): implement subplan spawning during plan execution` | Type/Feature · Priority/High · MoSCoW/Must have · State/Verified | | 2 | #8550 — `feat(plans): implement parallel subplan execution with configurable max_parallel` | Type/Feature · Priority/High · MoSCoW/Must have · State/Verified | | 3 | #8551 — `feat(plans): implement comprehensive subplan status tracking` | Type/Feature · Priority/High · MoSCoW/Must have · State/Verified | All three issues follow the CONTRIBUTING.md format with Metadata, Background and Context, Expected Behavior, Acceptance Criteria, Subtasks, and Definition of Done sections. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#8489
No description provided.