# Autobuilder tutorial

A short **happy path**: register your app in autobuilder, launch the daemon, watch it work, and steer or stop when you need to. For full field tables and flags, see the main [README](../README.md). For deeper topics, use the [documentation index](README.md).

## What this is

Autobuilder runs `builder_loop.py`, which repeats **iterations**. Each iteration is **one** AI request that can include pushing prior work, **product review** (find gaps, add tasks), **planning** (research, split work), and **execution** (TDD-style implementation and commits). The loop chooses which phases to run based on task state. See [Architecture](architecture.md) for the full picture.

```mermaid
flowchart LR
  registry["config.json"]
  daemon["builder_loop.py"]
  phases["Review / Plan / Execute"]
  output["Commits and tasks"]
  registry --> daemon --> phases --> output
```

## Prerequisites

- This **autobuilder** repository cloned locally (you run the daemon from its root).
- A **project** directory that can run your app (for example `npm run dev`), with autobuilder data under `.autobuilder/` — usually created with the **create-project** skill or by following **Quick Start** step 2 in the [README](../README.md).
- A **unique TCP port** per project for the dev server (do not reuse ports across projects; do not use `3333`, reserved for the dashboard).

## 1. Register the project

Create `config.json` at the **autobuilder repo root** (see [Configuration](configuration.md) and the [README](../README.md) Quick Start). Minimal example:

```json
{
  "projects": [
    {
      "name": "my-app",
      "dir": "/absolute/path/to/my-app",
      "autobuilderDir": "/absolute/path/to/my-app/.autobuilder",
      "port": 3000
    }
  ]
}
```

Use **absolute** paths. The `name` is what you pass to `--start`. Full rules (monorepos, `autobuilderDir` variants) are in the [README Quick Start](../README.md#quick-start).

## 2. Secrets and environment

Put API keys and runtime secrets in the project’s **`.env`** as usual. Autobuilder-specific layers (ports, test accounts, etc.) are covered in [Configuration](configuration.md). Never commit secrets.

## 3. Launch the daemon

From the **autobuilder repository root**:

```bash
python3 skills/build-feature/builder_loop.py --start my-app
```

Use `--executor codex` if you want Codex CLI instead of Cursor. You can also pass `--project-dir` and `--port` explicitly without `config.json` (see **Launch the daemon** in the [README](../README.md)).

Run in the background (for example `nohup ... &`) if you want it detached; otherwise it runs in the foreground.

## 4. While it runs

| Goal | Where |
|------|--------|
| High-level progress | `<project>/.autobuilder/status.md` |
| Log output | `tail -f <project>/.autobuilder/loop.log` |
| Change direction | [Steering](steering.md) — edit `spec.md`, `constraints.md`, optional `PRODUCT.md`, or write `backlog.md` |
| Stop cleanly | `touch <project>/.autobuilder/stop` |

Paths above are under your **project** directory (`dir` in `config.json`), not the autobuilder repo.

## 5. Concepts in 30 seconds

- **Initiative** — A folder with `spec.md` (and optional `constraints.md`) plus a `tasks/` directory. It defines *what* to build for that chunk of work.
- **Task** — A concrete work item (markdown file with YAML frontmatter). Tasks move from unplanned → planned → **executed**; **executed tasks are locked** — do not edit them; add new tasks instead.

Details: [Tasks and Initiatives](tasks-and-initiatives.md).

## If something goes wrong

See [Troubleshooting](troubleshooting.md).
