> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a production app from one prompt with AI agents

> Describe an app in one message, and the Build an App workflow scopes, scaffolds, tests and reviews a Forge project you own, then serves it on your machine.

You describe an app in one message. The built-in **Build an App** workflow turns it into a [Forge](https://docs.reliantlabs.io/forge/overview.md) project with a Go API, a Postgres schema and a Next.js frontend, gets its checks green, has a separate agent review the running app, and leaves it running on your machine. The result is ordinary code in your folder that you review, commit and deploy.

The checks are Forge's own: `generate`, `lint`, `build` and `task test`. Forge derives the wiring from the proto and the migrations ([Two sources of truth](https://docs.reliantlabs.io/forge/concepts/two-sources-of-truth.md)), so the agents write the domain.

## Before you begin

* Reliant v1.21.3 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)), with a connected machine ([Run a machine from the terminal](https://docs.reliantlabs.io/cli/run-a-machine.md)).
* Go, Node.js and Docker on that machine. `reliant forge project doctor` checks them.
* A `forge` command on your `PATH`, if you will run the stack yourself afterwards; see [Troubleshooting](#troubleshooting).
* An empty folder for the project. The workflow creates the project in place.
* Model credit: a run takes tens of minutes on a flagship model, with up to six sub-agents at once. In an organization, a run asks before it moves to your own AI account (`reliant workflow funding`).

**1. Start the workflow**

In the app, open a new chat, choose **Build an App** in the workflow selector and send your description. From the terminal, `reliant workflow run` takes the built-in by its id, `forge-one-shot`:

```bash terminal theme={null}
mkdir readinglist
reliant workflow run forge-one-shot --project-path "$PWD/readinglist" \
  -i unattended=true \
  -m "A reading-list app: books with title, author and a status (want to read, reading, read). Users add books and mark them read. Keep it small: one service, one entity, plain styling."
```

```text Output theme={null}
Workflow "forge-one-shot" triggered
  Chat/Execution ID: 535b9957-6733-4d23-ae0f-17cd89cfdd06
```

In a chat, the agent may ask about the data model and the look before it writes its plan, and the run pauses after each iteration for your review. `unattended=true` says no one is there, so the agent decides instead of asking. The run is listed under **Runs** in the app.

| Input | Default | What it does |
| - | - | - |
| `model` | a flagship model | Model for every phase |
| `mode` | `auto` | `manual` asks before each tool use |
| `ask` | on | Pause for your review after each iteration |
| `unattended` | off | No human: questions resolve unanswered and the agent decides |
| `working_directory` | `.` | Where the project is created |

**2. Follow the run**

```bash terminal theme={null}
reliant workflow watch 535b9957-6733-4d23-ae0f-17cd89cfdd06
reliant workflow status 535b9957-6733-4d23-ae0f-17cd89cfdd06
```

```text Output (trimmed) theme={null}
  Status:    COMPLETED
  Outcome:   ✓ SUCCESS
  Started:   2026-11-20T09:20:08Z
  Completed: 2026-11-20T09:50:26Z

STEP EXECUTIONS  (by node thread)
    STEP                     ACTIVITY                RUNS FAILED  LAST      LAST(ms)
    test                     ExecuteRunStep             1         ok        8638
    build                    ExecuteRunStep             1         ok        21114
    lint                     ExecuteRunStep             1         ok        61697
    review-save              SaveMessage                1         ok        59
    success                  SaveMessage                1         ok        46
```

The whole build is one [Get It Right](https://docs.reliantlabs.io/guides/get-it-right.md) loop, up to 7 iterations. In each iteration the workflow's brief tells the agent to:

1. Write `FORGE_PLAN.md`: entities, fields, pages and style. The gate fails while it is missing.
2. Run `reliant forge project new --in-place`, write each entity as a `// forge:entity` proto message and run `reliant forge scaffold`.
3. Read the migrations Forge drafted and correct types, nullability, `UNIQUE` and `CHECK` constraints and foreign keys, then seed the dev database once to prove a row the schema allows is one the API accepts.
4. Bring `generate`, `lint`, `task test` and `build` green before any feature work.
5. Fan out one sub-agent per part of the app (an entity's pages, a backend concern, the dashboard), six at a time, then integrate their work and run the gate again.

The engine then runs the checks itself, and a separate reviewer starts the app and judges it; a failing check overrides a passing review. The run above passed on its first iteration, in about 30 minutes. A last step runs `reliant forge env up dev`, posts the app's link from `reliant preview-url`, and the chat becomes an ordinary agent chat.

**3. Read what it built**

The folder is a complete Forge project. From the one-sentence prompt above:

```text readinglist/ (trimmed) theme={null}
FORGE_PLAN.md                         ← the plan the agent wrote and built to
proto/services/books/v1/books.proto   ← BooksService: the five CRUD rpcs, BookStatus enum
db/migrations/…_create_books.up.sql   ← books table, CHECKs, owner index
internal/handlers/books/              ← handlers, plus tests: lifecycle, privacy, mark-as-read
frontends/web/src/app/                ← home is the reading list; books/new, view, edit
deploy/kcl/{dev,staging,prod}/        ← environments, ready to deploy
```

Every book belongs to the signed-in user, and a test checks one user cannot read another's list. A call without a token is refused:

```text ListBooks response theme={null}
{"code":"unauthenticated","message":"missing Authorization header (procedure is not on the unauthenticated allow-list)"}
```

**4. Verify it yourself**

The run leaves the app running. Stop it, then check the code with the same tools the gate used:

```bash terminal theme={null}
cd readinglist
reliant forge env down dev
go build ./...
reliant forge lint --quiet
```

```text Output theme={null}
✅ All 29 gating linters passed.
```

Start the stack and look at the seeded data:

```bash terminal theme={null}
reliant forge env up dev
reliant forge db query dev "select status, count(*) from books group by 1 order by 1"
```

```text Output (trimmed) theme={null}
│  ● api                 http://localhost:8085  up
│  ● web                 http://localhost:3000  up
status                    count
BOOK_STATUS_READ          9
BOOK_STATUS_READING       4
BOOK_STATUS_WANT_TO_READ  8
```

Open the `web` URL, and run `reliant forge env down dev` when you are done.

**5. Review and commit**

The workflow creates a git repository but commits nothing. Read `FORGE_PLAN.md` and the code, then commit. To extend it, [add a table](https://docs.reliantlabs.io/guides/forge/add-table-crud-api-pages.md) or ask in the same chat.

## What this does not do

* **It does not deploy.** The app runs on your machine only. Deploy it with [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md), or say "Deploy it." in the same chat, which is now an ordinary agent chat.
* **It does not commit or open a pull request.**
* **A pass means the checks are green and the reviewer found the plan's high-priority features working.** Lower-priority features and hardening findings (error handling, validation, tests) are recorded in the review, not required to pass.
* **The "Build an app" button on the Apps page and the home screen is something else.** It opens an ordinary agent chat with a starter prompt that asks the agent to build and deploy. Choose the workflow in the selector to get the loop on this page.

## Troubleshooting

> [accordion] Didn't Fully Pass
>
> The loop used all 7 iterations without a pass. The project stays in the folder, and the reviewer's last feedback names what is missing.

> [accordion] Stopped — External Issue
>
> The blocker was tooling or the environment, such as an app that would not start. Run `reliant forge project doctor` and `reliant forge env up dev` in the project to see it.

> [accordion] forge: not found in .forge/logs/dev/api.log
>
> The API's hot-reload config calls `forge` by name. If you only have `reliant forge`, put a two-line script named `forge` on your `PATH` that runs `exec reliant forge "$@"`, then start the stack again.

## Next steps

> [card] [Build a Go and React app by hand](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md)
>
> The same kind of project, one command at a time

> [card] [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md)
>
> Put the app on a URL

> [card] [How forge generate works](https://docs.reliantlabs.io/deep-dives/how-forge-generate-works.md)
>
> What Forge writes from the proto and the migrations

> [card] [Get It Right](https://docs.reliantlabs.io/guides/get-it-right.md)
>
> The loop this workflow runs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.