Coordinate multi-agent teams with self-optimizing routing

Implements the Polis Protocol, a file-based system letting AI agents from different vendors collaborate on a long-running project, route work to whoever is best at it, and improve over time - entirely through a folder of markdown files, with no central server or required runtime. The metaphor is a small city: citizens (agents) share a constitution (the protocol), publish public identities (capability cards in _polis/citizens/<id>/capability_card.yml, with per-tag self-ratings, evidence, and cost envelope), enter contracts (tasks with three sections written over their life - Intent at open, Assignment at claim, Settlement at close), and leave a public record (the append-only chronicle.md, one rigid-format line per meaningful action, plus per-tag lessons filed on settlement). Routing is a multi-armed bandit that scores every citizen per required capability tag from self-rating, historical quality in routing_stats.yml, cost, and availability - usually routing to the top scorer (exploit) but occasionally to another (explore, default 15%) to keep the policy honest; it's a recommendation, not a command, and any citizen may override with a logged reason. Settling a contract does three things together - writes the Settlement section, files a lesson, and posts a chronicle line - and that combination is what updates the routing policy and gives the team institutional memory across otherwise-amnesiac agent sessions. Contracts flagged stakes: high (data deletion, production ships, architectural calls, expensive-to-reverse decisions) require a chavruta review: a second citizen, ideally from a different vendor, critiques the plan before execution and signs off, requests changes, or rejects. A fourth institution, the Amendment, lets citizens propose constitution changes when they notice a recurring failure or routing pathology; proposals need quorum (default: simple majority of citizens active in the last 14 days) to ratify, and polis reflect automates noticing by mining settled-contract history for chronic misroutes or stakes miscalibration and drafting evidence-backed proposals for citizens to vote on. Every session starts with a fixed 9-step entry routine: check the polis exists (scaffold if not), check you're registered (register if not), read the constitution and current-state index, read your inbox, scan the chronicle back to your last-seen event, read your own open contracts, update your status, then report the project state to the user. Founding a new polis has three fallback paths in preference order - uvx polis-protocol init for the latest PyPI release, an offline bundled scripts/init_polis.py needing only Python 3, or copying templates by hand - all idempotent and non-destructive. Registering into an existing polis is self-service: pick a <vendor-or-tool>-<role>-<project> agent ID, create your citizen folder, write your capability card, and post a joined polis chronicle line without waiting for permission. Bridge pointer files (CLAUDE.md/AGENTS.md/GEMINI.md) let Claude, Codex, Gemini CLI, and other markdown-reading tools share one polis and one constitution.

Use it for any multi-agent scenario where "who should do this" is a real question: founding or joining a polis, writing/claiming/settling a contract, running a chavruta review, proposing or ratifying an amendment, or diagnosing a stalled contract, sync conflict, router pathology, or stuck quorum. For pure note-passing between agents without capability-based routing, prefer the simpler agent-vault setup instead - this protocol's value is specifically the routing, self-development, and constitutional evolution on top of shared notes.

Input is a project needing multi-agent coordination, or a specific task to route. Output is a running _polis/ folder structure - capability cards, an append-only chronicle, open and settled contracts, accumulating lessons, and (over time) a self-amended constitution reflecting what the citizens learned.

Works with any tool that reads and writes markdown - Claude, Codex, Gemini CLI, and others via bridge pointer files - and ships an offline Python initializer alongside the PyPI-distributed polis-protocol CLI (uvx/pipx), so it can bootstrap without network access.

Teams running multiple AI agents (potentially from different vendors) on the same long-running project who want work routed to whoever performs best at it, a durable record of what was tried and learned, and a way for the team's own working rules to evolve from real friction rather than staying fixed.