How bmad-code-org/bmad-module-game-dev-studio works
1. What this repository is
- This is not an application runtime or game project. It is a content module for the BMad Method ecosystem, packaging game-development workflows, agent instructions, and documentation into a distributable npm module.
2. Primary architectural boundary
- The repo has two main consumption paths:
- BMad/Claude-style agent workflows consume the markdown/YAML/CSV assets under src/.
- The public documentation site consumes the docs content under docs/ and is rendered from the website/ Astro app.
3. Module metadata and packaging
- src/module.yaml and src/module-help.csv look like the root registry for the module’s capabilities and help surface.
- .claude-plugin/marketplace.json indicates this package is also intended to be installable as a Claude plugin-style marketplace item.
- package.json plus the README’s install flow show it ships as an npm package (bmad-game-dev-studio) rather than as compiled application code.
4. Agent subsystem
- src/agents/ contains the role-based assistant definitions:
- game architect
- game designer
- game dev
- QA
- scrum master
- solo dev
- tech writer
- Each agent is packaged as a SKILL.md plus bmad-skill-manifest.yaml, so the agent behavior is driven by static prompt/config assets rather than executable logic.
5. Workflow engine subsystem
- src/workflows/ is the largest part of the repo and is organized by delivery phase:
- 1-preproduction
- 2-design
- 3-technical
- 4-production
- gametest
- gds-quick-flow
- Each workflow is broken into step files, checklists, templates, and manifests. This is the core “process engine” of the repo: a deterministic sequence of markdown-driven steps that guide an AI assistant through planning and production tasks.
6. Preproduction and design flow
- The preproduction workflows cover brainstorming, game brief creation, and research.
- The design workflows generate artifacts such as:
- PRDs
- GDDs
- narrative docs
- UX design docs
- The data files inside these workflows, such as CSVs for domain complexity or game types, act as lookup tables and decision aids for structured document generation.
7. Technical architecture flow
- src/workflows/3-technical/gds-game-architecture/ is a dedicated architecture subsystem.
- It includes:
- engine-specific knowledge for Godot, Phaser, Unity, Unreal
- architecture pattern catalogs
- decision catalogs
- validation steps
- This is where the repo translates game design context into implementation-oriented architecture guidance, including engine-specific boundaries and cross-cutting concerns.
8. Production planning flow
- src/workflows/4-production/ contains the operational side of game production:
- story creation
- dev story execution
- sprint planning
- sprint status
- retrospectives
- code review and course correction
- These workflows are designed to keep implementation aligned to design/architecture artifacts through iterative production planning.
9. Game testing knowledge and QA
- src/gametest/knowledge/ and src/gametest/qa-index.csv form a test strategy knowledge base.
- The content spans playtesting, regression, performance, compatibility, localization, multiplayer, save testing, and engine-specific testing notes for Godot, Unity, and Unreal.
- This subsystem supports test planning and QA workflow generation rather than automated test execution itself.
10. Documentation site subsystem
- docs/ contains the user-facing documentation source.
- website/ is an Astro-based static site that renders the docs, with content config, markdown link rewriting, base-path handling, and custom styling.
- CNAME suggests the docs are deployed to a custom domain, so the website is part of the deliverable architecture, not just internal tooling.
11. Build, quality, and release tooling
- tools/build-docs.mjs is the main repository-local build script.
- GitHub Actions under .github/workflows/ handle:
- docs generation/deployment
- quality checks
- manual release
- Discord notifications
- Husky pre-commit, ESLint, Prettier, and markdown lint config indicate the repo is maintained as a documentation-heavy codebase with automation around content quality.
12. Data flow across the repository
- Authoring happens in src/ and docs/.
- Workflow steps and agent manifests are consumed by the BMad runtime / assistant tooling to generate or validate artifacts.
- The website build consumes docs content for publication.
- Release automation packages the module for installation and publishes docs/updates to the external distribution surfaces.
13. External integration points
- Runtime consumers are expected to be AI-assisted development environments such as Claude Code, Cursor, or GitHub Copilot, but the repo itself is mostly static content for those tools.
- Operationally, the repo also integrates with npm for distribution, Discord for community/release hooks, and GitHub for source control and CI/CD.
14. How to draw the architecture
- Model it as a content-and-workflow platform with three major lanes:
- Agent definitions
- Workflow/document generation
- Public docs + release tooling
- The central shared dependency is the structured content under src/, which feeds both assistant behavior and generated documentation artifacts.
Main entry points: src/workflows Workflows · agents Agents · module.yaml Module registry · .github/workflows CI release
Components 22
Content module
Static assets that drive agents and workflows
- Module registry · Root module metadata and help index for the package
src/module.yaml - Help index · Module help surface for consumers and assistant tooling
src/module-help.csv - Agents · Role-based assistant definitions packaged as skills
src/agents - Architect · Game architecture agent skill
src/agents/gds-agent-game-architect/SKILL.md - Designer · Game design agent skill
src/agents/gds-agent-game-designer/SKILL.md - Dev · Game development agent skill
src/agents/gds-agent-game-dev/SKILL.md - QA · Game quality assurance agent skill
src/agents/gds-agent-game-qa/SKILL.md - Writer · Technical writing agent skill and doc helpers
src/agents/gds-agent-tech-writer/SKILL.md - Workflows · Markdown-driven workflow engine for game development tasks
src/workflows - Preproduction · Brainstorming, brief creation, and research flows
src/workflows/1-preproduction - Design · PRD, GDD, narrative, and UX generation flows
src/workflows/2-design - Game architecture · Engine-specific architecture guidance and validation
src/workflows/3-technical/gds-game-architecture - Production · Story, sprint, review, and course-correction flows
src/workflows/4-production - Quick flow · Fast-path dev and spec workflows for shorter cycles
src/workflows/gds-quick-flow - Game testing · Testing and QA knowledge for playtest and validation planning
src/gametest - Test knowledge · Test strategy notes across engine and quality dimensions
src/gametest/knowledge
Docs site
Public documentation sources and Astro renderer
- Website · Astro app that renders the public documentation site
website - Docs content · User-facing documentation pages and reference content
docs
Distribution
Packaging and release surfaces
- Marketplace · Claude-plugin marketplace entry for installation
.claude-plugin/marketplace.json - Docs build · Repository-local docs generation and build entrypoint
tools/build-docs.mjs - CI release · GitHub Actions for docs, quality, release, and notifications
.github/workflows - npm package · Package and publish configuration for distributable module
package.json
Connections 26
- npm package → Module registry: ships · Package includes the content module registry
- npm package → Marketplace: installs as · Package is also exposed as a marketplace/plugin item
- Module registry → Help index: indexes · Registry and help surface are paired module metadata
- Module registry → Agents: defines · Module metadata enumerates the agent skills
- Module registry → Workflows: defines · Module metadata enumerates the workflow library
- Agents → Architect: contains · Role-based assistant skill definitions
- Agents → Designer: contains · Role-based assistant skill definitions
- Agents → Dev: contains · Role-based assistant skill definitions
- Agents → QA: contains · Role-based assistant skill definitions
- Agents → Writer: contains · Role-based assistant skill definitions
- Workflows → Preproduction: organizes · Top-level workflow lane for early discovery
- Workflows → Design: organizes · Top-level workflow lane for specification and design
- Workflows → Game architecture: organizes · Top-level workflow lane for technical architecture
- Workflows → Production: organizes · Top-level workflow lane for production execution
- Workflows → Quick flow: organizes · Top-level workflow lane for rapid task execution
- Workflows → Game testing: includes · Testing workflows and knowledge base
- Game testing → Test knowledge: uses · QA workflows are backed by test strategy knowledge
- Game architecture → Agents: feeds · Architecture guidance is consumed through agent skills
- Game architecture → Game testing: informs · Architecture and testing guidance share validation concerns
- Docs content → Website: renders in · Docs source is published through the Astro site
- Docs build → Website: builds · Local build script prepares website documentation output
- CI release → Docs build: runs · CI automates docs generation and deployment
- CI release → npm package: releases · CI handles release and quality automation around the package
- CI release → Marketplace: publishes · Release automation supports plugin distribution surfaces
- Docs content → Module registry: documents · Public docs explain module and workflow usage
- Website → Docs content: consumes · Static site renders docs content