From 465f2bdf98a762842f3c289ebb53ef1fadb794ce Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Tue, 24 Feb 2026 12:37:23 +0100 Subject: [PATCH 1/3] feat(config): add .claude/rules/ for modular auto-loaded instructions Introduces 5 rules files following Anthropic's recommended pattern for splitting large CLAUDE.md files. Rules auto-load every session and separate CLI reference material from core project identity. - tea-cli.md: Gitea CLI reference, PR creation, protected branches - git-safety.md: staging rules, commit conventions (from git-commit skill) - project-structure.md: full annotated directory tree - team-patterns.md: model selection, large content push pattern - local-services.md: Gitea/Qdrant/Ollama endpoints Co-Authored-By: Claude Opus 4.6 --- .claude/rules/git-safety.md | 16 +++++++++++ .claude/rules/local-services.md | 8 ++++++ .claude/rules/project-structure.md | 40 ++++++++++++++++++++++++++ .claude/rules/tea-cli.md | 45 ++++++++++++++++++++++++++++++ .claude/rules/team-patterns.md | 19 +++++++++++++ 5 files changed, 128 insertions(+) create mode 100644 .claude/rules/git-safety.md create mode 100644 .claude/rules/local-services.md create mode 100644 .claude/rules/project-structure.md create mode 100644 .claude/rules/tea-cli.md create mode 100644 .claude/rules/team-patterns.md diff --git a/.claude/rules/git-safety.md b/.claude/rules/git-safety.md new file mode 100644 index 000000000..0bb32471c --- /dev/null +++ b/.claude/rules/git-safety.md @@ -0,0 +1,16 @@ +# Git Safety + +## Staging rules + +- **Stage files by name** — never use `git add -A` or `git add .` +- Verify no secrets, saves, or binary blobs are staged +- Skip files in `.gitignore` +- The `.claude/` directory IS tracked — skills and agents belong in the repo + +## Commit conventions + +Use conventional commits: `(): ` + +Scopes: `agents`, `skills`, `docs`, `briefings`, `discussions`, `schema`, `db`, `config`, `engine`, `simulation`, `client`, `ui`, `audio`, `assets`, `meta` + +See `/git-commit` for full commit format, types, CHANGELOG workflow, and examples. diff --git a/.claude/rules/local-services.md b/.claude/rules/local-services.md new file mode 100644 index 000000000..4decd8975 --- /dev/null +++ b/.claude/rules/local-services.md @@ -0,0 +1,8 @@ +# Local Services + +Endpoints are also preconfigured in `db/connectors/config.json`. + +- **Gitea:** `http://git.schweitz.internal` (login: `schweitz`) +- **Qdrant:** `http://tower-of-joy:6333/` +- **Ollama:** `http://tower-of-joy:11434/` (nomic-embed-text) +- **Collection:** `commonwealth` (768 dimensions, cosine distance) diff --git a/.claude/rules/project-structure.md b/.claude/rules/project-structure.md new file mode 100644 index 000000000..02a3fcbb4 --- /dev/null +++ b/.claude/rules/project-structure.md @@ -0,0 +1,40 @@ +# Project Structure (detailed) + +``` +client/ # Godot 4 client +server/ # Rust/bevy_ecs simulation server +tooling/ # Build tools, scripts, asset pipelines +tests/ # Integration and end-to-end tests +.config/ # Configuration files (linters, formatters, CI) +.cache/ # Local caches for testing/linting (gitignored) +docs/ + discussions/ # Discussion rounds (archived here when complete) + briefings/ # Per-agent context briefings (maintained by Qatux) + architecture/ # Technical architecture documents + design/ # Game design documents + diagrams/ # d2 source + PNG renders + sprints/ # Sprint briefings per team + workshops/ # Workshop briefs and outputs +db/ + schema.sql # Database schema + connectors/ # Connector scripts for SQLite and Qdrant + config.json # Endpoint configuration + ticket # Ticket CLI + sqlite_connector.py # SQLite mini MCP + qdrant_connector.py # Qdrant + ollama mini MCP +.claude/ + agents/ # Agent personality files + skills/ # Skill definitions + rules/ # Auto-loaded instruction modules +decisions/ # Decision domain files (source of truth) + README.md # Domain index — use this to find specific D-records + architecture.md # Architecture decisions + perception.md # Perception and information system decisions + content.md # Content and narrative decisions + scope.md # Scope and feature decisions + process.md # Process and workflow decisions + questions.md # Open questions (Q-NNN) + rejected.md # Rejected proposals (R-NNN) +DECISIONS.md # Redirect to decisions/ directory +TEAM.md # Team roster and roles +``` diff --git a/.claude/rules/tea-cli.md b/.claude/rules/tea-cli.md new file mode 100644 index 000000000..34c8ea5e3 --- /dev/null +++ b/.claude/rules/tea-cli.md @@ -0,0 +1,45 @@ +# Gitea Access (tea CLI) + +**Never access the Gitea API directly** — use the `tea` CLI with all required flags to bypass interactive mode. + +Always pass `--login schweitz --repo jpmschweitzer/settled-reach --output simple` to avoid TTY prompts. + +```bash +# List open PRs +tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple + +# View a PR with comments +tea pr --login schweitz --repo jpmschweitzer/settled-reach --comments -o simple + +# Post a comment on a PR (or issue) +tooling/tea-comment "comment body" + +# Approve a PR +tea pr approve --login schweitz --repo jpmschweitzer/settled-reach + +# List issues +tea issue list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple +``` + +## Key rules + +- **All flags must be explicit** — omitting `--login` or `--repo` triggers interactive prompts that crash in Claude Code (no TTY) +- **Use `--output simple`** for machine-readable output (no table borders) +- **For comments, use `tooling/tea-comment "body"`** — handles temp files and cleanup automatically. Works with multi-line strings. +- **`tea pr reject` does not work on your own PRs** — use `tea comment` instead +- **Never delete protected branches:** `main`, `maintenance`, `server`, `client`, `copy`, `audio`, `visual`, `ci` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches. + +## Pull requests + +**Use `tea` (Gitea CLI), not `gh` (GitHub CLI).** The remote is Gitea at `git.schweitz.internal`. + +Always provide all required flags to ensure non-interactive execution: +```bash +tea pr create \ + --repo jpmschweitzer/settled-reach \ + --login schweitz \ + --title "feat(scope): short description" \ + --description "PR body here" \ + --base main \ + --head branch-name +``` diff --git a/.claude/rules/team-patterns.md b/.claude/rules/team-patterns.md new file mode 100644 index 000000000..a614eea5e --- /dev/null +++ b/.claude/rules/team-patterns.md @@ -0,0 +1,19 @@ +# Team Patterns + +## Model selection + +Default model is Opus 4.6 (200K context). For heavy sessions (workshops, +sprint planning, large reviews), switch to extended context on-demand: + +- `/model sonnet[1m]` — Sonnet 4.6 with 1M context window +- `/model opus[1m]` — Opus 4.6 with 1M context window +- Cost: 2x input + 1.5x output for tokens beyond 200K (Tier 4 required) + +## Large content pushes + +When producing many files (wiki pages, content batches, bulk docs): +1. **Lore librarian** agent (read-only): ingests all source material, answers focused context queries from writers, tracks cross-file consistency +2. **Multiple writer** agents (parallel, by domain): each gets a task slice, writes directly to disk using the Write tool — one file at a time, write often, no text accumulation +3. **Reviewer** agents (blocked until writing done): check voice consistency, attribute uniformity, style + +Key: writers use Write tool directly (no transcription bottleneck), librarian catches contradictions early, split work by domain not volume. From 0ce20b9cd22ee4d4e753b7ae686b4bb6e223cf6d Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Tue, 24 Feb 2026 12:37:29 +0100 Subject: [PATCH 2/3] refactor(meta): compact CLAUDE.md from 188 to 67 lines Move CLI reference material, endpoint configs, and orchestration patterns to .claude/rules/ (auto-loaded). CLAUDE.md now focuses on project identity, safety rules, and workflow conventions. Update cross-references in ticket, docs-search, and git-commit skills to point to new rules/ locations. Co-Authored-By: Claude Opus 4.6 --- .claude/skills/docs-search/SKILL.md | 6 +- .claude/skills/git-commit/SKILL.md | 6 +- .claude/skills/ticket/SKILL.md | 5 +- CLAUDE.md | 170 ++++------------------------ 4 files changed, 32 insertions(+), 155 deletions(-) diff --git a/.claude/skills/docs-search/SKILL.md b/.claude/skills/docs-search/SKILL.md index dbd96d32d..f36947254 100644 --- a/.claude/skills/docs-search/SKILL.md +++ b/.claude/skills/docs-search/SKILL.md @@ -10,9 +10,9 @@ allowed-tools: Bash, Read, Grep, Glob # Search Docs Skill -Semantic search across project documents. Basic commands (`qdrant-search`, -`qdrant-index`, `qdrant-health`, `qdrant-count`) and endpoints are documented -in CLAUDE.md. This skill covers advanced operations and workflows. +Semantic search across project documents. Endpoints are in +`.claude/rules/local-services.md`. This skill covers advanced operations +and workflows. ## Advanced Commands diff --git a/.claude/skills/git-commit/SKILL.md b/.claude/skills/git-commit/SKILL.md index 0392c6ed6..8d5704d62 100644 --- a/.claude/skills/git-commit/SKILL.md +++ b/.claude/skills/git-commit/SKILL.md @@ -136,7 +136,5 @@ chore(meta): release v0.1.0 ## Staging Rules -- Stage files by name — never use `git add -A` or `git add .` -- Verify no secrets, saves, or binary blobs are staged -- Skip files in `.gitignore` -- The `.claude/` directory IS tracked — skills belong in the repo +See `.claude/rules/git-safety.md` for staging rules (always-loaded). +These apply to ALL git operations, not just this skill. diff --git a/.claude/skills/ticket/SKILL.md b/.claude/skills/ticket/SKILL.md index bb796e8ae..ce4eaa732 100644 --- a/.claude/skills/ticket/SKILL.md +++ b/.claude/skills/ticket/SKILL.md @@ -10,9 +10,8 @@ allowed-tools: Bash, Read, Grep, Glob # Ticket Skill -Manage the project ticketing database. Basic usage (`ticket list`, `ticket show`, -`ticket sprint --active`) and raw SQL wrappers are documented in CLAUDE.md. -This skill covers the full command reference. +Manage the project ticketing database. Basic usage is in CLAUDE.md's CLI tools +section. This skill covers the full command reference. ## Commands diff --git a/CLAUDE.md b/CLAUDE.md index a5860da7a..87f2e1b9a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,51 +1,26 @@ # 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 (D-020). +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 (D-021) -**Repository name:** settled-reach (formerly commonwealth, renamed for clarity) +**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 (D-020) -server/ # Rust/bevy_ecs simulation server (D-020) +client/ # Godot 4 client +server/ # Rust/bevy_ecs simulation server tooling/ # Build tools, scripts, asset pipelines tests/ # Integration and end-to-end tests -.config/ # Configuration files (linters, formatters, CI) -.cache/ # Local caches for testing/linting (gitignored) -docs/ - discussions/ # Discussion rounds (all rounds archived here per D-022) - briefings/ # Per-agent context briefings (maintained by Qatux) - architecture/ # Technical architecture documents - design/ # Game design documents - diagrams/ # d2 source + PNG renders (architecture, data-flow, entity, state, ui) - sprints/ # Sprint briefings per team (server.md, client.md, copy.md, joint.md, etc.) - workshops/ # Workshop briefs and outputs (per-workshop subdirectories) -db/ - schema.sql # Database schema - connectors/ # Connector scripts for SQLite and Qdrant - config.json # Endpoint configuration - ticket # Ticket CLI (list, show, create, assign, sprint, etc.) - sqlite_connector.py # SQLite mini MCP - qdrant_connector.py # Qdrant + ollama mini MCP -.claude/ - agents/ # Agent personality files - skills/ # Skill definitions -decisions/ # Decision domain files (source of truth) - README.md # Domain index and query examples - architecture.md # D-008, D-009, D-010, D-012, D-020, D-026, D-030, D-031, D-041, D-042, D-054, D-055, D-066 - perception.md # D-011, D-015, D-016, D-017, D-018, D-019, D-033, D-035, D-043-D-049, D-052, D-056-D-061, D-067, D-069-D-072, D-076-D-078 - content.md # D-023, D-024, D-025, D-028, D-029, D-032, D-034-D-037, D-050, D-062-D-064 - scope.md # D-001, D-003, D-005, D-006, D-007, D-013, D-014, D-027, D-038, D-039, D-051, D-053, D-065 - process.md # D-004, D-021, D-022 - questions.md # Q-001 through Q-011 - rejected.md # R-001 through R-010 -DECISIONS.md # Redirect to decisions/ directory -TEAM.md # Team roster and roles +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. @@ -54,15 +29,11 @@ See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. A ### Worktree boundaries -This project uses **git worktrees** in a shared parent directory (`settled-reach/`). Each team branch (`server`, `client`, `copy`, `audio`, `visual`, `ci`) is checked out in its own worktree under that parent. The parent directory also contains shared resources like the ticketing database. +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. -Each worktree contains the full repository: `server/` (Rust backend), `client/` (Godot client), `docs/`, `decisions/`, etc. The worktree root IS the git root — use `git rev-parse --show-toplevel` if in doubt. - -Unless there is a direct instruction or a functional need (e.g. accessing the shared database in the parent directory), **all work must remain within the scope of the git root Claude is running in.** - -- All file paths are relative to the worktree/git root (e.g. `server/src/bridge/types.rs`, `client/scripts/rendering/fog.gd`). -- Do not navigate to or access sibling worktrees in the parent directory (`../client/`, `../copy/`, etc.) unless explicitly instructed. -- Do not navigate above the git root unless explicitly instructed. +- **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. ### Database @@ -74,68 +45,18 @@ The ticketing database (`settledreach.db`) lives in the **parent directory** sha 3. Read the relevant `decisions/*.md` domain file(s) referenced in the briefing 4. Background context: `docs/briefings/{your-name}.md`, `docs/discussions/` -### Ticket and database access -**Prefer the ticket CLI over raw SQL.** The CLI handles column names, joins, and output formatting correctly: -```bash -db/connectors/ticket list --sprint 2 --team server -db/connectors/ticket show 78 -db/connectors/ticket sprint --active -``` +### CLI tools -### Sprint CLI -**Use the sprint CLI for sprint-scoped operations.** It batches ticket queries and formats output for agent consumption: -```bash -db/connectors/sprint status # Current sprint progress -db/connectors/sprint status --team server # Team-scoped view -db/connectors/sprint start-work --team client # Full context dump for starting work -db/connectors/sprint prepare # Prepare next sprint (candidates + gaps) -db/connectors/sprint start # Activate a planned sprint -db/connectors/sprint stop # Complete an active sprint -``` -Team is auto-detected from the current git branch (if not `main`). Sprint is auto-detected from DB state. +**Prefer CLI wrappers over raw SQL.** Never use the `sqlite3` CLI — it crashes in Claude Code (std::bad_alloc). Use the wrapper scripts instead. -Only fall back to raw SQL for queries the CLI doesn't support. **Never use the `sqlite3` CLI** — it crashes in Claude Code due to a known std::bad_alloc bug. Use the wrapper scripts instead: -```bash -db/connectors/sqlite-query "SELECT * FROM tickets WHERE status='in_progress'" -db/connectors/sqlite-exec "UPDATE tickets SET status='done' WHERE id=1" -``` - -### Qdrant / document search -```bash -db/connectors/qdrant-search "asymmetric information design" -db/connectors/qdrant-index docs/briefings/tyre.md -db/connectors/qdrant-health -db/connectors/qdrant-count -``` - -### Gitea access (tea CLI) -**Never access the Gitea API directly** — use the `tea` CLI with all required flags to bypass interactive mode. - -Always pass `--login schweitz --repo jpmschweitzer/settled-reach --output simple` to avoid TTY prompts. - -```bash -# List open PRs -tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple - -# View a PR with comments -tea pr --login schweitz --repo jpmschweitzer/settled-reach --comments -o simple - -# Post a comment on a PR (or issue) -tooling/tea-comment "comment body" - -# Approve a PR -tea pr approve --login schweitz --repo jpmschweitzer/settled-reach - -# List issues -tea issue list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple -``` - -Key rules: -- **All flags must be explicit** — omitting `--login` or `--repo` triggers interactive prompts that crash in Claude Code (no TTY) -- **Use `--output simple`** for machine-readable output (no table borders) -- **For comments, use `tooling/tea-comment "body"`** — handles temp files and cleanup automatically. Works with multi-line strings. -- **`tea pr reject` does not work on your own PRs** — use `tea comment` instead -- **Never delete protected branches:** `main`, `maintenance`, `server`, `client`, `copy`, `audio`, `visual`, `ci` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches. +| 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 ..."` | — | +| 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) @@ -144,44 +65,3 @@ Key rules: - 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 - -### Commit conventions -Use conventional commits with project-specific scopes: -`agents`, `skills`, `docs`, `briefings`, `discussions`, `schema`, `db`, `config`, `engine`, `simulation`, `client`, `ui`, `audio`, `assets`, `meta` - -### Model selection - -Default model is Opus 4.6 (200K context). For heavy sessions (workshops, -sprint planning, large reviews), switch to extended context on-demand: - -- `/model sonnet[1m]` — Sonnet 4.6 with 1M context window -- `/model opus[1m]` — Opus 4.6 with 1M context window -- Cost: 2x input + 1.5x output for tokens beyond 200K (Tier 4 required) - -### Pull requests -**Use `tea` (Gitea CLI), not `gh` (GitHub CLI).** The remote is Gitea at `git.schweitz.internal`. - -Always provide all required flags to ensure non-interactive execution: -```bash -tea pr create \ - --repo jpmschweitzer/settled-reach \ - --login schweitz \ - --title "feat(scope): short description" \ - --description "PR body here" \ - --base main \ - --head branch-name -``` - -### Large content pushes (team pattern) -When producing many files (wiki pages, content batches, bulk docs): -1. **Lore librarian** agent (read-only): ingests all source material, answers focused context queries from writers, tracks cross-file consistency -2. **Multiple writer** agents (parallel, by domain): each gets a task slice, writes directly to disk using the Write tool — one file at a time, write often, no text accumulation -3. **Reviewer** agents (blocked until writing done): check voice consistency, attribute uniformity, style - -Key: writers use Write tool directly (no transcription bottleneck), librarian catches contradictions early, split work by domain not volume. - -### Local services -- Gitea: `http://git.schweitz.internal` (login: `schweitz`) -- Qdrant: `http://tower-of-joy:6333/` -- Ollama: `http://tower-of-joy:11434/` (nomic-embed-text) -- Collection: `commonwealth` (768 dimensions, cosine distance) From ca51594195a3336d26a4046137aec97794de479f Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Tue, 24 Feb 2026 12:37:44 +0100 Subject: [PATCH 3/3] chore(meta): update changelog Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 29b3b34c4..7657eef5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/). ## [Unreleased] ### Added +- `.claude/rules/` directory — modular auto-loaded instructions (tea-cli, git-safety, project-structure, team-patterns, local-services) - `tooling/tea-comment` — single-command wrapper for posting Gitea PR/issue comments with multi-line bodies - `/sprint-status` cleanup sweep skill — consistent health report with tickets by status, PR cross-reference, bookkeeping issue detection, and open work by team - `sprint sweep` CLI subcommand — structured JSON output for sprint health checks (grouped tickets, per-team summary, issue detection) @@ -17,6 +18,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/). - Entity renderer migrated from ColorRect placeholders to Sprite2D with D-019 angle sprites — self_modulate for D-033 tinting, 8→4 octant direction mapping, feet-anchored y-sort (#540) ### Changed +- CLAUDE.md compacted from 188 to 67 lines — CLI references, endpoints, and patterns moved to `.claude/rules/` - `/sprint-status` delegates to haiku subagent — keeps sweep JSON, template read, and PR list out of main context window - `sprint sweep` JSON trimmed — removed unused fields (`ok`, `sprint.status`, `priority`, `ticket_id`), shortened issue detail strings - Sprint status output template condensed — rendering rules moved to skill definition, bookkeeping table simplified to 2 columns