# Commonwealth Game Project

A top-down immersive sim set in Peter F. Hamilton's Commonwealth universe. Single-character, first-person perspective, asymmetric information as core mechanic, Rimworld-style storyteller.

## Project Structure

```
DECISIONS.md          # Confirmed decisions (D-001+), open questions (Q-001+)
DISCUSSION.md         # Active discussion round only
TEAM.md               # Team roster and roles
docs/
  discussions/        # Archived discussion rounds (historical)
  briefings/          # Per-agent context briefings (maintained by Qatux)
  architecture/       # Technical architecture documents
  design/             # Game design documents
db/
  commonwealth.db     # SQLite ticketing database
  schema.sql          # Database schema
  connectors/         # Connector scripts for SQLite and Qdrant
    config.json       # Endpoint configuration
    sqlite_connector.py   # SQLite mini MCP
    qdrant_connector.py   # Qdrant + ollama mini MCP
.claude/
  agents/             # Agent personality files
  skills/             # Skill definitions
```

## Agent Instructions

### Before starting work
1. Read your briefing at `docs/briefings/{your-name}.md` for current project context
2. Read `DECISIONS.md` for confirmed decisions relevant to your work
3. Check `DISCUSSION.md` for any active discussion

### SQLite access
**Never use the `sqlite3` CLI** - it crashes in Claude Code due to a known std::bad_alloc bug.

Use the connector script instead:
```bash
python3 db/connectors/sqlite_connector.py query "SELECT * FROM tickets WHERE status='in_progress'"
python3 db/connectors/sqlite_connector.py execute "UPDATE tickets SET status='done' WHERE id=1"
```

### Qdrant / document search
```bash
python3 db/connectors/qdrant_connector.py search "asymmetric information design"
python3 db/connectors/qdrant_connector.py index-file docs/briefings/tyre.md
python3 db/connectors/qdrant_connector.py health
```

### File conventions
- Decision IDs: `D-NNN` (confirmed), `Q-NNN` (open questions), `R-NNN` (rejected)
- Discussion rounds: numbered sequentially, archived to `docs/discussions/` when complete
- Briefings: one per agent, updated after decision-producing rounds
- Tickets: managed via `/ticket` skill or `sqlite_connector.py` directly

### Commit conventions
Use conventional commits with Commonwealth-specific scopes:
`agents`, `skills`, `docs`, `briefings`, `discussions`, `schema`, `db`, `config`, `engine`, `simulation`, `client`, `ui`, `audio`, `assets`

### Local services
- Qdrant: `http://tower-of-joy:6333/`
- Ollama: `http://tower-of-joy:11434/` (nomic-embed-text)
- Collection: `commonwealth` (768 dimensions, cosine distance)