diff --git a/README.md b/README.md index d81bde2..2d2bd2c 100644 --- a/README.md +++ b/README.md @@ -1,110 +1,215 @@ -# Claude Kingdoms - -An open-source medieval grand strategy game powered by Claude Code session activity. - -> **GIF placeholder** — `docs/media/session-to-reward-loop.gif` (PRD acceptance criterion #11). To be recorded after the M4 tutorial map is in place; capture target is a 30-second loop showing: (1) bridge daemon running, (2) Claude Code session active, (3) plan + goal events firing, (4) end-turn in Unciv, (5) per-city resource increase landing on the map. See `docs/media/README.md` for the recording protocol. - -## Vision - -Turn your real Claude Code sessions into an empire. Every plan created, every goal completed, and every active session grows your kingdom. Idle hands stir nothing; active minds stir empires. The kingdom never decays when you step away — but it only grows when you return. - -## Quick Start - -```bash -git clone https://github.com/SolshineCode/ClaudeKingdoms -cd ClaudeKingdoms -pip install -r requirements.txt -python run_tui.py -``` - -First launch shows the onboarding screen. After that, any save at `./saves/kingdom_save.json` is auto-loaded. - -### Key bindings (TUI) - -| Key | Action | -|-----|--------| -| `g` | Inject TaskCompleted (goal +1, momentum +1) | -| `p` | Inject SubagentStart Plan (plan +1) | -| `r` | Inject PermissionDenied (Redirect: momentum → 0) | -| `a` | Inject UserPromptSubmit (mark active) | -| `t` | Advance turn (score → save → callbacks) | -| `s` | Save now | -| `q` | Quit (auto-saves first) | - -## Development Status - -| Milestone | Status | Notes | -|---|---|---| -| Pre-M0 Spikes (1+2) | ✅ | ADR-001, ADR-002, save/load + observability spikes merged | -| M0 Scaffolding | ✅ | Bridge layer, TUI skeleton, JSON schema v1.0, ADR-003, CI | -| M1 Vertical Slice | 🟡 | SaveExchange, city_id mapping, close/reopen, E2E tests done; live wiring in progress | -| M2 Core Economy | 🟡 | HookListener, BridgeLoop integration, manual injection, per-city scoring done | -| M3 Medieval Aesthetic | 🟡 | Parchment palette, medieval voice, onboarding screen done; Unciv-side pending | - -102 tests passing on `main`. CI runs pytest on every push and PR. - -## Architecture - -``` - ┌──────────────────┐ - │ Claude Code │ - │ (your work) │ - └────────┬─────────┘ - │ JSONL hook events - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ Python Bridge │ -│ │ -│ HookListener ──→ SessionState ──→ ScoringEngine │ -│ │ │ │ │ -│ └──────────────────┴───────────────────┘ │ -│ │ │ -│ ┌───────┴────────┐ │ -│ ▼ ▼ │ -│ BridgeLoop SaveExchange │ -│ (turn pump) (file I/O) │ -└──────┬──────────┬─────────────────┬──────────────────────────┘ - │ │ │ - ▼ ▼ ▼ - Textual TUI ./saves/ Unciv mod - (live view) kingdom.json (game-side, M2+) -``` - -See: -- `docs/prd/ClaudeKingdomsPRD.md` — full vision and milestone definitions -- `docs/adr/` — architectural decision records (1: save injection, 2: hooks observability, 3: bridge architecture) -- `docs/bridge-tui-schema.md` — versioned Bridge–TUI JSON schema v1.0 - -## Repo layout - -``` -bridge/ Python bridge daemon (state, scoring, hook ingestion, save exchange) - tests/ Bridge unit + E2E tests -tui/ Textual TUI (panels, bindings, onboarding screen, medieval voice) - tests/ TUI tests -spikes/ Pre-M0 feasibility spikes (Java + Python PoCs) -docs/ PRD, ADRs, schema documents -scripts/ Auxiliary scripts (hello-world smoke, hook logger PoC) -.github/workflows/ CI (pytest on push/PR) -run_tui.py Cross-platform TUI launcher -``` - -## Testing - -```bash -pytest -q # full suite (~1.5s) -pytest bridge/tests/test_e2e_vertical_slice.py -v # the "vertical slice" E2E -bash scripts/hello.sh # repo-checkout smoke -``` - -## Contributing - -PRD §"Open-Source Operations" covers the contributor flow. TL;DR: - -- Test-first when feasible (PRD design pillar #5: "TDD by default") -- Local commits welcome; remote pushes via PR -- The Bridge–TUI JSON schema (`docs/bridge-tui-schema.md`) is the binding contract — TUI contributors and Bridge contributors both consume it - -## License - -MIT. See `LICENSE`. +# Claude Kingdoms + +An open-source medieval grand strategy game powered by Claude Code session activity. + +--- + +## ⚠ Pre-alpha — NOT a working game yet + +> **Status: pre-alpha / pre-V1. Not a playable game today.** Read +> this section before cloning if you're hoping to play. +> +> **What works right now (verified, tested):** +> - A Python bridge daemon that ingests Claude Code hook events and +> keeps session state, scoring, plans, goals, momentum, tokens. +> 248 unit + integration tests pass on every push. +> - A Textual TUI sandbox (`python run_tui.py`) where you can drive +> session state through keyboard bindings and watch resources +> accumulate. **This is a developer sandbox, not the game.** +> - A small medieval-flavor JSON mod folder +> (`mod/ClaudeKingdoms/`) with civilization, building, belief, and +> tutorial content for Unciv. +> +> **What does NOT work yet (honest list):** +> - **The actual game is not playable.** The bridge↔Unciv integration +> leg is unimplemented. Earlier project iterations shipped a Lua +> "mod hook" that turned out to be architectural fiction — Unciv +> does not support runtime Lua scripting (see +> `docs/unciv-research-2026-05-11.md`). That code has been removed +> from the repo. The replacement model is an **external save-edit +> tool** that mutates an Unciv save file while the game is closed +> (per ADR-001). That tool has not been written yet. +> - **The mod has not been validated against Unciv.** The JSON +> content in `mod/ClaudeKingdoms/` uses plausible field names but +> has never been parsed by a running Unciv. Only `Buildings.json` +> and `Units.json` (which we don't have) are officially +> "schema-validated" per Unciv's docs. Loading the mod will +> probably surface JSON-shape errors that need fixing. +> - **No playtest has happened.** PRD §M4 "fun-factor check" has +> not been performed. Whether the gameplay is fun is unknown. +> - **No GIF in the README.** That's intentional — recording a real +> demo depends on the loop above actually working in Unciv first. +> +> **What's the right expectation?** If you clone today, you'll get +> a clean tested Python bridge + a TUI you can poke + some Unciv +> mod JSON content. You will NOT get a Civ-like strategy game +> driven by your coding work. That's the goal, not the current +> state. +> +> See **`.claude/handoff.md`** for the full honest status +> (acceptance-criteria grid + critical-path next steps) and +> **`docs/audit-2026-05-08.md`** (with its 2026-05-11 retraction +> header) for the audit history. + +--- + +## Vision + +Turn your real Claude Code sessions into an empire. Every plan +created, every goal completed, and every active session grows your +kingdom. Idle hands stir nothing; active minds stir empires. The +kingdom never decays when you step away — but it only grows when +you return. + +## Quick Start (TUI sandbox only) + +```bash +git clone https://github.com/SolshineCode/ClaudeKingdoms +cd ClaudeKingdoms +pip install -r requirements.txt +python run_tui.py +``` + +First launch shows the onboarding screen. After that, any save at +`./saves/kingdom_save.json` is auto-loaded. + +### Key bindings (TUI) + +| Key | Action | +|-----|--------| +| `g` | Inject TaskCompleted (goal +1, momentum +1) | +| `p` | Inject SubagentStart Plan (plan +1) | +| `r` | Inject PermissionDenied (Redirect: momentum → 0) | +| `a` | Inject UserPromptSubmit (mark active) | +| `t` | Advance turn (score → save → callbacks) | +| `s` | Save now | +| `q` | Quit (auto-saves first) | + +### Run the daemon (production-shaped bridge, no UI) + +```bash +python -m bridge.daemon # turn loop + stdin hook ingestion +python -m bridge.daemon --no-hooks # turn loop only +``` + +Writes `./saves/kingdom_save.json` (state) and `./logs/audit.jsonl` +(event log). See `docs/hooks-setup.md` for how to actually wire +Claude Code's hook stream into the daemon's stdin. + +## Critical-path next steps (not done yet) + +1. **Install Unciv** (`https://github.com/yairm210/Unciv`) and try + to load `mod/ClaudeKingdoms/`. Iterate on JSON field names until + the mod loads cleanly. +2. **Inspect an Unciv save file** on disk. Determine its format and + where per-city yields live. +3. **Write the external save-edit tool** that reads the bridge's + `kingdom_save.json` and mutates an Unciv save file with per-city + deltas while the game is closed. This is the missing piece. +4. **Playtest** with the actual loop running and make calibration + decisions on the scoring constants. + +Until step 3 is done, **the game does not actually work.** The +Python bridge half is real. The Unciv half is a content pack with +an unimplemented save-edit tool waiting to be built against it. + +## Development Status + +| Milestone | Bridge side | Unciv side | +|-----------|-------------|------------| +| Pre-M0 Spikes (1+2) | ✅ ADRs published | n/a | +| M0 Scaffolding | ✅ | n/a | +| M1 Vertical Slice | ✅ | ❌ (needs save-edit tool) | +| M2 Core Economy | ✅ | ❌ (needs save-edit tool) | +| M3 Medieval Aesthetic | ✅ (TUI palette + onboarding) | 🟡 (JSON content only, unvalidated) | +| M4 Operators + Campaign | ❌ | ❌ | +| M5 Community Launch | ❌ | ❌ | + +248 tests passing on `main`. CI runs `pytest` on every push and PR. + +## Architecture (current, after 2026-05-11 cleanup) + +``` + ┌──────────────────┐ + │ Claude Code │ + │ (your work) │ + └────────┬─────────┘ + │ JSONL hook events + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Python Bridge │ +│ │ +│ HookListener ──→ SessionState ──→ ScoringEngine │ +│ │ │ │ │ +│ └──────────────────┴───────────────────┘ │ +│ │ │ +│ ┌───────┴────────┐ │ +│ ▼ ▼ │ +│ BridgeLoop SaveExchange │ +│ (turn pump) (file I/O) │ +└──────┬──────────┬─────────────────┬──────────────────────────┘ + │ │ │ + ▼ ▼ ▼ + Textual TUI ./saves/ [save-edit tool: NOT BUILT] + (live view) kingdom.json │ + ▼ + [Unciv save file] + ▼ + Unciv game +``` + +The dotted-line section (save-edit tool through Unciv) is the +unimplemented critical path. + +See: +- `docs/prd/ClaudeKingdomsPRD.md` — full vision and milestone definitions +- `docs/adr/` — architectural decision records +- `docs/bridge-tui-schema.md` — versioned bridge save-exchange JSON schema +- `docs/unciv-research-2026-05-11.md` — Unciv mod-system research +- `docs/audit-2026-05-08.md` — CTO audit (with 2026-05-11 retraction) +- `.claude/handoff.md` — current honest status + +## Repo layout + +``` +bridge/ Python bridge daemon (state, scoring, hooks, save, audit log) + tests/ 248 unit + integration tests +tui/ Textual TUI (panels, bindings, onboarding, medieval voice) + tests/ TUI tests (incl. Pilot) +mod/ClaudeKingdoms/ Unciv mod content (JSON only; unvalidated) +docs/ PRD, ADRs, schema, hooks-setup, audit, research +.github/workflows/ CI (pytest on push/PR) +run_tui.py Cross-platform TUI launcher +``` + +## Testing + +```bash +pytest -q # full suite (~5s) +pytest bridge/tests/test_e2e_vertical_slice.py -v # bridge-side E2E +bash scripts/hello.sh # repo smoke test +``` + +## Contributing + +See `CONTRIBUTING.md`. TL;DR: pick one of four paths (Bridge / TUI / +Mod content / Docs), write tests first when feasible, open a PR +against `main`, CI must be green before merge. Five vetted +`good first issue` candidate bodies live in +`docs/good-first-issues.md`. + +## License + +MIT. By contributing, you agree your contribution is MIT-licensed. + +## A note on what this is + +This project is an experiment in "gamifying" real cognitive work +through a strategy-game wrapper. It came out of a couple of intense +multi-day collaborative sessions between a human (Caleb) and several +AI agents (Hermes Agent + Claude Code). It is published in its +honest current state — pre-alpha, partly fictional in places that +have now been retracted, but with a clean tested core and a clear +path forward — rather than a polished-looking-but-broken state. If +that openness is useful to you, welcome. If you want a finished +game, this is not yet that.