docs(readme): pre-alpha disclaimer + honest status #35
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -1,110 +1,215 @@ | ||||||||
| # 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) | ||||||||
|
There was a problem hiding this comment. The
Suggested change
|
||||||||
| 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. | ||||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The architecture diagram refers to
kingdom.json, but the project consistently useskingdom_save.jsonelsewhere (e.g., lines 74, 95, and inbridge/save_exchange.py). Updating this will ensure documentation consistency.