# bmad-code-org/bmad-module-game-dev-studio architecture

> Architecture diagram of the GitHub repository bmad-code-org/bmad-module-game-dev-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bmad-code-org/bmad-module-game-dev-studio
- Repository: https://github.com/bmad-code-org/bmad-module-game-dev-studio

## Overview

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`](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows) (Workflows), [`src/agents`](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/agents) (Agents), [`src/module.yaml`](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/module.yaml) (Module registry), [`.github/workflows`](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/.github/workflows) (CI release)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_src["Content module"]
  node_module_manifest["Module registry<br/>metadata<br/>[module.yaml]"]
  node_module_help["Help index<br/>lookup csv<br/>[module-help.csv]"]
  node_agents["Agents<br/>prompt assets"]
  node_agent_architect["Architect<br/>skill<br/>[SKILL.md]"]
  node_agent_designer["Designer<br/>skill<br/>[SKILL.md]"]
  node_agent_dev["Dev<br/>skill<br/>[SKILL.md]"]
  node_agent_qa["QA<br/>skill<br/>[SKILL.md]"]
  node_agent_writer["Writer<br/>skill<br/>[SKILL.md]"]
  node_workflows["Workflows<br/>process library"]
  node_preproduction["Preproduction<br/>workflow lane"]
  node_design["Design<br/>workflow lane"]
  node_tech_arch["Game architecture<br/>workflow subsystem"]
  node_production["Production<br/>workflow lane"]
  node_quick_flow["Quick flow<br/>workflow lane"]
  node_gametest["Game testing<br/>knowledge base"]
  node_test_knowledge["Test knowledge<br/>knowledge docs"]
end

subgraph group_g_docs["Docs site"]
  node_website["Website<br/>astro site"]
  node_docs_content["Docs content<br/>documentation source"]
end

subgraph group_g_release["Distribution"]
  node_marketplace["Marketplace<br/>plugin manifest<br/>[marketplace.json]"]
  node_docs_build["Docs build<br/>build script<br/>[build-docs.mjs]"]
  node_ci_release["CI release<br/>automation<br/>[workflows]"]
  node_package["npm package<br/>package metadata<br/>[package.json]"]
end

node_package -->|"ships"| node_module_manifest
node_package -->|"installs as"| node_marketplace
node_module_manifest -->|"indexes"| node_module_help
node_module_manifest -->|"defines"| node_agents
node_module_manifest -->|"defines"| node_workflows
node_agents -->|"contains"| node_agent_architect
node_agents -->|"contains"| node_agent_designer
node_agents -->|"contains"| node_agent_dev
node_agents -->|"contains"| node_agent_qa
node_agents -->|"contains"| node_agent_writer
node_workflows -->|"organizes"| node_preproduction
node_workflows -->|"organizes"| node_design
node_workflows -->|"organizes"| node_tech_arch
node_workflows -->|"organizes"| node_production
node_workflows -->|"organizes"| node_quick_flow
node_workflows -->|"includes"| node_gametest
node_gametest -->|"uses"| node_test_knowledge
node_tech_arch -->|"feeds"| node_agents
node_tech_arch -->|"informs"| node_gametest
node_docs_content -->|"renders in"| node_website
node_docs_build -->|"builds"| node_website
node_ci_release -->|"runs"| node_docs_build
node_ci_release -->|"releases"| node_package
node_ci_release -->|"publishes"| node_marketplace
node_docs_content -->|"documents"| node_module_manifest
node_website -->|"consumes"| node_docs_content

click node_module_manifest "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/module.yaml"
click node_module_help "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/module-help.csv"
click node_marketplace "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/.claude-plugin/marketplace.json"
click node_agents "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/agents"
click node_agent_architect "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-architect/SKILL.md"
click node_agent_designer "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-designer/SKILL.md"
click node_agent_dev "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-dev/SKILL.md"
click node_agent_qa "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-qa/SKILL.md"
click node_agent_writer "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-tech-writer/SKILL.md"
click node_workflows "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows"
click node_preproduction "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/1-preproduction"
click node_design "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/2-design"
click node_tech_arch "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/3-technical/gds-game-architecture"
click node_production "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/4-production"
click node_quick_flow "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/gds-quick-flow"
click node_gametest "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/gametest"
click node_test_knowledge "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/gametest/knowledge"
click node_website "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/website"
click node_docs_content "https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/docs"
click node_docs_build "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/tools/build-docs.mjs"
click node_ci_release "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/.github/workflows"
click node_package "https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_module_manifest,node_module_help,node_agents,node_agent_architect,node_agent_designer,node_agent_dev,node_agent_qa,node_agent_writer,node_workflows,node_preproduction,node_design,node_tech_arch,node_production,node_quick_flow,node_gametest,node_test_knowledge toneBlue
class node_website,node_docs_content toneAmber
class node_marketplace,node_docs_build,node_ci_release,node_package toneMint
```

