Building a small site with AI agents and BMAD: what the paperwork bought

Letting an AI agent write a whole project is easy to start and hard to judge afterwards. The useful question is not whether the code works, but which parts of the process left a record you can still trust six months later. This post looks back at a small website I built with coding agents following the BMAD Method, version 6 as of April 2026. In that version it is a workflow that walks the agent from brainstorming to a PRD, an architecture, epics and stories, then implements and reviews each story. At the end is a small orchestrator I later wrote to run that loop without me.

The site is a static catalogue for a small furniture workshop: Astro, with a Git-based CMS so the owner can add products without touching code. The planning took two days in April 2026, the implementation four. Everything below comes from the files the process left in the repository, not from memory.

What the planning phase produced

BMAD runs as a series of agent "workflows", each writing a Markdown file that the next one reads. For this site, that was:

About 40,500 words (counted with wc -w), plus a market research document, for a site with 31 stories across 8 epics. The readiness report, an agent checking that every PRD requirement maps to an epic and that the UX spec and architecture agree, ended with a pass.

That is a lot of text for a catalogue site, and most of it was never read again by a human. The two files that kept earning their place were the shortest ones: the project context and the individual story files.

The project context file was the most useful page

project-context.md is a list of rules written for the agents, not for people: 95 of them, grouped into stack, language, framework, testing, code style, workflow and a "don't miss" list. They are the details an agent would otherwise get wrong because its training data disagrees:

- **Framework:** Astro 6 (SSG-only — no runtime backend, no SSR, no API routes)
- **Content Validation:** Zod 4 (NOT Zod 3 — breaking API differences) schemas in `content.config.ts`
- **Interactive Islands:** Svelte (only ImageGallery component, ~4KB JS — zero-JS-by-default principle)

22 of the 31 story files cite it as a source in their Dev Notes. This is the same idea as an AGENTS.md file: a short list of decisions that are not obvious from the code beats a long document that explains them. "Zod 4, not Zod 3" prevents a class of mistakes in one line; the architecture document's discussion of why does not.

Story files carried context from one story to the next

Each story file has the same shape: the user story, acceptance criteria, tasks, then Dev Notes written when the story is created, then a record the implementing agent fills in. Two sections in the Dev Notes did most of the work:

• "Previous Story Intelligence": what earlier stories in the epic had established, so the agent does not re-derive or contradict it. The deployment story, for example, opens with a section reconciling itself with the server setup story before it.
• "Anti-Patterns": what not to do in this story, stated bluntly.

Because each story starts a fresh agent session, these notes are the agent's only memory. They are also the best documentation the project has: a year from now, the story file explains why a component exists better than the code does.

The cost is that the history lives there and not in git. 19 of the 56 commits made that April are titled feat: story, most of them in a row. git log says nothing; you have to know which story file to open.

Review caught real bugs

After implementing a story, a separate review workflow reads the diff and writes findings back into the story file, ranked high, medium or low. The format varies from story to story (checklists, tables, "Fixed N issues" lines) and not every story has a review section. So I won't give an exact total: across the stories there were dozens of findings, most of them fixed. Some were style, but some were bugs that would have reached production:

• Open Graph and JSON-LD image URLs built with a doubled ./ path, so shared links and structured data pointed at images that did not exist.
• A race condition in the image lightbox, fixed by replacing a requestAnimationFrame workaround with Svelte's $effect.
• Category labels duplicated in three components, one of which the first fix missed and a second review round caught.

A review in a separate session, with no memory of writing the code, finds different things than the author. That held for agents as much as for people.

Deferred findings became permanent

The review checklist also has an escape hatch: an item can be deferred, usually because fixing it is out of the story's scope. About a dozen items ended up deferred or explicitly left unfixed. The most important one was ranked high (shortened from the story file, which mixes Vietnamese and English):

Migrate images schema z.string() → z.image() to enable Astro <Image> component, responsive srcset, WebP/AVIF conversion, LQIP blur. (Breaking change, deferred to dedicated story.)

The dedicated story was never created. The project context I approved promises build-time WebP/AVIF, responsive srcset and blurred placeholders, while the schema I shipped declares images as z.string(), so that promise is still waiting for its story. It is the first item on the plan for the site's next stage. A deferral moves the decision out of the story, and nothing in the process brings it back unless someone turns deferrals into stories.

The same thing happened at a larger scale. Every epic ends with an optional retrospective. I skipped all eight, and they are still marked optional in the sprint file, so the lessons of one epic never fed into the next.

The plan changed, and the documents did not

Two parts of the architecture did not survive contact with the real setup:

• CMS sign-in changed approach during implementation, once it turned out the CMS's GitHub backend needed its own OAuth flow. The story file for the original approach is marked done; the project context still describes it.
• Deployment was designed as a pipeline of its own for this one site. Six months later I moved it to the same CI-built images as my other projects, and the stories describing the original pipeline still read as current.

Neither change is a failure of the agents. Plans change. But 40,500 words of planning are only an asset while they are true, and the process has no step that updates them afterwards. Planning documents written by agents age exactly like ones written by people, just faster, because there are more of them.

Running the loop without me

For a later project, a local-first time management app, I wrote a small orchestrator that reads the sprint status file and runs the next workflow for each story through the opencode CLI (shortened):

const DISPATCH: Record<string, Action> = {
  backlog: { name: "create-story", prompt: (k) => `load skill bmad-create-story and create story for ${k} from epics` },
  "ready-for-dev": { name: "dev-story", prompt: (k) => `load skill bmad-dev-story and implement story ${k} from its story file ...` },
  // "in-progress" resumes the same story
  review: {
    name: "review",
    prompt: (k) => `load skill bmad-code-review and review story ${k}. YOLO MODE: set yolo=true. ... Do not HALT or wait for user input. Auto-apply all patches. Auto-resolve decision-needed to defer. ...`,
  },
};

Each run has a one-hour timeout, and a run that exits without moving the story's status forward is marked failed and not retried. The config has a maxRetry setting, but nothing reads it yet. That last rule matters: an agent can report that it finished without having done the work, and the status file is a check it cannot talk its way past.

The review prompt shows the trade-off clearly. To run unattended, the review must never stop and ask, so every decision that needs a person is resolved as "defer". Automation removes the human from exactly the decisions that need one. The open list from the first project shows where those decisions end up: in a checklist nobody reopens.

What I would keep, and what I would change

• Keep the project context file, and keep it short. It is the cheapest, most effective part.
• Keep story files with "previous story" notes. They are the agent's memory and the project's documentation.
• Keep a separate review pass. It found bugs the implementing session did not.
• Change deferrals into stories automatically, or fail the epic while high-ranked items are open.
• Change commit messages to name the story key, so git log and the story files point at each other.
• Cut the planning to what will be read again. For a site this size I would start with the PRD and the epics, and write the 9,900-word UX specification only if stories kept needing it.

Summary

If you have run agents through a structured workflow like this, I'd love to compare notes on what you kept and what you dropped. My email is on the home page.