Skip to content
Content
Agent

planning-and-execution

**Navigation**: [Agents package rules](../AGENTS.md) → **Planning, execution and sub-agents**

From plugin
nodetool
63614 skills14 agents

Claude Code

$ npx -y skills add nodetool-ai/nodetool --agent claude-code

Agent definition

planning-and-execution.md

Planning, execution and sub-agents

**Navigation**: [Agents package rules](../AGENTS.md) → **Planning, execution and sub-agents**

Paths are relative to `packages/agents/` unless they name another package.

Parallel Task Execution

`create_plan` decomposes an objective into parallel tasks via `TaskPlanner.planMultiTask()`, and `execute_plan` runs them. Tasks form a DAG — independent tasks run concurrently.

How It Works

1. **Planning**: LLM generates a `TaskPlan` with multiple `Task` objects, each with `dependsOn` arrays 2. **Scheduling**: `ParallelTaskExecutor` hands the tasks to `scheduleDag` (`utils/dag-scheduler.ts`), which starts a task the moment its last dependency settles. `TaskExecutor` schedules its steps the same way. 3. **Merging**: `createDynamicMerge()` interleaves the streams and admits a newly-started node into the running merge (`utils/merge-generators.ts`) 4. **Completion**: A task's result reaches shared memory and its terminal `task_update` is emitted before its dependents are released; the stream ends when every task has settled

Scheduling is event-driven, not round-based. The executors used to dispatch in barrier rounds — start every ready node, wait for the slowest, recompute — so a plan ran as slow as its slowest sibling in every round, and the cap on rounds per plan and per task turned depth into failure. Both caps are gone: what bounds the work is the run budget, `maxStepIterations` per step, and the permit pool. A cycle never reaches the scheduler (`PlanBuilder` rejects it), and a node nothing could ever run settles failed with `unsatisfiable dependency` rather than hanging.

The aggregation step is the finish step's dependency on every other step in the task, not a deferral rule: it runs last because it waits for its siblings, and a sibling that fails blocks it (I-5) instead of aggregating over a hole.

Task Plan Structure

interface TaskPlan {
  title: string;
  tasks: Task[];           // Multiple tasks forming a DAG
}

interface Task {
  id: string;
  title: string;
  steps: Step[];
  dependsOn?: string[];    // Task IDs this depends on ([] = independent)
}

interface Step {
  id: string;
  instructions: string;
  dependsOn: string[];     // Step IDs within this task
  tools?: string[];        // Restrict available tools
  outputSchema?: string;   // JSON schema for step result
}

Skipping Planning

`execute_plan` takes the tasks as its argument, so a caller that already knows the decomposition passes it straight in and never calls `create_plan`. The shape is the `TaskPlan` above with snake_case keys (`depends_on`), validated by `buildPlanFromTasks` (`tools/plan-builder-tools.ts`) before anything runs.

Executor defaults (`constants.ts`)

Two bounds are left, both in `constants.ts`, both read by `parallel-task-executor.ts` and `task-executor.ts` when a caller names none: `DEFAULT_MAX_STEP_ITERATIONS` (action rounds per step) and `DEFAULT_MAX_CONCURRENT_AGENTS`. The round caps that sat beside them are gone (see the scheduling note above); the rest of what bounds a run is `RunBudget` below.

Nothing resolves a per-run policy object: `execute_plan` passes the run's budget and the parent's per-step iteration cap directly.

