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-blueprint[engines]"
# Forever-compat alias: 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-blueprint[engines]"
# Forever-compat alias still works: pip install --upgrade "protocolcity[engines]"

What to clone vs install

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:

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

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:

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.