---
description: 'BMAD tool/output split and per-app artifact convention for Middle Earth'
globs:
  - '_bmad/**'
  - '_bmad-output/**'
  - 'apps/*/_bmad-output/**'
alwaysApply: false
---

# BMAD in Middle Earth

BMAD is how planning, drafting, and shipping work is captured. The split between **tool** and **output** is deliberate — read this before touching anything under `_bmad/` or `_bmad-output/`.

## The split: tool vs output

**Per-machine (installer scaffolding, reinstalled by each dev):**

- `_bmad/*` — agents, workflows, expansion packs (`bmm`, `bmb`, `cis`, `core`, `tea`), generated config (`config.yaml`, `config.user.toml`).
- `.claude/skills/bmad-*/` — skill copies the BMAD installer writes; not authored by hand.

**Team-shared (the canal of context — this is what is committed):**

- `_bmad/custom/` — exception inside the scaffolding. Team-built customizations land here and survive a reinstall.
- `_bmad-output/` (root) — monorepo/infra-wide artifacts only (cross-app brainstorms, charter).
- `apps/<app>/_bmad-output/` — same structure, scoped to one app. App-level work belongs here, **never** at the root.

Inside any `_bmad-output/` you get the same five buckets:

- `project-context.md` — living summary; the entrypoint for any human or agent ramping into the scope.
- `brainstorming/` — exploratory sessions (one dated MD per session).
- `planning-artifacts/` — PRDs, briefs, charter, editorial passes.
- `implementation-artifacts/` — stories, plans, dev specs (`<epic>-<story>-<slug>.md`).
- `research/`, `notes/` — supporting material.

## Onboarding flow

1. Ensure `_bmad/` is installed on your machine (BMAD installer).
2. Read `apps/<app>/_bmad-output/project-context.md` for the app you'll touch (and root `_bmad-output/project-context.md` if it exists, for the monorepo picture).
3. Check `apps/<app>/_bmad-output/implementation-artifacts/` for the active story before writing code.
4. When you finish, regenerate `project-context.md` via `bmad-generate-project-context` if the scope shifted, and commit new artifacts.

## Commit convention

Middle Earth commitlint enforces `scope-enum` = `config | lib | news-digest | release` (see `commitlint.config.mjs` — this is the source of truth; the prose in `CLAUDE.md` is inaccurate). There is no `bmad` or `ai` scope. Commit BMAD artifacts under the matching app scope when app-scoped (e.g. `docs(news-digest): ...`), or `docs(config)` for repo-wide AI/config changes, until/unless a dedicated scope is added.

## Pitfalls

- **Editing under `_bmad/`** outside `_bmad/custom/` — wiped on the next reinstall.
- **Artifacts at the wrong level** — app work goes in `apps/<app>/_bmad-output/`, not the root.
- **Stale `project-context.md`** — regenerate when an epic ships or the stack changes; stale context misleads every later BMAD session.
- **Real data** — never commit real PII / real person names into BMAD artifacts (org-wide rule; `cspell` runs in pre-commit).