harness-scaffold 0.2.2

Unified AI agent engineering scaffold for teams

Harness Scaffold

Unified AI agent engineering scaffold for teams.

Harness gives your team a single engineering process that works across every AI coding agent — Claude Code and Codex CLI by default, with Cursor / Copilot / Gemini extensible via the adapter registry. Instead of each agent inventing its own workflow, harness provides tool-neutral playbooks, a single deterministic verify script, and a Spec-Driven Development cycle, with thin adapter layers that translate them into each agent's native surface.

Why Harness?

AI coding agents are powerful but inconsistent. Different agents have different conventions, different context files, different ways of running commands. Teams end up with:

• Fragmented workflows — one process for Claude Code, another for Codex
• No shared quality bar — agents skip tests, ignore conventions, produce inconsistent output
• Lost context — decisions aren't recorded, specs aren't tracked, handoffs are lossy

Harness solves this with a one brain, many frontends architecture:

┌──────────────────────────────────────────────────┐
│              .harness/ (the brain)               │
│  playbooks · scripts · registry · knowledge      │
├──────────────────────┬───────────────────────────┤
│      Claude          │        Codex              │
│      /hx-*           │        /hx-*              │
└──────────────────────┴───────────────────────────┘
  (Cursor / Copilot / Gemini extensible via registry)

Core Concepts

• Playbooks — Tool-neutral step-by-step procedures for every engineering phase (14 commands from constitution to doctor)
• Spec-Driven Development (SDD) — Per-change artifacts live at specs/<NNN>-<slug>/ (spec-kit flat convention)
• Knowledge base — Diátaxis + C4 + arc42 + BIZBOK + Tech Radar hybrid: 7 fixed docs + how-to/ recipes + ADRs, all under .harness/knowledge/
• Flow levels — Scale ceremony to task size: quick (4 commands) → standard (7) → full (10+) → epic (multi-change)
• Verify as invariant — A single verify.sh script is invoked by editor hooks, pre-commit, and GitLab CI — so no two sensors can disagree about whether the build is green
• Adapters — Thin translation layers that map harness commands into each agent's native format (slash commands, rules, instructions)

Quick Start

PyPI distribution name is harness-scaffold (the bare harness name was already taken). The import path and CLI binary stay harness.

Install globally (recommended — gives you the harness command system-wide)

# With uv (recommended)
uv tool install harness-scaffold

# Or with pipx
pipx install harness-scaffold

uv tool / pipx install into an isolated environment and add the harness script to your PATH. Verify with harness --version.

Install per-project (inside a virtualenv)

# uv-managed project
uv add harness-scaffold
uv run harness --version

# Plain venv + pip
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install harness-scaffold
harness --version

Install from GitHub (track main, or before a release is cut)

uv tool install git+https://github.com/Onebyte1943/harness-scaffold.git
# or
pipx install git+https://github.com/Onebyte1943/harness-scaffold.git

harness: command not found after pip install? Bare pip install harness-scaffold (no venv) installs the script to user-site bin (~/.local/bin on Linux, ~/Library/Python/3.X/bin on macOS) which is often not on PATH; on Python 3.12+ PEP 668 blocks system installs entirely. Use uv tool install or pipx for global CLI use, or activate a venv first.

Initialize in your project

cd your-project
harness init --agent claude
harness doctor

This generates the design-v3 footprint:

your-project/
├── .harness/                    # Brain (tool-neutral)
│   ├── config.toml
│   ├── registry.toml
│   ├── playbooks/               # 14 workflow playbooks
│   ├── scripts/sh/              # Single-source-of-truth verify
│   ├── memory/                  # L-RULE (constitution lives here)
│   ├── knowledge/               # 7 docs + how-to/ + adr/
│   ├── principle-packs/         # Seed principles for /hx-constitution
│   ├── evals/                   # Regression samples for /hx-doctor
│   └── templates/               # Project-local template overrides
├── AGENTS.md                    # Shared agent contract (T13)
├── CLAUDE.md                    # Claude Code entry point (imports @AGENTS.md)
├── .claude/commands/            # /hx-* slash commands for Claude
├── .codex/commands/             # /hx-* slash commands for Codex
├── .gitlab-ci.yml               # MR pipeline (verify + review) + scheduled drift
├── .pre-commit-config.yaml      # Same verify.sh, pre-commit
├── .agent/                      # Cross-session progress log
└── specs/                       # Per-change artifacts (lazy)

See docs/quick-start.md for the full walkthrough.

The Workflow

Harness implements a four-phase engineering lifecycle:

Phase	Commands	Purpose
W0 Bootstrap	constitution, baseline	One-time project setup
W1 Change	next → propose → clarify → design → plan → tasks → analyze → implement → verify	SDD cycle per change
W2 Review & Archive	review, archive	Quality gate, post-merge knowledge refresh
W3 Steer	doctor	Self-check the harness itself

/hx-next is the router — call it any time you're unsure what command (and flow level) is appropriate from current state.

Each command maps to a playbook in .harness/playbooks/ and is invoked through the agent's native surface (e.g., /hx-verify in Claude Code or Codex).

Multi-Agent Support

# Initialize with multiple agents (defaults bundled)
harness init --agent claude --agent codex

# Add another agent later (Cursor / Copilot / Gemini extensible via registry)
harness init --agent codex

Each agent gets its own adapter layer while sharing the same brain. The registry tracks each agent's capabilities and provides graceful degradation paths. Cursor, Copilot and Gemini remain in the registry so a team can extend coverage without code changes — they are not promoted as the default bundle.

Documentation

• Quick Start — Get up and running in 5 minutes
• Use Cases — Real-world scenarios and workflows
• Advanced Usage — Presets, flow levels, customization, narrative language switch

Output language

Generated playbooks, AGENTS.md, CLAUDE.md, and the principle pack ship in two narrative languages — Chinese (zh, default) and English (en) — selected at init time via --output-lang:

harness init --agent claude              # 中文 narrative (default)
harness init --agent claude --output-lang en   # English narrative

Structural items always stay English regardless of the flag — section headings (## Purpose, ## Steps, …), YAML frontmatter keys, Provenance blocks (label + 3 content lines), ⟨…⟩ placeholders, {{ jinja_var }} template variables, /hx-* command names, stable IDs (REQ-NNN, DEC-NNN, …), tags ([enforceable], [inferential], [P]), proper nouns (C4, arc42, BIZBOK, MADR, Diátaxis, …), and code blocks. Agents pattern-match on these — switching them would break playbook parsing. See Advanced Usage → Output Language for the full translation contract.

Requirements

• Python >= 3.10
• Git (recommended)

License

MIT