chore: context pack for aicc-capsule reference testbed

- AGENTS.md: build instructions for AI coding agents - docs/: AICC core spec copy, JSON schema, testbed design notes - scripts/: setup.sh, BUILDLOG.md - README.md: overview and reading order
2026-08-08 03:31:42 +03:00
commit fb3b4935d9
7 changed files with 1001 additions and 0 deletions
@@ -0,0 +1,38 @@
+# 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.