@the-open-engine/zeroshot 6.2.0 → 6.4.0

package/README.md

@@ -1,554 +1,221 @@
-# zeroshot CLI
+<div align="center">
 
-> **🎉 New in v5.4:** Now supports **OpenCode** CLI! Use Claude, Codex, Gemini, or OpenCode as your AI provider. Also supports **GitHub, GitLab, Jira, and Azure DevOps** as issue backends. See [Providers](#providers) and [Multi-Platform Issue Support](#multi-platform-issue-support).
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/brand/zeroshot-hero-dark.png">
+  <img alt="Zeroshot. Self-driving software engineering. Layer 01 · Verification, The Open Engine." src="docs/brand/zeroshot-hero-light.png" width="100%">
+</picture>
 
-<!-- install-placeholder -->
-<p align="center">
-  <code>npm install -g @the-open-engine/zeroshot</code>
-</p>
-
-<p align="center">
-  <img src="./docs/assets/zeroshot-demo.gif" alt="Demo" width="700">
-  <br>
-  <em>Demo (100x speed, 90-minute run, 5 iterations to approval)</em>
-</p>
-
-[![CI](https://github.com/the-open-engine/zeroshot/actions/workflows/ci.yml/badge.svg)](https://github.com/the-open-engine/zeroshot/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@the-open-engine/zeroshot.svg)](https://www.npmjs.com/package/@the-open-engine/zeroshot)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/)
-![Platform: Linux | macOS](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue.svg)
-
-<!-- discord-placeholder -->
-
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/PdZ3UEXB)
-
-Zeroshot is an open-source AI coding agent orchestration CLI that runs multi-agent workflows to autonomously implement, review, test, and verify code changes.
+&nbsp;
 
-It runs a **planner**, an **implementer**, and independent **validators** in isolated environments, looping until changes are **verified** or **rejected** with actionable, reproducible failures.
+<a href="https://theopenengine.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/brand/social/website-dark.png"><img alt="Website" src="docs/brand/social/website-light.png" height="30"></picture></a>
+<a href="https://x.com/OpenEngineCo"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/brand/social/x-dark.png"><img alt="X · @OpenEngineCo" src="docs/brand/social/x-light.png" height="30"></picture></a>
+<a href="https://www.linkedin.com/company/the-open-engine-company"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/brand/social/linkedin-dark.png"><img alt="LinkedIn" src="docs/brand/social/linkedin-light.png" height="30"></picture></a>
+<a href="https://discord.gg/fZyzf2Cut9"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/brand/social/discord-dark.png"><img alt="Discord" src="docs/brand/social/discord-light.png" height="30"></picture></a>
 
-Built for tasks where correctness matters more than speed.
+[![npm](https://img.shields.io/npm/v/@the-open-engine/zeroshot?style=flat&labelColor=171411&color=171411)](https://www.npmjs.com/package/@the-open-engine/zeroshot)
+[![CI](https://img.shields.io/github/actions/workflow/status/the-open-engine/zeroshot/ci.yml?style=flat&labelColor=171411&label=CI)](https://github.com/the-open-engine/zeroshot/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-171411?style=flat)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2018-171411?style=flat)](#install)
+[![platforms](https://img.shields.io/badge/platforms-linux%20%C2%B7%20macos-171411?style=flat)](#install)
+[![stars](https://img.shields.io/github/stars/the-open-engine/zeroshot?style=flat&labelColor=171411&color=171411)](https://github.com/the-open-engine/zeroshot)
+[![Layer 01 · The Open Engine](https://img.shields.io/badge/Layer_01-The_Open_Engine-C2240C?style=flat&labelColor=171411)](#the-open-engine)
 
-## How It Works
+</div>
 
-- Plan: translate a task into concrete acceptance criteria
-- Implement: make changes in an isolated workspace (local, worktree, or Docker)
-- Validate: run automated checks with independent validators
-- Iterate: repeat until verified, or return actionable failures
-- Resume: crash-safe state persisted for recovery
+**The agent that wrote the code shouldn't be the one that says it works.**
 
-## Quick Start
+Zeroshot is an open-source, multi-agent orchestration engine for autonomous software engineering. It drives a coding agent you already run (Claude Code, OpenAI Codex, Gemini CLI, or OpenCode) through an **executor-verifier loop**: an agent writes the change, then an _independent_ verifier that never saw how it was made approves it, or hands back a reproducible failure. The loop runs until the change is verified.
 
-```bash
-zeroshot run 123                    # GitHub issue number
-zeroshot run feature.md             # Markdown file
-zeroshot run "Add dark mode"        # Inline text
-```
+## Install
 
-Or describe a complex task inline:
-
-```bash
-zeroshot run "Add optimistic locking with automatic retry: when updating a user,
-retry with exponential backoff up to 3 times, merge non-conflicting field changes,
-and surface conflicts with details. Handle the ABA problem where version goes A->B->A."
-```
-
-## Why Not Just Use a Single AI Agent?
-
-| Approach                   | Writes Code | Runs Tests | Blind Validation | Iterates Until Verified |
-| -------------------------- | ----------- | ---------- | ---------------- | ----------------------- |
-| Chat-based assistant       | ✅          | ⚠️         | ❌               | ❌                      |
-| Single coding agent        | ✅          | ⚠️         | ❌               | ⚠️                      |
-| **Zeroshot (multi-agent)** | ✅          | ✅         | ✅               | ✅                      |
-
-## Use Cases
-
-- Autonomous AI code refactoring
-- AI-powered pull request automation
-- Automated bug fixing with validation
-- Multi-agent code generation for software engineering
-- Agentic coding workflows with blind validation
-
-## Who Is This For?
-
-- Senior engineers who care about correctness and reproducibility
-- Teams automating PR workflows and code review gates
-- Infra/platform teams standardizing agentic workflows
-- Open-source maintainers working through issue backlogs
-- AI power users who want verification, not vibes
-
-## Install and Requirements
-
-**Platforms**: Linux, macOS. Windows (native/WSL) is deferred while we harden reliability and multi-provider correctness.
+<!-- install-placeholder -->
 
 ```bash
 npm install -g @the-open-engine/zeroshot
 ```
 
-**Requires**: Node 18+, at least one provider CLI (Claude Code, Codex, Gemini, Opencode).
-
-```bash
-# Install one or more providers
-npm i -g @anthropic-ai/claude-code
-npm i -g @openai/codex
-npm i -g @google/gemini-cli
-# Opencode: see https://opencode.ai
-
-# Authenticate with the provider CLI
-claude login        # Claude
-codex login         # Codex
-gemini auth login   # Gemini
-opencode auth login # Opencode
-
-# GitHub auth (for issue numbers)
-gh auth login
-```
-
-## Providers
-
-Zeroshot shells out to provider CLIs. Pick a default and override per run:
-
-```bash
-zeroshot providers
-zeroshot providers set-default codex
-zeroshot run 123 --provider gemini
-```
-
-See `docs/providers.md` for setup, model levels, and Docker mounts.
-See `docs/provider-cli-helper.md` for the strict TypeScript provider helper,
-the `zeroshot-agent-provider` JSON executable contract, and the boundary with
-Orchestra.
-
-## Why Multiple Agents?
-
-Single-agent sessions degrade. Context gets buried under thousands of tokens. The model optimizes for "done" over "correct."
-
-Zeroshot fixes this with isolated agents that check each other's work. Validators can't lie about code they didn't write. Fail the check? Fix and retry until it actually works.
-
-## What Makes It Different
-
-- **Blind validation** - Validators never see the worker's context or code history
-- **Repeatable workflows** - Task complexity determines agent count and model selection
-- **Accept/reject loop** - Rejections include actionable findings, not vague complaints
-- **Crash recovery** - All state persisted to SQLite; resume anytime
-- **Isolation modes** - None, git worktree, or Docker container
-- **Cost control** - Model ceilings prevent runaway API spend
-
-## Required Handoff Quality Gates
-
-Zeroshot owns a tool-neutral handoff contract for `--pr` and `--ship` flows. It does not know which tool produced a gate. Repos configure required gates, validators publish matching `qualityGates` evidence, and the git-pusher trigger refuses to wake until every configured gate has fresh passing evidence after `IMPLEMENTATION_READY`.
-
-Gate config can come from run options or repo settings:
-
-```json
-{
-  "ship": {
-    "requiredQualityGates": [
-      {
-        "id": "repo-quality",
-        "scope": "repo",
-        "description": "Repository quality gate",
-        "command": "repo-quality --changed --json"
-      }
-    ]
-  }
-}
-```
-
-The `id` and optional `scope` are generic. A repo may bind `repo-quality` to any local quality command, a CI status command, or another quality command outside Zeroshot. Validators receive the configured gate list and must publish entries with `status`, `completedAt` or `timestamp`, and `evidence.command`, `evidence.exitCode`, and string `evidence.output`. Failing or unavailable commands mean `approved: false` with gate status `FAIL` or `UNAVAILABLE`.
+Requires **Node ≥ 18** and at least one provider CLI (Claude Code, Codex, Gemini, or OpenCode). Linux and macOS today; Windows is deferred.
 
-The pusher fails closed before commit, push, PR creation, or merge when a configured gate is missing, failing, unavailable, stale, older than `IMPLEMENTATION_READY`, or lacks usable evidence. If no `requiredQualityGates` are configured, Zeroshot preserves its existing validator consensus behavior.
-
-## Cmdproof Command Reuse
-
-Clusters can make expensive exact commands reusable across workers and validators with `cmdproof`. Zeroshot does not intercept arbitrary shell commands; it gives agents a cluster-scoped helper for configured command proofs.
+<div align="center">
+  <img src="docs/assets/zeroshot-demo.gif" alt="Zeroshot resolving an issue through the executor-verifier loop" width="760">
+  <br>
+  <em>One run, unattended. 100× speed · 90-minute run · 5 iterations to approval.</em>
+</div>
 
-Issue bodies can opt in per run:
+## How it works
 
-````markdown
-```zeroshot-command-proofs
-[
-  {
-    "id": "repo-ci",
-    "profile": "ci-equivalent",
-    "scope": "repo",
-    "description": "Repository local CI-equivalent gate",
-    "command": "bash ./scripts/ci/run-local-ci-equivalent.sh"
-  }
-]
-```
-````
-
-Repos can also configure the same commands in `.zeroshot/settings.json`:
-
-```json
-{
-  "ship": {
-    "commandProofs": [
-      {
-        "id": "repo-ci",
-        "profile": "ci-equivalent",
-        "scope": "repo",
-        "description": "Repository local CI-equivalent gate",
-        "command": "bash ./scripts/ci/run-local-ci-equivalent.sh"
-      }
-    ]
-  }
-}
-```
+Zeroshot separates the agent that **writes** the code from the agent that **judges** it.
 
-Agents receive instructions to use:
+A conductor sizes the workflow to the task. An executor (an AI coding agent) implements the change in an isolated workspace (git worktree or Docker). Then an **independent verifier** inspects the result without ever seeing the executor's context or history, so it cannot approve its own reasoning. The verifier returns `APPROVED`, or `REJECTED` with an actionable, reproducible failure, and the loop repeats until the change is verified or hands back a concrete reason it isn't. Every step is written to a crash-safe SQLite ledger, so a run survives a reboot and resumes where it stopped.
 
-```bash
-zeroshot cmdproof check repo-ci
+```text
+task --> plan --> implement --> verify --> APPROVED --> done
+                      ^            |
+                      +- REJECTED -+   (reproducible failure)
 ```
 
-The helper uses a cluster-local cache and trusted-agent key under `~/.zeroshot/cmdproof/<cluster-id>/`, runs `cmdproof verify` first, and falls back to `cmdproof prove --fallback run` on misses. In `--ship` flows, configured command proofs are also required handoff quality gates.
-
-## When to Use Zeroshot
-
-Zeroshot performs best when tasks have clear acceptance criteria.
+Bring your own provider and your own backend. Zeroshot orchestrates the agents that write your code; it doesn't store your keys or replace your models.
 
-| Scenario                                        | Use | Why                       |
-| ----------------------------------------------- | --- | ------------------------- |
-| Add rate limiting (sliding window, per-IP, 429) | Yes | Clear requirements        |
-| Refactor auth to JWT                            | Yes | Defined end state         |
-| Fix login bug                                   | Yes | Success is measurable     |
-| Fix 2410 lint violations                        | Yes | Clear completion criteria |
-| Make the app faster                             | No  | Needs exploration first   |
-| Improve the codebase                            | No  | No acceptance criteria    |
-| Figure out flaky tests                          | No  | Exploratory               |
+## How is this different from a single coding agent?
 
-Rule of thumb: if you cannot describe what "done" means, validators cannot verify it.
+|                             | A single coding agent        | Zeroshot                                                                                    |
+| --------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
+| Who says it is correct?     | the same agent that wrote it | a separate agent that never saw how it was written                                          |
+| Is the code actually run?   | usually just claimed         | executed against your real tests                                                            |
+| When it fails, you get      | an assertion it is fine      | a reproducible failure                                                                      |
+| When does it stop?          | when it decides it is done   | when the change is verified, or provably is not                                             |
+| Which coding agent runs it? | one, fixed                   | any you already run: Zeroshot is the harness around Claude Code, Codex, Gemini, or OpenCode |
 
-## Command Overview
+## Quick start
 
 ```bash
-# Run
-zeroshot run 123                      # GitHub issue
-zeroshot run feature.md               # Markdown file
-zeroshot run "Add dark mode"          # Inline text
-
-# Isolation
-zeroshot run 123 --worktree       # git worktree
-zeroshot run 123 --docker         # container
-
-# Automation (--ship implies --pr implies --worktree)
-zeroshot run 123 --pr             # worktree + create PR
-zeroshot run 123 --ship           # PR + auto-merge on approval
-
-# Background mode
-zeroshot run 123 -d
-zeroshot run 123 --ship -d
-
-# Control
-zeroshot list
-zeroshot status <id>
-zeroshot logs <id> -f
-zeroshot resume <id>
-zeroshot stop <id>
-zeroshot kill <id>
-
-# Providers
-zeroshot providers
-zeroshot providers set-default codex
-
-# Agent library
-zeroshot agents list
-zeroshot agents show <name>
-
-# Maintenance
-zeroshot clean
-zeroshot purge
+zeroshot run 123                 # a GitHub issue number
+zeroshot run feature.md          # a markdown spec
+zeroshot run "Add a --json flag" # inline text
 ```
 
-## Multi-Platform Issue Support
-
-Zeroshot works with **GitHub, GitLab, Jira, and Azure DevOps**. Just paste the issue URL or key.
-When working in a git repository, zeroshot automatically detects the issue provider from your git remote URL. No configuration needed!
+Describe a non-trivial task inline and let the loop run it to a verified change:
 
 ```bash
-# GitHub
-zeroshot run 123
-zeroshot run https://github.com/org/repo/issues/123
-
-# GitLab (cloud and self-hosted)
-zeroshot run https://gitlab.com/org/repo/-/issues/456
-zeroshot run https://gitlab.mycompany.com/org/repo/-/issues/789
-
-# Jira
-zeroshot run PROJ-789
-zeroshot run https://company.atlassian.net/browse/PROJ-789
-
-# Azure DevOps
-zeroshot run https://dev.azure.com/org/project/_workitems/edit/999
-```
-
-**Requires**: CLI tools ([`gh`](https://cli.github.com/), [`glab`](https://gitlab.com/gitlab-org/cli), [`jira`](https://github.com/go-jira/jira), or [`az`](https://docs.microsoft.com/cli/azure/)) for the platform you use. See [issue-providers README](src/issue-providers/README.md) for setup and self-hosted instances.
-
-**Important for `--pr` mode**: Run zeroshot from the target repository directory. PRs are created on the git remote of your current directory. If you run from a different repo, zeroshot will warn you and skip the "Closes #X" reference (the PR is still created, but won't auto-close the issue).
-
-## Architecture
-
-Zeroshot is a message-driven coordination layer with smart defaults.
-
-- The conductor classifies tasks by complexity and type.
-- A workflow template selects agents and validators.
-- Agents publish results to a SQLite ledger.
-- Validators approve or reject with specific findings.
-- Rejections route back to the worker for fixes.
-
-```
-                                ┌─────────────────┐
-                                │      TASK       │
-                                └────────┬────────┘
-                                         │
-                                         ▼
-                ┌────────────────────────────────────────────┐
-                │                 CONDUCTOR                  │
-                │     Complexity × TaskType → Workflow       │
-                └────────────────────────┬───────────────────┘
-                                         │
-           ┌─────────────────────────────┼─────────────────────────────┐
-           │                             │                             │
-           ▼                             ▼                             ▼
-     ┌───────────┐                ┌───────────┐                ┌───────────┐
-     │  TRIVIAL  │                │  SIMPLE   │                │ STANDARD+ │
-     │  1 agent  │──────────▶     │  worker   │                │ planner   │
-     │ (level1)  │  COMPLETE      │ + 1 valid.│                │ + worker  │
-     │ no valid. │                └─────┬─────┘                │ + 3-5 val.│
-     └───────────┘                      │                      └─────┬─────┘
-                                        ▼                            │
-                                 ┌─────────────┐                     ▼
-                             ┌──▶│   WORKER    │             ┌─────────────┐
-                             │   └──────┬──────┘             │   PLANNER   │
-                             │          │                    └──────┬──────┘
-                             │          ▼                           │
-                             │   ┌─────────────────────┐            ▼
-                             │   │ ✓ validator         │     ┌─────────────┐
-                             │   │   (generic check)   │ ┌──▶│   WORKER    │
-                             │   └──────────┬──────────┘ │   └──────┬──────┘
-                             │       REJECT │ ALL OK     │          │
-                             └──────────────┘     │      │          ▼
-                                                  │      │   ┌──────────────────────┐
-                                                  │      │   │ ✓ requirements       │
-                                                  │      │   │ ✓ code (STANDARD+)   │
-                                                  │      │   │ ✓ security (CRIT)    │
-                                                  │      │   │ ✓ tester (CRIT)      │
-                                                  │      │   │ ✓ adversarial        │
-                                                  │      │   │   (real execution)   │
-                                                  │      │   └──────────┬───────────┘
-                                                  │      │       REJECT │ ALL OK
-                                                  │      └──────────────┘     │
-                                                  ▼                           ▼
-     ┌─────────────────────────────────────────────────────────────────────────────┐
-     │                                COMPLETE                                     │
-     └─────────────────────────────────────────────────────────────────────────────┘
+zeroshot run "Add optimistic locking with automatic retry: when updating a user,
+retry with exponential backoff up to 3 times, merge non-conflicting field changes,
+and surface conflicts with details. Handle the ABA problem where version goes A->B->A."
 ```
 
-### Complexity Model
-
-| Task                   | Complexity | Agents | Validators                                        |
-| ---------------------- | ---------- | ------ | ------------------------------------------------- |
-| Fix typo in README     | TRIVIAL    | 1      | None                                              |
-| Add dark mode toggle   | SIMPLE     | 2      | Generic validator                                 |
-| Refactor auth system   | STANDARD   | 4      | Requirements, code                                |
-| Implement payment flow | CRITICAL   | 7      | Requirements, code, security, tester, adversarial |
-
-### Model Selection by Complexity
-
-| Complexity | Planner | Worker | Validators |
-| ---------- | ------- | ------ | ---------- |
-| TRIVIAL    | -       | level1 | -          |
-| SIMPLE     | -       | level2 | 1 (level2) |
-| STANDARD   | level2  | level2 | 2 (level2) |
-| CRITICAL   | level3  | level2 | 5 (level2) |
-
-Levels map to provider-specific models. Configure with `zeroshot providers setup <provider>` or
-`settings.providerSettings`. (Legacy `maxModel` applies to Claude only.)
-
 <details>
-<summary><strong>Custom Workflows (Framework Mode)</strong></summary>
-
-Zeroshot is message-driven, so you can define any agent topology.
-
-- Expert panels: parallel specialists -> aggregator -> decision
-- Staged gates: sequential validators, each with veto power
-- Hierarchical: supervisor dynamically spawns workers
-- Dynamic: conductor adds agents mid-execution
-
-**Coordination primitives:**
+<summary><strong>Command reference</strong></summary>
 
-- Message bus (pub/sub topics)
-- Triggers (wake agents on conditions)
-- Ledger (SQLite, crash recovery)
-- Dynamic spawning (CLUSTER_OPERATIONS)
-
-#### Creating Custom Clusters with a Provider CLI
-
-Start your provider CLI and describe your cluster:
-
-```
-Create a zeroshot cluster config for security-critical features:
-
-1. Implementation agent (level2) implements the feature
-2. FOUR parallel validators:
-   - Security validator: OWASP checks, SQL injection, XSS, CSRF
-   - Performance validator: No N+1 queries, proper indexing
-   - Privacy validator: GDPR compliance, data minimization
-   - Code reviewer: General code quality
-
-3. ALL validators must approve before merge
-4. If ANY validator rejects, implementation agent fixes and resubmits
-5. Use level3 for security validator (highest stakes)
-
-Look at cluster-templates/base-templates/full-workflow.json
-and create a similar cluster. Save to cluster-templates/security-review.json
+```bash
+# Run
+zeroshot run <input>            # issue number / URL / key / markdown file / inline text
+zeroshot run 123 --worktree     # isolate in a git worktree
+zeroshot run 123 --docker       # isolate in a container
+zeroshot run 123 --pr           # worktree + open a pull request
+zeroshot run 123 --ship         # worktree + PR + auto-merge on approval
+zeroshot run 123 -d             # background (daemon)
+zeroshot run 123 --provider gemini   # override the provider for this run
+
+# Monitor & manage
+zeroshot list                   # all clusters (--json)
+zeroshot status <id>            # cluster details
+zeroshot logs <id> -f           # stream logs
+zeroshot resume <id> [prompt]   # resume a stopped/failed run
+zeroshot stop <id>              # graceful stop
+zeroshot kill <id>              # force kill
+zeroshot export <id>            # export the conversation
+
+# Library & config
+zeroshot providers              # list providers / set-default / setup
+zeroshot agents list            # available agents (agents show <name>)
+zeroshot settings               # view / get / set settings
+zeroshot cmdproof check <id>    # reuse a verified command result
 ```
 
-Built-in validation checks for missing triggers, deadlocks, and invalid type wiring before running.
-
-See [CLAUDE.md](./CLAUDE.md) for the cluster schema and examples.
-
 </details>
 
-## Crash Recovery
+## Providers and backends
 
-All state is persisted in the SQLite ledger. You can resume at any time:
+Zeroshot shells out to provider CLIs; it stores no API keys and manages no auth. Pick a default and override per run.
 
-```bash
-zeroshot resume cluster-bold-panther
-```
-
-## Isolation Modes
-
-### Git Worktree (Default for --pr/--ship)
+| Provider     | CLI                                    |
+| ------------ | -------------------------------------- |
+| Claude Code  | `npm i -g @anthropic-ai/claude-code`   |
+| OpenAI Codex | `npm i -g @openai/codex`               |
+| Gemini CLI   | `npm i -g @google/gemini-cli`          |
+| OpenCode     | see [opencode.ai](https://opencode.ai) |
 
 ```bash
-zeroshot run 123 --worktree
+zeroshot providers                    # see what's installed
+zeroshot providers set-default codex
+zeroshot run 123 --provider gemini
 ```
 
-Lightweight isolation using git worktree. Creates a separate working directory with its own branch. Auto-enabled with `--pr` and `--ship`.
-
-### Docker Container
+Issue backends are **auto-detected from your git remote**: **GitHub, GitLab, Jira, and Azure DevOps**. Paste a number, key, or URL:
 
 ```bash
-zeroshot run 123 --docker
+zeroshot run 123                                              # GitHub
+zeroshot run https://gitlab.com/org/repo/-/issues/456        # GitLab
+zeroshot run PROJ-789                                         # Jira
+zeroshot run https://dev.azure.com/org/project/_workitems/edit/999  # Azure DevOps
 ```
 
-Full isolation in a fresh container. Your workspace stays untouched. Useful for risky experiments or parallel runs.
+Each backend needs its own CLI installed (`gh`, `glab`, `jira`, or `az`). See [`docs/providers.md`](docs/providers.md) for model levels and setup.
 
-### When to Use Which
+## Isolation
 
-| Scenario                             | Recommended            |
-| ------------------------------------ | ---------------------- |
-| Quick task, review changes yourself  | No isolation (default) |
-| PR workflow, code review             | `--worktree` or `--pr` |
-| Risky experiment, might break things | `--docker`             |
-| Running multiple tasks in parallel   | `--docker`             |
-| Full automation, no review needed    | `--ship`               |
+By default, agents modify files only; they do **not** commit or push. Opt into isolation to let the loop own a branch (the flags cascade: `--ship` → `--pr` → `--worktree`).
 
-**Default behavior:** Agents modify files only; they do not commit or push unless using an isolation mode that explicitly allows it.
+| Mode         | Flag         | Use when                                         |
+| ------------ | ------------ | ------------------------------------------------ |
+| None         | _(default)_  | quick task, you review the changes yourself      |
+| Git worktree | `--worktree` | PR workflows, lightweight branch isolation       |
+| Docker       | `--docker`   | risky experiments, parallel runs, full isolation |
 
 <details>
-<summary><strong>Docker Credential Mounts</strong></summary>
-
-When using `--docker`, zeroshot mounts credential directories so agents can access provider CLIs and tools like AWS, Azure, and kubectl.
+<summary><strong>Docker credential mounts</strong></summary>
 
-**Default mounts**: `gh`, `git`, `ssh` (GitHub CLI, git config, SSH keys)
-
-**Available presets**: `gh`, `git`, `ssh`, `aws`, `azure`, `kube`, `terraform`, `gcloud`, `claude`, `codex`, `gemini`
+When using `--docker`, Zeroshot mounts credential directories so agents can reach provider CLIs and tools. Defaults: `gh`, `git`, `ssh`. Presets include `aws`, `azure`, `kube`, `terraform`, `gcloud`, and the provider configs.
 
 ```bash
-# Configure via settings (persistent)
-zeroshot settings set dockerMounts '["gh", "git", "ssh", "aws", "azure"]'
-
-# View current config
-zeroshot settings get dockerMounts
-
-# Per-run override
+zeroshot settings set dockerMounts '["gh","git","ssh","aws"]'
 zeroshot run 123 --docker --mount ~/.aws:/root/.aws:ro
-
-# Provider credentials
-zeroshot run 123 --docker --mount ~/.config/codex:/home/node/.config/codex:ro
-zeroshot run 123 --docker --mount ~/.config/gemini:/home/node/.config/gemini:ro
-
-# Disable all mounts
 zeroshot run 123 --docker --no-mounts
-
-# CI: env var override
-ZEROSHOT_DOCKER_MOUNTS='["aws","azure"]' zeroshot run 123 --docker
 ```
 
-See `docs/providers.md` for provider CLI setup and mount details.
-
-**Custom mounts** (mix presets with explicit paths):
+See [`docs/providers.md`](docs/providers.md) for mount details.
 
-```bash
-zeroshot settings set dockerMounts '[
-  "gh",
-  "git",
-  {"host": "~/.myconfig", "container": "$HOME/.myconfig", "readonly": true}
-]'
-```
+</details>
 
-**Container home**: Presets use `$HOME` placeholder. Default: `/root`. Override with:
+## Scope and status
 
-```bash
-zeroshot settings set dockerContainerHome '/home/node'
-# Or per-run:
-zeroshot run 123 --docker --container-home /home/node
-```
+Zeroshot performs best when a task has **clear acceptance criteria**. If you can't say what "done" means, an independent verifier can't confirm it.
 
-**Env var passthrough**: Presets auto-pass related env vars (for example, `aws` -> `AWS_REGION`, `AWS_PROFILE`). Add custom:
+| Task                                            | Good fit? | Why                     |
+| ----------------------------------------------- | --------- | ----------------------- |
+| Add rate limiting (sliding window, per-IP, 429) | Yes       | clear requirements      |
+| Refactor auth to JWT                            | Yes       | defined end state       |
+| Fix a login bug                                 | Yes       | success is measurable   |
+| "Make the app faster"                           | No        | needs exploration first |
+| "Improve the codebase"                          | No        | no acceptance criteria  |
 
-```bash
-zeroshot settings set dockerEnvPassthrough '["MY_API_KEY", "TF_VAR_*"]'
-```
+- **Pre-1.0 in spirit.** Interfaces still move between releases; pin your version. (The npm version auto-increments on every merge, so read it as a build counter, not a stability promise.)
+- **Crash-safe.** All state persists to a SQLite ledger; `zeroshot resume <id>` continues at any time.
+- **No TUI in this release.** Monitor with `zeroshot logs <id> -f`, `zeroshot list`, and `zeroshot status <id>`.
 
-</details>
+<details>
+<summary><strong>Architecture, quality gates and command proofs</strong></summary>
 
-## Resources
+Zeroshot is a message-driven coordination layer: a conductor classifies each task by complexity and type, a workflow template selects agents and validators, agents publish results to a SQLite ledger, and validators approve or reject with specific findings.
 
-- [CLAUDE.md](./CLAUDE.md) - Architecture, cluster config schema, agent primitives
-- `docs/providers.md` - Provider setup, model levels, and Docker mounts
-- `docs/context-management.md` - Context selection, context packs, and state snapshots
-- [Discord](https://discord.gg/PdZ3UEXB) - Support and community
-- `zeroshot export <id>` - Export conversation to markdown
-- `sqlite3 ~/.zeroshot/*.db` - Direct ledger access for debugging
+- **Required handoff quality gates**: in `--pr`/`--ship` flows, the git-pusher fails closed until every configured gate has fresh passing evidence.
+- **Cmdproof**: make expensive exact commands reusable across agents with `zeroshot cmdproof check <id>`.
 
-<details>
-<summary><strong>Troubleshooting</strong></summary>
-
-| Issue                         | Fix                                                                                       |
-| ----------------------------- | ----------------------------------------------------------------------------------------- |
-| `claude: command not found`   | `npm i -g @anthropic-ai/claude-code && claude auth login`                                 |
-| `codex: command not found`    | `npm i -g @openai/codex && codex login`                                                   |
-| `gemini: command not found`   | `npm i -g @google/gemini-cli && gemini auth login`                                        |
-| `gh: command not found`       | [Install GitHub CLI](https://cli.github.com/)                                             |
-| `--docker` fails              | Docker must be running: `docker ps` to verify                                             |
-| Cluster stuck                 | `zeroshot resume <id>` to continue                                                        |
-| Agent keeps failing           | Check `zeroshot logs <id>` for actual error                                               |
-| `zeroshot: command not found` | `npm install -g @the-open-engine/zeroshot`                                                |
-| Agents misbehave              | `/analyze-cluster-postmortem <id>` in Claude Code (creates issue if fix is generalizable) |
+See [CLAUDE.md](./CLAUDE.md) for the cluster schema, primitives, and the conductor's classification model.
 
 </details>
 
-## Contributing
+## The Open Engine
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+Zeroshot is **Layer 01 · Verification** of [The Open Engine](https://theopenengine.com), the open stack for autonomous software production. Generating code is easy; trusting it is not. The engine is layered because trust is layered:
 
-Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating.
+|        | Layer                      | Status                      |
+| ------ | -------------------------- | --------------------------- |
+| **01** | **Verification: Zeroshot** | This repo · open · shipping |
+| 02     | Constraints: **Opcore**    | Sibling · alpha             |
+| 03-05  | Intent · Context · Runtime | In development              |
 
-For security issues, see [SECURITY.md](SECURITY.md).
+Zeroshot runs the loop: an agent writes the change, and an **independent** verifier decides whether it holds: approve, or a reproducible failure. **Opcore** is the sibling layer, a deterministic, local, read-only **constraints** gate for coding agents (currently private alpha `0.1.0-alpha.0`, built in the open, not yet published). Verification asks _"does this meet the goal?"_; constraints ask _"is this within tolerance?"_
 
-## TUI
+Each layer ships the same way: extracted from the platform we run, then opened. **Trust nothing. Verify everything.**
 
-The TUI is not included in this release. Use `zeroshot logs -f`, `zeroshot logs -w`,
-`zeroshot list`, and `zeroshot status <id>` for monitoring.
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating, and [SECURITY.md](SECURITY.md) for security reports. More in [`docs/`](docs/) and [CLAUDE.md](./CLAUDE.md).
+
+<!-- discord-placeholder -->
 
----
+Questions and help: [Discord](https://discord.gg/fZyzf2Cut9).
 
-MIT - [The Open Engine Company](https://github.com/the-open-engine)
+## License
 
-Built on [Claude Code](https://claude.com/product/claude-code) by Anthropic.
+MIT. [The Open Engine Company](https://github.com/the-open-engine).