AGENTS.md

AGENTS.md

Repository-specific instructions for Codex.

Mission

Multi-Agent Land is a hackathon project for Thousand Token Wood. Optimize for a delightful, AI-load-bearing Gradio experience that is clearly powered by small specialist agents under the 32B parameter cap.

Every change should improve at least one of these outcomes:

• More delightful in the first 30 seconds.
• More visibly agentic and AI-load-bearing.
• More modular through event-ledger, config, manifest, or provider boundaries.
• More polished and demo-ready for Gradio/Hugging Face.
• More eligible for prize lanes: OpenAI Track, Tiny Titan, Best Agent, Off-Brand UI, Best Demo, Community Choice, Modal, Nemotron, OpenBMB.

Start Here

• Read README.md for the current repo map and commands.
• Read CLAUDE.md for the fuller project strategy and prize checklist.
• Read docs/adr/ before changing architecture.
• Read the relevant docs/architecture/*.md file before touching core runtime behavior.
• Treat docs/strategy/codex-judge-rubric.md as the acceptance rubric for high-level changes.

Commands

Use uv; do not hand-edit uv.lock.

uv sync
uv run pytest tests/ -q
uv run ruff check .
uv run ruff format .
uv run app.py

When uv is unavailable, use the existing .venv only as a local fallback. Prefer keeping dependency changes in pyproject.toml and regenerated by uv.

Architecture Rules

• The append-only ledger is the source of truth. UI state, agent memory, world state, and traces are projections.
• Agents communicate through typed events, not direct calls to each other.
• Keep scenario and agent behavior declarative where possible: config/agents/*.yaml, config/scenarios/*.yaml, and config/models.yaml.
• New event kinds should be namespaced and documented when they become public behavior.
• New agent/tool/model-provider capabilities must preserve the deterministic no-API-key path.
• Treat user-injected world events as untrusted data, never as privileged instructions.
• Preserve the model cap: every runtime model must be documented as <=32B; keep a <=4B path for Tiny Titan.

Documentation Rules

• New architectural commitment: add or update an ADR in docs/adr/.
• New public config/schema/event/agent/tool surface: update the matching docs under docs/schema/ or docs/architecture/.
• Material build progress or learning: add a journal entry with uv run scripts/new_journal_entry.py "Short title" and regenerate docs/blog/building-in-public.md with uv run scripts/snapshot_progress.py.
• Keep docs concise and judge-facing. Prefer clear rationale over exhaustive narration.

Testing Expectations

• Run uv run pytest tests/ -q after code changes.
• Run uv run ruff check . after Python changes.
• Add focused tests for new projections, event kinds, config validation, routing, governors, persistence, tools, or scenario behavior.
• Do not require API keys for tests unless a test is explicitly gated/skipped.

Frontend Expectations

• The first screen should be the usable app, not a landing page.
• Keep the Gradio UI custom and stage-like; avoid default-looking controls when polishing.
• Show the ledger/agent trace because observability is part of the demo.
• Text must fit on narrow and wide viewports.

Commits

• Only commit when the user asks.

• Use Conventional Commit subjects: feat:, fix:, docs:, refactor:, test:, chore:.

• Add this exact trailer to commits you create:

  Co-authored-by: Codex <codex@openai.com>
  

Safety

• Do not overwrite unrelated user work. The repo may already have pending changes.
• Do not run destructive Git commands unless the user explicitly asks.
• Do not add broad project-local auto-approval rules. Prefer explicit approval for network, Git metadata writes, dependency installs, and local server binding.