zero-employee 0.1.7

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

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.

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.

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

• 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