AI planning that settles the approach before code is written

In AI CodeOps, planning is the first steps of a session: agents read the project's real code, then write requirements, a design or a delivery plan before anything is built. Their output is passed to every later step, added to the workspace Plan board, and for discovery workflows recorded as a proposed architecture decision record (ADR).

A plan written by a model is only useful if it is grounded in the code it will change. So when a session targets a project with a repository, AI CodeOps first clones it read-only, using the git connection of the person who started the session. The agents receive a file tree and the files most relevant to the task. If the repository cannot be read, for example because nobody connected a git account that can see it, the session fails with that reason. It does not quietly plan a brand-new app instead.

Plan with AI, before any task exists

Planning often starts earlier than a session: with an idea that isn't a task yet. Plan with AI on the Plan board is a conversation with a planning assistant that works like a tech lead in a planning meeting. It asks what changes the plan (who it's for, the scope, what "done" means), proposes an approach, says what to leave out of a first version, and splits the work into pieces one agent can finish in one session.

When you agree, choose Draft tasks. The assistant turns the conversation into tasks, each with a description and acceptance criteria, a priority, the agent best suited to it and the project. Nothing is filed yet: you untick what you don't want, edit the rest, pick Backlog or To do, and create them. Each task's timeline says it was filed with the planning assistant.

The assistant knows the workspace's projects, its agents and the tasks already open on the board, so it doesn't draft a task twice. It doesn't read the repository: the agents do that when a task's session runs. It runs on the workspace's own model provider, or on the platform's Standard tier within your plan's allowance, and stops when the workspace's AI budget is spent.

Which agents run

Planning is spread across several built-in agents. Each one has its own instructions:

• Architect: the approach, the files and modules to change, key decisions, trade-offs and risks.
• Product Analyst: requirements with acceptance criteria, and what is in and out of scope.
• Project Planner: a phased delivery plan with dependencies, milestones and effort estimates.
• Researcher: prior art in the codebase, the libraries in use and the constraints that matter.
• ADR Writer: an Architecture Decision Record with Context, Decision, Consequences and Alternatives.
• UI Designer and DevOps Engineer: the plan for front-end work and for infrastructure or pipeline changes.

You choose a workflow when you start a session. These built-in workflows are mostly or entirely about planning:

Most other workflows open with a single planning step. Plan, Build, Review & Test starts with the Architect, UI Implementation with the UI Designer, DevOps Change with the DevOps Engineer, and Performance Tuning with an Architect's optimization plan after profiling.

Steps run one after another. Each agent receives the task, the repository context and what the earlier steps wrote. In Architecture Debate, that means the critic reads both architects' proposals, and the final step weighs all three.

With the Auto model tier, planning agents are treated as steering steps. The Architect, Product Analyst, Project Planner, Researcher and ADR Writer get the best tier you have allowance for, because everything after them depends on their output. See models.

What planning produces

A plan on the session page. Each step's output streams live, with its own tokens and cost. You can read the plan before the build step finishes.

Items on the Plan board. When a session completes, AI CodeOps takes the first step whose name contains "plan" (Plan, Delivery plan, UI plan, DevOps plan, Optimization plan) and turns its list items into Plan board entries. Each entry gets a severity guessed from its wording, starts as to do, and records which session it came from. Items whose title is already on the board are skipped, including archived and finished ones, so re-running a workflow does not refill the board. At most 50 items are added per sync. A session page can also push its planner output to the board on demand.

A proposed ADR. Three workflows produce a decision rather than a task list: Architecture Debate (its final synthesis), Discovery & Spec (its agreed requirements) and Threat Model (its Record ADR step). When one of them completes, AI CodeOps records that output as an ADR with status proposed, linked to the session and the agent that wrote it. Outputs too short to settle anything are not recorded. Nothing is accepted on the AI's word: a person moves the ADR to accepted or rejected under Plan, ADRs.

Here is a Plan board item as GET /api/plan returns it, after a Plan step proposed it:

{
  "id": "pln_01JA8Z3K6W9N2Q4R7T1V5X8Y0B",
  "title": "Add input validation to the coupon field",
  "body": "Reject codes longer than 32 characters and anything outside A-Z, 0-9.",
  "severity": "medium",
  "status": "todo",
  "source": "run:wfr_01JA8YQ4M2C7H5K9P3S6V8X1ZD",
  "projectID": "checkout",
  "createdAt": "2026-10-18T09:14:02.511Z",
  "updatedAt": "2026-10-18T09:14:02.511Z"
}

Severity is one of high, medium, low or info. Status moves through backlog, to do, in progress, in review, blocked and done as people and agents work the board.

Quality gates involved

Planning is where a session is allowed to start, so the checks here are about whether it may run at all.

• Workspace policy. Before anything is spent, the policy is checked for starting the workflow (workflow.dispatch) and for each agent in it (agent.dispatch). A deny stops the session. An ask opens an approval under Review & Gate, Approvals, and the session waits until someone decides. The check runs again when the session leaves the queue, in case the policy changed while it waited. See approvals and policies.
• Cost budget. Once the period's spend is over the workspace's hard limit, new sessions are refused at launch, and a running one stops before its next model call. See cost controls.
• Read-only grounding. The repository clone used for planning is never executed. Code runs later, in the test sandbox.

A plan does not pass or fail a gate by itself. The gates that decide whether a change ships come later: tests, the findings review of the real diff, and a human approval. They are described on the quality gates page.

Limits

The planning agents are language models. They do not run your code, measure performance or query outside systems unless your workspace has connected MCP tools that a policy allows. A plan can be wrong, and the code pass that follows can depart from it. Review the diff that comes out of the build stage, not the plan that went in.