# alterlab-ieu/alterlab_gameforge architecture

> Architecture diagram of the GitHub repository alterlab-ieu/alterlab_gameforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alterlab-ieu/alterlab_gameforge
- Repository: https://github.com/alterlab-ieu/alterlab_gameforge

## Overview

1. **What this repository is**
   - This is not a game app or engine plugin; it is a **prompt/skill toolkit for Claude Code and Claude Projects**.
   - The repository packages **34 production-grade game-development skills** as Markdown files, plus shared references, templates, hooks, starter configs, and CI validation.

2. **Top-level orchestration boundary**
   - `CLAUDE.md` is the main routing/config entry point for the repo.
   - It defines how Claude should interpret the repository and ties together the skill system, project conventions, and contribution rules.
   - For a diagram, treat this as the central control plane that points to all other content layers.

3. **Primary content subsystem: skills**
   - `skills/` is the core product surface.
   - It is split into:
     - `skills/agents/` — 11 studio-role skills such as Producer, Designer, QA Lead, Technical Director, etc.
     - `skills/workflows/` — 20 process skills such as Game Start, Brainstorm, Code Review, Sprint Plan, Launch, Playtest, Balance Check, CI Pipeline, and GDD Author.
     - `skills/engine-specialists/` — 3 engine-specific skills for **Godot, Unity, and Unreal**.
   - Each skill is a standalone `.md` prompt artifact, designed to be loaded into Claude and activated by intent.

4. **How the skills are organized conceptually**
   - The skills model a **virtual game studio** plus **workflow automation** plus **engine specialization**.
   - The architecture boundary is important: the repo is intentionally **engine-agnostic at the core**, with engine-specific guidance isolated into specialist skills and starter configs.
   - This makes the skill set reusable across different game stacks.

5. **Shared knowledge base**
   - `docs/` contains the reference layer used by multiple skills.
   - It includes governance, workflow guidance, coding standards, collaboration protocols, genre/spec docs, MCP integration guidance, and FAQs.
   - In the architecture, this is the common “knowledge substrate” that skills consult rather than duplicating content.

6. **Genre packs as consumable domain libraries**
   - `genre-packs/` contains reusable genre-specific design references, not standalone skills.
   - Current packs are:
     - `narrative/`
     - `roguelike/`
   - These enrich workflows like Brainstorm, Designer, Balance Check, and GDD Author with genre patterns, balance models, and example references.

7. **Template subsystem**
   - `templates/` provides the output artifacts that skills are meant to produce or fill in.
   - Examples include game design documents, sprint plans, post-mortems, accessibility audits, release checklists, economy models, and systems indexes.
   - In diagram terms, this is the output contract layer: skills generate structured artifacts from these templates.

8. **Starter configurations for real projects**
   - `starters/` contains bootstrap config for Claude-enabled game projects.
   - There is a shared base config in `starters/claude-config/` and engine-specific additions for:
     - Godot
     - Unity
     - Unreal
   - These are the handoff boundary between this repository and an actual game codebase.

9. **Lifecycle hooks and operational automation**
   - `hooks/` contains session and validation scripts such as session start/stop, compact handling, commit validation, and logging.
   - These hooks enforce workflow discipline around Claude sessions and repository changes.
   - They function as operational glue, not end-user content.

10. **Validation and release pipeline**
   - `scripts/validate.sh` and `.github/workflows/validate-skills.yml` form the quality gate.
   - The repo advertises automated validation of skill structure and content consistency, making the Markdown-based skill system safe to maintain at scale.
   - `marketplace.json` and `package.json` provide repo metadata and distribution/tooling integration points.

11. **External integration surface**
   - The repo references **MCP integrations** in the docs, with several skills containing built-in MCP sections.
   - These integrations connect the skills to external tools/services such as engine tooling, asset workflows, and project management systems.
   - Architecturally, MCP is an extension layer rather than a core dependency.

