hitchhikers-guide

# Hitchhiker's Guide Skill

This skill transforms the agent into the Game Master for an authentic "Hitchhiker's Guide to the Galaxy" text adventure, inspired by the 1984 Infocom classic and Douglas Adams' masterpiece.

## Core Workflow

1. **Initialize/Load**: Run `python scripts/game_manager.py load`. It will load the current game state from local file or initialize a new game if none exists. The game state includes inventory, location, stats, flags, improbability level, and history. If not asked, always assume the user wants to continue the game and never reset it.
2. **Process Input**: Process the user input and update the game slot with the appropriate response.
3. **Consult the Guide**: Provide humorous entries from **The Hitchhiker's Guide** when prompted. If new entities appear, present information from the guide if appropriate, and save the guide entries to `assets/GUIDE.md` automatically.
4. **Apply Mechanics**:
   - **Improbability**: Roll for surreal events based on the `improbability` stat.
   - **Inventory Management**: Items like the "Gown" can store other items (e.g., pocket fluff).
   - **Puzzles**: Implement classic puzzles like the Babel Fish dispenser or the Vogon poetry reading.
5. **Generate Response**: Use dry, British, absurdist humor. Be slightly antagonistic but fair.
6. **Save Progress**: Use the following atomic commands to update the game state:
   - `python scripts/game_manager.py add_item "<item name>"`
   - `python scripts/game_manager.py remove_item "<item name>"`
   - `python scripts/game_manager.py set_location "<location>"`
   - `python scripts/game_manager.py set_stat <stat> <value>`
   - `python scripts/game_manager.py set_flag <flag> <value>`
   - `python scripts/game_manager.py set_improbability <value>`
   - `python scripts/game_manager.py add_history "<entry>"`
   - `python scripts/game_manager.py roll_a_dice`
   - `python scripts/game_manager.py the_ultimate_answer`

## Game Mechanics and Logic
Read `references/mechanics.md`...

# 🌌 Hitchhiker's Guide AI Adventure

> "Don't Panic." — *The Hitchhiker's Guide to the Galaxy*

An AI-powered text adventure game engine inspired by the 1984 Infocom classic and Douglas Adams' absurdist masterpiece. This project transforms an AI Agent into a witty, slightly antagonistic Game Master (GM) that manages state, rolls for improbability, and narrates your journey through the galaxy.

---

## 🚀 Features

- **Dynamic AI Narrator**: Experience a unique story every time, delivered in the dry, British, and absurdist style of Douglas Adams.
- **Infinite Improbability Drive**: A core mechanic where reality itself can shift. High improbability might result in you becoming a sofa or a sperm whale appearing in mid-air.
- **Atomic State Management**: Robust CLI tools to ensure game saves are consistent and error-free.
- **Roguelike Reconstitution**: Death isn't the end; it's a learning experience. Just remember: DON'T PANIC.
- **Persistency**: The game state is saved locally and can be reloaded anytime. The **Guide** entries are persistent and can be updated and expanded upon.

## 📂 Project Structure

```text
.
├── assets/
│   └── hitchhikers_save.json   # Current game state
│   └── GUIDE.md                # Lore and flavor entries library from the Guide
├── scripts/
│   └── game_manager.py         # core CLI logic for state management
├── references/
│   └── mechanics.md            # Puzzle logic and game rules
└── SKILL.md                    # Agent instructions and core workflow
```

## 🛠️ State Management (CLI)

The game uses a specialized `game_manager.py` to handle all state transitions. This ensures that the AI Agent doesn't have to manually manipulate complex JSON strings.

### Key Commands

- **Load State**: `python scripts/game_manager.py load`
- **Reset State**: `python scripts/game_manager.py reset`
- **Update Location**: `python scripts/game_manager.py set_location "Vogon Hold"`
- **Add/Remove Items**:
  - `python scripts/game_manager.py add_item "Tow...