# AGENTS.md — aicc-capsule build instructions

You are building the reference testbed for the AICC Protocol: a 3D room with an AI-controlled capsule that an LLM agent drives through protocol tools. This file tells you what to build and how. Read `docs/aicc-core.md` (the protocol spec) and `docs/testbed-design.md` before writing code. The Python SDK to build on is at `~/Desktop/aicc-py` (sibling checkout; use it directly, do not reinvent).

## Mission

Prove the AICC Protocol end-to-end:

1. A 3D room with obstacles and one interactable object.
2. A capsule the agent can move (bridge-side physics + state).
3. A bridge implementing the protocol with tools: `proprioception`, `vision`, `move`, `turn`, `look_at`, `interact`.
4. A runnable demo: an agent (any LLM with tool calling) connects via WebSocket, perceives the room, walks to a target, interacts.

## Constraints

- **Use the aicc-py SDK** at `~/Desktop/aicc-py` (Bridge, AICCClient, WebSocketServer). Import it, do not copy its internals. If the SDK lacks something, extend the SDK repo, not the testbed.
- **Engine choice is yours** but must meet: Python-friendly, can render a first-person RGB frame for `vision` (or emit a fake-but-honest frame), simple physics for `move`/collision. Candidates: Panda3D, ursina, Godot (via Python bindings), or a minimal custom scene. A headless-friendly setup is strongly preferred so the demo runs without a display.
- **Protocol compliance is mandatory.** The bridge must pass the conformance scenarios: `python -m aicc.conformance ~/Desktop/aicc-spec/conformance/scenarios` (all 9 core scenarios green).
- Tools must have `description` (first line = tool purpose). Use snake_case ids.
- Follow the "single source of truth" principle: all world data only via sensors, manifest carries no world state.
- Keep it minimal. This is a reference, not a product. One room, one capsule, one interactable. No inventory, no combat, no save system.

## Definition of done

- [ ] `python -m aicc.conformance ...` passes 9/9 against the testbed bridge
- [ ] A demo script that: starts bridge, connects an agent loop, agent reaches a target and interacts, prints a transcript of tool calls to stdout
- [ ] `README.md` in testbed/ documenting how to run bridge + agent
- [ ] At least one commit per milestone (bridge skeleton, tools, demo loop)

## Environment

- Python 3.11+; venv in `testbed/.venv`
- aicc-py SDK available at `~/Desktop/aicc-py` — add it to PYTHONPATH or `pip install -e ~/Desktop/aicc-py`
- If you pick an engine, add its install command to `scripts/setup.sh`

## Communication

Report progress in short summaries. When done, print the final tool transcript example and conformance result.