zero-employee 0.3.0

Overview

zero-employee (zeo) is the governance layer and linter for multi-agent software organizations. It enforces deterministic schema validation, cost tracking, state board generation, and IDE/agent bridge synchronization across your entire repository fleet.

              ┌─────────────────────────────────┐
              │       GOVERNANCE DOCTRINE       │
              │       (CLAUDE.md / Rulings)     │
              └────────────────┬────────────────┘
                               │
           RULINGS             │  ▲  SOWs
        (Top-to-Bottom)        │  │ (Bottom-to-Top)
        Mandates & Precedents  │  │ Status & Deliverables
                               ▼  │
              ┌────────────────┴────────────────┐
              │       PROJECT WORKSTREAMS       │
              │    (projects/<repo>/sow/...)    │
              └─────────────────────────────────┘

Key Features

• Deterministic SOW Linting: Enforces strict frontmatter schemas (sow:, n:, status:, restaufwand:, done_when:).
• Zero-Clutter Scaffolding: Clean-by-default repository and workstream generation with opt-in IDE bridges (--cursor, --gemini, --claude, --agents).
• Cost & Token Proxies: Real-time token tracking (--session-cost, --repo-cost) with live rate cards.
• Fleet State Board (STATE.md): Local navigation board of active streams, open questions, and held workstreams (gitignored — regenerate with zeo --board, never commit).

Installation

Install globally via uv (recommended) or pip:

# Recommended (isolated global executable):
uv tool install zero-employee

# Standard pip install:
pip install zero-employee

Requirements: Python 3.11 or higher.

Quick Start

Want the real, worked walkthrough instead of a flag list? See the Tutorial — every command in it was actually run and its real output is shown.

zeo discovers a corpus by walking up from the current directory looking for claude-md/CLAUDE.md. You can also set ZEO_SOWS_ROOT or pass an explicit path.

# From inside a corpus (or with ZEO_SOWS_ROOT set):
zeo                     # human orientation dashboard
zeo orient --json       # agent briefing (canonical first command)
zeo new                 # start intake / SOW / project
zeo work                # continue governed work
zeo triage              # what needs attention
zeo help                # progressive help
zeo help --all          # full command reference

# Target a specific corpus path from anywhere:
zeo board /path/to/corpus
ZEO_SOWS_ROOT=/path/to/corpus zeo triage

If no corpus is found, zeo still orients you (suggests zeo init) and exits zero—it never hallucinates a board.

Command Reference

zeo accepts the same arguments as zeo.

Stream Priority (Nutzwertanalyse)

zeo --priority [path] ranks every OPEN/PAUSED/BLOCKED stream so a Master session has a stated, revisable reason for which stream gets the next session's tokens, instead of --triage's age-only ordering. It is a separate verb from --triage by design — triage stays the fast, unopinionated worklist; priority is the considered ranking you consult deliberately. It does not change --triage's own sort order.

Chartered by RULING-279 ("Nutzwertanalyse: ranking streams by token-denominated utility, not currency"), built against PRIORITY-NWA-SOW-1. The method is Nutzwertanalyse (German: utility-value analysis) — a weighted multi-criteria score, chosen over RICE (used elsewhere in this corpus, see RULING-278) because stream prioritization is a recurring, live ranking over a changing set of streams, not a one-shot scoring pass.

The four criteria — a first cut, explicitly flagged for revision (RULING-279 s5)

Nutzwert = (0.30 × Dringlichkeit_norm + 0.30 × Impact_norm + 0.15 × Risiko_norm)
           / Restaufwand_tokens

Dringlichkeit/Impact/Risiko are min-max normalized 0–1 across the current live stream set (relative to what else is competing for tokens this round — the Nutzwertanalyse convention, re-scored every run). Restaufwand sits directly in the denominator (utility-per-cost, not utility-minus-cost) so the two are never forced onto one invented exchange rate. Tokens throughout, never currency — --priority's own output never prints a $ figure.

When a stream declares no restaufwand: at all

A stream with no restaufwand: declaration and no SHIPPED/FINDING ledger claims to derive a per-claim token average from still ranks — it never silently drops out. Every row carries restaufwand_estimate_kind, one of:

• PER-STREAM-CLAIM-AVG — this stream's own tokens-per-claim figure.
• CORPUS-CLAIM-AVG — this stream declared restaufwand: but has no claims of its own yet; falls back to the corpus-wide average tokens-per-claim.
• ESTIMATE-LOCAL-MEDIAN — this stream has neither; falls back to the corpus median restaufwand-tokens as a last resort.

This mirrors cost.py's own tokenizer_label discipline: a degraded estimate is always visibly labeled, never a quiet number that looks as precise as a real one.

Opportunity cost, stated not implied (RULING-279 s3)