12. **Overall data flow**
   - A user or project loads `CLAUDE.md` and selected skill Markdown files into Claude.
   - Claude consults shared docs, genre packs, and templates to produce structured game-dev outputs.
   - Hooks and validation scripts enforce consistency, while starter configs bridge the skill system into real Godot/Unity/Unreal projects.

Main entry points: [`skills/workflows`](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills/workflows) (Workflows), [`CLAUDE.md`](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/CLAUDE.md) (CLAUDE.md), [`starters`](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/starters) (Starters), [`skills`](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills) (Skills)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_claude_md["CLAUDE.md<br/>routing config<br/>[CLAUDE.md]"]
end

subgraph group_skills["Skill library"]
  node_skills_root["Skills<br/>skill library"]
  node_skills_agents["Agents<br/>studio roles"]
  node_skills_workflows["Workflows<br/>process skills"]
  node_skills_engine["Engine skills<br/>engine specialists"]
  node_game_producer["Producer<br/>role skill<br/>[SKILL.md]"]
  node_game_designer["Designer<br/>role skill<br/>[SKILL.md]"]
  node_game_gdd_author["GDD Author<br/>workflow skill<br/>[SKILL.md]"]
  node_game_ci_pipeline["CI Pipeline<br/>workflow skill<br/>[SKILL.md]"]
  node_game_godot_specialist["Godot<br/>engine skill<br/>[SKILL.md]"]
end

subgraph group_knowledge["Knowledge base"]
  node_docs_root["Docs<br/>reference base"]
  node_genre_narrative["Narrative pack<br/>genre library"]
  node_genre_roguelike["Roguelike pack<br/>genre library"]
end

subgraph group_artifacts["Output contracts"]
  node_templates_root["Templates"]
end

subgraph group_runtime["Runtime bridge"]
  node_starters_root["Starters<br/>project bootstrap"]
  node_starter_claude["Base config<br/>starter config<br/>[CLAUDE.md]"]
  node_starter_godot["Godot starter<br/>starter config<br/>[CLAUDE.md]"]
  node_starter_unity["Unity starter<br/>starter config<br/>[CLAUDE.md]"]
  node_starter_unreal["Unreal starter<br/>starter config<br/>[CLAUDE.md]"]
end

subgraph group_ops["Ops and quality"]
  node_hooks_root["Hooks<br/>session automation"]
  node_validate_script["Validate<br/>validation script<br/>[validate.sh]"]
  node_github_workflow["CI workflow<br/>github actions"]
  node_marketplace_json["Marketplace<br/>distribution metadata<br/>[marketplace.json]"]
  node_package_json["Package<br/>tooling metadata<br/>[package.json]"]
end

node_claude_md -->|"routes to"| node_skills_root
node_claude_md -->|"consults"| node_docs_root
node_claude_md -->|"uses outputs"| node_templates_root
node_claude_md -->|"hands off to"| node_starters_root
node_claude_md -->|"governs"| node_hooks_root
node_skills_root -->|"contains"| node_skills_agents
node_skills_root -->|"contains"| node_skills_workflows
node_skills_root -->|"contains"| node_skills_engine
node_skills_agents -->|"example"| node_game_producer
node_skills_agents -->|"example"| node_game_designer
node_skills_workflows -->|"example"| node_game_gdd_author
node_skills_workflows -->|"example"| node_game_ci_pipeline
node_skills_engine -->|"example"| node_game_godot_specialist
node_docs_root -->|"supports"| node_skills_agents
node_docs_root -->|"supports"| node_skills_workflows
node_docs_root -->|"supports"| node_skills_engine
node_genre_narrative -->|"enriches"| node_skills_workflows
node_genre_roguelike -->|"enriches"| node_skills_workflows
node_templates_root -->|"shapes"| node_game_gdd_author
node_templates_root -->|"shapes"| node_game_ci_pipeline
node_starters_root -->|"contains"| node_starter_claude
node_starters_root -->|"contains"| node_starter_godot
node_starters_root -->|"contains"| node_starter_unity
node_starters_root -->|"contains"| node_starter_unreal
node_starter_claude -->|"aligns with"| node_skills_engine
node_hooks_root -->|"enforces"| node_validate_script
node_validate_script -->|"runs in"| node_github_workflow
node_marketplace_json -->|"publishes with"| node_package_json

