Your First Initiative

By the end of this article, you will have started an Autobuild initiative from a spec document, watched it decompose into features and executables, and know how to track its progress from Your builds.

Prerequisites: You have completed What is Autobuild? and Install the GitHub App. GitHub is connected, a sandbox is configured, and you have at least one Obvious project to work in.

If this is your first time setting up Autobuild, wait until each selected repository sandbox shows Ready. Project setup begins automatically and the wizard shows Setting up your project. You do not need to select a separate button to start the project.

What is a spec document?

A spec document is a plain written description of what you want Autobuild to build. It tells Autobuild what the work is, what done looks like, and any decisions you've already made about how it should be done. It doesn't need to be long or follow a special format. A clear document describing the feature, the acceptance criteria, and any constraints is enough.

You have two ways to create one. You can write it yourself: create a document artifact in your Obvious project and describe what you want built in plain language. Or you can ask the agent to draft it for you: open the agent chat in your project, describe your idea, and the agent will turn it into a structured spec document. Review it, adjust anything that doesn't look right, and save it as a document artifact in the project.

Either way, your spec document needs to exist as a document artifact in your Obvious project before you start an initiative.

What Autobuild does when you start an initiative

When you point Autobuild at a spec document, it reads the spec and creates an initiative, a named container for everything that needs to happen. It then decomposes the initiative into features (logical groupings of work) and executables (individual agent tasks that result in pull requests, documents, or other outputs). Agents start picking up executables immediately.

You end up with a structured, trackable build plan that runs automatically. You monitor it, handle reviews, and merge PRs.

Open your project

Open the Obvious project that contains your spec document. The spec should be a document artifact in the project, the same kind of artifact your agent reads and writes during normal work.

Start your initiative

With your spec document ready in the project, there are two ways to start an initiative.

The quickest is through the agent chat. Open the chat in your project and ask the agent to create an initiative from your spec. You can say something like:

"Create an Autobuild initiative from [document name]" or "Start an initiative from my spec"

The agent will read the spec, propose a decomposition, and create the initiative.

You can also start from the Autobuild home. Describe what you want built in the composer, and Autobuild starts the initiative.

Navigate to the Autobuild page

Once the initiative is created, go to Autobuild in the left sidebar.

The Autobuild home opens on the composer, with Your builds below it. Your new build appears there.

Find your build

Your build appears under Your builds on the Autobuild home. Select View all to open all builds, where you can search and filter by status and decision. You can view your builds as cards or as a list.

Track your build

Select your build to open the build drawer. The drawer shows the build's name, project, status, owner, and age at the top.

While the build works, you can follow its plan and see each task in it. When Autobuild needs you, the drawer shows the decision waiting on your input, with the options you can choose between. When the build completes, the drawer shows a summary with links to the work.

What to do next

Once builds start moving:

• Review PRs as they appear on the PRs page. Each PR is linked to the work that produced it.

• Monitor Your builds for work that needs your input. Open the build and respond to the decision in the drawer.

• If a build stops moving or something goes wrong, open it to review its status.