Cursor rule

1---
2description: 'BMAD tool/output split and per-app artifact convention for Middle Earth'
3globs:
4  - '_bmad/**'
5  - '_bmad-output/**'
6  - 'apps/*/_bmad-output/**'
7alwaysApply: false
8---
9 
10# BMAD in Middle Earth
11 
12BMAD 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/`.
13 
14## The split: tool vs output
15 
16**Per-machine (installer scaffolding, reinstalled by each dev):**
17 
18- `_bmad/*` — agents, workflows, expansion packs (`bmm`, `bmb`, `cis`, `core`, `tea`), generated config (`config.yaml`, `config.user.toml`).
19- `.claude/skills/bmad-*/` — skill copies the BMAD installer writes; not authored by hand.
20 
21**Team-shared (the canal of context — this is what is committed):**
22 
23- `_bmad/custom/` — exception inside the scaffolding. Team-built customizations land here and survive a reinstall.
24- `_bmad-output/` (root) — monorepo/infra-wide artifacts only (cross-app brainstorms, charter).
25- `apps/<app>/_bmad-output/` — same structure, scoped to one app. App-level work belongs here, **never** at the root.
26 
27Inside any `_bmad-output/` you get the same five buckets:
28 
29- `project-context.md` — living summary; the entrypoint for any human or agent ramping into the scope.
30- `brainstorming/` — exploratory sessions (one dated MD per session).
31- `planning-artifacts/` — PRDs, briefs, charter, editorial passes.
32- `implementation-artifacts/` — stories, plans, dev specs (`<epic>-<story>-<slug>.md`).
33- `research/`, `notes/` — supporting material.
34 
35## Onboarding flow
36 
371. Ensure `_bmad/` is installed on your machine (BMAD installer).
382. 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).
393. Check `apps/<app>/_bmad-output/implementation-artifacts/` for the active story before writing code.
404. When you finish, regenerate `project-context.md` via `bmad-generate-project-context` if the scope shifted, and commit new artifacts.
41 
42## Commit convention
43 
44Middle 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.
45 
46## Pitfalls
47 
48- **Editing under `_bmad/`** outside `_bmad/custom/` — wiped on the next reinstall.
49- **Artifacts at the wrong level** — app work goes in `apps/<app>/_bmad-output/`, not the root.
50- **Stale `project-context.md`** — regenerate when an epic ships or the stack changes; stale context misleads every later BMAD session.
51- **Real data** — never commit real PII / real person names into BMAD artifacts (org-wide rule; `cspell` runs in pre-commit).
52