jpmschweitzerandClaude Opus 4.6
bc226d8baf
Consolidates all connector scripts under tooling/ per project structure conventions. Symlink at db/connectors → tooling/db/ preserves backwards compatibility (remove after Sprint 22). Updated references in CLAUDE.md, Makefile, DEVOPS.md, all skill files, agent files, rules, schema comments, and Sprint 21 briefings. Python scripts updated with correct SCHEMA_PATH (now relative to WORKTREE_ROOT/db/schema.sql). 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 + 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.
|
|
|
|
## 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
|