## Components

### Content module

Static assets that drive agents and workflows

- [Module registry](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/module.yaml): metadata · Root module metadata and help index for the package · `src/module.yaml`
- [Help index](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/module-help.csv): lookup csv · Module help surface for consumers and assistant tooling · `src/module-help.csv`
- [Agents](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/agents): prompt assets · Role-based assistant definitions packaged as skills · `src/agents`
- [Architect](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-architect/SKILL.md): skill · Game architecture agent skill · `src/agents/gds-agent-game-architect/SKILL.md`
- [Designer](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-designer/SKILL.md): skill · Game design agent skill · `src/agents/gds-agent-game-designer/SKILL.md`
- [Dev](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-dev/SKILL.md): skill · Game development agent skill · `src/agents/gds-agent-game-dev/SKILL.md`
- [QA](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-game-qa/SKILL.md): skill · Game quality assurance agent skill · `src/agents/gds-agent-game-qa/SKILL.md`
- [Writer](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/src/agents/gds-agent-tech-writer/SKILL.md): skill · Technical writing agent skill and doc helpers · `src/agents/gds-agent-tech-writer/SKILL.md`
- [Workflows](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows): process library · Markdown-driven workflow engine for game development tasks · `src/workflows`
- [Preproduction](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/1-preproduction): workflow lane · Brainstorming, brief creation, and research flows · `src/workflows/1-preproduction`
- [Design](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/2-design): workflow lane · PRD, GDD, narrative, and UX generation flows · `src/workflows/2-design`
- [Game architecture](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/3-technical/gds-game-architecture): workflow subsystem · Engine-specific architecture guidance and validation · `src/workflows/3-technical/gds-game-architecture`
- [Production](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/4-production): workflow lane · Story, sprint, review, and course-correction flows · `src/workflows/4-production`
- [Quick flow](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/workflows/gds-quick-flow): workflow lane · Fast-path dev and spec workflows for shorter cycles · `src/workflows/gds-quick-flow`
- [Game testing](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/gametest): knowledge base · Testing and QA knowledge for playtest and validation planning · `src/gametest`
- [Test knowledge](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/src/gametest/knowledge): knowledge docs · Test strategy notes across engine and quality dimensions · `src/gametest/knowledge`

### Docs site

Public documentation sources and Astro renderer

- [Website](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/website): astro site · Astro app that renders the public documentation site · `website`
- [Docs content](https://github.com/bmad-code-org/bmad-module-game-dev-studio/tree/main/docs): documentation source · User-facing documentation pages and reference content · `docs`

### Distribution

Packaging and release surfaces

- [Marketplace](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/.claude-plugin/marketplace.json): plugin manifest · Claude-plugin marketplace entry for installation · `.claude-plugin/marketplace.json`
- [Docs build](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/tools/build-docs.mjs): build script · Repository-local docs generation and build entrypoint · `tools/build-docs.mjs`
- [CI release](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/.github/workflows): automation · GitHub Actions for docs, quality, release, and notifications · `.github/workflows`
- [npm package](https://github.com/bmad-code-org/bmad-module-game-dev-studio/blob/main/package.json): package metadata · Package and publish configuration for distributable module · `package.json`

## Connections

- 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
