polis-protocol

# 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:

1. **The Register**: identity and capability discovery.
2. **The Contract**: structured tasks with learned routing.
3. **The Chronicle**: lessons that compound and feed back into routing.
4. **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          (content-hashed 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.

1. **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").
2. **Check that you are registered.** Look for `_polis/citizens/<self>/capability_card.yml`. If it does not exist, register (see "Registering a citizen").
3. **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.
4. **Read `_polis/index.md`.** Short summary of where things stand. Two-minute read at most.
5. **Read your inbox.** `_polis/citizens/<self>/inbox.md` holds anything other citizens left for you.
6. **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.
7. **Read your open contracts.** Anything in `_polis/contracts/open/` with `owner: <self>` in its frontmatter.
8. **Update `last_seen_event` and `last_active` in your `status.md`.** This is how your next session knows where to pick up.
9. **Report back to the user.** A shor