Skill Tracer
Skills › BMAD Method › bmod-method › monorepo-and-polyrepo.md

monorepo-and-polyrepo.md

22 lines · skills/bmod-method/help/monorepo-and-polyrepo.md at bd70c64

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Monorepo and poly repo
2
3Use this when the user asks where to install BMad and keep planning when the work spans one repository or several.
4

Monorepo and poly repo

Use this when the user asks where to install BMad and keep planning when the work spans one repository or several.

Raw lines 1 to 4
5## Monorepo
6
7Install BMad once at the repository root. `_bmad` and the output folder sit at the root, and one session reaches every package. Planning for any part of the repo goes in the same output folder.
8

Monorepo

Install BMad once at the repository root. _bmad and the output folder sit at the root, and one session reaches every package. Planning for any part of the repo goes in the same output folder.

Raw lines 5 to 8
9## Poly repo
11Work from a workspace folder that holds every project checked out side by side.
13- Install BMad at the workspace root, not inside each project. There is one `_bmad` for the whole workspace, and the user starts their AI tool from the workspace root so one session reaches the plan and every project.
14- The output folder also sits at the workspace root, outside the individual repositories. All planning goes there, because a brief, a PRD, an architecture, or an initiative usually spans several of the projects. The folder is `_bmad-output` by default and can be renamed through the `output_folder` setting.
15- Make the output folder its own git repository and commit as planning progresses, so the planning has history apart from any one project. This is recommended for a monorepo too. For what to keep in it over time, see `help/artifact-lifetime.md`.
16- For each project, recommend a bare repository with worktrees: one bare clone per project, and a worktree per branch beside it. Several branches of one project can then be open at once, and agents working in parallel do not collide in one checkout.
17- A ticket names the projects it touches. `bmad-build` runs from the workspace root and works in the project, or the worktree, the story belongs to.
18- `bmad-project-context` rules belong to each project's own `AGENTS.md`, because each repository has its own conventions. Rules that hold across all of them go in an `AGENTS.md` at the workspace root.

Poly repo

Work from a workspace folder that holds every project checked out side by side.

  • Install BMad at the workspace root, not inside each project. There is one _bmad for the whole workspace, and the user starts their AI tool from the workspace root so one session reaches the plan and every project.
  • The output folder also sits at the workspace root, outside the individual repositories. All planning goes there, because a brief, a PRD, an architecture, or an initiative usually spans several of the projects. The folder is _bmad-output by default and can be renamed through the output_folder setting.
  • Make the output folder its own git repository and commit as planning progresses, so the planning has history apart from any one project. This is recommended for a monorepo too. For what to keep in it over time, see help/artifact-lifetime.md.
  • For each project, recommend a bare repository with worktrees: one bare clone per project, and a worktree per branch beside it. Several branches of one project can then be open at once, and agents working in parallel do not collide in one checkout.
  • A ticket names the projects it touches. bmad-build runs from the workspace root and works in the project, or the worktree, the story belongs to.
  • bmad-project-context rules belong to each project's own AGENTS.md, because each repository has its own conventions. Rules that hold across all of them go in an AGENTS.md at the workspace root.
Raw lines 9 to 19
Names a skill bmad-build :17
Names a skill bmad-project-context :18
Project instruction file AGENTS.md :18
20## The active initiative
22In the method, the active initiative's folder is its part of the ticket store: its planning documents, epics, entries, and joined plans stay together; standalone tickets live in a backlog. See `help/ticketing-setup.md`. A v6 project moves to that layout with `bmad migrate method`, which asks at plan time whether the store should be its own repository, sit in a workspace, and use worktrees, and makes those repository changes before it moves any artifact.

The active initiative

In the method, the active initiative's folder is its part of the ticket store: its planning documents, epics, entries, and joined plans stay together; standalone tickets live in a backlog. See help/ticketing-setup.md. A v6 project moves to that layout with bmad migrate method, which asks at plan time whether the store should be its own repository, sit in a workspace, and use worktrees, and makes those repository changes before it moves any artifact.

Raw lines 20 to 22