jpmschweitzerandClaude Opus 4.6
0cf4dcc3f9
- `db/connectors/decision next [D|Q|R]` — show next available ID - `db/connectors/decision claim <prefix> <domain> [title]` — reserve ID in DB - `db/connectors/decision check-dupes` — detect duplicate IDs in markdown - `tooling/check-decision-ids` — pre-commit hook for dupe detection - D-035 added as known exception (139 files, too embedded to renumber) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
71 lines
4.1 KiB
Markdown
71 lines
4.1 KiB
Markdown
# 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 + connector scripts (ticket CLI, SQLite, Qdrant)
|
|
.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.
|
|
|
|
## 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 `db/connectors/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 | `db/connectors/ticket list`, `show`, `create`, `assign` | `/ticket` skill |
|
|
| Sprints | `db/connectors/sprint status`, `start-work`, `prepare` | `/sprint-start` skill |
|
|
| SQL queries | `db/connectors/sqlite-query "SELECT ..."` | — |
|
|
| SQL writes | `db/connectors/sqlite-exec "UPDATE ..."` | — |
|
|
| Decisions | `db/connectors/decision next`, `claim`, `check-dupes` | — |
|
|
| Doc search | `db/connectors/qdrant-search "query"` | `/docs-search` skill |
|
|
| Doc index | `db/connectors/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:** `db/connectors/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 `db/connectors/ticket` CLI or `/ticket` skill
|