🔧 HarnessKit

Harness Engineering: A reliable AI agent is not just a raw model. It is defined as: $$\text{Reliable Agent} = \text{Model (AI)} + \text{Harness (Controls)} + \text{Human Auditor}$$

HarnessKit is a complete AI-assisted software engineering framework built on Harness Engineering—the principle that true reliability comes from enclosing generative models inside structured execution scaffolds, persistent memory, domain modeling, and strict test-driven quality loops.

At the core of HarnessKit is the Foundation Triad: three indispensable skills that establish project context, specify business domains, and guarantee code correctness. Every higher-level workflow—whether manual pair-programming or fully sovereign autonomous execution—rests entirely upon this foundation.

The Persistent Memory & Context Routing Engine

AI models suffer from context drift and hallucinations across long coding sessions. project-memory acts as the agent's long-term brain, creating and maintaining standardized living documentation in docs/:

• Architecture Decision Records (ADRs): Establishes mandatory baseline rules in docs/adr/ARCHITECTURE.md (patterns, layers, constraints) and docs/adr/TESTS.md (frameworks, test conventions, coverage bars).
• Token-Efficient Graph Indexing: Generates docs/.digest.md (fast executive orientation <60 lines) and docs/.graph.json (macro relation graph for 1-hop document and dependency lookup).
• Feature Micrographs: Embeds machine-readable routing blocks (entrypoints, registration_files, reference_files, code_files, test_files) directly in docs/feature/*.md so agents navigate codebases without costly repository scans.
• Strict Constraints: Enforces character caps (<8,000 chars per ADR), imperative rules (REQUIRED, PROHIBITED), and prevents architectural degradation over time.

The Domain-Driven Design (DDD) Modeling & Specification Engine

Before writing a single line of production code, scope-refinement breaks down requirements through rigorous Domain-Driven Design across four sequential phases:

Phase 1: Problem Space   → 001-problem-space.md (Domain Events, Subdomains, Ubiquitous Language)
Phase 2: Context Map     → 002-context-map.md (Bounded Contexts, Integrations, Upstream/Downstream)
Phase 3: Tactical Design → 003-*-tactical-design.md (Aggregates, Entities, Value Objects, Ordered Tasks)
Phase 4: Test Scenarios  → 004-*-test-scenarios.md (Given-When-Then Scenarios mapped to dev tasks)

• Eliminates Ambiguity: Resolves domain naming, business invariants, and boundaries prior to implementation.
• Pre-Specified Verification: Generates concrete Given-When-Then test cases in Phase 4 that directly dictate what the implementation phase must fulfill.
• Dual Execution: Runs interactively with human feedback gates or in headless autonomous mode.

The Test-Driven Development & Verification Engine

tdd-orchestrator coordinates the implementation phase by enforcing the Iron Law of TDD: no production code without a failing test first.

• Step 1 — RED Phase: Translates the Given-When-Then test scenarios from 004-*-test-scenarios.md into executable test code. Strictly verifies that tests fail before touching production code.
• Step 2 — GREEN + REFACTOR: Implements the minimal code required to pass tests, followed by structural refactoring to eliminate duplication while keeping test suites green.
• Step 3 — Auto-Debugging Gate: If tests fail unexpectedly, automatically routes diagnosis to the developer-debugging agent for root-cause analysis (5 Whys) before attempting fixes.
• Step 4 — Final Validation & Doc Sync: Executes the complete test suite for regression checks and invokes project-memory to update living feature docs (docs/feature/*.md) and API contracts.

The Foundation Triad forms a closed, self-sustaining loop that transforms raw requirements into verified, fully documented features:

┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. INITIALIZE MEMORY                                                        │
│    `project-memory` scans repo → creates baseline ADRs & graph indexes       │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 2. MODEL DOMAIN & SPECS                                                     │
│    `scope-refinement` runs DDD → produces tactical plan & test scenarios    │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 3. TEST-DRIVEN IMPLEMENTATION                                               │
│    `tdd-orchestrator` executes RED → GREEN → REFACTOR against test scenarios│
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 4. SYNC LIVING MEMORY                                                       │
│    `project-memory` updates `docs/feature/*.md` and `.graph.json` indexes   │
└─────────────────────────────────────────────────────────────────────────────┘

HarnessKit supports two primary ways to operate:

Invoke skills individually during daily development:

• Run /harness-kit:project-memory when onboarding a repo or documenting architectural changes.
• Run /harness-kit:pbb-design when turning an initial product or feature scope into a traceable Product Backlog.
• Run /harness-kit:scope-refinement when planning a complex feature or breaking down a new business domain.
• Run /harness-kit:tdd-orchestrator when executing test-first implementation for specific tasks.

For hands-off execution, the autonomous-orchestrator skill chains the entire Foundation Triad together in an atomic, continuous loop:

• Sovereign Execution: Executes domain planning, TDD implementation, and validation gates end-to-end without pausing for redundant questions.
• Live Auditing in the Cockpit: The human engineer acts as auditor with real-time telemetry and full command:
  • Pull Emergency Brake (Ctrl+C): Kill execution instantly if architectural drift occurs.
  • Hot-Interception: Inject new requirements or edit backlog files mid-flight.
  • Dynamic Tuning: Adjust quality gate thresholds (e.g. acceptance scores, maxReworks).
• Product State Machine: Tracks progress through dynamic transition gates:
  • COMPLETED: Approved and ready for final PR review.
  • RETRY: Logs failure details to REWORK-LOG.md and loops back to code.
  • BLOCKED: Critical crash; triggers circuit breaker for immediate human intervention.
  • FAILED: Non-blocking technical debt; logged for post-hoc audit.

To expose systemic risks (N+1 queries, memory leaks, race conditions, SOLID violations), HarnessKit employs Socratic code review. Rather than providing copy-paste solutions, the-grumpy-tech-lead asks deep architectural questions that guide the engineer (or agent) to solve root causes.

An autonomous quality agent that analyzes machine-readable specifications, tests, and source code to actively probe edge cases, boundary faults, and security vulnerabilities missed by standard TDD.

HarnessKit continuously evaluates and optimizes its own prompt harnesses based on real execution telemetry:

Sessions (real work)
       ↓
 meta-harness-agent    ← runs harness-tracer (records execution traces to docs/harness-history/)
       ↓
 harness-evaluator     ← aggregates traces, calculates Pareto frontier scores
       ↓
 meta-harness          ← proposes targeted improvements to SKILL.md instructions
       ↓
 Human review & promotion

HarnessKit is distributed as a plugin compatible with major AI developer ecosystems:

/plugin marketplace add romabeckman/harness-kit
/plugin install harness-kit@harness-kit
/harness-kit:project-memory --help

copilot plugin marketplace add romabeckman/harness-kit
copilot plugin install harness-kit@harness-kit

agy plugin install https://github.com/romabeckman/harness-kit

codex plugin marketplace add https://github.com/romabeckman/harness-kit
codex plugin add harness-kit@harness-kit

Discover @romabeckman/hrns, HarnessKit’s SDK and CLI for repeatable AI-assisted engineering workflows. Use hrns run to start the sovereign development loop, or hrns qa to plan, execute, and report user-facing acceptance tests with runtime evidence.

For CI/CD pipelines or running sovereign tasks without an open IDE chat session:

git clone https://github.com/romabeckman/harness-kit.git
cd harness-kit/sdk
npm install
npm run build
npm install -g .

Run from any project repository:

hrns run

📄 Full SDK documentation: sdk/README.md

📘 QA command scope and usage: sdk/docs/QA-TESTER-SCOPE.md — profiles, prerequisites, commands, reports, evidence, and current boundaries.

Explore the complete knowledge base inside docs/workflow/:

• Workflow Index — Main navigation index for documentation.
• Daily Use Playbook — Step-by-step tactical guide and command flows for daily development.
• Autonomous Loop Orchestration — Complete guide for running sovereign execution loops and hot-interception.
• Conceptual & Architectural Foundation — 3-layer architecture, prompt engineering principles, and continuous optimization.

• Harness Engineering — Reliability comes from controls and constraints, not raw model size.
• Product Backlog Building — Trace PBIs from real problems, expectations, personas, and functionalities before technical design.
• Foundation First — Strong architecture memory + DDD domain modeling + strict TDD make autonomous execution viable.
• Test-Driven Development — Write tests first. Always. No exceptions.
• Domain-Driven Design — Model the problem space before writing code.
• Socratic over Prescriptive — Ask questions that force root-cause understanding rather than shallow copy-paste answers.
• Continuous Self-Improvement — Measure every session and evolve prompts empirically.

HarnessKit is an open-source project. If it helps your development workflow, consider supporting its continued development.

Sponsor HarnessKit

Your support helps fund maintenance, documentation, research, and new features.

• Issues & Feedback: https://github.com/romabeckman/harness-kit/issues
• Author: Romario Beckman
• Contributors: @lnonatto98, @correriadev
• License: MIT License — see LICENSE for details.

• Lee, Y., Nair, R., Zhang, Q., Khattab, O., Finn, C., & Lee, K. (2026). Meta-Harness: End-to-End Optimization of Model Harnesses. arXiv:2603.28052.
• Birgitta Böckeler (2026). Harness engineering for coding agent users.