architecture-documenter

@cautiouskurns/architecture-documenter

1 forks

Updated 3/31/2026

Build and maintain a living architecture document tracking scene trees, data structures, system hierarchies, and game architecture. Use this when visualizing game structure, documenting scene hierarchies, or tracking data schemas.

Installation

$npx agent-skills-cli install @cautiouskurns/architecture-documenter

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorycautiouskurns/Blood-and-Gold

Path.claude/skills/architecture-documenter/SKILL.md

Branchmain

Scoped Name@cautiouskurns/architecture-documenter

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions

name: architecture-documenter description: Build and maintain a living architecture document tracking scene trees, data structures, system hierarchies, and game architecture. Use this when visualizing game structure, documenting scene hierarchies, or tracking data schemas. domain: architecture type: documenter version: 1.1.0 allowed-tools:

Read
Write
Edit
Glob
Grep
Bash

Architecture Documenter Skill

This skill creates and maintains a comprehensive Architecture Document that visualizes scene trees, tracks data structures, maps system hierarchies, and provides a structural overview of the entire game.

When to Use This Skill

Invoke this skill when the user:

Says "document the architecture" or "map out the game structure"
Asks "show me the scene tree" or "what's the scene hierarchy?"
Wants to track data structures: "what data does the game use?"
Says "update architecture doc" or "add [system] to architecture"
Needs to understand node relationships
Asks "how is [scene/system] structured?"
Wants a visual overview of the game
Says "create architecture document"

IMPORTANT: Use Mermaid Diagrams

All visual diagrams MUST use Mermaid syntax, not ASCII art.

Mermaid diagrams:

Render beautifully in GitHub, VS Code, Obsidian, and most markdown viewers
Are easier to maintain and update
Support colors, styling, and interactivity
Are more readable than ASCII art

Architecture Document vs Systems Bible

Aspect	Architecture Document	Systems Bible
Focus	Structure & hierarchy	Implementation details
Content	Scene trees, data schemas, Mermaid diagrams	Code, APIs, methods
Format	Visual (Mermaid diagrams, tables)	Prose with code snippets
Purpose	"What exists and how it's organized"	"How things work"
Updates	When structure changes	When implementation changes

Mermaid Diagram Types to Use

1. Flowcharts (graph TB/LR) - For Hierarchies & Scene Trees

graph TB
    Parent["Parent Node (Type)"]
    Child1["Child 1 (Type)"]
    Child2["Child 2 (Type)"]

    Parent --> Child1
    Parent --> Child2

    style Parent fill:#4a6741,stroke:#3d5636,color:#fff

Use for:

Scene tree hierarchies
Class inheritance diagrams
File structure visualization
Data flow diagrams
Dependency graphs

2. Flowcharts (graph LR) - For Sequences & Loops

graph LR
    A[Step 1] --> B[Step 2]
    B --> C[Step 3]
    C --> A

    style A fill:#4a6741,stroke:#3d5636,color:#fff

Use for:

Game loops
State machines
Signal flows
Process sequences

3. Subgraphs - For Grouping Related Items

graph TB
    subgraph Managers["Autoload Managers"]
        GM[GameManager]
        TM[TurnManager]
    end

    subgraph Scenes["Game Scenes"]
        Combat[Combat]
        Camp[Camp]
    end

    Managers --> Scenes

Use for:

Grouping related systems
Showing layers/categories
Organizing complex hierarchies

4. Gantt Charts - For Progress/Status

gantt
    title Implementation Progress
    dateFormat X
    axisFormat %s

    section Completed
    Feature 1    :done, 0, 1
    Feature 2    :done, 0, 1

    section In Progress
    Feature 3    :active, 0, 1

    section Pending
    Feature 4    :0, 1

Use for:

Implementation status
Phase progress
Feature completion tracking

Mermaid Styling Guidelines

Color Palette

Use consistent colors across all diagrams:

# Status Colors
Completed/Implemented:  fill:#48bb78,stroke:#38a169,color:#fff  (green)
In Progress:            fill:#d69e2e,stroke:#b7791f,color:#fff  (yellow/orange)
Planned/Pending:        fill:#a0aec0,stroke:#718096,color:#fff  (gray)

# Entity Type Colors
Player/Party:           fill:#3182ce,stroke:#2c5282,color:#fff  (blue)
Enemies:                fill:#e53e3e,stroke:#c53030,color:#fff  (red)
Soldiers/Allies:        fill:#38a169,stroke:#2f855a,color:#fff  (green)
Neutral/Base:           fill:#4a5568,stroke:#2d3748,color:#fff  (gray)

