Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

Playbooks · Coding tasks

Start work on a codebase you inherited without breaking what already works

Written October 28, 2026

For a developer handed a codebase they did not write: BMad is a method of agent skills for planning and building software. A skill is a reusable pack of instructions that teaches the agent how to do one job. Map the project before building anything, so a first change ships without breaking what already works. Building first, from a guess about how the code works, breaks behavior nobody knew to protect.

Before you start

You need the repository checked out, its tests runnable, and a branch to work on. BMad is a method of agent skills for the full software development lifecycle, and its documentation states the method works from a new idea or from an inherited codebase. The inherited-codebase path starts from the opposite end to a greenfield build (a build started from scratch): instead of writing requirements first and code second, it maps what exists first and builds from what the map shows.

The mapping step is a skill called bmad-project-context, which reads the repository's existing instructions, checks them, and writes a small verified block of project instructions into AGENTS.md. The block holds only what is expensive to rediscover — it does not repeat repo overviews, directory trees or tech-stack lists. An earlier skill with a similar name, bmad-document-project, is deprecated; if the skill your install offers is the older name, your install is out of date and the mapping step will not behave as described here. The project-context skill is the one to use. If the repository already has an AGENTS.md, CLAUDE.md or editor rules someone keeps current, skip this step: skipping it does not fail a build, and the skill's own guidance is to run it only when the instructions are missing, stale, or of unknown quality.

Size the job before you pick a path. A change that fits in one sitting goes straight to the build skill. A job that spans several sessions goes through the product-owner skill, which writes epic requirements and slices — an epic is a large job split into slices, and each slice is one session's work. A job large enough to need planning documents goes through the full planning path, starting with a PRD (product requirements document). Picking the heaviest path for the smallest job is the most common way this goes wrong: a one-line fix does not need an epic.

What "done" looks like

At the end of one sitting you have a project-context block in AGENTS.md that you have read and corrected, or the repository's current instructions you chose to keep, one change built and tested on a branch, and — only if the job spans sessions — an epic with slices that the next session can pick up without re-reading the whole repository. The repository's existing tests pass, and nothing was built from a guess about how the code works.

Steps

  1. Install BMad and confirm the project-context skill is present. The stable release is v6.12; v7 is a preview with a different install path. For v6.12, with Node.js 20.12+, Python 3.10+ and uv installed, run npx bmad-method install in your project; both install routes need uv. For the v7 preview, with Node.js and npm plus Git and a coding tool that supports skills, run npx skills add bmad-code-org/BMAD-METHOD/skills/core-tools --skill '*' and then npx skills add bmad-code-org/BMAD-METHOD/skills/method --skill '*' — core tools first, because they hold the bmad skill every install needs. The full install steps are on the BMad README. On v7, confirm the skill your install offers is bmad-project-context, not the deprecated bmad-document-project; if you see the older name, update the install before continuing. On v7, ask for bmad status to check versions and see what to run next.
  2. Run the project-context skill, then read what it wrote. The skill reads the repository's existing instructions and checks them, then writes a small block into AGENTS.md, between <!-- bmad:context --> markers: the rules, corrections and caveats that are expensive to rediscover, not an overview of the project. You see the complete block before anything is written, and nothing is written until you approve it. Read that block line by line. The skill's block is a draft, not a survey: correct anything it got wrong, delete anything it invented, and add the one fact only you know — for example, which parts of the codebase are frozen, or which test suite is flaky and routinely ignored. Later steps build from this block, so an error here compounds through the whole job. If you skipped this step because the repository's instructions are already current, later steps build from those instructions instead.
  3. Size the job and pick the lightest path that fits. One change, one sitting: go to the build skill in step 4. Several sessions with a natural order: ask the product-owner skill to write epic requirements and slices from the project context, then build one slice per session. A larger effort that needs agreement on scope first: go through the planning path, starting with the PRD skill. Do not write an epic for a one-sitting change, and do not start a multi-session job without slices: the first wastes a sitting, the second wastes every sitting after the first.
  4. For a small change, build directly from the project context. The build skill takes your change description plus any code examples, and works from what the project-context block says about the codebase. It follows the conventions it finds in the code rather than importing conventions from elsewhere: the codebase's own patterns win. Run the project's tests after the change, on the branch, before anything else. A change that passes the project's own tests and follows its own conventions is done; a change that needs a convention the codebase does not use is a design discussion, not a build step.
  5. For a multi-session job, build one slice at a time and close with a retrospective. The product-owner skill writes the epic requirements and slices; each slice is built in its own session, against the tests. When the last slice lands, run the retrospective skill, which reviews the finished epic against its requirements and records what the next epic should carry forward. The retrospective is the step that stops the next epic from re-learning what this one discovered about the codebase.
  6. Keep greenfield documents out of the build's reach. If the repository also contains planning documents from a from-scratch build — a PRD, an architecture document written before the code existed — archive them where the build skill cannot see them, or the build will follow the plan instead of the code. BMad's guidance is explicit on this: architecture work must use the documented architecture files and a scan of the codebase as it is, not a plan written for code that was never built. When the plan and the code disagree, the code is the truth and the plan is the document to fix.

Check the agent's work

What can go wrong

Limits

Related playbooks

Sources

Sources: BMAD-METHOD README, Start in an Existing Codebase — BMad docs, Set and Maintain Project Context — BMad docs, Choose a Planning Path — BMad docs.

Back to: Coding playbooks hub · Also: BMad skill page · Agree what to build before building it: write a short product requirements document with BMad