click node_claude_md "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/CLAUDE.md"
click node_skills_root "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills"
click node_skills_agents "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills/agents"
click node_skills_workflows "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills/workflows"
click node_skills_engine "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills/engine-specialists"
click node_game_producer "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/agents/game-producer/SKILL.md"
click node_game_designer "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/agents/game-designer/SKILL.md"
click node_game_gdd_author "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/workflows/game-gdd-author/SKILL.md"
click node_game_ci_pipeline "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/workflows/game-ci-pipeline/SKILL.md"
click node_game_godot_specialist "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/engine-specialists/game-godot-specialist/SKILL.md"
click node_docs_root "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/docs"
click node_genre_narrative "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/genre-packs/narrative"
click node_genre_roguelike "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/genre-packs/roguelike"
click node_templates_root "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/templates"
click node_starters_root "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/starters"
click node_starter_claude "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/claude-config/CLAUDE.md"
click node_starter_godot "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/godot/CLAUDE.md"
click node_starter_unity "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/unity/CLAUDE.md"
click node_starter_unreal "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/unreal/CLAUDE.md"
click node_hooks_root "https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/hooks"
click node_validate_script "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/scripts/validate.sh"
click node_github_workflow "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/.github/workflows/validate-skills.yml"
click node_marketplace_json "https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/marketplace.json"
click node_package_json "https://github.com/alterlab-ieu/alterlab_gameforge/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_claude_md toneBlue
class node_skills_root,node_skills_agents,node_skills_workflows,node_skills_engine,node_game_producer,node_game_designer,node_game_gdd_author,node_game_ci_pipeline,node_game_godot_specialist toneAmber
class node_docs_root,node_genre_narrative,node_genre_roguelike toneMint
class node_templates_root toneRose
class node_starters_root,node_starter_claude,node_starter_godot,node_starter_unity,node_starter_unreal toneIndigo
class node_hooks_root,node_validate_script,node_github_workflow,node_marketplace_json,node_package_json toneTeal
```

## Components

### Control plane

Repository entrypoint and governing config

- [CLAUDE.md](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/CLAUDE.md): routing config · Main repo entrypoint and instruction router · `CLAUDE.md`

### Skill library

Prompt skills organized by studio roles, workflows, and engines

- [Skills](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills): skill library · Top-level skill collection · `skills`
- [Agents](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills/agents): studio roles · Role-based game studio prompts · `skills/agents`
- [Workflows](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills/workflows): process skills · End-to-end game development workflows · `skills/workflows`
- [Engine skills](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/skills/engine-specialists): engine specialists · Engine-specific guidance isolated from the core skill set · `skills/engine-specialists`
- [Producer](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/agents/game-producer/SKILL.md): role skill · Representative studio-role skill · `skills/agents/game-producer/SKILL.md`
- [Designer](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/agents/game-designer/SKILL.md): role skill · Representative studio-role skill · `skills/agents/game-designer/SKILL.md`
- [GDD Author](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/workflows/game-gdd-author/SKILL.md): workflow skill · Representative documentation workflow · `skills/workflows/game-gdd-author/SKILL.md`
- [CI Pipeline](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/workflows/game-ci-pipeline/SKILL.md): workflow skill · Representative validation workflow · `skills/workflows/game-ci-pipeline/SKILL.md`
- [Godot](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/skills/engine-specialists/game-godot-specialist/SKILL.md): engine skill · Representative engine-specialist skill · `skills/engine-specialists/game-godot-specialist/SKILL.md`

### Knowledge base

Shared references and domain packs consulted by skills

- [Docs](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/docs): reference base · Shared knowledge substrate for skills · `docs`
- [Narrative pack](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/genre-packs/narrative): genre library · Reusable narrative design reference pack · `genre-packs/narrative`
- [Roguelike pack](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/genre-packs/roguelike): genre library · Reusable roguelike design reference pack · `genre-packs/roguelike`

### Output contracts

Templates for structured deliverables generated by skills

- [Templates](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/templates): artifact templates · Structured outputs produced by skills · `templates`

### Runtime bridge

Starter configs that connect the skill system to actual game projects

- [Starters](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/starters): project bootstrap · Claude-enabled project bootstrap configurations · `starters`
- [Base config](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/claude-config/CLAUDE.md): starter config · Shared Claude project configuration · `starters/claude-config/CLAUDE.md`
- [Godot starter](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/godot/CLAUDE.md): starter config · Godot project handoff configuration · `starters/godot/CLAUDE.md`
- [Unity starter](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/unity/CLAUDE.md): starter config · Unity project handoff configuration · `starters/unity/CLAUDE.md`
- [Unreal starter](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/starters/unreal/CLAUDE.md): starter config · Unreal project handoff configuration · `starters/unreal/CLAUDE.md`

### Ops and quality

Hooks, validation, and release metadata

- [Hooks](https://github.com/alterlab-ieu/alterlab_gameforge/tree/main/hooks): session automation · Operational scripts for sessions and validation · `hooks`
- [Validate](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/scripts/validate.sh): validation script · Repo-level skill validation gate · `scripts/validate.sh`
- [CI workflow](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/.github/workflows/validate-skills.yml): github actions · Automated validation pipeline · `.github/workflows/validate-skills.yml`
- [Marketplace](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/marketplace.json): distribution metadata · Repository distribution and marketplace metadata · `marketplace.json`
- [Package](https://github.com/alterlab-ieu/alterlab_gameforge/blob/main/package.json): tooling metadata · Repo package and tooling metadata · `package.json`

## Connections

- CLAUDE.md → Skills: routes to · Central entrypoint directs Claude toward the skill library
- CLAUDE.md → Docs: consults · Routing guidance relies on shared repository conventions
- CLAUDE.md → Templates: uses outputs · Defines the structured artifacts expected from skills
- CLAUDE.md → Starters: hands off to · Bridges the repo into real game projects
- CLAUDE.md → Hooks: governs · Session rules and operational automation sit under the main config
- Skills → Agents: contains · Skill library is organized into studio roles
- Skills → Workflows: contains · Skill library is organized into reusable workflows
- Skills → Engine skills: contains · Skill library isolates engine specialization
- Agents → Producer: example · Representative role skill
- Agents → Designer: example · Representative role skill
- Workflows → GDD Author: example · Representative documentation workflow
- Workflows → CI Pipeline: example · Representative validation workflow
- Engine skills → Godot: example · Representative engine specialist
- Docs → Agents: supports · Shared guidance feeds role prompts
- Docs → Workflows: supports · Workflow guidance and standards inform process skills
- Docs → Engine skills: supports · Engine comparison and MCP guidance inform specialist skills
- Narrative pack → Workflows: enriches · Narrative patterns feed brainstorming and design workflows
- Roguelike pack → Workflows: enriches · Roguelike patterns feed brainstorming and balance workflows
- Templates → GDD Author: shapes · Templates define the expected output format
- Templates → CI Pipeline: shapes · Templates also cover operational artifacts
- Starters → Base config: contains · Shared base starter config
- Starters → Godot starter: contains · Engine-specific project starter
- Starters → Unity starter: contains · Engine-specific project starter
- Starters → Unreal starter: contains · Engine-specific project starter
- Base config → Engine skills: aligns with · Shared starter config supports engine-specific handoff
- Hooks → Validate: enforces · Hook scripts complement repo validation
- Validate → CI workflow: runs in · Shell validation is executed by CI
- Marketplace → Package: publishes with · Distribution metadata and tooling metadata travel together