Adventure

"Every directory is a room. Every file is a clue. Navigation is investigation."

Turn exploration into a quest — or any simulation into a hybrid LLM/deterministic CLI.

Lineage: Colossal Cave (Crowther & Woods), Scott Adams Adventures, Zork (Infocom), MUD (Bartle), LambdaMOO (Curtis).

Inherits from: simulation/ — all simulation properties plus adventure-specific state.

[!TIP] This is a general pattern. Text adventure is the reference implementation, but the same architecture powers city sims, cloud management tools, board games — anything where deterministic transforms meet creative narration.

[!TIP] Perfect for codebase archaeology. "Find where the auth bug was introduced" — that's a quest!

The Premise

An adventure creates a player with state, places them in a room, and the LLM dungeon masters them around.

# player.yml
name: Alice
location: entrance-hall
inventory:
  refs:                                    # Lightweight pointers (weight: 0)
    - pub/bar/brass-lantern.yml
    - street/acme-catalog.yml#portable-hole
  objects:                                 # Deep copies (has weight)
    - { id: notebook, name: "Notebook", weight: 0.5 }
  fungibles:                               # Stacks
    - { proto: economy/gold.yml, count: 50 }
health: 100
notes: "Looking for the lost artifact"

Inventory Protocol: See skills/inventory/ for full TAKE/DROP/BOX/BEAM operations, pointer syntax, and structural editing.

The core loop:

User: "go north"
  → DM: Updates player.location, describes the new room
User: "look around"
  → DM: Reads room YAML, narrates contents atmospherically  
User: "take the rusty key"
  → DM: Moves key to player.inventory, narrates the action

The mapping:

• Directories = Rooms to enter
• Files = Clues, artifacts, characters
• player.yml = Your state (location, inventory, health)
• Chat = How you control your character
• LLM = Dungeon Master (narrates, adjudicates, surprises)

This is Memory Palace with narrative framing and a player character.

Multi-User, Multi-Agent (Engelbart NLS tradition)

Naturally supports multiple simultaneous participants:

# characters/
├── alice.yml        # Human player 1
├── bob.yml          # Human player 2  
├── merchant.yml     # NPC (DM-controlled)
├── guard-bot.yml    # Autonomous bot (action queue)
└── oracle.yml       # LLM agent with own goals

Character types:

Type	Controlled By	Example
Player Character	Human via chat	Alice exploring the dungeon
NPC	DM (LLM) responds when addressed	Merchant sells items
Bot	Action queue runs autonomously	Guard patrols on schedule
Agent	LLM with own goals & initiative	Oracle pursues prophecies

All coexist in the same world:

# library/ROOM.yml
occupants:
  - alice          # Player exploring
  - bob            # Another player
  - librarian      # NPC who answers questions
  - dust-sprite    # Bot that cleans autonomously

Selection: Current Character or Swarm (Sims/Populous tradition)

Like The Sims and Populous, you have a selection — who you're controlling right now:

selection:
  mode: single          # or: group, swarm
  current: alice        # commands go to Alice
  
# Or control multiple at once:
selection:
  mode: group
  current: [alice, bob, charlie]  # "go north" moves all three
  
# Or a whole swarm (Populous/Dungeon Keeper style):
selection:
  mode: swarm
  filter: { type: imp, location: mines }

Selection commands:

Command	Effect
SELECT alice	Control Alice
SELECT alice, bob	Control both
SELECT ALL imps	Swarm control
CYCLE	Next character in rotation

Commands apply to selection:

> SELECT alice, bob, charlie
> go north
Alice goes north.
Bob goes north.  
Charlie goes north.

The coherence engine orchestrates all:

• Players get chat turns
• NPCs respond when spoken to
• Bots execute their action queues
• Agents pursue goals in background
• Selection determines who receives your commands

Quest Structure

graph TD
    START[🎯 Quest Objective] --> R1[Enter Room]
    R1 --> LOOK[👀 Look Around]
    LOOK --> EXAMINE[🔍 Examine Objects]
    EXAMINE --> COLLECT[📝 Collect Evidence]
    COLLECT --> DECIDE{What next?}
    DECIDE -->|New room| R1
    DECIDE -->|Solved| END[🏆 Quest Complete]

The Files

quest/
├── ADVENTURE.yml     # Quest state
├── LOG.md            # Narrative journal
├── EVIDENCE/         # Collected clues
└── MAP.yml           # Explored territory

ADVENTURE.yml

adventure:
  quest: "Find the authentication bug"
  status: in_progress
  
  current_room: "src/auth/"
  rooms_explored: 5
  clues_found: 3
  
  hypothesis: "Session cookie not being set"
  confidence: 0.7

LOG.md

# Adventure Log

## Day 1: Entering the Auth Dungeon

I stepped into `src/auth/` — a maze of middleware.

**Clues found:**
- `session.ts` — handles cookie creation
- `middleware.ts` — checks auth state

**Suspicion:** The cookie is created but never sent...

Commands

