jpmschweitzerandClaude Opus 5.5
ddce4441a9
tooling/db/ (a misnamed directory: connectors, not database work),
trellis-batch.sh and synth_ui_sounds.py become `reach assets`:
audio {health,generate,batch,post {convert,normalize,trim,pipeline}},
image {health,generate}, trellis {health,generate,batch}, and synth-ui.
The four audio bash wrappers are retired, and tooling/db/ is gone.
Parity, from baselines taken before anything moved:
- the four UI-sound WAVs and the harmonic-synth WAVs (exponential and linear
decay) are byte-identical
- the ffmpeg pipeline's decoded PCM is identical. Its .ogg bytes are not,
even between two runs of the OLD code: Ogg picks a random stream serial,
so the encoded file was never the right thing to compare
- the network success paths can't be run in a gate (Stable Audio and Trellis
are kept off, Gemini costs money), so tooling/test_assets.py stands up a
fake Gradio and pins every payload: the audio submit, Trellis's six-call
session sequence with its 9-input image_to_3d, and the Gemini body. It
failed when one Trellis value was mutated (7.5 → 7.0)
Failure classification, in endpoints.py, is the point of the port. The
services are OFF by design (VRAM on tower-of-joy, D-17), and the topology doc
warns against "fixing" one by restarting it. So a refused connection says OFF
and asks for the service to be turned on rather than restarted; a 4xx/5xx says
the request was rejected; 401/403 says credentials; 429 says quota; and an
unreachable Gemini blames the network, not VRAM.
Behaviour changes, each a failure that used to read as success or crash:
- audio batch and trellis batch exited 0 with failures in their summaries;
they now print the summary and exit 1
- trellis generate on a missing image crashed with a TypeError
(print(..., indent=2)); it now names the file, and checks it before the
service so a typo is not reported as an outage
- the ffmpeg pipeline left its intermediates behind when a step failed
Structure: the connectors called each other as subprocesses (batch spawned
the connector, which spawned audio_post) and parsed each other's stdout. They
are now function calls, and ffmpeg is the only exec, through core/process.
ensure_venv() is removed: it os.execv'd into .venv, which D-263's exec rule
forbids, and reach declares the dependencies itself. config.json moved into
the domain deliberately, and the local-services rule follows it.
Output contract: results are still JSON on stdout with the same keys, so skill
readers keep working. Failures are an exit status with a Fix line, never
{"ok": false}. The audio-gen, glb-gen and image-gen skills, Araminta's agent
file and the allow-list are updated to match. glb-gen's "trellis-batch.sh is
hardcoded to one category" caveat is gone: batch takes --input-dir or --names.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
148 lines
8.2 KiB
Markdown
148 lines
8.2 KiB
Markdown
# 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
|
|
|
|
| Agent | File | Role | Model | When to use |
|
|
|-------|------|------|-------|-------------|
|
|
| `si` | si.md | Refinement Manager | sonnet | Ticket context review before batch activation (`/whats-next` step 2) — active now |
|
|
| `clerk` | clerk.md | Institutional Guardrail | sonnet | Manual D-record/ticket consistency audits — dormant on the pre-push path (disabled by default, #965; see clerk.md) |
|
|
|
|
### Implementation team (active)
|
|
|
|
| Agent | File | Role | Model | When to use |
|
|
|-------|------|------|-------|-------------|
|
|
| `dudley` | dudley.md | Server Developer | sonnet | Rust/bevy_ecs simulation: tick pipeline, ECS, world generation cascade, save/load — server/'s most active workstream |
|
|
| `stig` | stig.md | UI Developer | sonnet | Godot client UI: character customisation, insert/HUD, dialogue panels, fog/entity rendering |
|
|
| `justine` | justine.md | Polish & Deploy | sonnet | Build pipelines, packaging, performance, release prep, content-validation/pre-commit tooling |
|
|
| `mellanie` | mellanie.md | Copywriter | sonnet | In-game text, UI copy, tooltips, flavor text, player monologue |
|
|
|
|
### Standby team (activate when implementation starts)
|
|
|
|
| Agent | File | Role | Model | When to use |
|
|
|-------|------|------|-------|-------------|
|
|
| `oscar` | oscar.md | Networking Developer | sonnet | Multiplayer networking, sync, client-server protocol |
|
|
| `inigo` | inigo.md | Sound Designer | sonnet | Soundscape design, ambient layers, diegetic cues, audio propagation (D-018) — activate when sound design starts |
|
|
|
|
*Whether oscar (multiplayer) should exist yet for a Phase-4, pre-game project is an open question — see the team lead. Localization was decided out of scope (template-writing + Gemma integration prohibitively expensive), so the former `tiger` persona was removed (see governance/rejected).*
|
|
|
|
## 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)
|
|
- **Solo** for performance profiling, benchmarking, and technology stress-tests; **paired with Tyre** for architecture second opinions — never the sole voice on an architecture decision
|
|
- 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
|
|
- Drives image-gen/sprite-gen/glb-gen/audio-gen via Bash — no Skill/MCP tool grant, so she invokes the connectors directly, e.g. `reach assets image generate ...`
|
|
- **image-gen calls the paid Gemini API (`GEMINI_API_KEY`) — always ask Team Leader for permission before generating. glb-gen/audio-gen run against self-hosted tower-of-joy infrastructure and sprite-gen renders locally, so they don't carry the same per-call cost, but confirm intent before large batch jobs.**
|
|
|
|
### 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 — **mandatory participant in every team interaction and discussion round** (she is the record-keeper; a round without her produces no durable documentation)
|
|
- Maintains governance/ domain files, docs/discussions/ round records, 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. Add `memory: project` only for project-memory/librarian roles that persist learnings across sessions (currently just qatux) — one-shot task agents omit it
|
|
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:
|
|
- `governance/` - Domain-split decision files (see governance/README.md for index)
|
|
- `docs/discussions/` - Active + archived discussion rounds (`round-NN-topic.md`, indexed in `docs/discussions/README.md`)
|
|
- `TEAM.md` - Team roster and role descriptions
|
|
- `CLAUDE.md` - Project-wide conventions
|