punkfuncgames/architect-game

Architect Game — GDD to Architecture Pipeline

Prerequisites

• A completed GDD at docs/plans/{game-name}-gdd.md
• Load these skills before starting: code-style, patterns, project-overview, testing
• MCP bridge must be configured and connected — .mcp.json must exist with correct paths (set up by clone-game Step 0b). If MCP is not connected, STOP and tell the user to restart Claude Code.

Process

Step 0: Verify MCP Connection

Before any architecture work, verify the MCP bridge is running:

1. Check .mcp.json exists with valid paths
2. Call execute_editor_method (e.g., Application.unityVersion) to confirm the Unity editor is reachable
3. If the connection fails, STOP and tell the user: "MCP bridge is not connected. Open the Unity project in the editor and restart Claude Code."

Step 1: Read Inputs

1. Read the GDD file
2. Use read_package_registry(filter: "all") to get the full catalog of available packages with their descriptions, events, and useWhen hints
3. Load module skills for any packages that will be reused (e.g., wallet-module, stats-module, ui-module, etc.)

Step 2: Map Systems to Packages

For each system identified in the GDD:

• Check available packages first — use the registry's useWhen field to match GDD systems to existing packages
• Identify new modules needed — what game-specific logic requires new code?
• Mark integration points — where do new modules connect to existing packages via MessagePipe events or service interfaces?

Produce a mapping table:

| GDD System | Package / Module | Status | Notes | |-----------|-----------------|--------|-------| | Scoring | com.punkfuncgames.stats | Install | Map score to a stat | | Currency | com.punkfuncgames.wallet | Install | Define currency definitions | | Spawning | NEW: GameTemplate.Spawner | Create | Wave-based entity spawner |

Step 2b: Install Required Packages

After the mapping is complete, install the packages identified as needed:

1. For each package marked "Install" in the mapping table, call install_package(packageId) — this handles dependency resolution automatically
2. Install in tier order (lower tiers first) to minimize dependency chains

Example:

install_package("wallet")    # Tier 3 — auto-installs math dependency (already base)
install_package("stats")     # Tier 3
install_package("pool")      # Tier 2
install_package("audio")     # Tier 3

The tool will:

• Resolve and install all transitive dependencies
• Add git URLs to manifest.json
• Trigger Unity compilation
• Report wiring instructions for ProjectLifetimeScope

Step 2c: Validate Event Wiring

After all packages are installed, run analyze_composition() to verify:

• Connected events — publisher and subscriber both installed (good)
• Gaps — events being published with no subscriber (may need another package or game-specific wiring)
• Dead ends — events being subscribed with no publisher (may need game-specific code to publish)

Review the gaps and dead ends:

• If a gap suggests installing another package, evaluate whether the game needs it
• Dead ends for request events (e.g., PlaySfxRequest, CameraShakeRequest) are expected — game code publishes these

After resolving:

git add -A
git commit -m "build: install packages for {game-name} ({list packages})"

Step 3: Define Scene Graph

Define the scene structure following the bootstrap pattern:

BOOTSTRAP (ProjectLifetimeScope)
  → MAINMENU (MainMenuLifetimeScope)
  → GAMEPLAY (GameplayLifetimeScope)
  → [additional scenes if needed]

For each scene, list:

• LifetimeScope class name
• Which installers run in that scope
• What configs are injected

Step 4: Define Module Structure

For each NEW module, define its internal layout:

Assets/Scripts/PunkFuncGames/GameTemplate/Runtime/{Module}/
  Config/       — ScriptableObject config + Data struct
  Model/        — Domain models, containers, state
  Event/        — MessagePipe event structs
  Service/      — IService interface + implementation
  View/         — MonoBehaviour views + ViewModels
  Installer/    — Static Install method

For each component, specify:

• Class name and purpose
• Dependencies (constructor injection parameters)
• Key reactive properties exposed
• Events published/subscribed

Step 5: Prefab Plan

List every prefab needed:

| Prefab | Type | Pool? | Components | |--------|------|-------|------------| | Player | Entity | No | PlayerView, Rigidbody, Collider | | Enemy_Basic | Entity | Yes (pool: 20) | EnemyView, Rigidbody, Collider | | ScorePopup | UI | Yes (pool: 10) | FloatingTextView |

Step 6: VContainer Installer Plan

Define the installer registration for each scope:

// ProjectLifetimeScope — shared services
GameCoreInstaller.Install(builder, options, gameConfig);

// GameplayLifetimeScope — gameplay-specific
SpawnerInstaller.Install(builder, options, spawnerConfig);
PlayerInstaller.Install(builder, options, playerConfig);

Step 7: Test Plan

For each new module, list the test classes needed:

| Module | Test Class | Type | Key Test Cases | |--------|-----------|------|---------------| | Spawner | SpawnerServiceTests | EditMode | Wave timing, spawn counts, difficulty scaling | | Player | PlayerServiceTests | EditMode | Movement, health, damage, death | | Player | PlayerViewTests | PlayMode | Input handling, animation triggers |

Step 8: Write Architecture Document

Write to:

docs/plans/{game-name}-architecture.md

Use this structure:

# {Game Name} — Architecture Document

## Package Mapping
(table from Step 2)

## Installed Packages
(list from Step 2b with versions)

## Event Wiring Analysis
(summary from Step 2c — connected, gaps resolved, expected dead ends)

## Scene Graph
(diagram from Step 3)

## New Modules
### {Module Name}
- Config: {ConfigName} + {DataStruct}
- Models: (list)
- Service: I{Name}Service / {Name}Service
- Events: (list of event structs)
- Views: (list)
- Dependencies: (list)

## Prefab Plan
(table from Step 5)

## Installer Plan
(code from Step 6)

## Test Plan
(table from Step 7)

## Implementation Order
Ordered list of modules to implement (dependency-first):
1. Data/Configs (no dependencies)
2. Core services (depend on configs only)
3. Game-specific services (depend on core)
4. Views (depend on services)
5. Installers (wire everything)
6. Scenes (final assembly)

## Open Questions
Any design decisions that need user input before implementation.

Step 9: Commit

git add docs/plans/{game-name}-architecture.md
git commit -m "docs: add {game-name} architecture document"

Output

The architecture document path, the count of reused vs new modules, the event wiring analysis summary, and any open questions that need resolution before implementation.