cortex-plan

Planning a Conductor task tree

A plan is a dependency graph of tasks that workers on other machines run in parallel. A worker starts cold: a fresh worktree of the project's default branch, plus its own task's title, description and files. It never sees the plan, the other tasks or this conversation. Shape the plan for the machines you have, and write every task for that reader.

The same guide is served by cortex_task_tree_create(guide: true), so any model can read it.

1. Fill the plan brief

Answer each line before you plan. Ask the user for what you can't find; don't guess.

Outcome:      what is true when the whole plan is done (observable)
Out of scope: what this plan must not change
Repo/branch:  project and the base branch workers start from
Constraints:  deadline, compatibility, areas no one may touch
Machines:     one line per worker from cortex_agents (see 3)
Approvals:    who approves work (user or lead) and who merges PRs
Known traps:  what knowledge/memory recall turned up

2. Decide whether you need a tree

• One change in one or two files, under an hour of work: no tree. Do it, or create one task with cortex_task_create.
• A tree pays off with three or more independently reviewable changes, or work that can run on several machines at once.
• Two tasks in a row is not a plan. Merge them into one task, or find the work that can run beside them.

3. Survey the code and the machines

1. cortex_knowledge_search and cortex_memory_search on the request: earlier decisions and known traps.
2. cortex_code_search or cortex_code_context to find the code, and cortex_code_impact on shared symbols to see what else changes. Write down the files each change touches: you need them for files and to see what can run in parallel.
3. cortex_agents to see the workers. For each one note: idle or busy, OS, engines and models, capabilities, the project it is scoped to, and any exhausted quota. Then:
   • Width. Idle workers that can take this project's tasks are your parallelism. Aim for at least that many ready tasks at the widest level when the work allows it. More tasks than workers is fine: they queue.
   • Scope. A worker scoped to a project only takes that project's tasks. An unscoped one takes any.
   • Machine-specific work. Work that needs one environment (a Windows build, a GPU, a tool installed on one machine, a model only one machine has) gets requiredCapabilities that only those workers advertise. Use pinnedAgent only when exactly one machine may do it: a pinned task waits for that machine even while others sit idle.
   • Engines. Match the task to the engine: design and tricky debugging to the strongest model with high effort; mechanical edits to a cheaper one. agy runs headless and cannot run shell commands, not even the tests, so give it edit-only tasks. Add a fallback route for important tasks so an exhausted quota doesn't stall the plan.
   • Quota. Don't route to an engine and model whose quota is exhausted until after the plan should be done.