Execution Plans

An execution plan (usually just “a plan”) is a named, persisted workflow: you give a free-text goal, and Contenox stores an ordered list of step descriptions locally. One plan is active at a time; the runtime can advance it step by step, pause, recover from failures, or replan when the situation changes.

Plans are separate from a normal chat session or a one-shot contenox run: they are built for multi-step work you want to inspect, resume, and steer over time.

Planner and executor

Plan mode uses two roles, each backed by a task chain (the same JSON chain model as everywhere else in Contenox):

Planner — takes your goal (and context) and produces the step list (structured as an ordered sequence of strings the runtime can track).
Executor — takes the current step and runs it through the chain engine (model, hooks, tools) like any other Contenox run.

You choose which chains act as planner and executor when you integrate via CLI or API. That separation keeps “what to do next” and “how to do this step” explicit and swappable.

What gets stored

Plans are persisted (typically alongside other Contenox local state). The runtime tracks which steps are pending, in progress, or done, and which plan is active, so you can list plans, switch the active one, or delete plans you no longer need.

Typical workflow

Create a plan from a goal — the planner fills in the ordered steps.
Execute the next pending step — optionally with shell or other hooks enabled for that step, or in auto mode to run until completion or failure.
If something goes wrong — retry the step, skip it, or replan so the planner adjusts the remaining work.

The exact subcommands and flags are listed in the CLI reference.

API and workspace

The same plan lifecycle is available programmatically (HTTP APIs for integrations) and through the Contenox workspace (web UI) on deployments that expose it — so teams can drive plans from scripts, services, or a browser without reimplementing storage or state machines.

Practical walkthrough

1. Create a plan

contenox plan new "analyze main.go, find the bug, and write a fix to patch.diff"

The planner reads your goal and writes the ordered step list. Use --explore to also run the read-only repo explorer before the first step runs — this seeds a RepoContext (entry points, build/test commands, key files) that every subsequent step can reference:

contenox plan new --explore "refactor the auth package to use JWT"

2. Inspect and navigate

contenox plan list          # show all plans (* = active)
contenox plan show          # show active plan's steps and their status

3. Execute steps

contenox plan next           # run the next pending step
contenox plan next --shell   # run next step with local_shell enabled
contenox plan next --auto    # run all pending steps unattended

Gated execution — after each tool round a small model scores whether to continue. Use --gate when you want an extra safety check on tool outputs (e.g. prevent cascading bad writes), at the cost of extra latency:

contenox plan next --gate

Human-in-the-loop — pause before each write/shell tool call and require terminal approval:

contenox plan next --hitl
contenox plan next --auto --hitl   # unattended but paused at each tool call

4. Recover from failures

If a step fails you have three options:

contenox plan retry           # re-run the failed step from scratch
contenox plan skip            # mark the step done and move to the next
contenox plan replan          # ask the planner to revise the remaining steps

5. Seed repo context manually

Run the explorer at any point to update or populate the active plan's RepoContext:

contenox plan explore

6. Clean up

contenox plan delete <name>   # delete a specific plan
contenox plan clean           # delete all completed / archived plans