docs: add Build a Change page in plain English (#2780)

* docs: create Build a Change page and retire Quick Fixes and Build

Consolidate how-to/quick-fixes and explanation/build into the canonical
build/build-a-change page, opening with the sizing model and Where Build
Fits table and preserving the Build diagram and intent examples. Add the
Build sidebar group after Start, redirect both old routes, retarget
first-party English links and the llms.txt entry, and close the resulting
sidebar-order gaps.

* fix(docs): track Build a Change page by scoping Astro build ignore

The bare build/ gitignore rule also matched docs/build/, so the new
canonical page never entered the prior commit.

* docs: rewrite Build a Change page in plain English

Name the skill as bmad-build instead of Build, drop the duplicated
routing tables, and explain why it spends human attention on a few
checkpoints instead of a Continue slog.

.gitignore

@@ -82,10 +82,10 @@ _bmad/custom/*.user.toml
 .windsurf
 
 
-# Astro / Documentation Build
+# Astro / Documentation Build (repo-root output only — not docs/build/)
 website/.astro/
 website/dist/
-build/
+/build/
 
 # Web bundle release artifacts
 dist/web-bundles/

docs/build/build-a-change.md

@@ -0,0 +1,173 @@
+---
+title: 'Build a Change'
+description: Use bmad-build to turn a request, issue, spec, or story into implemented and reviewed code.
+sidebar:
+  order: 1
+---
+
+The core implementation skill is `bmad-build`. It takes any expression of
+what you want — a sentence, an issue, a spec, or a planned story — and asks
+questions until the goal is clear and small enough for one development
+session. Then it plans the change, implements it, reviews the result, and
+fixes the bugs it finds. See [how a run works](#run-bmad-build).
+
+## Size the Work
+
+Use the smallest amount of BMad that safely fits the change. A typical
+session is one goal: about 500 lines of code added or changed (not counting
+tests) in a small handful of files. If it fits, give it to `bmad-build`. If it
+doesn't, plan that bigger piece of work first — see
+[Choose a Development Path](../how-to/choose-a-development-path.md). You
+often cannot tell until you try; if you aren't sure, ask `bmad-help`.
+
+For a trivial edit you are willing to review yourself, skip the process
+and ask the agent to make it directly. But if a bug could escape into
+production, `bmad-build` is likely worth it.
+
+## Run `bmad-build`
+
+![bmad-build workflow diagram](/diagrams/build-diagram.png)
+
+### 1. Start a Fresh Chat
+
+Open a **fresh chat** in your AI IDE. Reusing a session from another workflow
+can mix contexts and confuse the run.
+
+### 2. Give It Your Intent
+
+You can describe the change before, with, or after the command. It does not
+have to be tidy. A ramble, a voice dump, a half-formed thought, an issue
+link, a file, or a planned story all work — anything the model can turn into
+a concrete goal.
+
+```text
+/bmad-build Fix the login validation bug that allows empty passwords.
+```
+
+```text
+/bmad-build Fix https://github.com/org/repo/issues/42.
+```
+
+```text
+/bmad-build Implement the intent in
+_bmad-output/implementation-artifacts/my-intent.md.
+```
+
+```text
+I think the problem is in the auth middleware, it's not checking token expiry.
+Let me look at it... yeah, src/auth/middleware.ts line 47 skips
+the exp check entirely. /bmad-build
+```
+
+```text
+/bmad-build
+> What would you like to do?
+Refactor UserService to use async/await instead of callbacks.
+```
+
+### 3. Clarify the Intent
+
+`bmad-build` first works with you to turn the request into one clear goal. The
+input can start rough, but before it runs on its own the goal must be small
+enough, clear enough, and free of contradictions. It uses any upstream context
+it already has and asks only about gaps it needs to implement safely.
+
+Answer those questions carefully. A wrong answer here is the most expensive
+kind of mistake to find later.
+
+### 4. Approve a Plan When Asked
+
+Once the goal is clear, `bmad-build` chooses a path. Tiny, low-risk changes go
+straight to implementation. Everything else gets a short written plan first, so
+the model has a firm boundary before it works longer without you.
+
+Approve the plan when it describes the right thing to build. Push back if it
+does not — fixing the plan is cheaper than fixing the code.
+
+### 5. Implementation and Review
+
+After that decision, `bmad-build` implements the change, reviews its own work
+with independent reviewers, fixes problems that belong to this change, and
+commits locally. This works best on a platform that can spawn subagents, or at
+least call another model from the command line and wait for a result.
+
+Review is triage, not a dump of every possible note. Issues that belong to the
+current change get fixed. Unrelated pre-existing issues get deferred. If the
+code is wrong because the plan was weak, or the plan is wrong because the goal
+was wrong, it goes back to that layer and regenerates from there instead of
+patching only the diff.
+
+### 6. Review the Result
+
+When it finishes, `bmad-build` shows you the completed change and its review
+notes. This is the main checkpoint.
+
+- Skim the diff to confirm the change matches your intent
+- If something looks off, tell the agent what to fix — it can iterate in the
+  same session
+
+Once you are satisfied, push the commit. It can offer to push and create a PR
+for you.
+
+:::caution[If Something Breaks]
+If a pushed change causes unexpected issues, use `git revert HEAD` to undo the
+last commit cleanly. Then start a fresh chat and run `bmad-build` again with a
+different approach.
+:::
+
+## What You Get
+
+- Modified source files with the change applied
+- Passing tests (if your project has a test suite)
+- A ready-to-push commit with a conventional commit message
+- An implementation record for the run, kept beside the parent spec or story
+  when there is one
+
+## Deferred Work
+
+Each run stays focused on one goal. If your request contains several independent
+goals, or review finds pre-existing issues unrelated to your change,
+`bmad-build` writes them to `deferred-work.md` in your implementation artifacts
+directory instead of trying to do everything at once.
+
+Check that file after a run — it is a backlog of follow-ups. You can feed each
+item into a fresh `bmad-build` run later.
+
+## When to Plan First
+
+Add a spec, or PRD, UX, architecture, and story planning, before running
+`bmad-build` when:
+
+- The change affects multiple systems or needs coordinated updates across many
+  files
+- You are unsure about the scope and need requirements discovery first
+- You need documentation or architectural decisions recorded for the team
+- Clarifying the intent keeps surfacing contradictions that one session cannot
+  resolve
+
+Larger work becomes a sequence of one-session changes. That sequence can change
+as implementation teaches you more. Parent specs keep the shared goal; story
+records carry decisions and completion state; integration checks and
+retrospectives cover the combined result. `bmad-build` handles one unit. It does
+not own the backlog, pick the next story, or replace those later checks.
+
+Use `bmad-build` for foundational, risky, or important stories where your
+decisions may set patterns for later work. Once those patterns are stable,
+`bmad-build-auto` can run one unit without waiting for you; see
+[Autonomous Development Loops](../reference/build-auto.md).
+
+## Why It Works This Way
+
+LLMs can see what looks important, not what actually is. Without your
+attention, the whole thing quickly falls apart.
+
+Ten minutes of inference is usually cheaper than ten seconds of your
+attention. Watching every step yourself is a slog of Continue — keep going,
+yes, proceed. That part is tedious, unnecessary, and it turns you into the
+bottleneck.
+
+`bmad-build` hands the "go on"s to the machine. It keeps your attention in a
+few places that actually need you — clarifying the goal, approving the plan,
+and reviewing the finished change — and brings you back only when it could not
+safely decide alone. That triage will sometimes be imperfect. Missing a
+low-value finding is usually better than flooding you with noise.

docs/explanation/build.md

@@ -1,132 +0,0 @@
----
-title: 'Build'
-description: Understand how the attentive Build workflow handles direct intent and planned stories.
-sidebar:
-  order: 7
----
-
-`bmad-build` is the attentive Build workflow for one coherent,
-session-sized unit of software work. It accepts anything from free-form intent
-or an issue to a fully planned story, then clarifies, plans, implements, and
-reviews that unit with as few human checkpoints as safety allows.
-
-Session-sized means that one implementation session can reasonably understand,
-implement, review, and finish the intent. It is a scope boundary, not a time
-estimate. A small change may require more planning because of its risk,
-ambiguity, or architectural reach.
-
-Invoke the `bmad-build` skill directly. Upstream planning determines the
-context Build receives; it does not require a different implementation agent.
-
-When a planned story enters Build, the story remains the product and acceptance
-context. Build creates an implementation record for the current run so
-decisions, completion state, and review findings remain traceable without
-replacing the story.
-
-![Build workflow diagram](/diagrams/build-diagram.png)
-
-## Where Build Fits
-
-Use the smallest planning path that safely produces a session-sized unit, then
-give that unit to Build.
-
-| Starting point    | What Build receives                             | What preserves the larger intent                              |
-| ----------------- | ----------------------------------------------- | ------------------------------------------------------------- |
-| Direct change     | A request, issue, or intent file                | The Build implementation record                               |
-| Spec-backed epic  | One entry from the spec folder's `stories.yaml` | `SPEC.md`, its companions, and prior story records            |
-| Full BMad project | One selected story                              | PRD, UX, architecture, epics, sprint tracking, and prior work |
-
-An obvious, low-risk edit may not need Build. An epic or project needs more
-planning around Build, but each implementation unit still uses the same workflow.
-See [Choose a Development Path](../how-to/choose-a-development-path.md) for the
-complete routing guide.
-
-## How Larger Work Reaches Build
-
-Larger intent becomes a sequence of session-sized units. That sequence can
-change as implementation produces evidence. Later stories may need to absorb a
-new constraint, reconcile a decision made by an earlier story, or be divided
-differently.
-
-The larger BMad flow reduces the risk of losing information when work is
-divided. Parent specs and planning artifacts preserve shared intent; story
-records carry decisions and completion state; integration checks judge the
-combined behavior; and retrospectives compare the whole epic with its contract.
-
-Build handles one unit in that lifecycle. It does not own the backlog, select
-the next story, coordinate several epic streams, or replace integration and
-retrospective review.
-
-## Attentive and Unattended Work
-
-Use Build for foundational, risky, or important stories where human decisions
-may establish patterns for later work. Once those patterns are stable,
-`bmad-build-auto` can execute one unit unattended. An AI coding session or
-another orchestrator, such as bmad-loop, must still select and dispatch each
-unit.
-
-Both Build workflows write story records under the same spec folder,
-so downstream integration and Retrospective can use their status regardless of
-which Build workflow produced them. See
-[Autonomous Development Loops](../reference/build-auto.md) for that contract.
-
-## Why This Exists
-
-Human-in-the-loop turns are necessary and expensive.
-
-Current LLMs still fail in predictable ways: they misread intent, fill gaps with confident guesses, drift into unrelated work, and generate noisy review output. At the same time, constant human intervention limits development velocity. Human attention is the bottleneck.
-
-`bmad-build` rebalances that tradeoff. It trusts the model to run unsupervised for longer stretches, but only after the workflow has created a strong enough boundary to make that safe.
-
-## The Core Design
-
-### 1. Compress intent first
-
-The workflow starts by having the human and the model compress the request into one coherent goal. The input can begin as a rough expression of intent, but before the workflow runs autonomously it has to become small enough, clear enough, and contradiction-free enough to execute.
-
-Intent can come in many forms: a couple of phrases, a bug tracker link, output from plan mode, text copied from a chat session, or a planned story from BMad's own epics and sprint artifacts. The workflow uses whatever upstream context exists and resolves any gaps it needs to implement safely.
-
-This workflow does not eliminate human control. It relocates it to a small number of high-value moments:
-
-- **Intent clarification** - turning a messy request into one coherent goal without hidden contradictions
-- **Spec approval** - confirming that the frozen understanding is the right thing to build
-- **Review of the final product** - the primary checkpoint, where the human decides whether the result is acceptable at the end
-
-### 2. Route to the smallest safe path
-
-Once the goal is clear, the workflow decides whether this is a true one-shot change or whether it needs the fuller path. Small, zero-blast-radius changes can go straight to implementation. Everything else goes through planning so the model has a stronger boundary before it runs longer on its own.
-
-### 3. Run longer with less supervision
-
-After that routing decision, the model can carry more of the work on its own. On the fuller path, the approved spec becomes the boundary the model executes against with less supervision, which is the whole point of the design.
-
-### 4. Diagnose failure at the right layer
-
-If the implementation is wrong because the intent was wrong, patching the code is the wrong fix. If the code is wrong because the spec was weak, patching the diff is also the wrong fix. The workflow is designed to diagnose where the failure entered the system, go back to that layer, and regenerate from there.
-
-Review findings are used to decide whether the problem came from intent, spec generation, or local implementation. Only truly local problems get patched locally.
-
-### 5. Bring the human back only when needed
-
-The intent interview is human-in-the-loop, but it is not the same kind of interruption as a recurring checkpoint. The workflow tries to keep those recurring checkpoints to a minimum. After the initial shaping of intent, the human mainly comes back when the workflow cannot safely continue without judgment and at the end, when it is time to review the result.
-
-- **Intent-gap resolution** - stepping back in when review proves the workflow could not safely infer what was meant
-
-Everything else is a candidate for longer autonomous execution. That tradeoff is deliberate. Older patterns spend more human attention on continuous supervision. Build spends more trust on the model, but saves human attention for the moments where human reasoning has the highest leverage.
-
-## Why the Review System Matters
-
-The review phase is not just there to find bugs. It is there to route correction without destroying momentum.
-
-This workflow works best on a platform that can spawn subagents, or at least invoke another LLM through the command line and wait for a result. If your platform does not support that natively, you can add a skill to do it. Context-free subagents are a cornerstone of the review design.
-
-Agentic reviews often go wrong in two ways:
-
-- They generate too many findings, forcing the human to sift through noise.
-- They derail the current change by surfacing unrelated issues and turning every run into an ad hoc cleanup project.
-
-Build addresses both by treating review as triage.
-
-Some findings belong to the current change. Some do not. If a finding is incidental rather than causally tied to the current work, the workflow can defer it instead of forcing the human to handle it immediately. That keeps the run focused and prevents random tangents from consuming the budget of attention.
-
-That triage will sometimes be imperfect. That is acceptable. It is usually better to misjudge some findings than to flood the human with thousands of low-value review comments. The system is optimizing for signal quality, not exhaustive recall.

docs/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "Checkpoint Preview"
 description: LLM-assisted human-in-the-loop review that guides you through a change from purpose to details
 sidebar:
-  order: 8
+  order: 7
 ---
 
 `bmad-checkpoint-preview` is an interactive, LLM-assisted human-in-the-loop review workflow. It walks you through a code change — from purpose and context into details — so you can make an informed decision about whether to ship, rework, or dig deeper.

docs/explanation/deep-recon.md

@@ -2,7 +2,7 @@
 title: "Deep Recon"
 description: Decision-grade research three ways — draft a prompt for your own deep-research tool, process a finished report, or run the research in place
 sidebar:
-  order: 14
+  order: 13
 ---
 
 Deep Recon researches anything you need to decide on. This page explains its three modes, how to pick between them, and what actually happens inside a native research run.

docs/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "Established Projects FAQ"
 description: Common questions about using BMad Method on established projects
 sidebar:
-  order: 12
+  order: 11
 ---
 Quick answers to common questions about working on established projects with the BMad Method (BMM).
 

docs/explanation/forge-idea.md

@@ -2,7 +2,7 @@
 title: "Forge an Idea"
 description: Pressure-test an idea through persona-driven interrogation until it hardens, proves out, or dies cheaply
 sidebar:
-  order: 13
+  order: 12
 ---
 
 Take a half-formed idea and pressure-test it now, in conversation, while changing your mind is still free.

docs/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Party Mode"
 description: Get your AI agents in one conversation — run them, build your own cast, and choose how independently they think
 sidebar:
-  order: 9
+  order: 8
 ---
 
 Party mode puts your AI agents in one room and lets them talk, to each other and to you. This page explains what a party is, the four ways it can run, how to build your own cast of personas instead of using the installed agents, and how a party remembers you between sessions.

docs/explanation/project-context-theory.md

@@ -2,7 +2,7 @@
 title: "The Theory of Project Context"
 description: Why bmad-project-context captures so little, what earns a place in a repository's agent instructions, and what is deliberately left out
 sidebar:
-  order: 11
+  order: 10
 ---
 
 `bmad-project-context` is built on an uncomfortable finding: most documentation written *for* AI agents makes them worse. This page explains the theory behind the skill — what it captures and why, and more importantly, what it deliberately refuses to capture. If you are coming from `bmad-document-project` or `bmad-generate-project-context`, the last section explains exactly what changed.

docs/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Project Context"
 description: How bmad-project-context writes a repository's agent instructions — a small verified block in AGENTS.md
 sidebar:
-  order: 10
+  order: 9
 ---
 
 `bmad-project-context` sets up a repository so AI agents work well in it. The output is a small verified block inside the repo's `AGENTS.md`: what the org requires, the commands that were actually run, the conventions where the obvious guess is wrong, and the mistakes agents keep making here.

docs/explanation/retrospective.md

@@ -2,7 +2,7 @@
 title: 'Retrospective'
 description: Close out a finished epic by reading the evidence it left — the diff, the commits, the specs — and judging the result instead of trusting memory.
 sidebar:
-  order: 15
+  order: 14
 ---
 
 Run `bmad-retrospective` directly when an epic is done. It reads what the epic

docs/explanation/sprint-planning.md

@@ -2,7 +2,7 @@
 title: "Sprint Planning"
 description: One skill owns the sprint-status artifact end to end — gate the plan, generate the tracking, view the status, repair it when it breaks — with the mechanical work done by a deterministic script.
 sidebar:
-  order: 16
+  order: 15
 ---
 
 Run `bmad-sprint-planning` at the boundary between planning and implementation. It answers three questions with one skill: is this plan actually buildable (the readiness gate), what work exists and where does it stand (`sprint-status.yaml` generation), and where are we now (the status view). It also validates and repairs the tracking file itself. Say "check implementation readiness", "run sprint planning", "show sprint status", "validate sprint status", or "fix sprint status" — the skill detects which you want.

docs/how-to/choose-a-development-path.md

@@ -70,7 +70,7 @@ existing formats.
 
 Build accepts direct intent, an issue, an intent file, an existing Build spec,
 or a planned story. It clarifies the unit, plans when needed, implements it,
-reviews the result, and records what happened. See [Build](../explanation/build.md)
+reviews the result, and records what happened. See [Build a Change](../build/build-a-change.md)
 for the implementation model.
 
 ### 4. Start Epic-Sized Work

docs/how-to/customize-bmad.md

@@ -2,7 +2,7 @@
 title: 'How to Customize BMad'
 description: Customize agents and workflows while preserving update compatibility
 sidebar:
-  order: 6
+  order: 5
 ---
 
 Tailor agent personas, inject domain context, add capabilities, and configure workflow behavior -- all without modifying installed files. Your customizations survive every update.

docs/how-to/established-projects.md

@@ -2,7 +2,7 @@
 title: 'Established Projects'
 description: How to use BMad Method on existing codebases
 sidebar:
-  order: 5
+  order: 4
 ---
 
 Use BMad Method effectively when working on existing projects and legacy codebases.
@@ -107,5 +107,5 @@ Pay close attention here to prevent reinventing the wheel or making decisions th
 
 ## More Information
 
-- **[Quick Fixes](./quick-fixes.md)** - Bug fixes and ad-hoc changes
+- **[Build a Change](../build/build-a-change.md)** - Bug fixes and ad-hoc changes
 - **[Established Projects FAQ](../explanation/established-projects-faq.md)** - Common questions about working on established projects

docs/how-to/expand-bmad-for-your-org.md

@@ -2,7 +2,7 @@
 title: 'How to Expand BMad for Your Organization'
 description: Six customization patterns that reshape BMad without forking — agent-wide rules, workflow conventions, external publishing, template swaps, agent roster changes, and advanced integration patterns
 sidebar:
-  order: 8
+  order: 7
 ---
 
 BMad's customization surface lets an organization reshape behavior without editing installed files or forking skills. This guide walks through six recipes that cover most enterprise needs.

docs/how-to/get-answers-about-bmad.md

@@ -2,7 +2,7 @@
 title: 'How to Get Answers About BMad'
 description: Use an LLM to quickly answer your own BMad questions
 sidebar:
-  order: 10
+  order: 9
 ---
 
 Use BMad's built-in help, source docs, or the community to get answers — from quickest to most thorough.

docs/how-to/pressure-test-an-idea.md

@@ -2,7 +2,7 @@
 title: "Pressure-Test an Idea"
 description: Use the bmad-forge-idea skill to harden, prove, or kill an idea before you invest in it
 sidebar:
-  order: 9
+  order: 8
 ---
 
 Use the `bmad-forge-idea` skill to put a half-formed idea under adversarial questioning. It either survives with earned conviction or dies cheaply.

docs/how-to/project-context.md

@@ -2,7 +2,7 @@
 title: 'Manage Project Context'
 description: Set up and maintain your repository's agent instructions with bmad-project-context
 sidebar:
-  order: 7
+  order: 6
 ---
 
 Use `bmad-project-context` to set up a repository so AI agents work well in it — for a new project or an existing codebase, with or without a BMad install. The output is a small verified block in your `AGENTS.md`.

docs/how-to/quick-fixes.md

@@ -1,108 +0,0 @@
----
-title: 'Quick Fixes'
-description: How to make quick fixes and ad-hoc changes
-sidebar:
-  order: 4
----
-
-Use the `bmad-build` workflow for a small targeted change that benefits from
-planning and structured review. This is the same attentive implementation
-workflow used for planned stories.
-
-## When to Use This
-
-- Bug fixes with a clear, known cause
-- Small refactorings (rename, extract, restructure) contained within a few files
-- Minor feature tweaks or configuration changes
-- Dependency updates
-
-## When to Skip This
-
-Make an obvious, low-risk edit directly when Build's planning and review would
-not add useful safety or clarity. If the work no longer fits one implementation
-session, use [Choose a Development Path](./choose-a-development-path.md) to add
-the right planning context.
-
-:::note[Prerequisites]
-
-- BMad Method installed (`npx bmad-method install`)
-- An AI-powered IDE (Claude Code, Cursor, or similar)
-  :::
-
-## Steps
-
-### 1. Start a Fresh Chat
-
-Open a **fresh chat session** in your AI IDE. Reusing a session from a previous workflow can cause context conflicts.
-
-### 2. Give It Your Intent
-
-Build accepts free-form intent — before, with, or after the invocation. Examples:
-
-```text
-/bmad-build Fix the login validation bug that allows empty passwords.
-```
-
-```text
-/bmad-build Fix https://github.com/org/repo/issues/42.
-```
-
-```text
-/bmad-build Implement the intent in
-_bmad-output/implementation-artifacts/my-intent.md.
-```
-
-```text
-I think the problem is in the auth middleware, it's not checking token expiry.
-Let me look at it... yeah, src/auth/middleware.ts line 47 skips
-the exp check entirely. /bmad-build
-```
-
-```text
-/bmad-build
-> What would you like to do?
-Refactor UserService to use async/await instead of callbacks.
-```
-
-Plain text, file paths, GitHub issue URLs, bug tracker links — anything the LLM can resolve to a concrete intent.
-
-### 3. Answer Questions and Approve
-
-Build may ask clarifying questions or present a short spec for your approval before implementing. Answer its questions and approve when you're satisfied with the plan.
-
-### 4. Review and Push
-
-Build implements the change, reviews its own work, patches issues, and commits locally. When it's done, it shows you the review spec.
-
-- Skim the diff to confirm the change matches your intent
-- If something looks off, tell the agent what to fix — it can iterate in the same session
-
-Once satisfied, push the commit. Build will offer to push and create a PR for you.
-
-:::caution[If Something Breaks]
-If a pushed change causes unexpected issues, use `git revert HEAD` to undo the last commit cleanly. Then start a fresh chat and run Build again to try a different approach.
-:::
-
-## What You Get
-
-- Modified source files with the fix or refactoring applied
-- Passing tests (if your project has a test suite)
-- A ready-to-push commit with a conventional commit message
-
-## Deferred Work
-
-Build keeps each run focused on a single goal. If your request contains multiple independent goals, or if the review surfaces pre-existing issues unrelated to your change, Build defers them to a file (`deferred-work.md` in your implementation artifacts directory) rather than trying to tackle everything at once.
-
-Check this file after a run — it's your backlog of things to come back to. Each deferred item can be fed into a fresh Build run later.
-
-## When to Add Formal Planning
-
-Before running the same Build implementation loop, consider adding PRD, UX, architecture, or story planning when:
-
-- The change affects multiple systems or requires coordinated updates across many files
-- You are unsure about the scope and need requirements discovery first
-- You need documentation or architectural decisions recorded for the team
-
-See [Choose a Development Path](./choose-a-development-path.md) for the
-epic-sized and project-sized paths, or [Build](../explanation/build.md) for how
-direct intent and planned work use the same Build workflow.

docs/index.md

@@ -34,7 +34,7 @@ complete routing guide, from a trivial edit to a multi-epic project.
 empty project.
 
 **You know exactly what needs to change, and it is small.**
-Run `bmad-build` and describe the change. See [Quick Fixes](./how-to/quick-fixes.md).
+Run `bmad-build` and describe the change. See [Build a Change](./build/build-a-change.md).
 
 **You are working in an existing codebase.**
 Consider running `bmad-project-context`, then build as usual. See

docs/reference/build-auto.md

@@ -6,7 +6,7 @@ sidebar:
 ---
 
 `bmad-build-auto` is the unattended worker for one session-sized unit in the
-canonical [Build](../explanation/build.md) implementation model. One invocation
+canonical [Build a Change](../build/build-a-change.md) implementation model. One invocation
 clarifies, plans, implements, and reviews one intent or story, then exposes a
 terminal status that a human or orchestrator can act on.
 

tools/build-docs.mjs

@@ -165,7 +165,7 @@ function generateLlmsTxt(outputDir) {
     '',
     '## Core Concepts',
     '',
-    `- **[Build](${siteUrl}/explanation/build/)** - Canonical implementation workflow for direct intent and fully planned work`,
+    `- **[Build a Change](${siteUrl}/build/build-a-change/)** - Canonical implementation workflow for direct intent and fully planned work`,
     `- **[Party Mode](${siteUrl}/explanation/party-mode/)** - Multi-agent collaboration`,
     `- **[Workflow Map](${siteUrl}/reference/workflow-map/)** - Visual overview of phases and workflows`,
     '',

tools/validate-published-implementation-model.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const CANONICAL_LLMS_ENTRY = '**[Build]';
+const CANONICAL_LLMS_ENTRY = '**[Build a Change]';
 const CANONICAL_LLMS_DESCRIPTION = 'Canonical implementation workflow for direct intent and fully planned work';
 
 const FORBIDDEN_TERMS = [

website/astro.config.mjs

@@ -20,6 +20,8 @@ export default defineConfig({
     '/how-to/install-bmad': `${basePath}start/install-bmad/`,
     '/how-to/non-interactive-installation': `${basePath}start/install-bmad/`,
     '/tutorials/getting-started': `${basePath}start/build-your-first-change/`,
+    '/how-to/quick-fixes': `${basePath}build/build-a-change/`,
+    '/explanation/build': `${basePath}build/build-a-change/`,
     '/fr/how-to/non-interactive-installation': `${basePath}fr/how-to/install-bmad/`,
     '/cs/how-to/non-interactive-installation': `${basePath}cs/how-to/install-bmad/`,
     '/vi-vn/how-to/non-interactive-installation': `${basePath}vi-vn/how-to/install-bmad/`,
@@ -128,6 +130,23 @@ export default defineConfig({
             },
           ],
         },
+        {
+          label: 'Build',
+          translations: { 'vi-VN': 'Xây dựng', 'zh-CN': '构建', 'fr-FR': 'Construire', 'cs-CZ': 'Sestavit' },
+          collapsed: false,
+          items: [
+            {
+              label: 'Build a Change',
+              translations: {
+                'vi-VN': 'Xây dựng một thay đổi',
+                'zh-CN': '构建一个变更',
+                'fr-FR': 'Construire un changement',
+                'cs-CZ': 'Sestavit změnu',
+              },
+              slug: 'build/build-a-change',
+            },
+          ],
+        },
         {
           label: 'Tutorials',
           translations: { 'vi-VN': 'Hướng dẫn nhập môn', 'zh-CN': '教程', 'fr-FR': 'Tutoriels', 'cs-CZ': 'Tutoriály' },