ProtocolCity-BluePrint

Pre-release (0.1.x). Installable suite for coordinating AI agents with plain files you own — WorkLane (work orders) · WorkForce (agents) · this BluePrint (map + CLI). Expect sharp edges; file issues.

A map of the AI instructions already living in your project folders.
It does not replace Claude, Cursor, or Grok — it shows what those agents are supposed to follow, who is hired, and which work orders are still open.

Every agent has instructions. Every job is a file. Every work order closes the loop.

Install the suite (recommended)

macOS (Homebrew)

brew install protocolcity/tap/blueprint
blueprint setup                 # soft default ~/BluePrint — or use an existing folder
# blueprint setup ~/my-workspace --create --yes
blueprint serve --root ~/BluePrint --with-engines
# → http://127.0.0.1:8801/  (Overview; Map digs in at /workspace-map)

That installs the BluePrint suite (CLI + Map) and pulls WorkLane + WorkForce from PyPI. The taught CLI is blueprint only (no protocolcity command alias). Product source repos stay separate; install does not require cloning them.

Windows — first time (nothing installed)

1. Install Python once from python.org/downloads/windows
(Python 3.11+). Tick Add python.exe to PATH, finish, then open a new PowerShell.

2. Paste this whole block into PowerShell and press Enter:

py -3 -m pip install --upgrade pip
py -3 -m pip install --upgrade "protocolcity[engines]"
blueprint setup "$env:USERPROFILE\ProtocolCity" --create --yes
blueprint serve --root "$env:USERPROFILE\ProtocolCity"
# If blueprint is not on PATH: py -3 -m protocolcity setup … / serve …

3. Open http://127.0.0.1:8801/ in your browser.
Leave PowerShell open while you use the suite. Stop with Ctrl+C.

Stuck? WINDOWS_FIRST_USER.md — PATH fixes, firewall, next-day restart.

Any OS (pip)

python3 -m pip install --upgrade "protocolcity[engines]"

What to clone vs install

You want… Do this
Run the suite (Overview · Map · work orders · agents on the map) macOS: Homebrew · Windows/Linux: pip (three packages above)
Read the papers (Charter, templates, example) Browse/clone ProtocolCity-BluePrint — docs only
Contribute to an engine Clone WorkLane / WorkForce source repos (developer path)

Cloning BluePrint alone does not install a runnable suite.

What you see

Open the suite → Overview (system summary). Click Map (http://127.0.0.1:8801/workspace-map) to dig in — then click a project folder to see:

Layer What it is Typical files
You Human decisions and gates (you, in the loop)
Workspace Rules for the whole folder root AGENTS.md, boundaries
Project One app or repo under the workspace project AGENTS.md
Agent (worker/hand) Hired AI that claims work orders workers/<id>/CONTRACT.md · roster kind=lane
This run Shift brief for that agent workers/<id>/prompt.md
Job Scheduled workspace duty (Map diamond) roster kind=job · seed-ops
Work orders Tracked tickets until done WorkLane desk

Nobody has to learn a “city” metaphor to run the system. Optional deeper docs (Charter, Manifesto) keep the brand story for people who want it.

Why

Agents are brilliant and unaccountable. Every vendor wants orchestration to live inside its own runtime, in its own config format. Decisions evaporate in chat windows. BluePrint is the opposite bet: coordination as files you can read, work orders you can audit, and agents that sign what they do — owned by you.

WorkLane tracks work orders. WorkForce runs hired agents.
BluePrint is the map that ties the folder, the instructions, and the loop together.

What's inside

Papers live on GitHub (links work from PyPI too):

Document What it is
CHARTER.md Full protocol spec (advanced / optional depth)
MANIFESTO.md Why we built this — brand voice
FOUNDING.md Paper path: templates + compliance (no install)
RUNNING.md Day-to-day loops after setup
templates/ Fill-in-the-blank instruction files
example/ Minimal workspace (one root, one project, one agent)

The short version

A workspace is one root folder. Each project is a subfolder with instructions agents must follow (AGENTS.md). Work moves as work orders. Your agents are any vendor, each with a registered identity that signs what it does. Boundaries say what agents may not touch.

A project is set up well when three things are true:

  1. Instructions exist — an AGENTS.md at its root.
  2. Work is tracked — a work order with clear scope.
  3. Agents sign — every action carries a registered identity.

Start with one project, one agent, one instruction file — FOUNDING.md walks the paper path; the install path above opens the map so you can see the same structure visually.

Report a bug

Local only until you paste. No telemetry.

You alone

blueprint feedback --write
# or: blueprint feedback ~/my-workspace --open

Paste into ProtocolCity-BluePrint issues.

With any AI host (Cursor / Claude / Grok)

  1. Run blueprint feedback --agent-prompt and paste that ritual into chat
    (or: “File a BluePrint beta bug — run blueprint feedback and fill symptoms”).
  2. Agent gathers versions/doctor/logs, redacts secrets, fills Summary/Expected/Actual.
  3. You paste the markdown into the issues URL. Agents do not post without you.

Rough routing:

Symptom Board
Overview / Map / setup / serve shell BluePrint issues
Work orders / tk / desk stores WorkLane issues
Hire / roster / agent daemon WorkForce issues
Formula only homebrew-tap

Status

v0.1.x pre-release. Install path (Homebrew / PyPI) is live. Suite UX is map-first and still sharpening. Expect the shell and ship words to move quickly as first-user feedback lands.

License

CC BY 4.0 — use it, adapt it, build on it, with attribution.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.48)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for seoeli from gravatar.com seoeli

Requires

Python >=3.9

Provides Extra

engines

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

protocolcity-0.1.29.tar.gz (631.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

protocolcity-0.1.29-py3-none-any.whl (620.5 kB view details)

Uploaded Python 3

File details

Details for the file protocolcity-0.1.29.tar.gz.

File metadata

  • Download URL: protocolcity-0.1.29.tar.gz
  • Upload date:
  • Size: 631.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.9.6

File hashes

Hashes for protocolcity-0.1.29.tar.gz
Algorithm Hash digest
SHA256 1e79989e0259e78d9e7f068151de1f39cd305982a0f3f66a146d25e43cb5c8b3
MD5 3b575fe134f71d983f779050e56867cc
BLAKE2b-256 af4c5e491289680c1d49dbace0014abb3c1a91679d8aa26859f803e6c276e5e5

See more details on using hashes here.

File details

Details for the file protocolcity-0.1.29-py3-none-any.whl.

File metadata

  • Download URL: protocolcity-0.1.29-py3-none-any.whl
  • Upload date:
  • Size: 620.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.9.6

File hashes

Hashes for protocolcity-0.1.29-py3-none-any.whl
Algorithm Hash digest
SHA256 5f5847263ca2890799f7b7281da4a55951da2636a2489b385be28a4d90040346
MD5 a53fd106e936ee51edabab66bb03c324
BLAKE2b-256 f77848b994513432e347aa7f045c13c757ee93f2d594ba0f0065aa1e66d4b8b7

See more details on using hashes here.

Release history Release notifications | RSS feed

0.1.48

2 files

0.1.47

2 files

0.1.46

2 files

0.1.45

2 files

0.1.44

2 files

0.1.43

2 files

0.1.42

2 files

0.1.41

2 files

0.1.40

2 files

0.1.39

2 files

0.1.38

2 files

0.1.37

2 files

0.1.36

2 files

0.1.34

2 files

0.1.33

2 files

0.1.32

2 files

0.1.31

2 files

0.1.30

2 files

This release

0.1.29 This release

2 files

0.1.28

2 files

0.1.27

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page