Every --priority run prints the top-N FUNDED streams and the next-M OPPORTUNITÄTSKOSTEN (opportunity cost) near-miss streams, each with its Nutzwert delta to the last funded stream — so picking stream A is a visible, stated decision not to fund stream B, C, D this round, not a hidden one.

zeo --priority                       # top 3 funded + next 3 near-miss, from cwd
zeo --priority --top 5 --near-miss 5 /path/to/corpus
zeo --priority --json                # machine-readable

What this does NOT do (PRIORITY-NWA-SOW-1 s3): it never changes --triage's own sort order, never prints currency, and never runs a full ant-CLI-equivalent credential resolution — a narrow, stated set of remediation paths only.

On the token credential (RULING-279 s4): --count-via anthropic and --calibrate (used by --kosten/--repo-cost, not by --priority itself) call Anthropic's free count_tokens endpoint and need an API key. A live Claude Code session's own credential is not exposed as an environment variable by default — this is the tool's most common execution context, not an edge case — so a missing key now fails loudly naming both remediation paths (set ANTHROPIC_API_KEY, or install and authenticate the ant CLI), and --api-key-env <VARNAME> lets a caller whose credential lives under a different variable name use it, without a full credential-chain resolver.

Modular IDE & Agent Scaffolding

Scaffolding commands stay clean by default to avoid polluting repositories with unused tool directories. You explicitly pass flags to generate tool-specific bridges:

# Clean SOW creation (no IDE clutter):
zeo sow new ducktyper render-pipeline --title "Render pipeline"

# Greenfield project+stream (also creates project CLAUDE.md):
zeo scaffold ducktyper render-pipeline

# Add Cursor MDC rules and .cursorrules symlink:
zeo scaffold ducktyper render-pipeline --cursor

# Add Gemini support:
zeo scaffold ducktyper render-pipeline --gemini

# Install the full agent & IDE bridge suite:
zeo scaffold ducktyper render-pipeline --all

Supported bridge flags: --cursor, --gemini, --claude, --agents, --all.

zeo equip — overriding the shipped templates

zeo equip <repo> installs the ALWAYS-tier .claude/ + CLAUDE.md files (see Command Reference) into a work repo. zero-employee is MIT-licensed and distributed on PyPI, so any file it writes can be adapted to your own org's needs without forking the package — a forked template silently opts you out of every future improvement, which is worse than the drift it was meant to avoid.

For each file zeo equip is about to write (never for a file the repo already has — see "never clobbers" below), it resolves the content to use through a 4-level precedence chain, first match wins:

1. The repo's own file, if it already exists. Reported kept, never touched, never read from as a content source. This is zeo equip's "never clobber by default" guarantee (--force overwrites; --diff previews without writing) — it is not itself an override source, just the reason overrides never apply to a file you've already customized in place.
2. $ZEO_TEMPLATES_DIR — an environment variable pointing at a directory shaped like scaffold_templates/ (e.g. $ZEO_TEMPLATES_DIR/CLAUDE.md, $ZEO_TEMPLATES_DIR/claude-settings.json). Explicit and highest-precedence among the override levels — set it in CI or a wrapper script to pin a specific org-wide template set.
3. ~/.config/zeo/templates/ — the same directory shape, per-user, for a developer's own standing preferences without needing an env var in every shell.
4. The packaged default (zero_employee/scaffold_templates/) — what ships in the wheel, used when neither override level has the file.

Every file zeo equip actually writes (from any of levels 2–4) is stamped with an UPSTREAM-SHA: <sha256 hex> line (#-, //-, or <!-- -->-commented, matching the file's own syntax), hashing the content that was actually written — an override's own bytes, not the packaged default's. This is deliberate: once a future zeo --resync-check gains visibility into .claude/, a template you've deliberately overridden must grade as current against itself, not show up as permanently "stale" against a packaged default you already chose not to use.

.claude/settings.json is the one exception to the comment-syntax list above: it is strict JSON, live-loaded by Claude Code itself, which has no tolerance for // or /* */ comments. Its stamp lives in a top-level "_upstreamSha" string field instead — real, hashed the same way, greppable — but not yet machine-discoverable by the shared UPSTREAM-SHA: regex the way the other files' stamps are.

Local Development & Testing

We use uv and make for deterministic, hermetic local builds:

# Clone repository
git clone https://github.com/zeroemployeeorg/zero-employee.git
cd zero-employee

# Setup virtualenv and install dependencies
make setup

# Run linting and test suite
make verify

Documentation & Resources

• Tutorial — A real, verified walkthrough: idea → grounded proposal → SOW → a design fork ruled and delivered → --priority. Start here if you want to see why, not just what.
• Getting Started Guide — Step-by-step onboarding for new corpora.
• Release Process — Versioning, changelogs, and PyPI publishing.
• Contributing Guidelines — Code style, test expectations, and PR rules.

License & Community

Distributed under the terms of the MIT License.

• Maintainer Email: zeroemployeeorg@dreamhuggers.com
• Organization: Zero Employee Organizations