> The Markdown version of [build`: turn a Ready story into a pull request](build.html) on the aayudha docs site. Every page is listed in [llms.txt](../llms.txt). # `build`: turn a Ready story into a pull request A Ready story is a promise, not code, and one big unchecked change is hard to review. `build` writes the code in its own worktree, one layer at a time, checks each step, and opens a pull request. | Field | Value | |---|---| | In plain words | Writes the code for a Ready story in small checked steps, one layer at a time, and opens a pull request. | | Journey stage | [Build it](../journey-4-build.md) | | Accountable seat | [AI Native Engineer](https://github.com/rahulnakmol/agentic-ayudha/blob/de79988060cd4c1522adb9e991f78cc9e58b9a68/seats/ai-native-engineer/CHARTER.md?utm_campaign=docs-site&utm_medium=docs&utm_source=agentic-ayudha) (Nakul) | | Does the work | Nakul, the Accountable seat's twin, in the [`build`](../how-models.md) model lane, with the seat's paired human when it has one | | Consulted | [Code Architect](https://github.com/rahulnakmol/agentic-ayudha/blob/de79988060cd4c1522adb9e991f78cc9e58b9a68/seats/code-architect/CHARTER.md?utm_campaign=docs-site&utm_medium=docs&utm_source=agentic-ayudha) (Vishwa), [Production Engineer](https://github.com/rahulnakmol/agentic-ayudha/blob/de79988060cd4c1522adb9e991f78cc9e58b9a68/seats/production-engineer/CHARTER.md?utm_campaign=docs-site&utm_medium=docs&utm_source=agentic-ayudha) (Shesha) | | Informed | [Engineering Manager](https://github.com/rahulnakmol/agentic-ayudha/blob/de79988060cd4c1522adb9e991f78cc9e58b9a68/seats/engineering-manager/CHARTER.md?utm_campaign=docs-site&utm_medium=docs&utm_source=agentic-ayudha) (Drona) | | Layers it can touch | [every layer](../concepts-layers.md) | | Who reasons | your agent's own model, inside the skill | | Writes as | the bot identity (a GitHub App); without one, your identity, tagged as human fallback | | Where it runs | the `aayu` command, a skill in your agent, an MCP tool (only with `[mcp] expose_writes` on) | | The skill your agent reads | [skills/build/SKILL.md](https://github.com/rahulnakmol/agentic-ayudha/blob/de79988060cd4c1522adb9e991f78cc9e58b9a68/skills/build/SKILL.md?utm_campaign=docs-site&utm_medium=docs&utm_source=agentic-ayudha) | ## When to use it - A story or Bug is labelled `status:ready`, and you want it built. - `inspect` said `fix` on the pull request, or you moved machines: `--resume` carries on after the last checkpoint. - You want another agent's cloud to build it: `--delegate codex`, `cursor`, `claude`, `amp`, or `auto`. Not Ready yet? Make it Ready first with [`ready`](../skills/ready.md). ## Run it Ask your agent. It writes the code; `aayu` owns the worktree, the commits, the checks, and the pull request. ```text Use the build skill to build issue 42, and tell me when it reaches each checkpoint I asked to see. ``` ```sh aayu build [] ``` | Input | Required | What it does | |---|---|---| | `` | no | Ready story or bug to build; required unless --next. | | `--next` | no | The build-ready loop, with no model: ship lists the loop's own open PRs, oldest first, and changes nothing; pick blocks the loop's stale claims, then, under [build] in_flight, claims the first Ready story or bug (the current release's accepted baseline in its order, else priority, then age) and cuts its worktree. One of: `ship`, `pick`. | | `--stop` | no | Stop this build for good: move the story to status:blocked with this reason and page its owner; the lease stays until it expires. | | `--resume` | no | Resume from the last Aayudha-Checkpoint trailer. | | `--delegate` | no | Hand the story to another agent's cloud agent with the delegation brief, or sync it: its PR, inspect's findings, and follow-ups (auto picks the cheapest adequate connected one). One of: `codex`, `cursor`, `claude`, `amp`, `auto`. | | `--local` | no | With --delegate: run the receiver's CLI on this machine in an aayu worktree, with no GitHub credential; aayu commits, verifies, pushes, and opens the PR. | | `--asked` | no | The person's own words asking for this story. An agent needs them to pick up a Ready story that did not come out of grill in this session; without them build stops with a warning before taking the story. | | `--decline` | no | Decline open items of the last session review, one "\: \" a line; the reason goes into the PR's session review summary, and the merge gate's inspect still judges them. | > **Needs setup:** `aayu build 42 --delegate auto` needs the receiver's CLI, sign-in, and cloud environment. Run > `aayu install --env --verify` once; see [hand work to an agent](../guide-build.md). ## What you get back A lease on the story, so no other builder picks it up, and a worktree under `.aayudha/worktrees/`. One **checkpoint** commit per layer ([glossary](../glossary.md)), each with an `Aayudha-Checkpoint: k/N` trailer and its own `verify` run, then a pushed branch and an open pull request. **You should see** a pull request, and a comment on the story that reads like a flight log: checkpoint, layer, result, and budget used. Stuck? See [Ready problems](../troubleshooting.md#ready) or [hand-off problems](../troubleshooting.md#hand-offs). ## Gates It checks these before it acts, and stops when one fails: - **ready:** The issue is Ready and its body hash matches the Ready snapshot. - **budget:** The [budget] and [autonomy] budget limits are not exceeded. - **halt:** The repository is not halted (aayu halt). The default budget is 8 hours, 3 failed attempts, and 60 USD of metered spend. The spend limit applies only when aayudha's own model calls are pay-as-you-go (a gateway endpoint or a provider key); subscription use is not counted. Past the budget, the story moves to `status:blocked` and a person is paged. When a local receiver hits its subscription usage limit and says when it resets, the build waits for the reset and continues. With no reset time, it stops as paused (exit 4) and prints the command to run again; with a reset after the wall clock ends, the story is blocked for wall time, and `aayu ready` gives it a fresh budget. A pause is not a failed attempt, and the wall clock keeps running. ## What only a person does The registry reserves no step of this verb for a person. An agent builds only a story you asked for: otherwise it stops, asks you, and passes your words with `--asked`. After a budget stop, you run `aayu ready ` to continue. Later, a person approves and runs [`ship`](../skills/ship.md). ## What's next - The pull request is open; prove it: [`verify`](../skills/verify.md) and [`inspect`](../skills/inspect.md). - The whole flow, here or in another agent's cloud: [hand work to an agent](../guide-build.md). - [Every skill](../skills/index.md).