agora AGENTS.md

AGENTS.md — The Agora

Overview

The Agora is a plugin-based MCP coordination server. A lightweight Python backbone loads plugins (Chat, Board, Log, Memory, Lock/Signal) that provide tools for multi-agent collaboration via SQLite-backed MCP endpoints.

All design documents live in the reference/ directory. Read these before writing any code:

• reference/META.md — vision, why MCP, name origin
• reference/ARCHITECTURE.md — plugin API, backbone responsibilities, startup sequence
• The relevant reference/NNN-*.md task file(s) for what you're implementing
• reference/CONVENTIONS.md — capability vocabulary, manifest standards
• reference/AGENTS.md — this file (coding standards, testing, workflow)

Technology Decisions (Settled)

Decision	Choice	Rationale
Language	Python 3.12+	Simple plugin model (import + class), mature SQLite ecosystem (sqlite-vec, apsw), pytest for testing
MCP Framework	FastMCP	Clean tool definition, built-in schema validation, stdio + Streamable HTTP support
Database	SQLite with WAL mode (via apsw)	Zero infrastructure, concurrent reads+writes, sqlite-vec for vector search later
Testing	pytest + pytest-asyncio	Standard for Python async servers, rich fixture system
Linting	ruff	Fast, covers flake8 + isort + pyupgrade, single dependency
Type Checking	mypy (strict)	Catch type errors before runtime
Packaging	uv (or pip)	Simple single-package install, no build step
Virtual Environment	./venv/ (in project root)	Must use this exact path. All commands assume source venv/bin/activate. Never use system Python or a differently-named venv.

Architecture Constraints

These must never be violated:

1. Backbone never calls an LLM. That's plugin territory. The backbone owns transport, identity, routing, and plugin lifecycle. No exceptions.
2. Every tool call is authenticated. The backbone rejects unregistered agents before routing to any plugin.
3. Plugins own their tables. Plugin A cannot read Plugin B's database tables directly. Communication is via the event bus only.
4. Tool names are prefixed. chat_, board_, log_, mem_, lock_, signal_. No prefix collisions.
5. The event bus is in-process (not MCP). Plugins emit and subscribe to Python events. No serialization overhead.
6. The database is single-file. One agora.db with WAL mode. No separate log database. No external vector database in v1.