jpmschweitzerandClaude Opus 4.6
dd75203d11
Persistent worktrees (server, client, copy, audio, visual, ci, planning,
maintenance) caused agents crossing boundaries, stuck agents leaving
uncommitted work, and index.lock collisions. Replaced with ephemeral
sprint branches (sprint-{N}/{team}) and worktrees created on demand.
Changes:
- New start-sprint script replaces start-session (dynamic tabs per active team)
- Sprint teardown integrated into sprint-start skill (A1c step)
- SR_DB_PATH env var for database access from any directory
- CLAUDE.md team boundaries rewritten (scope-based, not directory-based)
- Agent Rule 0 updated to team scope dirs instead of worktree isolation
- PR review uses git show instead of cross-directory reads
- Briefing template updated for sprint-{N}/{team} branch naming
- Deleted worktree-update skill (obsolete)
- Removed WORKTREE_TEAM env var and cross-directory Read permissions
- All 8 persistent worktrees removed
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
104 lines
7.6 KiB
Markdown
104 lines
7.6 KiB
Markdown
# The Settled Reach
|
|
|
|
A top-down life-sim — asymmetric information, occlusion-based perception, single-character perspective, Rimworld-style storyteller. Systems interactions like The Sims, combat and visuals like single-character Rimworld, world generation inheriting patterns from Dwarf Fortress and NMS, economy inspired by X4/EVE. Many systems interactable and ready for player participation, but capable of being ignored — the world is alive for any given run. Set in an original science fiction universe. Godot 4 client + Rust/bevy_ecs simulation server via subprocess/IPC.
|
|
|
|
**Official Title:** The Settled Reach
|
|
**Repository name:** settled-reach
|
|
**Version source of truth:** `project.yaml` (root `version` field, scheme: `0.1.{sprint_number}`)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
client/ # Godot 4 client
|
|
server/ # Rust/bevy_ecs simulation server
|
|
tooling/ # Build tools, scripts, asset pipelines
|
|
tests/ # Integration and end-to-end tests
|
|
docs/ # Architecture, design, briefings, sprints, workshops
|
|
db/ # Schema + seed data (connectors moved to tooling/db/)
|
|
.claude/ # Agents, skills, rules
|
|
decisions/ # Decision domain files (D-NNN confirmed, Q-NNN open, R-NNN rejected)
|
|
```
|
|
|
|
Full annotated tree: `.claude/rules/project-structure.md`
|
|
|
|
## DevOps
|
|
|
|
See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. All development operations go through the top-level `Makefile` — run `make` for a summary of targets.
|
|
|
|
## Development Cascade — First Things First
|
|
|
|
Development follows a strict cascade. Each phase has a concrete deliverable. **Do NOT discuss, design, or implement detail from a later phase while an earlier phase is incomplete.** If you encounter references to later-phase detail (room grammar, NPC bundles, heritage tokens, etc.) in documents or decisions, either ignore them silently and stay at the correct level, or flag that the reference is dragging attention to the wrong scope level and suggest it be rephrased or moved.
|
|
|
|
| Phase | Focus | Deliverable |
|
|
|-------|-------|-------------|
|
|
| 1 | Wiki content complete — all planets, moons, stations, heightmaps, artwork | Implant-ready Godot map of the Reach with click-throughs + wiki/GTTR popups |
|
|
| 2 | Economics layer — supply/demand, transport, political/social pressure, corporations, supply chains | Economics spreadsheets/graphs with runtime-tweakable simulation |
|
|
| 3 | Planetary/moon maps & station layouts — cities, rivers, mountains, roads, biomes, rail | Atlas of the Reach (implant app) |
|
|
| 4 | Player control scheme — 2-floor test map, character rendering, walls/stairs/doors, lighting | Player viewport with final-version assets |
|
|
| 5 | World generation (tile/chunk/block) — walkable world, parallel asset pipeline | Walkable generated world + asset catalog |
|
|
| 6 | Detail coloring — room-level NPC population, cultural room grammar | Only when the world is walkable |
|
|
|
|
**v0.2 target is dropped.** No scoping negotiations. Build the base systems fully.
|
|
|
|
## Agent Instructions
|
|
|
|
### Team boundaries
|
|
|
|
**Your team is determined by your sprint branch** (e.g. `sprint-31/server` → server team).
|
|
|
|
- All file paths are relative to the repo root (e.g. `server/src/bridge/types.rs`).
|
|
- **Stay within your team's scope.** Server team modifies `server/`. Client team modifies `client/`. Copy team modifies `wiki/`, `docs/atlas/`, `content/`. Shared directories (`docs/`, `decisions/`) are readable by all teams.
|
|
- **Do NOT modify files outside your team scope** unless the ticket explicitly requires it.
|
|
- **Never chain git commands** in a single Bash call (e.g. `git add ... && git commit ...`). Always run `git add` and `git commit` as **separate sequential Bash calls**.
|
|
- **Stale git lock files:** If a `git` command fails with `index.lock: File exists`, you may remove the lock file at `.git/index.lock` (or `.git/worktrees/<name>/index.lock` if in a worktree).
|
|
|
|
### Database
|
|
|
|
The ticketing database (`settledreach.db`) is accessed via `SR_DB_PATH` env var (set in `.claude/settings.json`). A backup is committed to `docs/backups/settledreach.db.backup` via main only.
|
|
|
|
### Before starting work
|
|
1. Read your sprint briefing at `docs/sprints/sprint-N/{team}.md` for current tasks
|
|
2. Use `tooling/db/ticket show <id>` for full ticket details
|
|
3. Read the relevant `decisions/*.md` domain file(s) referenced in the briefing
|
|
4. Background context: `docs/briefings/{your-name}.md`, `docs/discussions/`
|
|
|
|
### CLI tools
|
|
|
|
**Prefer CLI wrappers over raw SQL.** Never use the `sqlite3` CLI — it crashes in Claude Code (std::bad_alloc). Use the wrapper scripts instead.
|
|
|
|
| Tool | Command | Full reference |
|
|
|------|---------|----------------|
|
|
| Tickets | `tooling/db/ticket list`, `show`, `create`, `assign` | `/ticket` skill |
|
|
| Sprints | `tooling/db/sprint status`, `start-work`, `prepare` | `/sprint-start` skill |
|
|
| SQL queries | `tooling/db/sqlite-query "SELECT ..."` | — |
|
|
| SQL writes | `tooling/db/sqlite-exec "UPDATE ..."` | — |
|
|
| Decisions | `tooling/db/decision next`, `claim`, `check-dupes` | — |
|
|
| Doc search | `tooling/db/qdrant-search "query"` | `/docs-search` skill |
|
|
| Doc index | `tooling/db/qdrant-index path/to/file.md` | `/docs-search` skill |
|
|
|
|
### Testing preferences
|
|
|
|
- **Prefer live Gauntlet testing over mocks.** For visual tests and rendering verification, use the full client/server pipeline (`--test-mode` + `SR_LIVE=1`) instead of TestHarness mocks. The Gauntlet test world produces production-identical data. Mocks can mask rendering bugs by taking different code paths.
|
|
- **Gauntlet rooms are immutable.** Never modify existing rooms — new systems get new rooms. This ensures StableId determinism and fixture stability.
|
|
- Three test tiers: (1) Live server — highest fidelity, (2) MessagePack replay via `Protocol.decode_snapshot()` — for unreachable rooms, (3) TestHarness mock — for UI-only tests where fog data doesn't matter.
|
|
- `make fixtures-gauntlet` regenerates real server snapshot fixtures from the Gauntlet world.
|
|
|
|
### GDScript conventions
|
|
|
|
**Autoload parse-order rule:** Autoload scripts (`client/scripts/autoloads/`) compile before global `class_name` scripts are registered. Referencing a `class_name` type directly in an autoload causes a parse-time "not declared" error. Pattern:
|
|
- Declare fields untyped: `var my_field = null` (comment the intended type)
|
|
- Do **not** reference `class_name` types at the top level or in `_ready()` of autoloads
|
|
- In method bodies called at runtime (e.g. `apply_snapshot`), use `load()` inline — by then the script is cached and `load()` returns the cached resource without reloading: `var CVD := load("res://scripts/rendering/character_visual_descriptor.gd")`
|
|
- Do **not** cache the `load()` result in `_ready()` — `_ready()` fires during autoload init, before the target script is in the resource cache, causing an actual file reload that breaks self-references in scripts using their own `class_name`
|
|
|
|
`game_state.gd` (`character_visual_descriptor` field) and `sim_bridge.gd` (`harness` field) follow this pattern.
|
|
|
|
### File conventions
|
|
- Decisions: domain files in `decisions/` (see `decisions/README.md` for index)
|
|
- Decision IDs: `D-NNN` (confirmed), `Q-NNN` (open questions), `R-NNN` (rejected)
|
|
- **Claim IDs before writing:** `tooling/db/decision claim D <domain> "title"` — prevents ID collisions across parallel branches
|
|
- Diagrams: `.d2` source + `.png` renders in `docs/diagrams/{category}/`. Create or update diagrams via `/d2-diagram` when D-records are added or modified.
|
|
- Discussion rounds: numbered sequentially, archived to `docs/discussions/` when complete
|
|
- Briefings: one per agent, updated after decision-producing rounds
|
|
- Tickets: managed via `tooling/db/ticket` CLI or `/ticket` skill
|