Polis Protocol: A Self-Optimizing City of Agents

A protocol that lets a team of AI agents from different vendors collaborate on a long-running project, route work to whoever is best at it, and get measurably better over time. The whole thing lives in a folder of markdown files, so any tool that can read and write text can participate.

The core idea

Treat the project as a small polis: a city of citizens (the agents) that share a constitution (the protocol), publish public identities (capability cards), enter into contracts (tasks), and leave a public record of how things went (lessons). The polis has three institutions, and a fourth mechanism that lets the city itself change:

The Register: identity and capability discovery.
The Contract: structured tasks with learned routing.
The Chronicle: lessons that compound and feed back into routing.
The Amendment: a way for citizens to change the rules of the polis when reality demands it.

Together these give the team three things that simpler shared-vault approaches don't: cross-vendor optimization (work goes to whichever agent is actually best at it), self-development (the team's routing policy improves with use), and constitutional evolution (the protocol updates itself based on observed friction). Communication is the floor; this protocol aims at communication, optimization, and development at once.

The whole thing is portable because every artifact is a markdown file with structured YAML frontmatter. There is no central server. There is no required runtime. Any agent that can read and write text can participate.

When this skill is active

Activate this skill when the user is doing any of the following:

Setting up a new polis (bootstrapping the constitution, capability registry, contract folder, and chronicle).
Joining an existing polis as a new agent (publishing a capability card, reading the constitution, catching up on the chronicle, claiming a contract).
Writing a new contract (drafting intent and acceptance criteria, scoring candidate agents, routing).
Settling a contract (recording the outcome, writing the lesson, updating capability stats).
Running a chavruta review (paired critique of a high-stakes plan before execution).
Proposing or ratifying an amendment to the protocol.
Diagnosing a stalled contract, a sync conflict, a router pathology, or a quorum that cannot be reached.

If the user describes any multi-agent scenario where "who should do this" is a real question rather than "fine, whoever is available", this protocol applies. If the user already has agent-vault running and wants to upgrade, the migration path is straightforward (see references/troubleshooting.md, section "Migrating from agent-vault").

Structure of a polis

A polis lives inside a folder called _polis/ at the project root. The underscore prefix keeps it at the top of the file tree in Obsidian, VS Code, and most other tools. Everything outside _polis/ is project content and the protocol does not touch it.

<project-root>/
├── CLAUDE.md / AGENTS.md / GEMINI.md        (cross-tool entry pointers)
├── .agents/skills/polis-protocol/SKILL.md   (Codex-format skill copy)
├── _polis/
│   ├── CONSTITUTION.md                      (canonical tool-agnostic protocol)
│   ├── README.md                            (protocol explainer for humans)
│   ├── index.md                             (canonical project state)
│   ├── chronicle.md                         (append-only event log)
│   ├── citizens/
│   │   └── <agent-id>/
│   │       ├── capability_card.yml          (signed capability manifest)
│   │       ├── status.md                    (current state, last-seen pointer)
│   │       ├── inbox.md                     (messages from other citizens)
│   │       └── journal.md                   (private working notes)
│   ├── contracts/
│   │   ├── open/<contract-id>.md            (currently active)
│   │   ├── settled/<contract-id>.md         (closed with retrospective)
│   │   └── routing_stats.yml                (learned policy, updated on settle)
│   ├── lessons/
│   │   └── <capability-tag>/<lesson-id>.md  (filed by capability)
│   ├── reviews/
│   │   └── <YYYY-MM-DD-HHMM>-<contract>.md  (chavruta critique notes)
│   └── amendments/
│       ├── proposed/<amendment-id>.md
│       └── ratified/<amendment-id>.md
└── <project content folders>                (untouched)

Citizens link to project files using standard wikilinks ([[path/to/note]]). The _polis/ folder is the only thing the protocol owns.

The first thing to do every session

Before touching any project file, an agent runs the entry routine, in this order. This is the same shape as a well-run team meeting: read the state, hear what's pending for you, see what's in flight, then start work.

Check that the polis exists. Look for _polis/CONSTITUTION.md at the project root. If it does not exist, scaffold it (see "Founding a polis").
Check that you are registered. Look for _polis/citizens/<self>/capability_card.yml. If it does not exist, register (see "Registering a citizen").
Read _polis/CONSTITUTION.md if you have not already in this session. The constitution is the canonical version of this protocol; this SKILL.md is equivalent, but the constitution is what other tools read.
Read _polis/index.md. Short summary of where things stand. Two-minute read at most.
Read your inbox. _polis/citizens/<self>/inbox.md holds anything other citizens left for you.
Scan the tail of chronicle.md. Read backward from the end until you hit the timestamp recorded in your status.md under last_seen_event:. That is your catch-up.
Read your open contracts. Anything in _polis/contracts/open/ with owner: <self> in its frontmatter.
Update last_seen_event and last_active in your status.md. This is how your next session knows where to pick up.
Report back to the user. A short summary: state of the project, what is in flight, what wants your input, and a concrete suggestion for the first move.

The whole routine should take a couple of small reads. If chronicle.md has grown large, the rollover policy (see references/troubleshooting.md) keeps it bounded.

Recording what you did: the chronicle

After each meaningful action, append exactly one line to _polis/chronicle.md. The format is rigid on purpose, because the chronicle is parsed by the router and by other citizens, and an unreadable log is worse than no log at all.

- YYYY-MM-DD HH:MM | <agent-id> | <verb-phrase> | [[<wikilink>]] | <one-line note or - >

Examples:

- 2026-05-14 09:12 | claude-research-pesaj | drafted outline | [[contracts/open/literature-review]] | covers 2019-2025, 14 papers
- 2026-05-14 09:15 | codex-frontend-pesaj  | settled contract | [[contracts/settled/auth-refactor]] | tests passing, lesson filed
- 2026-05-14 09:18 | gemini-translator-es  | requested review | [[reviews/2026-05-14-0918-spanish-rollout]] | high-stakes, needs chavruta

A meaningful action is anything another citizen needs to know about: a contract opened or settled, a handoff, a blocker hit, a review requested, an amendment proposed, an index keeper change. Internal reasoning and minor edits stay in your private journal.md and never reach the chronicle. The signal-to-noise ratio of the chronicle is the single most important thing to protect.

Reserved verb phrases (these carry semantic meaning that scripts and other agents may filter on):

joined polis, left polis: registration and retirement.
opened contract, claimed contract, settled contract, abandoned contract: contract lifecycle.
filed lesson: a retrospective was written into lessons/.
requested review, signed off, rejected review: chavruta lifecycle.
proposed amendment, ratified amendment, rejected amendment: amendment lifecycle.
blocked on <thing>, unblocked: state transitions f

polis-protocol