Guide

Start a Project

Overplane projects are defined by a single overplane.yaml configuration file. This file contains project configuration, including the project's name, description, and the location of the specs that make up the project. A project directory generally starts empty, but can also contain existing files and directories.

overplane init: Create Project

The overplane init command will create a default overplane.yaml project configuration file in the working directory if it does not exist. There are no restrictions on other files that may be present in the working directory.

> mkdir my-first-project
> cd my-first-project
> overplane init

Once created, overplane.yaml can be customized to the project's needs (every field is documented in the configuration reference). Running overplane init again will validate the current contents of overplane.yaml.

Two of the most important configuration options are the project and dirs options, which specifies the project name and the locations of the specs, generated IR, and code directories relative to the project directory.

project:
  # Globally unique, identifier-friendly project name. 'overplane init' derives
  # it from the project directory name, lowercased with unsupported characters
  # replaced by hyphens. Must start with a lowercase letter or digit and may
  # contain lowercase letters, digits, dots, underscores, and hyphens.
  name: my-first-project

# Overplane-managed directories, given as paths relative to the project root
# (the directory containing overplane.yaml). Absolute paths and paths that
# escape the root with '..' are rejected.
dirs:

  # Directory holding the project's spec documents: numbered Markdown files with
  # YAML frontmatter. This is the durable record of your project's intent and
  # belongs in version control.
  specs: specs

  # Directory for disposable, machine-local working state. It is never
  # committed: 'overplane init' adds it to .gitignore and creates it on demand.
  # Deleting it is always safe.
  cache: .cache

  # Directory where 'overplane build' writes its final generated output. This is
  # the default destination for -o/--output.
  code: code

  # Directory for the Intermediate Representation (IR) files produced during the
  # build pipeline.
  ir: ir

The dirs section indicates default locations for various project-specific directories.

• specs: The directory that will hold the project's spec documents.
• ir: The directory for the Intermediate Representation (IR) files produced from the specs in the build pipeline.
• code: The directory where 'overplane build' writes its final generated output. This is the default destination, and can be overridden with the -o/--output flag to overplane build.
• cache: The directory for disposable, machine-local working state that is responsible for caching LLM outputs and other intermediate data. It is generally not committed, but can be pointed at a persistent location if desired. Deleting the cache directory is always safe; it will be recreated if missing.

overplane sandbox build: Create Sandbox

Overplane uses per-project, local containers to run AI coding agents in an consistent, isolated sandbox. Each project's container is built from a base image (Debian Linux by default), using an image recipe, and can be customized to the project's needs (e.g., adding or removing system packages) via overplane.yaml.

The overplane sandbox build command must be run at least once per project to build the project's container image locally.

> overplane sandbox build

Once the sandbox is successfully built, you can find it in the listing of sandbox container images using overplane sandbox list-images.

overplane spec new: Write First Spec

A spec is a natural language specification of a desired behavior, feature, or output. There is no fixed form to the content. Specs are written in Markdown format, with a YAML metadata block documented in the spec reference, and sequentially numbered.

You can create and edit these files by hand, or use overplane spec new, which lets you interactively create the next spec file in the sequence.

> overplane spec new --title "First Spec"

After editing the metadata fields (e.g., tags), copy and paste the following content into the spec file that was just created.

Create a self-contained, standalone HTTP file called `index.html`
that displays a complex, demoscene-like live, looping animation in
the full viewport using only HTML, CSS, and JavaScript. Must be
embeddable in an HTML iframe from any another HTML page. Must use
vector graphics and CSS animations exclusively, no images or videos.
Embed model name somewhere into the animation.

The project can now be built with overplane build.

overplane build: Build Project

With one or more specs written, overplane build turns them into working code. Every spec moves through the same three phases, in order:

• raise: an agent lifts the spec into a formal intermediate representation (IR), written to the ir directory (see IR Generation).
• verify: the Z3 theorem prover checks each spec's model, and a merged model of all specs together, for logical contradictions (see Spec Verification).
• codegen: a coding agent generates the software, with the checked model available for reference (see Codegen with IR).

All agent work runs inside the project sandbox you built earlier, never directly on your machine. Before spending any agent time, you can preview exactly what a build will do with --plan:

# Preview specs, phases, and steps (no execution)
> overplane build all --plan

# Full pipeline over all specs with default configured agent
> overplane build all

Agent phases can take several minutes per spec; long runs print a liveness ping every couple of minutes, so a quiet stretch does not mean the build is stuck. For a live progress table—one row per spec, one column per phase—run the build with --tui. If verification finds a contradiction between your specs, the build stops (exit code 9) before any code is generated; fix the conflicting requirement and run the build again.

A successful build ends with a build summary table and the path to the generated code. The code directory (dirs.code) is rebuilt as a clean snapshot of the final output, and the IR files land in the ir directory. Completed steps are cached by content in the cache directory, so re-running a build after editing one spec only re-runs the work that spec affects (see FileSet for how content-hashed builds work).

Try It Out

The generated code in the code directory is a complete, ordinary project: build and run it as you would any codebase in its language. If you would rather not install a toolchain on your host, run it inside the project sandbox instead with overplane sandbox run.

For this walkthrough, the build produces a single self-contained code/index.html. This is the actual artifact generated from the spec above, embedded live (you can also open it standalone in a new tab):

Change The Model

The build above used the project's default agent. The -a/--agent flag selects a different one: any named agent configuration from overplane.yaml (or a raw backend id). Pair it with -o/--output to keep each agent's output in its own directory, and you get independent implementations of the same spec:

# Named agent configs from overplane.yaml
> overplane build all -a codex -o code/codex
> overplane build all -a opencode -o code/opencode

Each agent raises and codegens the specs itself, so the implementations are fully independent. Completed steps are cached by content, per agent: re-running a build that has already happened is free, and only work the new agent has not done yet spends tokens. Below are the results of running the same spec through three different agents, rendered in mobile-sized viewports:

From here, keep adding numbered specs and rebuilding. For complete worked projects, from two-spec browser games to a wire-compatible Redis clone, browse the example projects: each one publishes its full specs and the resulting build.