settled-reach/whatsinagame/skill/references/customization-examples.md

# Customization Examples

How The Settled Reach (the project this kit was extracted from) customized the base patterns. Use these as inspiration for how far you can take the templates.

## The Settled Reach: Overview

A top-down immersive sim with occlusion-based detective mechanics. Godot 4 client + Rust/bevy_ecs simulation server. Single-player with asymmetric information as core mechanic.

### 20 Agents with Themed Names and Personalities

Instead of generic names, The Settled Reach gave every agent a name from the project's science fiction universe. Each personality was tuned to the specific role and project context.

| Name | Archetype | Unique Flavor |
|------|-----------|---------------|
| tyre | architect | Named after a setting element. Evaluates engine choices, client-server architecture, rendering pipelines. Specializes in Godot + Rust trade-offs. |
| si | project-manager | Manages sprint cycles across 6 team branches. Coordinates parallel workstreams. |
| hoshe | qa-engineer | Writes GDScript tests, Rust tests, and integration tests. Verifies simulation determinism. |
| gestalt | designer | Systems design specialist. Evaluates whether mechanics create "interesting decisions." Maps system interactions. |
| dudley | developer-backend | Rust simulation server specialist. Entity systems, deterministic tick processing, bevy_ecs. |
| stig | developer-frontend | Godot client specialist. Rendering, UI systems, fog of war, input handling. |
| mellanie | content-author | Writes in-game text: internal monologue, dialogue, descriptions, news ticker content. |
| troblum | consultant | Technical sparring partner. Evaluates architecture decisions alongside tyre. |
| araminta | visual-designer | Art direction, sprite standards, UI component patterns, color palettes. |
| inigo | audio-designer | Soundscape design, ambient layers, diegetic audio cues, spatial audio specs. |
| oscar | developer-backend (networking) | Client-server communication specialist. Network protocol, sync mechanisms. |
| qatux | librarian | Maintains decision records, discussion archives, briefings, Qdrant search index. |
| ozzie | stakeholder (wow-factor) | "Does this make players feel something?" Evaluates excitement and emotional resonance. |
| paula | stakeholder (narrative) | Political depth, conversation systems, faction mechanics, consequences. |
| gore | stakeholder (themes) | Philosophical questions, ascension paths, what the game is fundamentally ABOUT. |
| nigel | stakeholder (replayability) | Sandbox advocate. "What happens the SECOND time you play this?" |
| miri | worldbuilder | Setting designer. Factions, cultures, technology, locations, history, lore consistency. |
| justine | devops | Build pipelines, performance profiling, platform packaging, release quality. |
| tiger | localization | Translation infrastructure, cultural adaptation. |

**Key lesson**: Themed names make agents feel like team members, not tools. The project's fiction naturally provided memorable, distinct names.

### Game-Specific Commit Scopes

Standard scopes were replaced with project-specific ones:

```
agents, skills, docs, briefings, discussions, schema, db, config,
engine, simulation, client, ui, audio, assets, meta
```

Compare with generic: `feat, fix, docs, chore, test, refactor`

**Key lesson**: Commit scopes should match your project's actual domains. A web app might use: `api, frontend, auth, db, deploy, infra, docs`.

### 6 Worktree Branches

Instead of one main branch, the project uses worktrees for parallel development:

| Branch | Worktree | Team |
|--------|----------|------|
| server | `../server/` | dudley, oscar |
| client | `../client/` | stig |
| copy | `../copy/` | mellanie |
| audio | `../audio/` | inigo |
| visual | `../visual/` | araminta |
| ci | `../ci/` | justine |

Each sprint branch contains the full repository. Sprint briefings are written per-team (`docs/sprints/sprint-N/server.md`, `client.md`, etc.). Merges happen via PR review on main.

**Key lesson**: Sprint branches (`sprint-N/team`) with ephemeral worktrees via `isolation: "worktree"` give each agent an isolated copy without persistent worktree management.

### Qdrant + Ollama for Semantic Document Search

The project uses local Qdrant (vector database) and Ollama (embedding model) for semantic search across hundreds of design documents, discussion rounds, and decision records.

```bash
# Search across all project documents
tooling/db/qdrant-search "asymmetric information design"

# Index a new document
tooling/db/qdrant-index docs/briefings/tyre.md

# Health check
tooling/db/qdrant-health
```

Configuration:
```json
{
  "qdrant_url": "http://tower-of-joy:6333/",
  "ollama_url": "http://tower-of-joy:11434/",
  "embedding_model": "nomic-embed-text",
  "collection": "commonwealth",
  "dimensions": 768,
  "distance": "cosine"
}
```

**Key lesson**: Semantic search becomes valuable when you have 50+ documents. Below that, grep is fine. The full profile includes Qdrant; the standard profile uses grep-only `/docs-search`.

### Custom Skills

Beyond the standard kit skills, the project added domain-specific ones:

| Skill | Purpose |
|-------|---------|
| render-sprite | Render 3D models to 2D sprites via Godot pipeline (4 directions, 3 resolutions) |
| gen-audio | Generate audio assets using Stable Audio Open API |
| gen-image | Generate visual assets using Gemini image generation |

**Key lesson**: The skill system is extensible. Use `/skill-create` to build project-specific skills for any repetitive workflow.

### Domain-Specific Decision Files

Instead of a single `decisions.md`, the project organizes decisions by domain:

```
decisions/
  README.md           # Domain index with query examples
  architecture.md     # D-008, D-009, D-010, D-012, D-020, ...
  perception.md       # D-011, D-015, D-016, D-017, ...
  content.md          # D-023, D-024, D-025, ...
  scope.md            # D-001, D-003, D-005, ...
  process.md          # D-004, D-021, D-022
  questions.md        # Q-001 through Q-011
  rejected.md         # R-001 through R-010
```

Each decision has an ID, status, date, and summary. The README provides an index and grep-friendly query examples.

**Key lesson**: Start with 2-3 domain files (architecture, scope, process) and add more as needed. The standard profile deploys these three. The full profile adds domain files based on the project type.

### Workshop Orchestration

Multi-agent design workshops with structured rounds:

1. Workshop brief written to `docs/workshops/workshop-N/brief.md`
2. `/workshop-start` parses the brief, spawns participants as teammates
3. Rounds proceed with facilitator, participants discuss, decisions are captured
4. Output: decision records, updated domain files, next-steps

Workshops are used for major design decisions (game mechanics, architecture choices, scope planning). Smaller decisions go through async discussion rounds.

**Key lesson**: Workshops are the full profile's killer feature. They turn "Claude discussing with itself" into structured, multi-perspective design sessions with real output.