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 on the Board.

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. If repository preparation fails, select Retry failed repos. If project setup fails after the repositories are ready, select Try again.

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.

If you prefer a form-based flow, select New in the left sidebar, then Task, then Build. This opens the New task modal. Enter a Task name, describe what Autobuild should work on, select a project, attach your spec document, and select Create task.

Navigate to the Autobuild page

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

The Autobuild interface has seven tabs: Overview, Pull Requests, Board, Initiatives, Improvements, Issues, and Settings.

By default, the page opens on the Overview tab. At the top right, you'll see a Mine / All toggle that filters the view to your work or all workspace work.

Find your initiative

Select the Initiatives tab. Your new initiative will appear as a card in the Active filter group. The tab filter shows three groups: Active (N), Completed (N), and Planned / Paused (N) — the count updates as work progresses. There's also a Search initiatives field to find initiatives by name or description.

Each initiative card shows:

• The initiative name and its current priority level

• A segmented progress bar that fills as executables complete

• Health chips that summarize the state at a glance:

  • ✓ N done — executables that have completed

  • ⚠ N in review — executables that are in review or paused

  • ● N blocked — executables that are blocked or failed

  • N planned — executables that have not started yet

• Linked PR pills for pull requests associated with the initiative

• An Updated [time] timestamp in the bottom-right corner

Select the initiative card to open the full initiative detail view.

The initiative detail view

The detail view shows the full picture of your initiative.

At the top, you'll see a navigation trail showing where you are: Autobuild > Initiatives > [initiative name]. Below that are the initiative name, its status badge, priority indicator, and any linked project.

The detail view is split into a main column for narrative content and timelines, and a details panel on the right.

Main column:

• Initiative narrative — the description Autobuild captured from your spec

• Execution Timeline — features and direct executables organized by output type, status, and latest activity

• Activity Timeline — a log of everything that has happened on this initiative

Details panel:

• Stats — counts of features, executables, completed executables, pull requests, threads, artifacts, and dependencies

• Features — a scrollable list of features decomposed from your spec; each feature is clickable and links to its own detail view

• Direct executables — any executables attached to the initiative that aren't nested under a feature

• Dates and ownership — owner, created date, updated date, and strategy

• Cost — total credits consumed across all executables

If the initiative is active, you'll see a Pause button in the top-right corner. If it's already paused, a Resume button appears instead.

Track executables on the Board

Go back to the Board tab for a kanban view of all executables across the initiative.

The Board has five columns. Executables move from left to right as work progresses:

• Planned — Created, but no agent has picked it up yet.

• Queued — Waiting for an available agent to start.

• In Progress — An agent is actively working. Select the card to watch its thread in real time.

• In Review — Ready for your review and approval before the code merges.

• Completed — The pull request is merged and that piece of work is done.

You don't need to act on Planned or Queued cards. Focus on In Review.

Select any executable card to open the executable detail panel, where you can see its description, linked PR, associated agent thread, and status history.

At the top of the Board, you'll find an All Initiatives dropdown to filter executables to a single initiative and a Group by initiative checkbox that reorganizes cards by initiative within each column.

What to do next

Once executables start moving through the Board:

• Review PRs as they appear in the Pull Requests tab. Each PR is linked to the executable that produced it.

• Monitor the Board for executables that enter In Review — those need human review before the code merges.

• If an executable becomes blocked or failed, select it to open the detail panel. Review the blocker information, open the linked agent thread to see what went wrong, and adjust the status where an available action fits the situation.

• To pause the entire initiative while you re-scope the spec, use the Pause button in the initiative detail view. Resume it when you're ready.

• When all executables complete, return to the Initiatives tab and mark the initiative complete from its right-click context menu (Mark Complete).