# Data Type Colors
Resources (.tres):      fill:#805ad5,stroke:#6b46c1,color:#fff  (purple)
JSON files:             fill:#d69e2e,stroke:#b7791f,color:#fff  (orange)
Scenes (.tscn):         fill:#3182ce,stroke:#2c5282,color:#fff  (blue)

# System Colors
Managers/Autoloads:     fill:#1a365d,stroke:#2c5282,color:#fff  (dark blue)

Node Naming Convention

graph TB
    Node["Display Name (NodeType)<br/>Additional info"]

Use descriptive display names
Include node type in parentheses
Use <br/> for line breaks within nodes
Keep node IDs short for readability

Architecture Document Structure

# [GAME TITLE] - Architecture Document

**Version:** [X.Y.Z]
**Engine:** Godot [Version]
**Last Updated:** [Date]
**Phase:** [Current Phase]

---

## TABLE OF CONTENTS

1. [High-Level Architecture](#high-level-architecture)
2. [Main Scene Tree](#main-scene-tree)
3. [System Scene Trees](#system-scene-trees)
4. [Data Architecture](#data-architecture)
5. [Resource Definitions](#resource-definitions)
6. [Signal Map](#signal-map)
7. [Group Registry](#group-registry)
8. [Autoload Registry](#autoload-registry)
9. [Collision Layers](#collision-layers)
10. [File Structure](#file-structure)
11. [Implementation Status](#implementation-status)

---

## HIGH-LEVEL ARCHITECTURE

### Game Structure Overview

```mermaid
graph TB
    subgraph Game["GAME TITLE"]
        subgraph Autoloads["Autoloads"]
            GM[GameManager]
            ...
        end

        subgraph Scenes["Scenes"]
            Main[Main Scene]
            ...
        end
    end

    Autoloads --> Scenes

Core Game Loop

graph LR
    A[Phase 1] --> B[Phase 2]
    B --> C[Phase 3]
    C --> A

...


---

## Workflow

### Creating New Architecture Document

1. **Scan the project structure:**

Glob for all .tscn files (scene trees)
Glob for all .tres files (resources)
Glob for all .gd files (scripts, esp. autoloads)
Check project.godot for autoloads


2. **Build scene tree documentation:**
- Read main scene file
- Parse node hierarchy
- Document node types, scripts, groups
- **Generate Mermaid graph TB diagrams for each scene**

3. **Catalog data structures:**
- Find all Resource class definitions
- Document exported properties
- Map resource file locations
- **Generate Mermaid diagrams showing data relationships**

4. **Map relationships:**
- Signal connections
- Group memberships
- Collision layers
- Autoload dependencies
- **Use Mermaid flowcharts to show dependencies**

5. **Generate Mermaid diagrams for:**
- High-level architecture overview
- Scene trees (using graph TB)
- Data flow (using graph LR)
- Dependencies (using subgraphs)
- Implementation status (using gantt)

6. **Save to `docs/architecture.md`**

---

### Updating Architecture Document

When the user says "update architecture":

1. **Read current architecture.md**

2. **Ask what changed:**
- New scene added?
- Scene restructured?
- New data type?
- New autoload?
- Collision layers changed?

3. **Scan for changes:**
- Compare file structure
- Read modified scenes
- Check for new resources

4. **Update appropriate sections:**
- Add new scene trees as Mermaid diagrams
- Update data schemas
- Refresh dependency diagrams
- Update file structure

5. **Add changelog entry**

---

## Mermaid Scene Tree Template

For each scene, use this template:

```mermaid
graph TB
 Root["SceneName (RootType)<br/>Script: script_name.gd"]
 Child1["ChildName (Type)"]
 Child2["ChildName (Type)"]
 GrandChild["GrandChild (Type)"]

 Root --> Child1
 Root --> Child2
 Child1 --> GrandChild

 style Root fill:#4a5568,stroke:#2d3748,color:#fff

Scene Tree Conventions

Root node gets darker styling
Implemented nodes get green styling
Planned nodes get gray styling
Include script name if attached
Include groups if assigned

Mermaid Dependency Graph Template

For autoloads and system dependencies:

graph TB
    A[System A<br/>Description]
    B[System B<br/>Description]
    C[System C<br/>Description]

    B -->|depends on| A
    C -->|depends on| A
    C -->|depends on| B

    style A fill:#1a365d,stroke:#2c5282,color:#fff
    style B fill:#2c5282,stroke:#3182ce,color:#fff
    style C fill:#3182ce,stroke:#4299e1,color:#fff

Reading .tscn Files

To extract scene tree structure for Mermaid conversion:

# .tscn files are text-based
# Key patterns to look for:

[node name="NodeName" type="NodeType" parent="."]
[node name="Child" type="Type" parent="NodeName"]
[node name="GrandChild" type="Type" parent="NodeName/Child"]

# Extract hierarchy from parent paths
# "." means root
# "NodeName" means direct child of that node
# "NodeName/Child" means nested path

Convert to Mermaid:

Create node for each [node] entry
Use parent to determine connections
Add styling based on node type/status

Data Schema Extraction

When documenting Resource classes:

Find class definition:
```
class_name WeaponData
extends Resource
```

Extract all @export variables:

@export var damage: int
@export var fire_rate: float

Document in table format (tables render well alongside Mermaid)
Show relationships between resources using Mermaid:

graph TB
    subgraph Resources["Resource Types"]
        WD[WeaponData]
        ED[EnemyData]
        AD[AbilityData]
    end

    WD -->|"references"| AD

Example Invocations

User: "Create architecture document" User: "Document the scene tree for player.tscn" User: "Update architecture - I added a new enemy type" User: "Show me all data types in the game" User: "What's the collision layer setup?" User: "Map out the autoload dependencies" User: "Document the signal architecture"

Output Location

Primary file: docs/architecture.md

Alternative locations:

docs/game-architecture.md
docs/technical/architecture.md

Always check if file exists before creating. If exists, update rather than overwrite.

Quality Checklist

Before finalizing:

All major scenes have Mermaid tree diagrams
Mermaid diagrams use consistent color styling
Data schemas include all @export properties
Dependency graphs show all autoload relationships
Groups are all documented with purpose
Autoloads match project.godot
File structure reflects actual project
Implementation status uses gantt or progress diagram
Changelog entry added

Integration with Other Skills

With `systems-bible-updater`

Architecture doc shows STRUCTURE (Mermaid diagrams)
Systems bible shows IMPLEMENTATION (code snippets)
Cross-reference between them

With `scene-optimizer`

Architecture doc shows current structure
Optimizer suggests improvements
Update architecture after optimization

With `system-diagram-generator`

Both use Mermaid diagrams
Architecture doc is the source of truth
System diagrams can be extracted for presentations

This skill ensures the game's structural organization is always documented with clear, visual Mermaid diagrams that are easy to maintain and understand.

More by cautiouskurns

View all

feature-implementer

Implement a feature spec by creating all necessary scenes, scripts, and resources. Use this when the user wants to implement a documented feature from the docs/features/ directory.

prototype-roadmap-planner

Read a prototype GDD and generate a phased implementation roadmap with concrete tasks, organized by implementation phases with specific deliverables and test criteria.

scene-optimizer

Analyze Godot scene files (.tscn) for structural issues, performance problems, and optimization opportunities. Use this when the user wants to optimize a scene, check scene structure, or troubleshoot scene-related issues.

design-bible-updater

Create and maintain a Game Design Bible documenting design vision, pillars, mechanics philosophy, and creative direction. Use this when establishing design principles or documenting high-level creative decisions.

architecture-documenter

Installation

Details

Usage

Skill Instructions

Architecture Documenter Skill

When to Use This Skill

IMPORTANT: Use Mermaid Diagrams

Architecture Document vs Systems Bible

Mermaid Diagram Types to Use

1. Flowcharts (graph TB/LR) - For Hierarchies & Scene Trees

2. Flowcharts (graph LR) - For Sequences & Loops

3. Subgraphs - For Grouping Related Items

4. Gantt Charts - For Progress/Status

Mermaid Styling Guidelines

Color Palette

Node Naming Convention

Architecture Document Structure

Core Game Loop

Scene Tree Conventions

Mermaid Dependency Graph Template

Reading .tscn Files

Data Schema Extraction

Example Invocations

Output Location

Quality Checklist

Integration with Other Skills

With systems-bible-updater

With scene-optimizer

With system-diagram-generator

More by cautiouskurns

With `systems-bible-updater`

With `scene-optimizer`

With `system-diagram-generator`