Agent Skills: Room

Room

Rooms are intertwingled navigable activation context maps. Entering = calling. Exiting = returning.

Directories as cognitive spaces where cards come to life.

The Metaphor

| Filesystem | Simulation | Programming | |------------|------------|-------------| | Directory | Room | Stack frame | | cd room/ | Enter | Function call | | cd .. | Exit | Return | | Files in dir | Active entities | Local variables | | Links | Exits/doors | Calls to other functions |

Room Anatomy

room-name/
├── ROOM.yml        # Room definition (REQUIRED!)
├── README.md       # Room's voice (optional)
├── CARD.yml        # Card sidecar (optional)
├── character-*.yml # NPCs embedded in room
├── object-*.yml    # Objects in room
├── inbox/          # Objects thrown INTO this room
├── outbox/         # Objects staged to throw OUT
├── region/         # Sub-region of this room
│   └── ROOM.yml    # Region must also declare itself!
└── nested-room/    # Full sub-room (different location)
    └── ROOM.yml

Regions vs Sub-Rooms

What's a Region?

A region is a sub-directory that represents a portion of the same room — like the stage area of the pub, or the back corner of a library.

# pub/ROOM.yml
room:
  name: "The Gezelligheid Grotto Pub"
  
  # Regions are PARTS of this room
  regions:
    stage:
      path: "stage/"
      description: "The performance stage"
      visibility: public
      
    back-room:
      path: "back-room/"
      description: "Private back room"
      visibility: private
      requires: "bartender approval"
      
    bar:
      path: "bar/"
      description: "The bar counter area"

Regions Have Rules

Each region can have its own:

# pub/back-room/ROOM.yml
room:
  name: "Back Room"
  type: region                    # Marks as region, not full room
  parent: "../"                   # Part of parent room
  
  # Access control
  access:
    visibility: private           # Not visible to everyone
    requires: "bartender approval OR staff badge"
    who_allowed:
      - "characters/staff/*"
      - "player if has_flag('vip_access')"
    who_denied:
      - "characters/troublemakers/*"
      
  # Ethics & behavior
  rules:
    - "No recording"
    - "Confidential conversations"
    - "Staff only by default"
    
  # Privacy
  privacy:
    eavesdropping: false          # Can't hear from outside
    visible_from_parent: false    # Can't see inside from pub
    
  # What happens in the back room...
  narrative:
    on_enter: "The door closes behind you with a soft click."
    on_exit: "You return to the bustling pub."

Visibility Types

| Type | Description | |------|-------------| | public | Anyone can see and enter | | visible | Can see but may need permission to enter | | private | Hidden unless you know about it | | secret | Hidden AND requires discovery |

Region vs Full Sub-Room

| Feature | Region | Sub-Room | |---------|--------|----------| | Part of parent? | Yes | No | | Own identity? | Partial | Full | | Exit returns to? | Parent | Varies | | Shares parent context? | Yes | No | | Type field | type: region | type: room |

Directory Type Declaration

The Rule

Every directory in an adventure MUST declare what it is.

| Directory Type | Declaration File | |----------------|------------------| | Room | ROOM.yml | | Region | ROOM.yml (with type: region) | | Character | CHARACTER.yml | | Adventure root | ADVENTURE.yml | | Personas | ROOM.yml (with type: personas) | | Storage | ROOM.yml (with type: storage) |

Lint Error: Undeclared Directory

# LINT ERROR: Directory without type declaration
- type: MISSING_TYPE_DECLARATION
  severity: WARNING
  path: "pub/mysterious-corner/"
  message: "Directory has no ROOM.yml, CHARACTER.yml, or other type declaration"
  suggestion: "Add ROOM.yml with appropriate type field"

Valid Non-Room Directories

Some directories aren't rooms and that's OK:

# These don't need ROOM.yml:
messages/           # Mail storage (system)
inbox/              # Postal inbox (system)
outbox/             # Postal outbox (system)
sessions/           # Session logs (meta)
images/             # Asset storage (meta)

Marking System Directories

# Alternative: mark as system directory
# pub/messages/.meta.yml
meta:
  type: system
  purpose: "Mail storage for pub"
  requires_room_yml: false

Container Directories (Inheritance Scopes)

Some directories are inheritance containers — they provide shared properties to child rooms without being navigable themselves. Like OpenLaszlo's <node> element.

# maze/CONTAINER.yml — Not a room, but defines inherited properties
container:
  name: "The Twisty Maze"
  description: "Groups maze rooms with shared grue rules"
  
  inherits:
    is_dark: true
    is_dangerous: true
    grue_rules:
      can_appear: true
      
  ambient:
    sound: "dripping water"
    light_level: 0

All child rooms (room-a/, room-b/, etc.) automatically inherit these properties!

