Metadata-Version: 2.5
Name: zero-employee
Version: 0.9.1
Summary: Open-source tools and infrastructure for building Zero Employee Organizations powered by AI agents.
Project-URL: Homepage, https://zeroemployee.org
Project-URL: Documentation, https://zeroemployee.org/docs
Project-URL: Repository, https://github.com/zeroemployeeorg/zero-employee
Project-URL: Issues, https://github.com/zeroemployeeorg/zero-employee/issues
Project-URL: Changelog, https://github.com/zeroemployeeorg/zero-employee/releases
Author-email: Zero Employee Organizations <zeroemployeeorg@dreamhuggers.com>
Maintainer-email: Zero Employee Organizations Maintainers <zeroemployeeorg@dreamhuggers.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,automation,governance,llm-orchestration,sow-ruling-gate,zeo,zero-employee
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: typer>=0.27.1
Description-Content-Type: text/markdown

<div align="center">

# zero-employee

**A command-line toolkit for keeping AI-agent software work organized, reviewable, and recoverable.**

`zero-employee` installs the `zeo` command. It helps a team of humans and AI
agents turn raw ideas into tracked work, keep decisions in durable files, lint
those files, and see what needs attention next.

[![CI](https://github.com/zeroemployeeorg/zero-employee/actions/workflows/ci.yml/badge.svg)](https://github.com/zeroemployeeorg/zero-employee/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/zero-employee.svg?color=blue)](https://pypi.org/project/zero-employee/)
[![Python Version](https://img.shields.io/pypi/pyversions/zero-employee.svg)](https://pypi.org/project/zero-employee/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Start here](docs/getting-started.md) • [Tutorial](docs/tutorial.md) • [Mental model](docs/mental-model.md) • [Contributing](CONTRIBUTING.md)

</div>

---

## Who this is for

Use `zero-employee` if you are experimenting with AI agents that create code,
docs, designs, or reviews, and you need a better answer to:

- What work exists?
- Who or what is blocked?
- Which decisions were made?
- Which files prove the work is done?
- Can a new person or agent resume without reading a giant chat transcript?

You only need basic command-line and Python familiarity to start. The first
workflow is local: install the package, scaffold a tiny example corpus, capture
one idea, and ask `zeo` what to do next.

## What `zeo` gives you

- **A corpus**: a normal git repository that stores your work records.
- **Intake files**: quick notes for raw ideas before you know the exact work.
- **SOWs**: “Statements of Work” with machine-checked status, scope, and done criteria.
- **Rulings**: durable decisions that answer design or governance questions.
- **Boards and triage**: generated views that show what needs attention.
- **Hooks and scaffolding**: optional guardrails for teams using agents, Codex,
  Claude Code, Cursor, Gemini, or plain git.
- **Session tooling**: branch/worktree/session cleanup for multi-agent work.

The important idea: chat is temporary; the corpus is the durable record.

## Install

Recommended:

```bash
uv tool install zero-employee
zeo --version
```

If you do not have `uv` yet:

```bash
python -m pip install uv
uv tool install zero-employee
```

Standard `pip` also works:

```bash
python -m pip install zero-employee
zeo --version
```

Requirements: Python 3.11 or newer.

The old `sow-lint` executable name still works as a compatibility alias for
older corpora and historical checks. New docs, scripts, and CI should use
`zeo`. In GitHub Actions, prefer the check/workflow name
`zeo-sow-ruling-gate` for SOW/ruling validation.

Upgrade an existing install:

```bash
uv tool upgrade zero-employee
```

If `zeo --version` still shows an old version, your shell is finding a different
`zeo` executable first. Run `which zeo` to see which one.

## 10-minute first run

This creates a disposable practice corpus in `/tmp`, captures one idea, and
shows the basic dashboard.

```bash
mkdir -p /tmp/zeo-demo
cd /tmp/zeo-demo
git init
git branch -m main
zeo init
git add .gitignore CLAUDE.md claude-md governance intake
git commit -m "initialize zeo corpus"
zeo intake "add a health-check endpoint to the demo service"
zeo
zeo triage
```

What just happened:

1. `zeo init` created the minimum files that make this directory a ZEO corpus.
2. `zeo intake ...` saved your idea as a small Markdown file under `intake/`.
3. `zeo` printed the orientation dashboard.
4. `zeo triage` showed whether anything needs a decision, a successor, or cleanup.

Next: follow the full [Getting started guide](docs/getting-started.md).

## The beginner path

Read these in order:

1. [Getting started](docs/getting-started.md) — copy/paste setup and first useful commands.
2. [Mental model and glossary](docs/mental-model.md) — corpus, SOW, ruling, stream, seat, session.
3. [Tutorial](docs/tutorial.md) — convert one raw idea into a grounded SOW.
4. [Codex swap guide](docs/codex-swap.md) — if you want Codex Master/Sparring/Stream seats.
5. [Contributing](CONTRIBUTING.md) — if you want to change `zero-employee` itself.

## Common commands

| Command | Use it when you want to... |
| --- | --- |
| `zeo` | See where you are and what the tool thinks you should do next. |
| `zeo init` | Turn the current git repo into a ZEO corpus. |
| `zeo intake "..."` | Capture a raw idea without writing YAML. |
| `zeo new` | Start an intake, SOW, or project from a guided menu. |
| `zeo work` | List governed work that can be continued. |
| `zeo next` | Ask for the highest-priority next action. |
| `zeo triage` | Show the operator worklist: blocked items, open questions, handoffs. |
| `zeo board` | Regenerate local `STATE.md` from corpus files. |
| `zeo sow new ...` | Create a schema-valid Statement of Work. |
| `zeo doctor PATH` | Explain what is wrong with one SOW or changed files. |
| `zeo hooks install` | Install local git hooks for linting ZEO files. |
| `zeo help --all` | Show the full command reference for the installed version. |

## Minimal workflow

For a solo developer:

```bash
zeo intake "describe the problem in plain English"
zeo intake mission intake/<created-file>.md
# investigate the real repo, then follow docs/tutorial.md to propose and promote
zeo triage
```

For an agent-assisted team:

```bash
zeo orient --json
zeo relay register --seat master --instance master-demo-1 --runtime codex
git checkout -b master/demo-20260824
zeo session start --id master-demo-20260824 --master master-demo-1 --branch master/demo-20260824
zeo workspace create --seat master --instance master-demo-1
zeo session status --id master-demo-20260824
```

The first workflow is the one to learn first. The second is for teams already
running multiple agent seats and branches.

## Repository layout after `zeo init`

```text
my-org/
├── claude-md/CLAUDE.md       # corpus marker and imported doctrine entrypoint
├── governance/GOVERNANCE.md  # tool-neutral governance starter
├── intake/                   # raw ideas live here first
├── projects/                 # SOWs grouped by project and stream
├── ruling/                   # durable decisions
└── .zeo/                     # local runtime state, ignored by git
```

Generated board files such as `STATE.md` and `stream-index.md` are local views.
They are intentionally ignored by git.

## Developing this package

```bash
git clone https://github.com/zeroemployeeorg/zero-employee.git
cd zero-employee
make setup
make verify
```

`make verify` runs formatting checks, linting, and the full test suite. See
[CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow.

## Documentation

- [Getting started](docs/getting-started.md)
- [Mental model and glossary](docs/mental-model.md)
- [Tutorial](docs/tutorial.md)
- [Seat identities](docs/seats.md)
- [Codex swap guide](docs/codex-swap.md)
- [Release process](docs/releasing.md)
- [Non-goals](docs/non-goals/README.md)
- [Changelog](CHANGELOG.md)

## License

MIT. See [LICENSE](LICENSE).
