中文

harness-orchestrator

Cursor-native AI engineering framework — plan, build, review, and ship inside Cursor with structured quality gates.

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 process, no complex setup.

Quick Start

1. Install

pip install harness-orchestrator
harness --version

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

2. Initialize your project

cd /path/to/your/project
harness init

The wizard walks you through setup: project info, trunk branch, CI command, and optional Memverse integration. It generates skills, subagents, and rules directly into .cursor/.

3. Start building

Open your project in Cursor. Three primary entry points cover all task sizes:

All three use recursive composition (brainstorm ⊃ vision ⊃ plan) and share the same review → ship pipeline.

Utility skills:

Pipeline skills (for granular control):

Try it now:

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

How it works

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

5-role review system

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

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.

Graceful degradation

Generated artifacts

harness init generates everything Cursor needs:

To regenerate after config changes:

harness install --force

Configuration

Project settings live in .agents/config.toml:

CLI reference

Task artifacts

All task state lives under .agents/:

.agents/
├── config.toml            # Project configuration
├── vision.md              # Project vision
├── tasks/
│   └── task-001/
│       ├── plan.md        # Plan with spec and contract
│       ├── evaluation-r1.md
│       ├── build-r1.log
│       └── ...
└── archive/               # Archived sessions

Local-first: all state stays on disk — no cloud dependency.

Repository layout

harness-orchestrator/
├── src/harness/
│   ├── cli.py              # CLI entry (Typer)
│   ├── commands/            # init, install, update, status
│   ├── core/                # Config, state, UI, events
│   ├── native/              # Cursor-native artifact generator
│   ├── templates/           # Jinja2 templates
│   └── integrations/        # Git, Memverse
├── tests/
├── docs/                    # Architecture and historical docs
└── pyproject.toml

Internationalization

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

Updating

harness update          # upgrade, reinstall artifacts, check config
harness update --check  # just check for new version

Development

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

Historical documentation

Architecture notes from earlier versions (orchestrator mode, state machine, driver compatibility) are preserved in docs/historical.md.

License

MIT