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
- 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 installin 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, runnpx skills add bmad-code-org/BMAD-METHOD/skills/core-tools --skill '*'and thennpx skills add bmad-code-org/BMAD-METHOD/skills/method --skill '*'— core tools first, because they hold thebmadskill every install needs. The full install steps are on the BMad README. On v7, confirm the skill your install offers isbmad-project-context, not the deprecatedbmad-document-project; if you see the older name, update the install before continuing. On v7, ask forbmad statusto check versions and see what to run next. - 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. - 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.
- 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.
- 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.
- 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
- Check the project-context block in
AGENTS.mdagainst the repository itself: build commands, test commands, and directory structure must match what is actually there. - Check that the change follows a convention the codebase already uses. A new pattern introduced by one change, with no existing example, is a design decision to raise, not a detail to let through.
- Check that the project's tests were run after the change, on the branch, and that failures were fixed rather than skipped.
- Check that each slice in a multi-session job names the epic requirement it satisfies. A slice with no requirement behind it is work the epic never asked for.
- Check that no greenfield planning document was used as a source for the build. If the build cites a PRD the code never matched, the source is wrong, not the code.
What can go wrong
- Building before mapping. The build skill without a project-context block works from the chat's description of the codebase, which is a guess. The mapping step exists so the build works from the repository.
- Trusting the map without reading it. The project-context skill drafts its findings. An unchecked error — a wrong build command, a misread directory — sends every later step down the wrong path.
- Using the deprecated document-project skill. The older skill is deprecated in favour of project-context. An out-of-date install produces a different document shape, and later skills will not find what they expect.
- Letting a greenfield PRD steer an inherited codebase. A plan written before the code existed describes a product that was never built. Archive it out of reach, or the build follows the plan and breaks the code.
- Writing an epic for a one-sitting change. The epic ceremony costs more than the change. Size the job first; the lightest path that fits is the right one.
Limits
- This workflow maps and builds on code that exists. It does not audit the codebase for security problems, and it does not decide whether the inherited code should be kept at all.
- The project-context skill describes the repository as it finds it. A repository with no tests, no build documentation, and no consistent conventions gives the skill little to work with, and the map will show that honestly.
- BMad v7 is a preview release. Skill names and commands can move between preview releases; the README for the version you installed is the authority when this page and the installed skill disagree.
Related playbooks
- Document a codebase so a stranger can work in it
- Onboard onto an unfamiliar codebase with an agent
- 180M repos: most agent work is unattributed
- Check for planted instruction files before you start an agent in a folder you did not fill yourself
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