Metadata-Version: 2.4
Name: harness-orchestrator
Version: 3.1.6
Summary: Contract-driven multi-agent development orchestrator for Cursor & Codex
Project-URL: Homepage, https://github.com/arthaszeng/harness-orchestrator
Project-URL: Repository, https://github.com/arthaszeng/harness-orchestrator
Project-URL: Issues, https://github.com/arthaszeng/harness-orchestrator/issues
Project-URL: Changelog, https://github.com/arthaszeng/harness-orchestrator/releases
Author: Arthas Zeng
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,codex,cursor,development,harness,multi-agent,orchestration
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: eval-type-backport>=0.1.0; python_version < '3.10'
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer[all]>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

[中文](README.zh-CN.md)

# harness-orchestrator

> Contract-driven multi-agent development framework — run a full plan-build-review-ship pipeline inside Cursor with one command.

[![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

AI coding tools excel at single-shot tasks. Continuous development needs more: goal tracking, quality gates, adversarial review, and audit trails. Harness organizes these into a contract-driven engineering loop that runs **inside your Cursor IDE** — no separate orchestrator process, no complex setup. For CI/CD and headless automation, an optional [orchestrator mode](#advanced-cross-client-orchestrator-mode) drives Cursor and Codex agents via external CLI.

## Quick Start (Cursor-native, 3 minutes)

### 1. Install harness

```bash
pip install harness-orchestrator
harness --version   # verify (also works: python3 -m harness --version)
```

<details>
<summary>Alternative: install from source (for contributors)</summary>

```bash
git clone https://github.com/arthaszeng/harness-orchestrator.git
cd harness-orchestrator
pip install -e ".[dev]"
```

</details>

### 2. Initialize your project

```bash
cd /path/to/your/project
harness init
```

The wizard walks you through setup. When asked for **Workflow Mode**, choose **cursor-native**:

```
Step 5/9  Workflow Mode
  Choose how harness drives development:
  1. orchestrator -- External CLI process drives cursor-agent (default)
  2. cursor-native -- Skills + subagents inside Cursor IDE (no external process)
  Choose [2]: 2
  → cursor-native mode: will generate skills, subagents, and rules
```

This generates skills, subagents, and rules directly into your `.cursor/` directory.

### 3. Use it in Cursor

Open your project in Cursor. You now have **three primary entry points** that cover all task sizes — from vague ideas to specific requirements:

**Start here — three entry points for all task sizes:**

| Skill | When to use | What it does |
|-------|-------------|--------------|
| `/harness-brainstorm` | "I have an idea" | Divergent exploration → vision → plan → review gate → auto build/eval/ship/retro |
| `/harness-vision` | "I have a direction" | Clarify vision → plan → review gate → auto build/eval/ship/retro |
| `/harness-plan` | "I have a requirement" | Refine plan + 5-role review → review gate → auto build/eval/ship/retro |

All three use recursive composition (brainstorm ⊃ vision ⊃ plan) and share the same plan review → ship pipeline. After plan approval, `/harness-ship` handles build → eval → iterate → ship → PR.

**Utility skills:**

| Skill | What it does |
|-------|-------------|
| `/harness-investigate` | Systematic bug investigation: reproduce → hypothesize → verify → minimal fix |
| `/harness-learn` | Memverse knowledge management: store, retrieve, update project learnings |
| `/harness-retro` | Engineering retrospective: commit analytics, hotspot detection, trend tracking |

**Advanced skills** (for granular control):

| Skill | What it does |
|-------|-------------|
| `/harness-build` | Implement the contract, run CI, triage failures, write a structured build log |
| `/harness-eval` | 5-role code review (architect + product-owner + engineer + qa + project-manager) |
| `/harness-ship` | Full pipeline: test → review → fix → commit → push → PR |
| `/harness-doc-release` | Documentation sync: detect stale docs after code changes |

**Try it now** — open Cursor chat and type:

```
/harness-plan add input validation to the user registration endpoint
```

Harness will plan with 5-role review, apply a review gate, build, run 5-role code evaluation, auto-fix trivial issues, create bisectable commits, and open a PR — all without leaving your IDE.

### Updating

```bash
harness update          # upgrade to latest, reinstall agents, check config
harness update --check  # just check if a new version is available
```

---

## What happens under the hood

```
You type /harness-ship "add feature X"
  → Rebase onto main, run tests
  → 5-role code evaluation (all dispatched in parallel):
      Architect:       design + security review
      Product Owner:   completeness + behavior
      Engineer:        quality + performance
      QA:              regression + testing (only role running CI)
      Project Manager: scope + delivery
  → Fix-First: auto-fix trivial issues, ask about important ones
  → Bisectable commits + push + PR
```

### Unified 5-role review system

The same 5 specialized roles review both **plans** and **code**, dispatched in parallel:

| Role | Plan Review Focus | Code Eval Focus |
|------|------------------|-----------------|
| **Architect** | Feasibility, module impact, dependency changes | Conformance, layering, coupling, security |
| **Product Owner** | Vision alignment, user value, acceptance criteria | Requirement coverage, behavioral correctness |
| **Engineer** | Implementation feasibility, code reuse, tech debt | Code quality, DRY, patterns, performance |
| **QA** | Test strategy, boundary values, regression risk | Test coverage, edge cases, CI health |
| **Project Manager** | Task decomposition, parallelism, scope | Scope drift, plan completion, delivery risk |

Findings from 2+ roles are flagged as **high confidence**. Each role can use a different model via `[native.role_models]` in `.agents/config.toml`.

### Fix-First auto-remediation

Review findings are classified before presenting:

- **AUTO-FIX** — High certainty, small blast radius, reversible. Fixed immediately and committed.
- **ASK** — Security findings, behavior changes, or low confidence. Presented to you for decision.

Trivial issues never block shipping. Important decisions always get human judgment.

### Graceful degradation

| Roles responding | Behavior |
|-----------------|----------|
| 5/5 | Full synthesis with cross-validation |
| 3-4/5 | Proceed with available reviews, note missing perspectives |
| 1-2/5 | Log warning, fall through to single-agent review |
| 0/5 | Fall back to single generalPurpose subagent |

---

## Generated artifacts

When you choose cursor-native mode, `harness init` generates:

| Artifact | Path | Purpose |
|----------|------|---------|
| `/harness-brainstorm` | `.cursor/skills/harness/harness-brainstorm/SKILL.md` | Divergent exploration → vision → plan → auto-execute to PR |
| `/harness-vision` | `.cursor/skills/harness/harness-vision/SKILL.md` | Clarify vision → plan → auto-execute to PR |
| `/harness-plan` | `.cursor/skills/harness/harness-plan/SKILL.md` | Refine plan + 5-role review → auto-execute to PR |
| `/harness-build` | `.cursor/skills/harness/harness-build/SKILL.md` | Build: implement contract, run CI, triage failures |
| `/harness-eval` | `.cursor/skills/harness/harness-eval/SKILL.md` | 5-role code review with Fix-First auto-remediation |
| `/harness-ship` | `.cursor/skills/harness/harness-ship/SKILL.md` | Full pipeline: test → 5-role review → fix → commit → PR |
| `/harness-investigate` | `.cursor/skills/harness/harness-investigate/SKILL.md` | Systematic bug investigation and minimal fix |
| `/harness-learn` | `.cursor/skills/harness/harness-learn/SKILL.md` | Memverse knowledge management |
| `/harness-doc-release` | `.cursor/skills/harness/harness-doc-release/SKILL.md` | Documentation sync after code changes |
| `/harness-retro` | `.cursor/skills/harness/harness-retro/SKILL.md` | Engineering retrospective and trend analysis |
| Architect | `.cursor/agents/harness-architect.md` | Architecture reviewer (plan + code, dual-mode) |
| Product Owner | `.cursor/agents/harness-product-owner.md` | Product reviewer (plan + code, dual-mode) |
| Engineer | `.cursor/agents/harness-engineer.md` | Engineering reviewer (plan + code, dual-mode) |
| QA | `.cursor/agents/harness-qa.md` | QA reviewer with CI ownership (plan + code, dual-mode) |
| Project Manager | `.cursor/agents/harness-project-manager.md` | Delivery reviewer (plan + code, dual-mode) |
| Trust boundary | `.cursor/rules/harness-trust-boundary.mdc` | Always-on: Builder output is untrusted |
| Fix-First | `.cursor/rules/harness-fix-first.mdc` | Always-on: classify findings before presenting |
| Workflow conventions | `.cursor/rules/harness-workflow.mdc` | Commit format, branch naming, task state |
| Safety guardrails | `.cursor/rules/harness-safety-guardrails.mdc` | Always-on: destructive command detection and warning |
| Worktrees config | `.cursor/worktrees.json` | Parallel Agents: worktree init script for isolated checkouts |

To regenerate after config changes:

```bash
harness install --force
```

---

## Parallel Development

> **Key feature** — Run multiple harness tasks simultaneously without file conflicts.

When you run several Cursor agent tabs in the same project, they share one working directory.
Uncommitted changes from one task leak into another, causing confusion and broken builds.

Harness solves this automatically via **Cursor Parallel Agents** — each agent gets its own
isolated git worktree with a separate checkout. Cursor creates, uses, and cleans up these
worktrees transparently.

### How it works

`harness init` generates `.cursor/worktrees.json`, which tells Cursor how to initialize
each worktree. The generated script:

1. Creates `.agents/tasks/` and `.agents/archive/` directories
2. Copies `.agents/config.toml` and `.agents/vision.md` from the main worktree
3. Copies the entire `.cursor/` directory (skills, agents, rules) from the main worktree

This ensures every parallel agent has full harness context — skills, review roles, and
project configuration — without manual setup.

### Usage

No extra steps needed. After `harness init`, simply open multiple agent tabs in Cursor
and start different tasks. Each agent operates in its own isolated checkout.

### Customization

Edit `.cursor/worktrees.json` to add project-specific setup commands (e.g., dependency
installation):

```json
{
  "setup-worktree-unix": [
    "mkdir -p .agents/tasks .agents/archive",
    "cp \"$ROOT_WORKTREE_PATH/.agents/config.toml\" .agents/ 2>/dev/null || true",
    "cp \"$ROOT_WORKTREE_PATH/.agents/vision.md\" .agents/ 2>/dev/null || true",
    "cp -r \"$ROOT_WORKTREE_PATH/.cursor\" . 2>/dev/null || true",
    "pip install -e '.[dev]' -q"
  ]
}
```

> **Note:** `harness install --force` regenerates the default `worktrees.json`. If you have
> custom setup commands, back them up first or re-add them after regeneration.

### Known limitations

- **LSP support in worktrees** is not yet available in Cursor — linting and type-checking
  may not work in worktree checkouts. This is a Cursor-side limitation being actively developed.
- **Requires Cursor 2.0+** with Parallel Agents support. On older versions, the
  `worktrees.json` file is harmless and simply ignored.

---

## Configuration

Project settings live in `.agents/config.toml`:

| Key | Default | Description |
|-----|---------|-------------|
| `workflow.mode` | "orchestrator" | `orchestrator` or `cursor-native` |
| `workflow.profile` | "standard" | `lite` / `standard` / `autonomous` |
| `workflow.max_iterations` | 3 | Max iterations per task |
| `workflow.pass_threshold` | 7.0 | Evaluator pass threshold (out of 10) |
| `workflow.auto_merge` | true | Auto-merge branch after pass |
| `workflow.dual_evaluation` | false | Add alignment review after quality review |
| `workflow.branch_prefix` | "agent" | Task branch prefix |
| `native.gate_full_review_min` | 5 | Escalation score for full human review |
| `native.gate_summary_confirm_min` | 3 | Escalation score for summary confirmation |
| `native.adversarial_model` | "gpt-4.1" | Cross-model reviewer model |
| `native.adversarial_mechanism` | "auto" | Adversarial dispatch mode. Allowed: `subagent`, `cli`, `auto` |
| `native.review_gate` | "eng" | Review gate strictness. Allowed: `eng` (hard gate), `advisory` (log only) |
| `native.plan_review_gate` | "auto" | Plan review gate mode. Allowed: `human` (always stop), `ai` (auto-approve), `auto` (complexity-adaptive) |
| `native.retro_window_days` | 14 | Default retro analysis window in days (1–365) |
| `native.role_models.*` | `{}` | Per-role model overrides. Keys: `architect`, `product_owner`, `engineer`, `qa`, `project_manager` |
| `autonomous.max_tasks_per_session` | 10 | Max tasks per autonomous session |
| `autonomous.consecutive_block_limit` | 2 | Stop after this many consecutive blocks |

### Models (optional)

Per-role model selection under `[models]`. Harness only passes `--model` when the resolved value is non-empty.

**Resolution order**: `role_overrides.<role>` → `driver_defaults.<driver>` → `models.default` → empty.

```toml
[models]
default = ""

[models.driver_defaults]
# codex = "o3"
# cursor = "claude-4-opus"

[models.role_overrides]
# planner = "o3-pro"
# builder = ""  # explicit: always use IDE default
```

### Workflow profiles

| Profile | Flow | When to use |
|---------|------|-------------|
| **lite** | planner → builder → eval (no spec/contract split; threshold cap 3.0; max 2 rounds) | Small changes, quick fixes |
| **standard** | planner → spec + contract → builder → eval (full review) | Day-to-day development (default) |
| **autonomous** | strategist → standard loop → reflector | Vision-driven autonomous mode |

---

## Task artifacts

All artifacts live under `.agents/` at the project root:

```
.agents/
├── config.toml            # Project config
├── vision.md              # Project vision
├── state.json             # Runtime state
├── .stop                  # Stop signal
├── runs/
│   └── <session-id>/
│       └── events.jsonl   # Structured events
├── tasks/
│   └── task-001/
│       ├── spec-r1.md     # Spec: analysis and technical plan
│       ├── contract-r1.md # Contract (Markdown)
│       ├── contract-r1.json # Contract (JSON sidecar)
│       ├── evaluation-r1.md # Review (Markdown)
│       ├── evaluation-r1.json # Review (JSON sidecar)
│       ├── alignment-r1.md # Alignment review (if dual_evaluation)
│       ├── build-r1.log   # Builder log
│       └── ...
└── archive/               # Archived sessions
```

Every step is traceable. JSON sidecars suit automation and UIs without regex-parsing Markdown.

**Local-first**: All state stays on disk; no cloud dependency. The `.agents/` tree is usually gitignored. To share `config.toml` or `vision.md` with your team, use `git add -f .agents/config.toml`.

---

## Command reference

| Command | Description |
|---------|-------------|
| `harness install [--force] [--lang]` | Install agent definitions to local IDE |
| `harness init [--name] [--ci] [--lang] [-y]` | Initialize project configuration (interactive wizard) |
| `harness vision` | Create or update project vision |
| `harness run <req> [--resume] [--verbose]` | Run a single development task |
| `harness auto [--resume] [--verbose]` | Start the autonomous development loop |
| `harness status` | Show current progress |
| `harness stop` | Gracefully stop the current task |
| `harness --version` | Show version |

---

## Advanced: Cross-Client Orchestrator Mode

Cursor-native mode covers most interactive development workflows. For **CI/CD pipelines**, **headless automation**, or **multi-IDE setups** (Cursor + Codex), use orchestrator mode.

### Prerequisites

| Dependency | Requirement | Notes |
|------------|-------------|-------|
| **Python** | >= 3.9 | Runs the Harness CLI |
| **Cursor CLI and/or Codex CLI** | At least one | Provides agent capability |
| **Git** | Any version | Project must be a Git repo |

IDE CLI setup:

- **Cursor**: Command Palette → `Install 'cursor' command`
- **Codex**: `npm install -g @openai/codex` or from [GitHub](https://github.com/openai/codex)

### Orchestrator vs Cursor-native

|  | Orchestrator | Cursor-native |
|---|---|---|
| **How it runs** | External `harness` CLI spawns agent processes | Skills + subagents inside Cursor IDE |
| **Entry point** | `harness run` / `harness auto` | `/harness-brainstorm`, `/harness-vision`, `/harness-plan` |
| **Cross-model review** | Configurable per role | 5-role parallel reviewers with per-role model overrides (`native.role_models`) |
| **When to use** | CI/CD, headless, multi-IDE | Interactive development, Cursor-only |

### Role architecture

| Role | Responsibility | Default backend (`auto` mode) |
|------|----------------|-------------------------------|
| **Planner** | Analyze requirements; produce spec and contract | Codex |
| **Builder** | Implement against the contract; commit changes | Cursor |
| **Evaluator** | Independent review; four-dimensional scoring | Codex |
| **Alignment Evaluator** | Requirement alignment and intent drift detection | Codex |
| **Strategist** | Pick the next task from vision (autonomous mode) | Codex |
| **Reflector** | Distill lessons into long-term memory | Codex/Cursor |

Each role's backend is configurable under `[drivers.roles]`. See [docs/compatibility.md](docs/compatibility.md) for CLI version requirements.

### Orchestrator setup

```bash
# 1. Install agent definitions to IDE directories
harness install

# 2. Initialize (choose "orchestrator" mode)
cd /path/to/your/project
harness init

# 3. Create project vision
harness vision

# 4. Run
harness run "add user authentication"   # single task
harness auto                            # autonomous loop

# 5. Monitor
harness status
harness stop
```

### Single-task flow (`harness run`)

```
Requirement
  → Planner: spec + iterative contract
  → Builder: implement and commit
  → Evaluator: four-dimensional score
      → Pass (≥ 7.0) → done
      → Fail → feedback to Builder, iterate
  → Max iterations (3) → blocked
```

### Autonomous loop (`harness auto`)

```
Vision
  → Strategist: pick next task
  → Single-task flow
  → Reflector: distill lessons
  → Loop until: all done / stop signal / block limit / task limit
```

### Dual Evaluator

With `workflow.dual_evaluation = true`, quality review is followed by alignment review:

- **Quality** — Code quality + regression (four-dimensional scoring)
- **Alignment** — Requirement coverage + contract fit + intent drift

If alignment returns `MISALIGNED`, the task iterates back to Builder. If `CONTRACT_ISSUE`, feedback goes to Planner to revise the contract instead.

```toml
[workflow]
dual_evaluation = true
```

---

## Troubleshooting

### Resuming interrupted work

```bash
harness run "original requirement" --resume
harness auto --resume
```

`--resume` reloads from `state.json` and continues from the interrupted phase.

### Stop behavior

`harness stop` writes `.agents/.stop`. The task finishes its current phase and exits cleanly. For immediate abort, use `Ctrl+C` — Harness saves a checkpoint before exit.

### IDE CLI not found

If you see `Neither Cursor nor Codex CLI detected`:

- **Cursor**: Command Palette → `Install 'cursor' command`
- **Codex**: `npm install -g @openai/codex`

Ensure the binary is on PATH. For cursor-native mode, Cursor CLI is optional — harness generates files that work directly in the IDE.

### Reinstalling

If `harness install` fails or produces a broken setup:

```bash
harness install --force
```

This overwrites existing files, retries CLI installations, and regenerates native artifacts.

---

## Observability

Each session writes structured events to `.agents/runs/<session-id>/events.jsonl`:

```json
{"ts": "2026-03-31T10:00:00.000Z", "event": "agent_end", "role": "planner", "driver": "codex", "exit_code": 0, "elapsed_ms": 12340}
```

Event types: `agent_start`/`agent_end`, `ci_result`, `state_transition`, `task_start`/`task_end`.

---

## Repository layout

```
harness-orchestrator/
├── src/harness/
│   ├── cli.py              # CLI entry (Typer)
│   ├── commands/            # Subcommand implementations
│   ├── orchestrator/        # Workflow core
│   ├── drivers/             # IDE agent invocation abstraction
│   ├── core/                # State, config, UI, events
│   ├── methodology/         # Evaluation, scoring, contracts
│   ├── native/              # Cursor-native mode generator
│   ├── agents/              # Role definitions (Cursor / Codex)
│   ├── templates/           # Prompt templates (orchestrator + native)
│   └── integrations/        # Git, Memverse
├── tests/                   # Test suite
├── docs/                    # State machine, compatibility
└── pyproject.toml
```

---

## When it fits — and when it doesn't

**Good fit:**

- You use Cursor and want quality gates on agent output, not blind trust
- You want traceability across multi-step work
- You want adversarial review to catch what a single pass misses

**Poor fit:**

- Expecting a one-click "build the whole product" autopilot
- Enterprise approval workflows unrelated to coding
- Environments where you cannot install Python or any supported agent CLI (Cursor/Codex)

---

## Internationalization

```bash
harness init --lang zh    # Chinese
harness init --lang en    # English (default)
```

Affects CLI messages, agent prompts, generated files, and installed agent definitions. Stored in `.agents/config.toml` under `[project] lang`.

---

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check src/ tests/
ruff format src/ tests/
```

Ruff targets Python 3.9 with line length 100. See [docs/releasing.md](docs/releasing.md) for the release process.

---

## Further reading

| Doc | Description |
|-----|-------------|
| [docs/state-machine.md](docs/state-machine.md) | Task state machine |
| [docs/compatibility.md](docs/compatibility.md) | CLI version requirements |
| [docs/releasing.md](docs/releasing.md) | Release process and PyPI publishing |
| [examples/todo-api-benchmark/](examples/todo-api-benchmark/) | Benchmark: five tasks, three modes |

---

## License

[MIT](LICENSE)
