# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install requests

# Set API key
export OPENROUTER_API_KEY="your-key-here"

# Run tests
python3 -m unittest discover -v tests/

# Run simulation (coming soon)
python3 -m src.main

Project Structure

among-us-agents/
├── config/
│   ├── game_settings.yaml     # Game rules & parameters
│   └── prompts/               # LLM prompt templates
├── data/
│   ├── maps/skeld.json        # The Skeld map
│   └── agents/{agent_id}/     # Per-agent scratchpads
├── docs/                      # Design docs & API reference
├── src/
│   ├── engine/
│   │   ├── simulator.py       # Discrete event simulator
│   │   ├── game.py            # Game mechanics
│   │   ├── triggers.py        # Trigger registry
│   │   ├── fog_of_war.py      # Per-player knowledge
│   │   ├── available_actions.py  # Dynamic actions
│   │   ├── trigger_messages.py   # Trigger JSON schemas
│   │   ├── meeting_flow.py    # Meeting lifecycle
│   │   ├── discussion.py      # Discussion orchestrator
│   │   └── types.py           # Core data types
│   ├── map/graph.py           # Graph-based map
│   ├── agents/
│   │   ├── agent.py           # LLM agent wrapper
│   │   ├── scratchpads.py     # File-based memory
│   │   └── prompt_assembler.py  # Prompt builder
│   ├── llm/client.py          # OpenRouter client
│   └── main.py                # Game orchestrator
└── tests/                     # 138 tests

Architecture

Engine

Continuous time simulation (seconds, not discrete ticks)
Event-driven: triggers fire → time freezes → agent responds → time resumes
Fog of war: each agent only knows what they've observed

Agents

Stateless LLM calls: each trigger = fresh invocation
JSON scratchpads: persistent memory across ticks
Toggleable settings: personas, strategy injection, meta-awareness

Discussion

Priority bidding: agents bid to speak, highest priority wins
Vote-when-ready: discussion ends when all vote
Ghost chat: dead players observe

Documentation

Document	Description
design_main_game.md	Game loop, triggers, tools, state
design_discussion.md	Discussion, voting, personas
openrouter_api.md	LLM integration

Tests

python3 -m unittest discover -v tests/
# 118 tests across map, simulator, triggers, game, discussion

Status

✅ Phase 1: Core Engine
✅ Phase 2: Agent Scaffolding
✅ Phase 3: Prompt Engineering Design
🔄 Phase 4: Implementation
⏳ Phase 5: Prompt Templates
⏳ Phase 6: Testing & Polish

License

MIT