Bundled upstream support

Supporting files are included at skill-relative paths. See UPSTREAM-NOTICE.md for their pinned sources, licenses, hashes, and import changes.

Polis Protocol: A Self-Optimizing City of Agents

When to Use

Use this skill when you need polis Protocol: A Self-Optimizing City of Agents.

A protocol that lets 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. Everything lives in a folder of markdown files, so any tool that reads and writes text can participate — no central server, no required runtime.

The core idea

Treat the project as a small polis: citizens (the agents) that share a constitution (the protocol), publish public identities (capability cards), enter contracts (tasks), and leave a public record of how things went (lessons). Three institutions plus a self-change mechanism:

1. The Register — identity and capability discovery (capability cards).
2. The Contract — structured tasks with learned routing.
3. The Chronicle — lessons that compound and feed back into routing.
4. The Amendment — citizens change the rules when reality demands it.

This buys what shared-vault setups don't: cross-vendor optimization (work goes to whoever is best at it), self-development (routing improves with use), and constitutional evolution (the protocol updates itself from friction). For pure note-passing without routing, prefer agent-vault.

When this skill is active

Any multi-agent scenario where "who should do this" is a real question: founding or joining a polis; writing, claiming, or settling a contract; running a chavruta review; proposing or ratifying an amendment; or diagnosing a stalled contract, sync conflict, router pathology, or stuck quorum. Upgrading from agent-vault → references/troubleshooting.md ("Migrating from agent-vault").

Structure of a polis

A polis lives in a _polis/ folder at the project root; everything outside it is project content the protocol never touches.

• CONSTITUTION.md — canonical tool-agnostic protocol · index.md — current state · README.md — human explainer
• chronicle.md — append-only event log
• citizens/<agent-id>/ — capability_card.yml, status.md, inbox.md, journal.md
• contracts/open/<id>.md · contracts/settled/<id>.md · contracts/routing_stats.yml (learned policy, updated on settle)
• lessons/<capability-tag>/<id>.md · reviews/<YYYY-MM-DD-HHMM>-<contract>.md · amendments/proposed|ratified/
• Project root also gets CLAUDE.md / AGENTS.md / GEMINI.md bridge pointers and .agents/skills/polis-protocol/SKILL.md (Codex/Antigravity copy), all pointing at CONSTITUTION.md.

Citizens link to project files with 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, run the entry routine, in order:

1. Polis exists? Look for _polis/CONSTITUTION.md. If absent, scaffold it (see "Founding a polis").
2. You are registered? Look for _polis/citizens/<self>/capability_card.yml. If absent, register (see "Registering a citizen").
3. Read _polis/CONSTITUTION.md once per session — it is the canonical protocol for this polis; this SKILL.md is the seed it grew from.
4. Read _polis/index.md — where things stand (a two-minute read).
5. Read your inbox — _polis/citizens/<self>/inbox.md.
6. Scan the tail of chronicle.md backward until you reach the last_seen_event: in your status.md. That is your catch-up.
7. Read your open contracts — anything in _polis/contracts/open/ with owner: <self>.
8. Update last_seen_event and last_active in your status.md.
9. Report back to the user — state of the project, what's in flight, what needs their input, a concrete first move.

If chronicle.md has grown large, the rollover policy (references/troubleshooting.md) keeps it bounded.

The chronicle: recording what you did

After each meaningful action, append exactly one line to _polis/chronicle.md. The format is rigid because the router and other citizens parse it:

- YYYY-MM-DD HH:MM | <agent-id> | <verb-phrase> | [[<wikilink>]] | <one-line note or - >
- 2026-05-14 09:15 | codex-frontend-pesaj | settled contract | [[contracts/settled/auth-refactor]] | tests passing, lesson filed

…