# Fantasy Gamebook Engine

A solo-play **gamebook** (Fighting Fantasy–style) engine where an AI acts as the
game master and narrator. The whole design turns on one hard rule:

> **The AI never invents numbers or rolls dice in prose.** All randomness, state, and combat
> math go through an MCP server. The AI only narrates and offers choices.

Everything numeric — dice, attribute generation, luck tests, combat rounds, persistence — is
owned by a deterministic Python engine and exposed to the narrator as **MCP tools**. The
narrator (Phase 1: Claude Code) reads real state, calls tools, and writes the story around the
results.

**Status:** Phase-1 MVP — implemented and green. Python engine under `src/gamebook/`, an MCP
server exposing **18 tools**, **158 passing tests** at **96% coverage** across `tests/engine`,
`tests/server`, and `tests/qa`. The narrator harness lives as Claude Code skills and commands
under `.claude/`.

---

## Why it's built this way

The system decomposes into 8 modules, and the **golden rule of the design** is that
dependency arrows point only at *interfaces/contracts*, never at concrete implementations.
That discipline is what makes three things swappable without touching the rest:

1. **Storage** — `JSONStorage` today, `PostgresStorage` tomorrow. Injected at server startup.
2. **Adventure** — swap the lore module without touching the engine. Today a `SKILL.md`.
3. **Harness** — swap who narrates (terminal → web) while reusing the same MCP tool contract.

```
07 harness ───────► 05 mcp ◄──────── 08 commands
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
   01 rules      04 combat     03 storage (interface)
        │             │             ▲
        └──────►──────┘             │ implements
                  │                 │
                  ▼                 │
            02 domain ◄─────────────┘   (shared data contracts)

06 adventure-module ──(lore consumed by)──► 07 harness
```

| #  | Module             | Responsibility                                                                 | Pluggable?              |
|----|--------------------|--------------------------------------------------------------------------------|-------------------------|
| 01 | `rules`            | Pure rules engine — dice, attributes, luck test, one combat round. No I/O, RNG injected. | — (stable)   |
| 02 | `domain`           | Shared data contracts + invariant validation. Depends on nothing.              | — (stable)              |
| 03 | `storage`          | Persistence behind the `StorageBackend` interface.                             | ✅ JSON ↔ Postgres      |
| 04 | `combat`           | Combat lifecycle (start → rounds → flee → end).                                | —                       |
| 05 | `mcp`              | MCP server exposing tools to the harness. No game rules of its own.            | — (stable contract)     |
| 06 | `adventure-module` | Pluggable static lore (zones, bestiary, victory). Debut: **Ignarok**.          | ✅ Ignarok ↔ others     |
| 07 | `harness`          | The narrator/master that talks to the player and calls the MCP.                | ✅ Claude Code ↔ agent  |
| 08 | `commands`         | System commands (`/hero`, `/backpack`, `/map`, `/save`).                       | ✅ add new ones         |

## Project layout

```
src/gamebook/
  domain/    # data contracts: CharacterSheet, World, Event, Combat, ArchiveRecord
  rules/     # pure rules engine (interfaces + implementation), injectable RNG
  storage/   # StorageBackend interface + JSONStorage + in-memory impl
  combat/    # combat lifecycle (interfaces + implementation)
  mcp/       # FastMCP server over stdio — orchestrates the modules
docs/
  00-index.md … 08-commands.md   # specs (requirements)
  CONTRACTS.md                   # authoritative English code contract
  adrs/                          # architecture decision records
  learning-lessons/              # captured gotchas
.claude/
  skills/    # game-master, combat-sub-agent, ignarok (the Phase-1 harness)
  commands/  # /hero, /backpack, /map, /save
tests/
  engine/  server/  qa/
```

## Requirements

- Python **3.13** (`.python-version`), `requires-python >= 3.12`
- [`uv`](https://docs.astral.sh/uv/) for dependency management and running

## Quickstart

```bash
# Run the full test suite
uv run pytest -q

# Scope it
uv run pytest tests/engine -q     # pure rules (seeded RNG, in-memory storage)
uv run pytest tests/server -q     # storage + MCP server
uv run pytest tests/qa -q         # plugability / isolation / e2e

# The golden-rule plugability audit (catches any module reaching past an interface)
uv run pytest tests/qa/test_dependencies.py tests/qa/test_isolation.py -q

# Start the MCP server over stdio (exits cleanly on EOF)
uv run python -m gamebook.mcp.server
```

The server is registered for Claude Code in `.mcp.json`, so the narrator skills can call it
directly.

## MCP tools (18)

The authoritative contract is `docs/CONTRACTS.md` §6. Grouped by purpose:

| Group       | Tools                                                                                   |
|-------------|-----------------------------------------------------------------------------------------|
| Dice & luck | `roll_dice`, `test_luck`                                                                 |
| Character   | `create_character`, `read_character_sheet`, `update_character_sheet`, `archive_character`|
| World       | `read_world`, `update_world`                                                             |
| Chronicle   | `register_event`, `read_events`, `read_summary`, `update_summary`                        |
| Combat      | `start_combat`, `resolve_combat_round`, `flee_combat`, `end_combat`                      |
| Saves       | `save_progress`, `load_progress`                                                         |

## Game rules (reference)

- **Attributes:** `skill` = 1d6+6, `stamina` = 2d6+12, `luck` = 1d6+6 — each tracks `initial`/`current`.
- **Luck test:** success if roll ≤ current luck; luck always decrements by exactly 1 afterward.
- **Combat round:** each side's attack strength = `skill` + 2d6; higher AS hits for base
  damage 2, a tie deals 0.
- **Luck on a hit:** won+lucky → 4, won+unlucky → 1, lost+lucky → 1, lost+unlucky → 3.
- **Death / flee:** hero at 0 stamina → `alive: false`; fleeing costs 2 stamina and only if allowed.

`rules` and `combat` are tested in full isolation with a seeded RNG and in-memory storage —
deterministic, no disk, no AI.

## Playing a session (Phase-1 harness)

When you sit down to **play** rather than develop, Claude Code becomes the Game Master.

**Session-opening rule:** before narrating anything, the master reads real engine state via
MCP (`read_character_sheet`, `read_world`, `read_events`, `read_summary`). No living character
→ it offers `create_character` and starts the adventure's opening. A living character → it
resumes from the exact recorded point (never restarts, re-rolls, or contradicts recorded
facts). Every number and state change routes through MCP tools.

- **Skills** (`.claude/skills/`): `game-master` (narrator), `combat-sub-agent` (runs one
  fight), `ignarok` (the debut adventure — swap this file to swap adventures).
- **Commands** (`.claude/commands/`): `/hero`, `/backpack`, `/map`, `/save` — read-outs and
  checkpoints that reflect real MCP state and don't advance the story.

## Documentation

- **`docs/00-index.md`** — start here; maps every module.
- **`docs/CONTRACTS.md`** — the authoritative English code contract (cross-module interfaces,
  domain schema §2, MCP tool contract §6). When code and a spec disagree, CONTRACTS.md governs.
- **`docs/adrs/`** — architecture decision records (ADR-001 … ADR-010).
- **`docs/learning-lessons/`** — captured gotchas worth not relearning.
- **`CLAUDE.md`** — guidance for Claude Code working in this repo.

## Roadmap

- **Phase 1 (current):** Claude Code as harness, `JSONStorage`, adventure as `SKILL.md`.
- **Phase 2:** a PydanticAI/FastAPI harness with structured `Scene` output for a web frontend,
  plus `PostgresStorage` — reusing the *same* MCP tool contract and adventure module unchanged.
  That reuse is the entire point of the architecture.