|
| 1 | +# Game-Dev Studio Sync Plan — 2026-04-14 |
| 2 | + |
| 3 | +Syncing `bmad-module-game-dev-studio` against `bmad-code-org/BMAD-METHOD@main` (`6b964acd`, post-v6.3.0). |
| 4 | + |
| 5 | +## Architectural guardrail — DO NOT touch |
| 6 | + |
| 7 | +Upstream lives under `src/bmm-skills/{1-analysis,2-plan-workflows,3-solutioning,4-implementation}/` plus `src/core-skills/`. Game-dev lives under `src/workflows/{1-preproduction,2-design,3-technical,4-production,gametest,gds-quick-flow,gds-document-project}/` plus `src/agents/` and `src/gametest/`. |
| 8 | + |
| 9 | +**This sync preserves game-dev's top-level organization.** We port *content and skill-directory shape* within the existing tree; we do not relocate into `src/bmm-skills/`. |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Decisions locked in 2026-04-14 |
| 14 | + |
| 15 | +**Agents (Phase 4 mirror):** Merge `gds-agent-game-qa` and `gds-agent-game-scrum-master` into `gds-agent-game-dev`. Upstream collapsed to a single Developer agent (commits `48c2324b` / `003c979d`) — Phase 4 of game-dev will follow. Phases 1–3 agents (designer, architect, solo-dev, tech-writer) remain distinct. |
| 16 | + |
| 17 | +**quick-dev:** Delete `gds-quick-dev` and `gds-quick-spec` entirely. Port upstream `bmad-quick-dev` 1:1 as the replacement. No chain, no overlap-preservation. |
| 18 | + |
| 19 | +**gametest relocation:** Move `src/gametest/` (the knowledge base + `qa-index.csv`) into `src/agents/gds-agent-game-dev/gametest/`. Reason: `_bmad-output/` is being deprecated as a runtime location; knowledge the dev agent uses should live with the dev agent. `src/workflows/gametest/` (the 7 test workflows) stays where it is. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## Phase 1 — quick-dev full replacement + quick-flow cleanup |
| 24 | + |
| 25 | +### Scope |
| 26 | + |
| 27 | +- **Delete** `src/workflows/gds-quick-flow/gds-quick-dev/` (all current content — divergent enough that no salvage is useful) |
| 28 | +- **Delete** `src/workflows/gds-quick-flow/gds-quick-spec/` (redundant once upstream's bmad-quick-dev is ported; upstream absorbs spec generation into `step-02-plan`) |
| 29 | +- **Delete** `src/workflows/gds-quick-flow/gds-quick-dev-new-preview/` (already-approved cleanup) |
| 30 | +- **Port** upstream `bmad-quick-dev` 1:1 to a new `src/workflows/gds-quick-flow/gds-quick-dev/` |
| 31 | + |
| 32 | +### Upstream source |
| 33 | + |
| 34 | +`src/bmm-skills/4-implementation/bmad-quick-dev/` — 11 files, flat layout: |
| 35 | +- `SKILL.md`, `workflow.md`, `spec-template.md`, `step-oneshot.md` |
| 36 | +- `step-01-clarify-and-route.md`, `step-02-plan.md`, `step-03-implement.md`, `step-04-review.md`, `step-05-present.md` |
| 37 | +- `compile-epic-context.md`, `sync-sprint-status.md` |
| 38 | + |
| 39 | +### Adaptation work during port |
| 40 | + |
| 41 | +Copy upstream files as-is, then rewrite references for game-dev context: |
| 42 | +- `_bmad/bmm/` → `_bmad/gds/` config paths |
| 43 | +- `bmad-agent-dev` → `gds-agent-game-dev` |
| 44 | +- Any `{module_root}` resolutions to point at game-dev module structure |
| 45 | +- Preserve upstream step names, structure, and framing ("hardened, reviewable artifact") |
| 46 | + |
| 47 | +After port, verify `gds-quick-flow/` only contains the new `gds-quick-dev/`. The flow folder may eventually collapse to just the skill itself — flag in `TODO.md` if it does. |
| 48 | + |
| 49 | +### Phase 1 verification |
| 50 | + |
| 51 | +- `npm run lint:md` clean |
| 52 | +- `gds-quick-dev` resolves via installer (manual `npx bmad-method install` smoke test) |
| 53 | +- Grep confirms zero refs to `gds-quick-spec` or `gds-quick-dev-new-preview` remain in `src/` |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## Phase 2 — PRD + GDD skill split |
| 58 | + |
| 59 | +### Upstream shape |
| 60 | + |
| 61 | +``` |
| 62 | +src/bmm-skills/2-plan-workflows/ |
| 63 | +├── bmad-create-prd/ (SKILL.md, workflow.md, steps-c/, data/, templates/) |
| 64 | +├── bmad-edit-prd/ (SKILL.md, workflow.md, steps-e/, data/prd-purpose.md) ← NEW data file |
| 65 | +└── bmad-validate-prd/ (SKILL.md, workflow.md, steps-v/) |
| 66 | +``` |
| 67 | + |
| 68 | +`bmad-edit-prd` just gained new step files (`step-e-01-discovery.md`, `step-e-01b-legacy-conversion.md`, `step-e-02-review.md`, `step-e-03-edit.md`, `step-e-04-complete.md`) and a new `data/prd-purpose.md` reference. Upstream `bmad-create-prd/steps-c/step-08-scoping.md` and `step-11-polish.md` also changed. |
| 69 | + |
| 70 | +### Game-dev current shape |
| 71 | + |
| 72 | +**PRD is consolidated** at `src/workflows/2-design/create-prd/`: |
| 73 | +``` |
| 74 | +create-prd/ |
| 75 | +├── bmad-skill-manifest.yaml (no SKILL.md!) |
| 76 | +├── data/, templates/ |
| 77 | +├── steps-c/, steps-e/, steps-v/ |
| 78 | +├── workflow-create-prd.md |
| 79 | +├── workflow-edit-prd.md |
| 80 | +└── workflow-validate-prd.md |
| 81 | +``` |
| 82 | + |
| 83 | +**GDD is a single skill** at `src/workflows/2-design/gds-create-gdd/` with `steps/` (14 step files) — no edit or validate variant. |
| 84 | + |
| 85 | +### Plan |
| 86 | + |
| 87 | +**2a. Split PRD into 3 skill dirs:** |
| 88 | + |
| 89 | +``` |
| 90 | +src/workflows/2-design/ |
| 91 | +├── gds-create-prd/ (from workflow-create-prd.md + steps-c/ + shared data/templates) |
| 92 | +├── gds-edit-prd/ (from workflow-edit-prd.md + steps-e/; port upstream step-e-* updates + prd-purpose.md) |
| 93 | +└── gds-validate-prd/ (from workflow-validate-prd.md + steps-v/) |
| 94 | +``` |
| 95 | + |
| 96 | +Each gets `SKILL.md` + `bmad-skill-manifest.yaml`. Shared `data/` and `templates/` stay deduplicated where possible (symlink or copy-with-note). |
| 97 | + |
| 98 | +**2b. Mirror the same split for GDD** (user-approved — "GDD is used as PRD by default in gds"): |
| 99 | + |
| 100 | +``` |
| 101 | +src/workflows/2-design/ |
| 102 | +├── gds-create-gdd/ (existing, rename steps/ → steps-c/ for consistency) |
| 103 | +├── gds-edit-gdd/ (NEW — model on gds-edit-prd; port step-e pattern, adapt to game-design content) |
| 104 | +└── gds-validate-gdd/ (NEW — model on gds-validate-prd; adapt AC and quality checks to GDD structure) |
| 105 | +``` |
| 106 | + |
| 107 | +This is the **biggest net-new content** in the sync. `gds-edit-gdd` and `gds-validate-gdd` do not exist today. |
| 108 | + |
| 109 | +**2c. Port upstream content changes:** |
| 110 | +- `bmad-create-prd/steps-c/step-08-scoping.md` (93 line change) and `step-11-polish.md` → into `gds-create-prd/steps-c/` equivalents |
| 111 | +- `bmad-edit-prd/data/prd-purpose.md` (197 new lines) → into `gds-edit-prd/data/` (and optionally `gds-edit-gdd/data/gdd-purpose.md` as a parallel) |
| 112 | +- All `step-e-*` file updates → `gds-edit-prd/steps-e/` |
| 113 | + |
| 114 | +### Phase 2 verification |
| 115 | + |
| 116 | +- All three PRD skills resolve via installer |
| 117 | +- GDD edit + validate stubs compile (OK if step bodies are initially lean — flag in `TODO.md`) |
| 118 | + |
| 119 | +--- |
| 120 | + |
| 121 | +## Phase 2.5 — Agent merge + gametest relocation |
| 122 | + |
| 123 | +### Agent merge |
| 124 | + |
| 125 | +Goal: mirror upstream's single-Developer-agent model for Phase 4 roles. |
| 126 | + |
| 127 | +1. **Capabilities audit** — read: |
| 128 | + - `src/agents/gds-agent-game-qa/SKILL.md` (Quinn-equivalent; owns QA knowledge lookup) |
| 129 | + - `src/agents/gds-agent-game-scrum-master/SKILL.md` (Bob-equivalent; owns sprint/story ceremony) |
| 130 | + - Upstream `bmad-agent-dev/SKILL.md` post-merge (shows how QA was absorbed — party-mode and generate-e2e-tests references preserved) |
| 131 | +2. **Merge into `src/agents/gds-agent-game-dev/SKILL.md`:** |
| 132 | + - Keep Link Freeman persona; append QA + SM capability sections under `## Capabilities` |
| 133 | + - Pull QA-specific critical actions (knowledge-fragment lookup via `gametest/qa-index.csv` — see relocation below) |
| 134 | + - Pull SM-specific critical actions (sprint-status sync, story-file ownership) |
| 135 | + - Update `description` frontmatter to note combined role without losing Link Freeman trigger phrase |
| 136 | +3. **Delete** `src/agents/gds-agent-game-qa/` and `src/agents/gds-agent-game-scrum-master/` directories entirely |
| 137 | +4. **Global reference sweep:** |
| 138 | + - grep `src/` for `gds-agent-game-qa` and `gds-agent-game-scrum-master` — redirect every hit to `gds-agent-game-dev` |
| 139 | + - Expected hit sites: workflows in `4-production/` (sprint planning/status/retro reference SM), `gametest/` workflows (reference QA), `module-help.csv`, `bmad-skill-manifest.yaml` files |
| 140 | +5. **`module.yaml` + `module-help.csv`** — remove dropped agents; update agent registry |
| 141 | + |
| 142 | +### gametest relocation |
| 143 | + |
| 144 | +Move knowledge base from `src/gametest/` to `src/agents/gds-agent-game-dev/gametest/`. |
| 145 | + |
| 146 | +1. Move: |
| 147 | + - `src/gametest/knowledge/*.md` (17 files) → `src/agents/gds-agent-game-dev/gametest/knowledge/` |
| 148 | + - `src/gametest/qa-index.csv` → `src/agents/gds-agent-game-dev/gametest/qa-index.csv` |
| 149 | +2. Delete empty `src/gametest/` directory |
| 150 | +3. **Path rewrites** — grep `src/` for: |
| 151 | + - `{module_root}/gametest/` → `{skill_root}/gametest/` (or `{agents_root}/gds-agent-game-dev/gametest/` depending on which variable resolves correctly at install time — verify with upstream's path-resolver convention) |
| 152 | + - `gametest/qa-index.csv` (bare) → new path |
| 153 | + - `gametest/knowledge/` (bare) → new path |
| 154 | + - Known hit sites to verify: `src/workflows/gametest/gds-test-design/test-design-template.md:205`, former `gds-agent-game-qa/SKILL.md:30,33` content now living in `gds-agent-game-dev/SKILL.md` |
| 155 | +4. `_bmad-output` references (currently 1 hit in `gds-code-review/workflow.md:20`) — review with user in Phase 4 whether to remove the explicit exclusion comment since `_bmad-output` is being deprecated (leave for now; it's informational) |
| 156 | + |
| 157 | +### Phase 2.5 verification |
| 158 | + |
| 159 | +- No lingering refs to `gds-agent-game-qa`, `gds-agent-game-scrum-master` in `src/` (grep exits with no matches) |
| 160 | +- No lingering refs to `src/gametest/` or `{module_root}/gametest/` at the old location |
| 161 | +- `gds-agent-game-dev/SKILL.md` parses; frontmatter valid |
| 162 | +- Installer smoke test loads combined agent + gametest knowledge correctly |
| 163 | + |
| 164 | +--- |
| 165 | + |
| 166 | +## Phase 3 — Production-phase steps/ backfill |
| 167 | + |
| 168 | +### Current state (game-dev, no `steps/` subdir) |
| 169 | + |
| 170 | +- `src/workflows/4-production/gds-code-review/` |
| 171 | +- `src/workflows/4-production/gds-correct-course/` |
| 172 | +- `src/workflows/4-production/gds-create-story/` |
| 173 | +- `src/workflows/4-production/gds-dev-story/` |
| 174 | +- `src/workflows/4-production/gds-retrospective/` |
| 175 | +- `src/workflows/4-production/gds-sprint-planning/` |
| 176 | +- `src/workflows/4-production/gds-sprint-status/` |
| 177 | + |
| 178 | +### Upstream source to port from |
| 179 | + |
| 180 | +- `bmad-code-review/steps/{step-01-gather-context.md, step-02-review.md, step-04-present.md}` — recently updated |
| 181 | +- `bmad-correct-course/workflow.md` + `checklist.md` — updated |
| 182 | +- `bmad-retrospective/workflow.md` — updated (268-line change; substantial rewrite) |
| 183 | +- `bmad-sprint-planning/workflow.md`, `bmad-sprint-status/workflow.md` — minor |
| 184 | +- `bmad-create-story`, `bmad-dev-story` — no `steps/` upstream either (skip) |
| 185 | + |
| 186 | +### Plan |
| 187 | + |
| 188 | +For each game-dev skill above, create a `steps/` subdir matching upstream's step decomposition. Copy step file contents, rewrite references to: |
| 189 | +- `_bmad/bmm/...` → `_bmad/gds/...` |
| 190 | +- `bmad-agent-dev` → `gds-agent-game-dev` |
| 191 | +- `gds-agent-game-qa` / `gds-agent-game-scrum-master` refs → `gds-agent-game-dev` (per Phase 2.5 — should already be clean by the time Phase 3 runs) |
| 192 | +- Any terminology swap (story → game-story where appropriate) |
| 193 | + |
| 194 | +Update each `workflow.md` to reference the new step files if it currently inlines everything. |
| 195 | + |
| 196 | +### Phase 3 verification |
| 197 | + |
| 198 | +- `npm test` in game-dev repo passes |
| 199 | +- Each skill's `workflow.md` correctly references its new `steps/*.md` via relative paths |
| 200 | + |
| 201 | +--- |
| 202 | + |
| 203 | +## Phase 4 — Manifest + module.yaml audit |
| 204 | + |
| 205 | +### Scope |
| 206 | + |
| 207 | +- `src/module.yaml` — compare schema against upstream's `src/bmm-skills/module.yaml` and `src/core-skills/module.yaml`; harmonize field set |
| 208 | +- Every `bmad-skill-manifest.yaml` under `src/workflows/**/` and `src/agents/**/` — validate against upstream skill-manifest schema (whatever `tools/validate-skills.js` in upstream expects) |
| 209 | +- `src/module-help.csv` — regenerate from skill frontmatter (post-agent-merge; drops QA + SM entries) |
| 210 | +- Any dangling references to `bmad-agent-qa` / `bmad-agent-sm` / `bmad-init` in copied content → clean up |
| 211 | + |
| 212 | +### Plan |
| 213 | + |
| 214 | +1. Run upstream's `tools/validate-skills.js` against game-dev `src/` (adapt path config) |
| 215 | +2. Regenerate `module-help.csv` from SKILL.md frontmatter |
| 216 | +3. Diff `module.yaml` schema against upstream; add missing fields with game-dev values |
| 217 | +4. grep game-dev for `bmad-agent-qa`, `bmad-agent-sm`, `bmad-init` (removed in #2159) — clean up refs |
| 218 | + |
| 219 | +### Phase 4 verification |
| 220 | + |
| 221 | +- `npm run lint` + `npm run lint:md` + `npm run format:check` clean |
| 222 | +- Validate-skills script exits 0 |
| 223 | + |
| 224 | +--- |
| 225 | + |
| 226 | +## Phase 5 — Cleanup |
| 227 | + |
| 228 | +- `src/workflows/gds-quick-flow/gds-quick-dev-new-preview/`, `gds-quick-spec/`, and original `gds-quick-dev/` should already be gone from Phase 1 |
| 229 | +- `src/agents/gds-agent-game-qa/` and `src/agents/gds-agent-game-scrum-master/` should already be gone from Phase 2.5 |
| 230 | +- `src/gametest/` should already be gone from Phase 2.5 |
| 231 | +- Delete stale `install-success-message.md`, `codex-review.md` at repo root if superseded (check git log first) |
| 232 | +- Update `TODO.md` with any known-deferred items (incomplete GDD edit/validate step bodies, etc.) |
| 233 | +- Update `CHANGELOG.md` with sync summary |
| 234 | + |
| 235 | +--- |
| 236 | + |
| 237 | +## Out of scope (deferred) |
| 238 | + |
| 239 | +- Restructuring `src/workflows/` → `src/bmm-skills/` (game-dev's top-level org is intentional) |
| 240 | +- Adding `gds-help` and `gds-party-mode` (user skipped) |
| 241 | +- Editorial/adversarial review skills (`bmad-editorial-review-*`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter`) — not requested; flag in `TODO.md` for future |
| 242 | +- Full `src/workflows/gametest/` relocation into the dev agent (out of scope for this sync; only the knowledge-base `src/gametest/` moves) |
| 243 | +- Whether `gds-quick-flow/` parent directory survives long-term (flag for follow-up) |
| 244 | + |
| 245 | +--- |
| 246 | + |
| 247 | +## Execution order + checkpoints |
| 248 | + |
| 249 | +All pre-flight decisions are locked in. Recommend phase-by-phase execution with a commit between each: |
| 250 | + |
| 251 | +1. Phase 1 (quick-dev full replacement + delete quick-spec + delete new-preview) — commit |
| 252 | +2. Phase 2a (PRD split into 3 skill dirs) — commit |
| 253 | +3. Phase 2b (GDD split into 3 skill dirs) — commit |
| 254 | +4. Phase 2c (port upstream PRD content updates — step-08-scoping, step-11-polish, step-e-*, prd-purpose.md) — commit |
| 255 | +5. Phase 2.5 (agent merge QA+SM→dev; relocate `src/gametest/` into `gds-agent-game-dev/gametest/`) — commit |
| 256 | +6. Phase 3 (production steps/ backfill; agent refs already clean from 2.5) — commit |
| 257 | +7. Phase 4 (manifest audit + module-help.csv regen + final cleanup) — commit |
| 258 | +8. Full `npm test` run + manual `npx bmad-method install` smoke test into a scratch dir → push |
| 259 | + |
| 260 | +Each phase is independently revertible via `git revert`. |
0 commit comments