Alternatively, you can make the container into an actual room:

# maze/ROOM.yml — The maze entrance IS a room
room:
  name: "Maze Entrance"
  description: "Dark passages branch off in every direction..."
  
  exits:
    a: room-a/
    b: room-b/
    # ... etc

DESIGN CHOICE:

• Use CONTAINER.yml if you want inheritance without navigation (see container skill)
• Use ROOM.yml if you want the directory to be a navigable space

Hierarchy Example

adventure-4/
├── ADVENTURE.yml           # Adventure declaration
├── pub/
│   ├── ROOM.yml            # Room declaration
│   ├── stage/
│   │   └── ROOM.yml        # Region (type: region)
│   ├── bar/
│   │   └── ROOM.yml        # Region
│   ├── back-room/
│   │   └── ROOM.yml        # Private region
│   └── messages/
│       └── .meta.yml       # System directory (no ROOM.yml needed)
├── characters/
│   ├── ROOM.yml            # Hall of characters (type: personas)
│   └── don-hopkins/
│       └── CHARACTER.yml   # Character declaration
└── maze/
    ├── ROOM.yml            # Room declaration
    └── room-a/
        └── ROOM.yml        # Sub-room (full room, not region)

ROOM.yml Structure

room:
  name: "Debug Session"
  purpose: "Hunt down the authentication bug"
  
  context:
    - "Bug: Login fails with valid credentials"
    - "Suspected: Session cookie handling"
    
  cards_in_play:
    - instance: "goblin-001"
      card: "Git Goblin"
      goal: "Find when bug was introduced"
      
  working_set:
    - "ROOM.yml"
    - "state/progress.yml"
    
  exits:
    parent: "../"
    related: "../feature-work/"
    
  # Optional: position in 2D world-space
  world_position:
    x: 5
    y: 12
    
  # Optional: objects with positions in room-space
  objects:
    - name: "workbench"
      position: {x: 3, y: 7}

Spatial Coordinates

Rooms can exist in world-space. Objects can have positions in room-space.

# World-space: where is this room in the world?
world_position:
  x: 5
  y: 12

# Room-space: where are objects within this room?
objects:
  - name: "workbench"
    position: {x: 3, y: 7}

Navigation can use coordinates:

• NORTH from (5,12) → find room at (5,13)
• Named exits override coordinates

Not all rooms need coordinates. Abstract spaces can exist outside world-space.

Vehicles: Portable Rooms That Move

A vehicle is a room you can embark, drive, and disembark.

# vehicle-tent.yml
room:
  name: "Research Tent"
  is_vehicle: true
  world_position: {x: 5, y: 12}  # Changes when you drive

| Command | Effect | |---------|--------| | EMBARK tent | Enter the vehicle room | | DISEMBARK | Exit to current world location | | DRIVE NORTH | Move vehicle (and occupants) to (5,13) |

Riding the Turtle

RIDE the turtle. Move around the room, draw on the floor, jump through doors:

> RIDE turtle
You mount the turtle. The world scrolls beneath you.

> FORWARD 100
The turtle moves forward. A red line appears on floor.svg.

> RIGHT 90
> FORWARD 50
You're near the door-north.

> ENTER door-north
You jump through the door INTO the next room.
The turtle comes with you.

# turtle.yml — a vehicle within room-space
turtle:
  position: {x: 100, y: 100}
  heading: 90  # degrees, 0 = north
  pen_down: true
  pen_color: "#e94560"
  rider: "the-explorer"

| Command | Effect | |---------|--------| | RIDE turtle | Mount the turtle, move with it | | FORWARD 50 | Move forward, draw if pen down | | RIGHT 90 | Turn right | | ENTER door | Jump through door to connected room | | INTO subroom | Descend into nested sub-room | | ZOOM OUT | See the room graph navigator |

Lineage: Papert's Logo turtle, Rocky's Boots (1982), Robot Odyssey (1984).

Snap Cursor & Pie Menus

When you approach an object, the cursor snaps to it and shows a pie menu of scored actions:

        EXAMINE (80)
           ╱
 REPAIR ──●── USE (95) ← default
           ╲
        TAKE (20)

This IS The Sims interaction model:

• Objects advertise their available actions
• Actions are scored based on context, needs, state
• High-scoring actions appear prominently

Lineage: Don Hopkins' Pie Menus + Will Wright's SimAntics.

Cursor as Vehicle: Direct Manipulation

The cursor carries tools and applies them to the room floor:

> SELECT pen-tool
Cursor now carries: 🖊️ pen (red)

> CLICK workbench
*snap* Cursor at workbench. Pen ready.

> DRAG to door-north
Drawing line from workbench to door-north...
Line added to floor.svg

