feat(plan): implement subplan spawning during Execute phase with parent-child tracking #9290

Open
opened 2026-04-14 14:13:00 +00:00 by HAL9000 · 0 comments
Owner

Metadata

  • Branch: feat/plan-subplan-spawning-execution
  • Commit message: feat(plan): implement subplan spawning during Execute phase with parent-child tracking
  • Milestone: v3.3.0 (M4: Corrections + Subplans + Checkpoints)

Background and Context

The v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints) requires that plans can spawn child subplans during execution. Currently, the Execute phase processes tasks as a flat sequence without the ability to decompose complex tasks into hierarchical sub-plans. This limits the system's ability to handle tasks that are too large or complex to be addressed in a single plan execution.

When the LLM determines during execution that a task should be decomposed into smaller, more manageable units, it needs a mechanism to spawn child plans (subplans) that can be tracked, executed (sequentially or in parallel), and whose results can be merged back into the parent plan's ChangeSet. Without this capability, the milestone acceptance criteria for subplan spawning and parent-child status tracking cannot be met.

This issue implements the core subplan spawning infrastructure: the data model (foreign key linkage), the spawning logic in the Execute phase, the concurrency control (max_parallel), the status propagation from child to parent, and the CLI visibility via agents plan status <PLAN_ID>.


Expected Behavior

When the Execute phase determines a task requires decomposition:

  1. The LLM signals that a task should be spawned as a subplan.
  2. A new Plan record is created with parent_plan_id set to the originating plan's ID.
  3. The subplan is queued for execution — either immediately (parallel) or after prior subplans complete (sequential), governed by max_parallel configuration.
  4. The parent plan transitions to a waiting state, polling or subscribing to subplan status updates.
  5. Each subplan progresses through its own lifecycle (pending → running → completed/failed).
  6. The parent plan's status reflects the aggregate state of all subplans.
  7. Upon all subplans completing successfully, their ChangeSets are merged into the parent plan's ChangeSet.
  8. If any subplan fails, the parent plan is marked failed (or retried, per retry policy).
  9. agents plan status <PLAN_ID> renders a tree view showing the parent plan and all child subplans with their individual statuses.

Acceptance Criteria

  • The plans table has a nullable parent_plan_id foreign key column referencing plans.id.
  • The Execute phase can emit a "spawn subplan" signal/event that creates a child Plan record linked to the parent.
  • Subplans are executed sequentially when max_parallel = 1 (default) and in parallel up to max_parallel when configured higher.
  • The parent plan correctly tracks the status of all child subplans (pending, running, completed, failed).
  • The parent plan waits for all subplans to reach a terminal state before proceeding.
  • Completed subplan ChangeSets are merged into the parent plan's ChangeSet without data loss or conflict.
  • A failed subplan causes the parent plan to be marked as failed.
  • agents plan status <PLAN_ID> displays a hierarchical tree of the plan and all its subplans with statuses.
  • Unit tests cover: subplan creation, sequential execution, parallel execution (up to max_parallel), ChangeSet merge, and failure propagation.
  • Integration test covers an end-to-end scenario: parent plan spawns 2 subplans, both complete, parent completes with merged ChangeSet.

Subtasks

  • DB migration: Add parent_plan_id nullable FK column to plans table; add index on parent_plan_id.
  • Model update: Update Plan model/struct to include parent_plan_id field and subplans relationship.
  • Spawn signal: Define and implement a SpawnSubplanSignal (or equivalent event/return value) that the Execute phase can emit when the LLM requests decomposition.
  • Subplan factory: Implement SubplanFactory.create(parent_plan, task_description) that creates a child Plan record with parent_plan_id set.
  • Execution scheduler: Implement SubplanScheduler that respects max_parallel config — queues subplans and dispatches up to max_parallel concurrently.
  • Parent wait loop: Implement the parent plan's waiting mechanism (polling or event-driven) that monitors all child subplan statuses.
  • Status aggregation: Implement logic to aggregate child statuses into parent status (all completed → parent proceeds; any failed → parent fails).
  • ChangeSet merge: Implement ChangeSet.merge(other_changeset) (or extend existing merge logic) to combine subplan results into the parent ChangeSet.
  • CLI tree view: Update agents plan status <PLAN_ID> command to recursively fetch and render subplans as an indented tree with status indicators.
  • Unit tests: Write unit tests for each of the above components.
  • Integration test: Write an end-to-end integration test covering the full subplan spawning lifecycle.
  • Documentation: Update relevant docs/comments to describe the subplan spawning system and max_parallel configuration.

Definition of Done

