harnessed

Harnessed

中文版

Independent quality verification for AI coding agents. Code isn't done until an isolated evaluator independently reviews it.

Why

AI coding agents evaluate their own work — and get it wrong. Research shows self-evaluation disagrees with independent evaluation 31% of the time, and AI-generated code initially passes only 42% of comprehensive tests. The fix is simple: don't let the same agent that wrote the code judge the code.

What It Does

Harnessed adds an independent QA loop to your AI coding workflow:

Standalone:     Task → Contract → Code → QA → Fix Loop → Gate → Done
Complementary:  Task → SP Planning → Code → QA → Fix Loop → Gate → Done
Micro:          Task → Code → Gate → Done

• Contract Writing — Testable acceptance criteria before coding begins. After drafting, every user requirement is mapped to a criterion and gaps are filled automatically.
• Independent QA — Isolated evaluator path grades code against the contract. High-risk tasks use corroborating reviewers, security-sensitive tasks add a dedicated security reviewer, and reviewer disagreement triggers tie-break escalation.
• Verification Gate — Structured evidence (file:line citations) required before "done". If code changed since QA last ran, the gate re-runs QA before accepting.

Installation

Claude Code (Plugin Marketplace — recommended)

# Register the Harnessed marketplace (one-time)
claude plugin marketplace add tt-a1i/harnessed

# Install the plugin
claude plugin install harnessed

Updates are automatic — Claude Code syncs plugins on startup.

Manual Installation (alternative)

# Clone the repository
git clone https://github.com/tt-a1i/harnessed.git

# Option A: Install as a project plugin (project-local)
cp -r harnessed/ your-project/harnessed/

# Option B: Install globally for all projects
cp -r harnessed/ ~/.claude/plugins/harnessed/

If you downloaded a zip instead of cloning, run chmod +x harnessed/hooks/session-start.

After Installation

Verify: start a new Claude Code session — you should see Harnessed respond with "I'll draft acceptance criteria before coding" on your first coding task.

Harnessed automatically adds .harnessed/ to your project's .gitignore on first use.

With Superpowers

Harnessed detects Superpowers automatically. When both are installed:

• Superpowers handles planning, TDD, and process discipline
• Harnessed handles independent QA and verification
• No duplication, no conflict

When both are installed, Harnessed QA runs after Superpowers' process completes. If Superpowers is detected but no specs exist for the current task, Harnessed falls back to Standalone Mode.

How It Works

Standalone Mode (no Superpowers)

1. You give a coding task
2. Contract Writing generates testable acceptance criteria → .harnessed/contract.md
3. Agent writes code
4. Independent QA dispatches isolated reviewers
   • Primary evaluator sees: diff + contract + project context
   • Evaluators do NOT see: generator's reasoning or self-assessment
   • High-risk tasks use corroborating review, disagreement-triggered tie-break review, and explicit calibration status
   • Security-sensitive tasks add heuristic security issue flagging plus Semgrep/CodeQL/bandit outputs when available
   • QA reports now record Confidence and Uncertainty so weak evidence is downgraded instead of overstated
   • Overall grade: SHIP / SHIP_WITH_HUMAN_REVIEW / ITERATE / BLOCKED
5. If ITERATE: agent fixes issues, QA re-runs (max 3 rounds)
6. If SHIP or SHIP_WITH_HUMAN_REVIEW: Verification Gate collects file:line evidence for every criterion
7. Task complete with full audit trail

Complementary Mode (with Superpowers)

Same as above, but contract-writing is skipped (Superpowers' specs are used instead).

Three-Tier Verification

• Tier 1 (Code Review) — Always available. Evaluator reads the diff and checks criteria.
• Tier 1.5 (HTTP Smoke Tests) — Auto-detected when a dev server is running but no test suite is present. Evaluator uses curl/HTTP requests to verify behavior against the live server.
• Tier 2 (Execution Verification) — Auto-detected when test frameworks are present. Evaluator runs tests and interacts with the application.

Project-Level Learning

The independent QA evaluator categorizes each failure it finds, and those categories are recorded in .harnessed/failure-patterns.md across tasks. During contract writing, patterns with Count ≥ 2 automatically inform acceptance criteria so the same class of bug doesn't recur. One-off patterns decay after 90 days.

Example QA Report

After running independent QA, Harnessed produces a structured report at .harnessed/qa-report.md:

# QA Report

## Overview
- **Verification Tier:** 2
- **Overall Grade:** ITERATE
- **Criteria Passed:** 7/9
- **Critical Issues:** 0

## Per-Criterion Evaluation