| Tool | Icon | Action | |------|------|--------| | pen | 🖊️ | Draw lines on floor | | eraser | 🧽 | Remove drawings | | selector | 👆 | Pick up and move objects | | linker | 🔗 | Draw connections between objects | | stamper | 📌 | Place copies of cards |

Throwing Objects: Data Flow Programming

Throw objects through exits. They pile up on the other side.

> THROW blueprint door-north
Throwing blueprint through door-north...
blueprint landed in assembly/inbox/

Inbox / Outbox

room/
  inbox/           # Objects thrown INTO this room land here
    task-001.yml
  outbox/          # Stage objects before throwing OUT
    result-001.yml

| Command | Effect | |---------|--------| | THROW obj exit | Toss object through exit | | INBOX | List waiting items | | NEXT | Process next item (FIFO) | | STAGE obj exit | Add to outbox | | FLUSH | Throw all staged objects |

Rooms as Pipeline Stages

Each room is a processing node. Exits are edges. Thrown objects are messages.

# Document processing pipeline:
uploads/          # Raw files land here
  inbox/
parser/           # Extract text
  script: parse.py
analyzer/         # LLM analyzes  
  prompt: "Summarize and extract entities"
output/           # Final results collect here

This is Kilroy-style data flow: rooms as nodes, files as messages, the filesystem as the network.

Inventories

Characters carry inventories — portable rooms always with them.

# character/inventory/
sword.card
map.yml
notes/
  finding-001.md

| Command | Effect | |---------|--------| | GET sword | Pick up from room → inventory | | DROP map | Put from inventory → room | | GIVE torch TO companion | Transfer to another character | | INVENT | List what you're carrying |

Your inventory IS a pocket dimension.

Nested Containers

Objects can contain other objects, to arbitrary depth:

> PUT screwdriver IN toolbox
> PUT toolbox IN backpack
> OPEN backpack
backpack contains:
  - toolbox (3 items)
  - sandwich

Object Paths

Address nested objects with paths:

> EXAMINE backpack/toolbox/wrench
> USE inventory/potions/healing
> TAKE ../chest/gold FROM here

Path syntax:

• container/sub/item — absolute within scope
• ./toolbox/wrench — relative to current
• ../sibling/item — parent's sibling
• /repo-name/path — multi-repo addressing

Tags for Search

> TAG wrench @favorite
> SEARCH backpack @tool
Found in backpack:
  toolbox/screwdriver [@tool]
  toolbox/wrench [@tool @favorite]

Room Graph Navigator

ZOOM OUT to see the whole world:

> ZOOM OUT
│  ROOM GRAPH: moollm-palace              │
│       [room] [card] [chat]              │
│         │                               │
│      [★ YOU ARE HERE]                   │

> LINK room TO card
Connection created. You can now JUMP directly.

| Command | Effect | |---------|--------| | ZOOM OUT | See room graph overview | | ZOOM IN room | Enter selected room | | LINK a TO b | Create connection between rooms |

Like Rocky's Boots: Navigate the structure. Edit while exploring.

Speed of Light vs Carrier Pigeons

Traditional multi-agent: Each agent in isolation. One LLM call per agent. Communication by carrier pigeon. Slow. Expensive. Sad.

MOOLLM: Simulate as many agents together as possible in ONE LLM call. Communication at the speed of light. Multiple simulation steps per iteration.

# In one LLM iteration:
simulation:
  - step: 1
    papert-001: "Microworlds need low floors"
    kay-001: "Yes! Like Smalltalk for children"
    
  - step: 2
    papert-001: 
      responds_to: kay-001
      says: "Exactly! Accessible entry, unlimited ceiling"
      
  - step: 3
    synthesis:
      emerged: "Low floor + high ceiling + prototypes = MOOLLM"

Three characters, three steps, instant cross-talk — ONE LLM call.

This IS The Sims

The Sims: One frame, all Sims simulated, instant interaction
MOOLLM:   One call, all cards simulated, instant messaging

Instead of isolated agent prisons, we have a shared microworld.

Room Navigation

| Action | What Happens | |--------|--------------| | Enter | Push room's working_set to context | | Exit | Pop context, return to parent | | Look | Read ROOM.yml and README.md | | Activate card | Clone card template into room | | Complete card | Card writes return_value, can be removed |

Nested Rooms (Virtual Zones)

Rooms can contain rooms (subdirectories) or virtual zones (no physical directory):

# cat-cave.yml — TARDIS-like nested room
id: cat-cave
type: [room, furniture]  # Both!

zones:  # Virtual sub-rooms
  nap-zone:
    description: "Sunny spot, cushions everywhere"
    path: "pub/cat-cave/nap-zone"  # Virtual path
  box-jungle:
    description: "Cardboard paradise"
    path: "pub/cat-cave/box-jungle"

Characters reference virtual zones:

# cat-terpie.yml
home: pub/cat-cave/
location: pub/cat-cave/nap-zone  # Virtual zone

Room Relationships

Rooms can remember visitors:

relationships:
  don-hopkins:
    visits: 3
    reputation: "regular"
    memory: "Always nice to the cats"

Home vs Location Protocol

Entities have home (where file lives) and location (where they are):

character:
  home: pub/cat-cave/terpie.yml     # File never moves
  location: pub/                     # Currently in pub

Movement updates location, not file. See character/.

Pie Menu Room Topology

Full specification: TOPOLOGY.yml

The eight-direction compass maps to two types of connections:

| Direction | Type | Function | |-----------|------|----------| | N/S/E/W | Cardinal | Navigate to major rooms (spiderweb) | | NW/NE/SW/SE | Diagonal | Expand into storage grids (quadrants) |

4 ways OUT (navigation) + 4 quadrants IN (infinite storage) = Unlimited worlds

Grid naming: {quadrant}-{x}-{y} (e.g., ne-2-3 = 2 east, 3 north in NE)

See: exit skill for PIE-MENU-TOPOLOGY protocol, memory-palace/ for Method of Loci

Codebase as Navigable World

Directories are rooms. Files are objects. Functions are chambers you can enter.

# Location paths with line numbers
location: "@central/apps/insights/pyleela/brain/Schema.py:142"

# Path syntax
- @repo/path/to/file.py       # file in repo
- @repo/path/to/file.py:42    # specific line
- @repo/path/dir/             # directory (room)

See character/ for party-based code review, README.md for detailed examples.

NPC Embedding Patterns

| Pattern | When | Example | |---------|------|---------| | cat-name.yml | Embedded NPC | pub/cat-terpie.yml | | name/CHARACTER.yml | Complex character | characters/don-hopkins/ | | staff-name.yml | Role-based grouping | pub/staff-marieke.yml |

See naming/ for conventions.

Rooms ARE Logistic Containers!

The Unification: Sims + Factorio

Rooms can participate in a logistics network:

| Feature | Source | MOOLLM | |---------|--------|--------| | Action advertisements | The Sims | Objects advertise what they DO | | Item requests | Factorio | Containers advertise what they NEED | | Attractiveness scores | Both | Higher score = higher priority |

Room Logistics Mode

room:
  name: "The Kitchen"
  
  logistics:
    mode: requester              # passive-provider, requester, buffer...
    request_list:
      - tags: ["ingredient"]
        count: 10
        priority: high

Logistic Advertisements

Rooms advertise their NEEDS with attractiveness scores:

logistic_advertisements:
  
  NEED_INGREDIENTS:
    description: "Kitchen needs ingredients"
    wants:
      - tags: ["ingredient"]
        count: 10
    score: 70                    # Base priority
    score_if: "chef_is_cooking"  # When to boost
    score_bonus: 30              # Total 100 when cooking!
    
  DESPERATELY_NEED_LIGHT:
    wants:
      - tags: ["light-source"]
        count: 1
    score: 100                   # Very high!

Stacking in Rooms

Rooms can have stacks of items:

room:
  name: "Armory"
  
  stacks:
    # Fungible (just count)
    arrow: 500
    bolt: 300
    
    # Instance (individual state)
    magic-sword:
      count: 3
      instances:
        - { id: flame-blade, damage: 50 }
        - { id: frost-edge, damage: 45 }
        
  stack_limit: 1000

Grid Room Cells

Warehouse rooms can be grid cells:

room:
  name: "Iron Ore Storage"
  type: grid-cell
  
  grid_cell:
    enabled: true
    parent: "../"
    coordinates: { x: 2, y: 3 }
    item_type: iron-ore
    
  stacks:
    iron-ore: 2500

The Flow

1. ROOMS advertise logistic needs with scores
2. LOGISTICS ENGINE collects all advertisements
3. Items route to HIGHEST-SCORING requester
4. BOTS or BELTS move items physically
5. ROOM receives items, fires on_item_added

See logistic-container/ and factorio-logistics-protocol.md.

The Philosophy

Spatial navigation IS cognitive navigation.

When you "enter" the debug-session room:

• Your context shifts to debugging
• Relevant cards are already in play
• The room's knowledge is loaded
• You know where the exits lead

Live Examples

• examples/adventure-3/pub/ — A room with NPCs
• examples/adventure-3/pub/cat-cave/ — Nested room with zones

Dovetails With

Sister Skills

• card/ — Cards live in rooms
• memory-palace/ — Memory Palace IS Room + mnemonic intent
• adventure/ — Adventure IS Room + narrative framing
• data-flow/ — Rooms as processing nodes
• speed-of-light/ — Multi-agent instant communication

Kernel

• kernel/context-assembly-protocol.md — Working set loading