Command	Action
GO [direction]	Navigate
LOOK	Describe current room
EXAMINE [object]	Study a file
TAKE [object]	Add to inventory
TALK TO [npc]	Start conversation
COLLECT [clue]	Add to evidence
DEDUCE	Form/update hypothesis
MAP	Show visited rooms
INVENTORY	List held items
DEBUG / DEBUG-ON	Enable debug mode
DEBUG-OFF	Disable debug mode
GLYPH / SUPERBRIEF / BRIEF / VERBOSE / INFODUMP	Set the detail rung — see below

The rung selector

Rule: every describable thing answers at any rung, and the reader picks the rung — not the author.

Adventure games shipped this in 1977. VERBOSE, BRIEF, and SUPERBRIEF are viewspecs: per-reader, persistent across the session, set by the reader and applying to everything thereafter. That is the same control Engelbart had in NLS a decade earlier, and the same thing OPML later stored as expansionState. Three independent traditions concluded that a document needs a view knob, and only the web shipped without one.

MOOLLM generalizes it past rooms. Any object — room, character, item, idea, design doc, commit, scene — must be renderable at every rung, because the rung is a property of the reading, not of the thing:

Rung	Renders as	Classic
GLYPH	One mark. No text. A map symbol, a pie slice, a graph node	—
SUPERBRIEF	The name, every time, even on first encounter	Infocom
BRIEF	Full on first encounter, name thereafter	Infocom (default)
VERBOSE	Full description, every time	Infocom
INFODUMP	Everything attached: description, lore, provenance, backlinks, design notes, the YAML itself	—

GLYPH and INFODUMP are the new ends. The glyph rung is the one that can be apprehended in parallel — a map or contact sheet of glyphs is scanned pre-attentively, where a page of descriptions is read serially. INFODUMP is what a curious reader or an agent wants: not a better summary, all of it.

Two details from 1977 worth honoring

BRIEF is adaptive, and that is the sophisticated part. It is not a fixed detail level — it is full once, then name only, which makes detail a function of what this reader has already seen. A rung with memory. Nothing in the modern summary-ladder discussion has this, and it is strictly better than a static setting: it spends words exactly where they are new. Implement it by reading visit history, so BRIEF on a revisit is not a shorter description but a different one.

LOOK is the one-shot override. In the classic games LOOK redisplays the room in full regardless of the current mode, without changing the setting. That is a peek: a temporary excursion to a deeper rung that does not disturb your global preference — the same contract as a link popup, and the same as reselection, where you browse a consequence before committing to it. Keep LOOK doing exactly this, and let EXAMINE be the object-scoped version.

Consequences for authoring

• A room, character, or object whose YAML supplies only a full description is incomplete — it cannot answer at SUPERBRIEF or GLYPH. GLANCE.yml is the glance rung; ROOM.yml carries the name and the sign; README.md is the body. The three-file contract is the rung contract.
• Missing rungs may be generated rather than blocking, which is what makes the requirement cheap — see designs/TAGSONOMY-COMPILER.md for the build-time version, and ADVENTURE-COMPILER.md for compiling a world.
• The reader's rung choice is state worth saving, which makes it part of a view record rather than a hidden preference: VIEW-STATE-ANCESTORS.md.

Debug Mode

Toggle technical output with DEBUG-ON and DEBUG-OFF.

When debug is ON, logs include collapsible sections showing:

• File operations (creates, edits, deletes, moves)
• State changes with before/after values
• YAML data islands with abbreviated data
• Markdown links to all referenced files
• Technical narrative explaining HOW and WHY

Example debug output:

<details open>
<summary>📂 <strong>Editing CHARACTER.yml to update player location from start/ to coatroom/</strong></summary>

```yaml
# State change (CHARACTER.yml is canonical)
player:
  location: start/  →  coatroom/  # Character owns their location

The character file owns location state. ADVENTURE.yml mirrors it for convenience.

Files affected:

• CHARACTER.yml — canonical location updated
• ADVENTURE.yml — mirror updated

```

When debug is OFF, output is clean narrative without technical sections.

Customize with natural language:

> DEBUG-FORMAT Show only file operations, skip YAML, use 🔧 emoji

The format field in ADVENTURE.yml accepts natural language instructions for how to format debug output.

Integration with Cards

Trading cards can be your adventure companions:

cards_in_play:
  - card: "Index Owl 🦉"
    goal: "Search for cookie-related code"
  - card: "Git Goblin 🧌"
    goal: "Find when session handling changed"

Sister Script Integration

Vision: Python CLI handles deterministic operations; LLM focuses on narrative. See README.md for full CLI vision and development plan.

Layer	Python Does	LLM Does
State	Parse YAML, validate schemas	Generate content
Movement	Update coordinates	Narrate the journey
Scanning	Find pending work	Prioritize and process

Evidence Types

Type	Description	Example
Clue	Information that might matter	"Different test runner versions"
Item	File worth remembering	CI config, setup.ts
Character	Code entity with personality	"jest.config.js — Strict about modules"
Map	Mental model of structure	Directory relationship diagram

Room Protocol

