settled-reach/CLAUDE.md

The Settled Reach

A top-down immersive sim — occlusion-based detective game with combat elements, set in an original science fiction universe. Single-character perspective, asymmetric information as core mechanic, Rimworld-style storyteller. 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 for build, test, lint, and CI procedures. All development operations go through the top-level Makefile — run make for a summary of targets.

Agent Instructions

Worktree boundaries

This project uses git worktrees in a shared parent directory (settled-reach/). Each team branch (server, client, copy, audio, visual, ci) has its own worktree. The worktree root IS the git root.

• All work must remain within the git root unless explicitly instructed otherwise.
• All file paths are relative to the worktree root (e.g. server/src/bridge/types.rs).
• Do not navigate to or access sibling worktrees (../client/, ../copy/, etc.) unless explicitly instructed.
• Exception — stale git lock files: Worktree index locks live in the shared .git directory (e.g. main/.git/worktrees/copy/index.lock). If a git command fails with index.lock: File exists, you may remove the lock file for your own worktree only. Never touch lock files belonging to other worktrees.

Database

The ticketing database (settledreach.db) lives in the parent directory shared across all worktrees — it is not tracked in git. 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

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 worktrees
• 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