settled-reach/.claude/agents/README.md

# The Settled Reach - Agent Team

## Overview

**The Settled Reach** uses Claude Code agent teams to simulate a game development team. Each agent has a distinct personality, expertise area, and role. The team leader (Jeroen) directs the team through chat.

All agents read their briefing file at `docs/briefings/{name}.md` before starting work. Briefings contain current project state, relevant decisions, and priorities — keeping agent profiles stable while context evolves.

## Agent Roster

### Core team (brainstorming + design discussions)

| Agent | File | Role | Model |
|-------|------|------|-------|
| `miri` | miri.md | Worldbuilder & Setting Designer | sonnet |
| `ozzie` | ozzie.md | Player Experience / Wow Factor | sonnet |
| `paula` | paula.md | Narrative & Political Depth | sonnet |
| `gore` | gore.md | Themes & Endgame Design | sonnet |
| `gestalt` | gestalt.md | Systems Design & Fun Factor | sonnet |
| `nigel` | nigel.md | Sandbox & Replayability | sonnet |
| `tyre` | tyre.md | Technical Architecture | opus |
| `qatux` | qatux.md | Documenter & Librarian | sonnet |

### Specialist team (task-focused, not in regular discussions)

| Agent | File | Role | Model | When to use |
|-------|------|------|-------|-------------|
| `troblum` | troblum.md | Technical Consultant / Tyre's sparring partner | sonnet | Evaluation sidequests alongside Tyre |
| `burnelli-sheldon` | burnelli-sheldon.md | Economist & Simulation Modeler | sonnet | Economic systems, market models, price formation, stability analysis |
| `araminta` | araminta.md | Visual Designer | sonnet | Visual decisions, style guides, asset generation |
| `hoshe` | hoshe.md | QA Engineer / Tester | sonnet | Testing, test plans, bug reports, verification |

### Infrastructure team (active now)

| Agent | File | Role | Model | When to use |
|-------|------|------|-------|-------------|
| `si` | si.md | Refinement Manager | sonnet | Ticket context review before batch activation (`/whats-next` step 2) |
| `clerk` | clerk.md | Institutional Guardrail | sonnet | Pre-push D-record/ticket consistency checks |

### Standby team (activate when implementation starts)

| Agent | File | Role | Model | When to use |
|-------|------|------|-------|-------------|
| `stig` | stig.md | UI Developer | sonnet | UI implementation, HUD, menus, insert/minimap |
| `dudley` | dudley.md | Server Developer | sonnet | Game server, ECS, simulation loop, world state |
| `oscar` | oscar.md | Networking Developer | sonnet | Multiplayer networking, sync, client-server protocol |
| `justine` | justine.md | Polish & Deploy | sonnet | Build pipelines, packaging, performance, release prep |
| `mellanie` | mellanie.md | Copywriter | sonnet | In-game text, UI copy, tooltips, flavor text |
| `tiger` | tiger.md | Translator | sonnet | Localization, i18n framework, translation management |

## Usage Modes (Hybrid Approach)

### 1. Single session - for brainstorming & discussion
The main Claude session plays all **core team** agents in conversation, switching voices as appropriate. Agent files serve as personality references. This is the default mode for design discussions.

**When to use:** Brainstorming, design debates, quick decisions, anything where fast back-and-forth between agents matters.

### 2. Subagent delegation - for focused tasks
Spawn individual agents as subagents for specific work:
```
Use tyre to evaluate Godot vs Bevy for our requirements.
Use miri to verify the canon accuracy of our Guardian faction design.
Use qatux to update DECISIONS.md with today's discussion.
Use araminta to create the initial color palette and style guide.
Use hoshe to write a test plan for the LOS system.
```

**When to use:** One agent needs to do focused, independent work and report back.

### 3. Agent teams - for parallel work
Spawn multiple agents as teammates with shared task list:
```
Create a team: spawn tyre and troblum as teammates.
Tyre: evaluate Godot against our requirements.
Troblum: evaluate Bevy against our requirements.
Compare findings when both are done.
```

```
Create a team: spawn gestalt, paula, and miri as teammates.
Each independently evaluate the character system proposal from their perspective.
Synthesize findings.
```

**When to use:** Parallel research, competing evaluations, design reviews from multiple perspectives, independent implementation tasks.

### Mode selection guide

| Task type | Mode | Why |
|-----------|------|-----|
| Design brainstorming | Single session | Fast, cheap, good voice consistency |
| Quick lore check | Subagent (miri) | Focused, returns answer |
| Engine evaluation | Team (tyre + troblum) | Parallel research, sparring |
| Design review | Team (core agents) | Independent perspectives, genuine disagreement |
| Style guide creation | Subagent (araminta) | Focused creative work |
| Test writing | Subagent (hoshe) | Focused, spec-driven |
| Implementation batch | Team (tyre + hoshe + relevant others) | Parallel build + test |
| Documentation update | Subagent (qatux) | Structured, accurate citations |

## Agent usage notes

### Troblum (Technical Consultant)
- **Always paired with or supporting Tyre** - never works alone on architecture decisions
- Spawned for specific evaluation sidequests, not open-ended discussion
- Blunt, data-driven, will challenge Tyre's assumptions with evidence

### Araminta (Visual Designer)
- Joins discussions only when visual consistency decisions are needed
- Has access to `/asset-gen` skill and `generate_image` MCP tool
- **Image generation costs money - always ask Team Leader for permission before generating**

### SI (Refinement Manager)
- Spawned by `/whats-next` to review ticket context before batch activation
- Reads D/Q-records, workshop outcomes, existing code to assess ticket readiness
- Reports READY (with context summary) or GAPS (with specific ambiguities)
- Does not implement — refines

### Qatux (Documenter & Librarian)
- Core team member — participates in discussion rounds as documenter
- Maintains DECISIONS.md, DISCUSSION.md, and briefings
- Answers "did we discuss this?" with citations

## Extending the team

To add a new agent:
1. Create a `.md` file in this directory
2. Use YAML frontmatter with at minimum: name, description, tools, model, memory
3. Write a personality prompt in the markdown body
4. Add `Read your briefing at docs/briefings/{name}.md before starting work.` to the profile
5. Create a briefing file in `docs/briefings/{name}.md`
6. Add to the appropriate team table above
7. Update TEAM.md

## Project documents

All agents read their briefing at `docs/briefings/{name}.md` for current context. Key project documents:
- `decisions/` - Domain-split decision files (see decisions/README.md for index)
- `DISCUSSION.md` - Active discussion round (archives in `docs/discussions/`)
- `TEAM.md` - Team roster and role descriptions
- `CLAUDE.md` - Project-wide conventions