`maxConcurrentAgents` bounds one merge numerically (tasks per plan, steps per task), not the run. The run-level bound is the budget's permit pool below, and a permit stands for one open provider conversation, not one layer: a task takes none, each step holds one through `branchPool` (`subagent.ts`), and a child a step or sub-agent spawns runs on its parent's permit while the parent is idle in the spawning call and borrows from the run pool beyond that. A holder never queues for a second permit, so nesting cannot deadlock, and one pool bounds tasks, steps and sub-agents together (`run-budget-propagation.test.ts`, "bounds every layer"). `start_subtask` refuses past `MAX_BACKGROUND_SUBTASKS_PER_TURN` (`tools/start-subtask-tool.ts`) with `background_limit_reached`; a detached child still on its parent's permit can overlap the parent's next turn. Planning draws on the same budget: `TaskPlanner` takes a `budget` (falling back to the context's) and a refused turn stops planning naming the budget's reason.

One budget per run (`@nodetool-ai/runtime` → `RunBudget`)

A run's bounds are one object, created by the host and shared downward, never re-created by a child. `RunBudget` carries four:

| Bound | What refuses | Setting | |---|---|---| | `turns` | a turn whose worst case would cross the USD cap | `NODETOOL_AGENT_TURN_COST_CAP_USD` | | `deadline` | any turn or tool call after the wall clock runs out | `NODETOOL_AGENT_TURN_DEADLINE_MS` | | `concurrency` | a permit past the run's pool — tasks, steps, nested executors and sub-agents all draw from it, a holder's own permit counting as one | `NODETOOL_AGENT_MAX_CONCURRENCY` | | `turnCount` | a turn past the run's cumulative total | `NODETOOL_AGENT_MAX_TURNS` |

Spend admission is reserve-then-commit, because the next call's cost is only known afterwards: $0.49 spent under a $0.50 cap still admits a $0.30 call. `turns.reserve` is the single admission point and records the first reason it refuses; `exhausted` is set once, so a run that ran out of money and then ran out of time stopped for the money.

**A reservation is a handle, because the budget is shared.** `turns.reserve` answers a `TurnReservationHandle` carrying that turn's own worst case and its own pricing (or `null` when it refused), and `turns.commit(handle, actualUsd)` settles exactly that one — every other loop's reservation stays outstanding. One shared counter released whatever was in flight, so a chat turn committing its turn handed a concurrent sub-agent's headroom back and the cap stopped holding; a single `unpriced` flag likewise booked whichever turn committed first under the other's pricing.

**An unpriced model is not a free one.** A model the price catalog does not cover has

Read more
@nodetool-ai
Ships withnodetool

Open-source AI film studio · agent + node workflows Direct AI films, shot by shot. Start with one sentence. The agent writes the story, draws a still for every shot, and cuts the clips on a timeline.

6361 skill14 agents
Get the whole plugin

Stars on GitHub

Momentum

stars in total
636
Star history of nodetool-ai/nodetool on GitHub, a chart by star-history.com

Other agents on nodetool.

MUTATION_TESTING

MUTATION_TESTING

Agent

The agent package's pure, deterministic core (the chat permission gate, the control-tool plumbing, JSON extraction, and the…

cli

cli

Agent

**Navigation**: [Agents package rules](../AGENTS.md) → **Running Agents from CLI**

More agents from other plugins.

prompt-manager

prompt-manager

Agent

Agent for managing AI prompts on prompts.chat - search, save, improve, and organize your prompt library.

@gh-f@gh-fInstall Agent
humanize-diagnostician

humanize-diagnostician

Agent

정밀(strict) 모드 1단계 진단 에이전트. 글 전체를 한 번에 보고 "가장 지배적인 AI 티 패턴 3~6개"를 taxonomy ID와 함께 진단한다. 불안정한 span 열거(0↔18개로 요동) 대신 "무엇이 이 글을…

@epoko77-ai@epoko77-aiInstall Agent
blog-cluster-curator
Auto-invoked

blog-cluster-curator

Agent

Topic Clusters curator for the Claude Blog Brain. Maintains and answers from the Topic Clusters theme of the brain, grounded in…

@agricidaniel@agricidanielInstall Agent

Questions about planning-and-execution.

Which coding agents can use planning-and-execution?
planning-and-execution installs in Claude Code and Cursor: each loads subagents from .claude/agents, so copy the file there. Flowy's auto-invocation runs in Claude Code only.