This issue is closed when:

  1. All acceptance criteria checkboxes above are verified passing.
  2. All subtask checkboxes are completed and code is merged to the feat/plan-subplan-spawning-execution branch.
  3. CI passes (all tests green, no linting errors).
  4. A PR has been reviewed and approved by at least one maintainer.
  5. The feature is demonstrable end-to-end: a parent plan spawns subplans, they execute, and agents plan status <PLAN_ID> shows the correct tree with statuses.
  6. The milestone v3.3.0 acceptance criteria for subplan spawning are satisfied by this implementation.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch:** `feat/plan-subplan-spawning-execution` - **Commit message:** `feat(plan): implement subplan spawning during Execute phase with parent-child tracking` - **Milestone:** v3.3.0 (M4: Corrections + Subplans + Checkpoints) --- ## Background and Context The v3.3.0 milestone (M4: Corrections + Subplans + Checkpoints) requires that plans can spawn child subplans during execution. Currently, the Execute phase processes tasks as a flat sequence without the ability to decompose complex tasks into hierarchical sub-plans. This limits the system's ability to handle tasks that are too large or complex to be addressed in a single plan execution. When the LLM determines during execution that a task should be decomposed into smaller, more manageable units, it needs a mechanism to spawn child plans (subplans) that can be tracked, executed (sequentially or in parallel), and whose results can be merged back into the parent plan's ChangeSet. Without this capability, the milestone acceptance criteria for subplan spawning and parent-child status tracking cannot be met. This issue implements the core subplan spawning infrastructure: the data model (foreign key linkage), the spawning logic in the Execute phase, the concurrency control (`max_parallel`), the status propagation from child to parent, and the CLI visibility via `agents plan status <PLAN_ID>`. --- ## Expected Behavior When the Execute phase determines a task requires decomposition: 1. The LLM signals that a task should be spawned as a subplan. 2. A new `Plan` record is created with `parent_plan_id` set to the originating plan's ID. 3. The subplan is queued for execution — either immediately (parallel) or after prior subplans complete (sequential), governed by `max_parallel` configuration. 4. The parent plan transitions to a waiting state, polling or subscribing to subplan status updates. 5. Each subplan progresses through its own lifecycle (pending → running → completed/failed). 6. The parent plan's status reflects the aggregate state of all subplans. 7. Upon all subplans completing successfully, their ChangeSets are merged into the parent plan's ChangeSet. 8. If any subplan fails, the parent plan is marked failed (or retried, per retry policy). 9. `agents plan status <PLAN_ID>` renders a tree view showing the parent plan and all child subplans with their individual statuses. --- ## Acceptance Criteria - [ ] The `plans` table has a nullable `parent_plan_id` foreign key column referencing `plans.id`. - [ ] The Execute phase can emit a "spawn subplan" signal/event that creates a child `Plan` record linked to the parent. - [ ] Subplans are executed sequentially when `max_parallel = 1` (default) and in parallel up to `max_parallel` when configured higher. - [ ] The parent plan correctly tracks the status of all child subplans (pending, running, completed, failed). - [ ] The parent plan waits for all subplans to reach a terminal state before proceeding. - [ ] Completed subplan ChangeSets are merged into the parent plan's ChangeSet without data loss or conflict. - [ ] A failed subplan causes the parent plan to be marked as failed. - [ ] `agents plan status <PLAN_ID>` displays a hierarchical tree of the plan and all its subplans with statuses. - [ ] Unit tests cover: subplan creation, sequential execution, parallel execution (up to `max_parallel`), ChangeSet merge, and failure propagation. - [ ] Integration test covers an end-to-end scenario: parent plan spawns 2 subplans, both complete, parent completes with merged ChangeSet. --- ## Subtasks - [ ] **DB migration:** Add `parent_plan_id` nullable FK column to `plans` table; add index on `parent_plan_id`. - [ ] **Model update:** Update `Plan` model/struct to include `parent_plan_id` field and `subplans` relationship. - [ ] **Spawn signal:** Define and implement a `SpawnSubplanSignal` (or equivalent event/return value) that the Execute phase can emit when the LLM requests decomposition. - [ ] **Subplan factory:** Implement `SubplanFactory.create(parent_plan, task_description)` that creates a child `Plan` record with `parent_plan_id` set. - [ ] **Execution scheduler:** Implement `SubplanScheduler` that respects `max_parallel` config — queues subplans and dispatches up to `max_parallel` concurrently. - [ ] **Parent wait loop:** Implement the parent plan's waiting mechanism (polling or event-driven) that monitors all child subplan statuses. - [ ] **Status aggregation:** Implement logic to aggregate child statuses into parent status (all completed → parent proceeds; any failed → parent fails). - [ ] **ChangeSet merge:** Implement `ChangeSet.merge(other_changeset)` (or extend existing merge logic) to combine subplan results into the parent ChangeSet. - [ ] **CLI tree view:** Update `agents plan status <PLAN_ID>` command to recursively fetch and render subplans as an indented tree with status indicators. - [ ] **Unit tests:** Write unit tests for each of the above components. - [ ] **Integration test:** Write an end-to-end integration test covering the full subplan spawning lifecycle. - [ ] **Documentation:** Update relevant docs/comments to describe the subplan spawning system and `max_parallel` configuration. --- ## Definition of Done This issue is closed when: 1. All acceptance criteria checkboxes above are verified passing. 2. All subtask checkboxes are completed and code is merged to the `feat/plan-subplan-spawning-execution` branch. 3. CI passes (all tests green, no linting errors). 4. A PR has been reviewed and approved by at least one maintainer. 5. The feature is demonstrable end-to-end: a parent plan spawns subplans, they execute, and `agents plan status <PLAN_ID>` shows the correct tree with statuses. 6. The milestone v3.3.0 acceptance criteria for subplan spawning are satisfied by this implementation. --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.3.0 milestone 2026-04-14 14:14:55 +00:00
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#9290
No description provided.