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.