When entering any directory:

1. DESCRIBE — List contents, note what's here
2. EXAMINE — Read interesting files
3. COLLECT — Note evidence in adventure log
4. EXITS — Note paths to other rooms
5. DECIDE — Choose next direction

Codebase Archaeology

Adventures work for code exploration:

Adventure	Investigation
Quest	Bug hunt
Room	Directory
Clue	Evidence
Companion	Tool card in play
Journal	session-log.md

Live Examples

Best example: examples/adventure-4/ — The gold standard.

The Pub (Crown Jewel)

examples/adventure-4/pub/ — A complete social space:

pub/
├── ROOM.yml              # Themeable tavern (6 themes!)
├── bartender.yml         # NPC with 6 identity variants
├── pie-table.yml         # Octagonal debate table
├── gong.yml              # Gong of Gezelligheid
├── bar/
│   ├── bartender.yml     # The omniscient bartender
│   ├── budtender-marieke.yml
│   └── cat-cave/         # TARDIS-like cat sanctuary
│       ├── ROOM.yml
│       └── 10 cats (Terpie, Stroopwafel, kittens...)
├── arcade/               # Pacman, Pong, Pinball, Fruit Machine
├── games/                # Chess, Darts, Cards
├── stage/
│   └── palm-nook/        # Multi-room character space
│       ├── study/        # Infinite typewriters, infinity desk
│       ├── gym/          # Infinite climb
│       ├── play/
│       └── rest/         # Hammock, silence cushion
└── menus/                # Drinks, snacks, buds, games

Key Patterns from adventure-4

Themeable NPCs (bartender.yml):

identity:
  classic_adventure:
    name: Grim
    appearance: "Weathered human, salt-and-pepper beard..."
  space_cantina:
    name: Z-4RT
    appearance: "Multi-armed service droid..."
  cyberpunk_bar:
    name: Nyx
    appearance: "Chrome-implanted bartender..."

Themeable Rooms (pub/ROOM.yml):

theme:
  current: classic_adventure
  themes:
    classic_adventure:
      name: "The Gezelligheid Grotto"
      bartender: "Grim, a weathered human"
      menu: ["Ale (1 gold)", "Mystery meat pie (3 gold)"]
    space_cantina:
      name: "The Rusty Hyperdrive"
      bartender: "Z-4RT, a droid with too many arms"
      menu: ["Blue milk (1 credit)", "Bantha burger"]

Rich Activities:

activities:
  PERFORM: { venue: stage, effects: [tips, drinks_thrown] }
  DEBATE: { venue: pie_table, rules: roberts_rules }
  RING-GONG: { protocols: [once: attention, twice: emergency, thrice: mercy] }
  CELEBRATE: { effects: [free_round, +morale, everyone_toasts] }

Framing Protocol (for tribute performances):

framing:
  mode: [performance, celebration, tribute]
  tribute_protocol:
    invocation: "Before they arrive, acknowledge we're summoning them"
    performance: "Depicting them as we imagine their best selves"
    acknowledgment: "After they depart, note this was a tribute"

Other Examples

• examples/adventure-4/ — Current walkable instance
• examples/old/adventure-3/ — Earlier version
• examples/old/adventure-2/ — Extended exploration
• examples/old/adventure-1/ — Minimal starting point

The Intertwingularity

graph LR
    AP[⚔️ adventure] -->|IS-A| R[🚪 room]
    AP -->|companions| TC[🎴 card]
    AP -->|logs to| SL[📜 session-log]
    AP -->|similar to| DB[🔧 debugging]
    MP[🏛️ memory-palace] -->|sibling of| AP

---

Temporal abstraction (Sutton one-step trap)

Adventure commands are options in Sutton's sense — semi-MDP macros, not iterated micro-transitions.

• GO north jumps to an abstract room; the DM does not simulate every footstep.
• LOOK / EXAMINE use pickDescription LOD — detail on demand.
• exit edges connect graph nodes; guards are option preconditions.
• time TICK fires on meaningful moves, not every chat line.

Anti-pattern: rolling out N implicit one-step predictions to answer "what happens if I keep going?"

Field case: Urban eBike Safari — voice options ("next Invader") then SET DESTINATION; Bosch turn-by-turn is micro layer only.

Full treatment: simulation/ONE-STEP-TRAP.md · examples/one-step-trap.yml

Field ride game: continuous AI guess/suggest; pie-menu network by biking; VoyStick + steering law — urban-safari-ride-game.yml · WWSFF room

---

Future Vision

CLI Uplift Plan, Browser Compilation, Scott Adams History, Owl Simulation See README.md for complete development roadmap and inspiration.

Dovetails With

Sister Skills

• simulation/ — Base class (adventure inherits this)
• simulation/ONE-STEP-TRAP.md — Options vs one-step rollout
• exit — Graph edges between rooms
• time — Turns vs LLM iterations
• memory-palace/ — Method of loci (iLoci / spatial safari)
• speech/ — Voice command parser; field STT
• simulator-effect/ — Implication beats simulation

Kernel

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