Guide
Start a Project
overplane init: Create Project
The presence of an overplane.yaml configuration file marks an Overplane
project. This file contains project configuration.
The overplane init command will create a working default overplane.yaml file in the working directory if it does not exist. There are no restrictions
on other files and directories in the working directory.
> overplane init
Once created, overplane.yaml can be customized to the project's needs.
Running overplane init again will validate the current contents of
overplane.yaml.
overplane sandbox build: Create Sandbox
Overplane uses per-project, locally-built sandbox containers to run AI
coding agents and other utilities inside an isolated, consistent sandbox.
Each project's container is built from a base image, such as Debian Linux, 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
Overplane stores user-written spec Markdown files in the specs
directory by default. Each spec is a numbered Markdown file with a YAML metadata
block (frontmatter): e.g., 001-bootstrap.md, 002-some-feature.md, etc.
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 overplane build: Build Project
With one or more specs written, overplane build turns them into code.
It runs each spec through a fixed pipeline of three phases:
raise (drive an agent to lift the spec into a formal intermediate
representation and SMT files under dirs.ir),
verify (run the Z3 solver over each spec's model and a merged
model of all specs; validate is accepted as an alias, and a contradiction
stops the build with exit code 9), and codegen
(drive an AI coding agent to generate the software, with the checked model mounted
for reference). Raise and codegen run each spec's agent in its own isolated project
container; verify runs Z3 inside the same sandbox.
# Preview specs, phases, and steps (no execution)
> overplane build all --plan
# Dev flow: codegen specs 1..1
> overplane build -p codegen -n 1
# Full pipeline over all specs
> overplane build all
Generated code is written to the code directory configured in
overplane.yaml (dirs.code). Codegen runs in an
internal staging directory; on success dirs.code is rebuilt as a
clean copy of the final content-addressable snapshot (stray files are deleted
— pass --additive to overlay without deleting). Use
-a/--agent to pick the default agent for the run: a
named agent config from overplane.yaml (for example
codex) or a raw backend id. Use --prompt to select a
different stdprompt template (default codegen/auto). Pass
global
-v anywhere before -- for debug-level prep and execution
logs (assistant text at INFO, tool calls at DEBUG). Long agent runs emit liveness
pings every ~2 minutes. A colored stats table and the final agent output (success
color) appear when the build succeeds; the code directory path is printed to stdout.