{
  "markdown": "# 🔧 HarnessKit\n\n![HarnessKit - 5-Step Engineering Cycle](docs/assets/harness-cycle-banner.png)\n\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/romabeckman?style=flat&logo=githubsponsors&label=Sponsor)](https://github.com/sponsors/romabeckman)\n\n> **Harness Engineering**: A reliable AI agent is not just a raw model. It is defined as:\n> $$\\text{Reliable Agent} = \\text{Model (AI)} + \\text{Harness (Controls)} + \\text{Human Auditor}$$\n\nHarnessKit 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.\n\n---\n\n## 🏛️ The Foundation Triad\n\nAt 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.\n\n![HarnessKit - Foundation Triad](docs/assets/triad.png)\n\n---\n\n### 1. 🧠 Project Memory (`project-memory`)\n> **The Persistent Memory & Context Routing Engine**\n\nAI 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/`:\n\n* **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).\n* **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).\n* **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.\n* **Strict Constraints:** Enforces character caps (<8,000 chars per ADR), imperative rules (`REQUIRED`, `PROHIBITED`), and prevents architectural degradation over time.\n\n---\n\n### 2. 📐 Scope Refinement (`scope-refinement`)\n> **The Domain-Driven Design (DDD) Modeling & Specification Engine**\n\nBefore writing a single line of production code, `scope-refinement` breaks down requirements through rigorous Domain-Driven Design across four sequential phases:\n\n```text\nPhase 1: Problem Space   → 001-problem-space.md (Domain Events, Subdomains, Ubiquitous Language)\nPhase 2: Context Map     → 002-context-map.md (Bounded Contexts, Integrations, Upstream/Downstream)\nPhase 3: Tactical Design → 003-*-tactical-design.md (Aggregates, Entities, Value Objects, Ordered Tasks)\nPhase 4: Test Scenarios  → 004-*-test-scenarios.md (Given-When-Then Scenarios mapped to dev tasks)\n```\n\n* **Eliminates Ambiguity:** Resolves domain naming, business invariants, and boundaries prior to implementation.\n* **Pre-Specified Verification:** Generates concrete Given-When-Then test cases in Phase 4 that directly dictate what the implementation phase must fulfill.\n* **Dual Execution:** Runs interactively with human feedback gates or in headless autonomous mode.\n\n---\n\n### 3. 🧪 TDD Orchestrator (`tdd-orchestrator`)\n> **The Test-Driven Development & Verification Engine**\n\n`tdd-orchestrator` coordinates the implementation phase by enforcing the **Iron Law of TDD: no production code without a failing test first**.\n\n* **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.\n* **Step 2 — GREEN + REFACTOR:** Implements the minimal code required to pass tests, followed by structural refactoring to eliminate duplication while keeping test suites green.\n* **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.\n* **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.\n\n---\n\n## 🔄 The Complete Engineering Cycle\n\nThe Foundation Triad forms a closed, self-sustaining loop that transforms raw requirements into verified, fully documented features:\n\n```text\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 1. INITIALIZE MEMORY                                                        │\n│    `project-memory` scans repo → creates baseline ADRs & graph indexes       │\n└──────────────────────────────────────┬──────────────────────────────────────┘\n                                       │\n                                       ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 2. MODEL DOMAIN & SPECS                                                     │\n│    `scope-refinement` runs DDD → produces tactical plan & test scenarios    │\n└──────────────────────────────────────┬──────────────────────────────────────┘\n                                       │\n                                       ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 3. TEST-DRIVEN IMPLEMENTATION                                               │\n│    `tdd-orchestrator` executes RED → GREEN → REFACTOR against test scenarios│\n└──────────────────────────────────────┬──────────────────────────────────────┘\n                                       │\n                                       ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 4. SYNC LIVING MEMORY                                                       │\n│    `project-memory` updates `docs/feature/*.md` and `.graph.json` indexes   │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 🚀 Execution Modes: Interactive vs. Autonomous\n\nHarnessKit supports two primary ways to operate:\n\n### Mode A: Interactive Pair-Programming (Human in the Driver's Seat)\nInvoke skills individually during daily development:\n* Run `/harness-kit:project-memory` when onboarding a repo or documenting architectural changes.\n* Run `/harness-kit:scope-refinement` when planning a complex feature or breaking down a new business domain.\n* Run `/harness-kit:tdd-orchestrator` when executing test-first implementation for specific tasks.\n\n### Mode B: Sovereign Autonomous Loop (`autonomous-orchestrator` & CLI)\nFor hands-off execution, the **`autonomous-orchestrator`** skill chains the entire Foundation Triad together in an atomic, continuous loop:\n\n* **Sovereign Execution:** Executes domain planning, TDD implementation, and validation gates end-to-end without pausing for redundant questions.\n* **Live Auditing in the Cockpit:** The human engineer acts as auditor with real-time telemetry and full command:\n  * **Pull Emergency Brake (`Ctrl+C`):** Kill execution instantly if architectural drift occurs.\n  * **Hot-Interception:** Inject new requirements or edit backlog files mid-flight.\n  * **Dynamic Tuning:** Adjust quality gate thresholds (e.g. acceptance scores, `maxReworks`).\n* **Product State Machine:** Tracks progress through dynamic transition gates:\n  * **`COMPLETED`**: Approved and ready for final PR review.\n  * **`RETRY`**: Logs failure details to `REWORK-LOG.md` and loops back to code.\n  * **`BLOCKED`**: Critical crash; triggers circuit breaker for immediate human intervention.\n  * **`FAILED`**: Non-blocking technical debt; logged for post-hoc audit.\n\n![Autonomous State Machine](docs/assets/update-state-machine.png)\n\n---\n\n## 🛡️ Quality Gates & Self-Optimization\n\n### 🔍 Socratic Code Review (`the-grumpy-tech-lead`)\nTo 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.\n\n![Socratic Code Review Example](docs/assets/code-review.png)\n\n### 🎯 Adversarial QA (`adversarial-qa`)\nAn 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.\n\n### 🧬 Meta-Harness Optimization Loop\nHarnessKit continuously evaluates and optimizes its own prompt harnesses based on real execution telemetry:\n\n```text\nSessions (real work)\n       ↓\n meta-harness-agent    ← runs harness-tracer (records execution traces to docs/harness-history/)\n       ↓\n harness-evaluator     ← aggregates traces, calculates Pareto frontier scores\n       ↓\n meta-harness          ← proposes targeted improvements to SKILL.md instructions\n       ↓\n Human review & promotion\n```\n\n---\n\n## 📦 Installation & Quick Commands\n\nHarnessKit is distributed as a plugin compatible with major AI developer ecosystems:\n\n### Claude Code\n```bash\n/plugin marketplace add romabeckman/harness-kit\n/plugin install harness-kit@harness-kit\n/harness-kit:project-memory --help\n```\n\n### GitHub Copilot CLI\n```bash\ncopilot plugin marketplace add romabeckman/harness-kit\ncopilot plugin install harness-kit@harness-kit\n```\n\n### Gemini CLI\n```bash\nagy plugin install https://github.com/romabeckman/harness-kit\n```\n\n### Codex CLI\n```bash\ncodex plugin marketplace add https://github.com/romabeckman/harness-kit\ncodex plugin add harness-kit@harness-kit\n```\n\n---\n\n## 💻 SDK & CLI — `@romabeckman/hrns`\n\nFor CI/CD pipelines or running sovereign tasks without an open IDE chat session:\n\n```bash\ngit clone https://github.com/romabeckman/harness-kit.git\ncd harness-kit/sdk\nnpm install\nnpm run build\nnpm install -g .\n```\n\nRun from any project repository:\n```bash\nhrns run\n```\n\n> 📄 Full SDK documentation: [`sdk/README.md`](sdk/README.md)\n\n---\n\n## 🛠️ What's Inside\n\n### Core Skills (`/skills`)\n\n| Category | Skill | Core Function |\n| --- | --- | --- |\n| **Foundation** | **[Project Memory](skills/project-memory/SKILL.md)** (`project-memory`) | Creates and maintains persistent technical documentation (`docs/adr/`, `.digest.md`, `.graph.json`). The agent's long-term memory. |\n| **Foundation** | **[Scope Refinement](skills/scope-refinement/SKILL.md)** (`scope-refinement`) | DDD orchestrator. Maps Bounded Contexts, Aggregates, and Given-When-Then test scenarios before implementation. |\n| **Foundation** | **[TDD Orchestrator](skills/tdd-orchestrator/SKILL.md)** (`tdd-orchestrator`) | Enforces RED → GREEN → REFACTOR. Coordinates test-first implementation and quality gates. |\n| **Orchestration** | **[Autonomous Orchestrator](skills/autonomous-orchestrator/SKILL.md)** (`autonomous-orchestrator`) | Sovereign loop manager. Fully automates execution across planning, TDD, validation, and auto-tuning phases. |\n| **Orchestration** | **[Read UI Prototype](skills/read-ui-prototype/SKILL.md)** (`read-ui-prototype`) | Translates interface prototypes into structured frontend specs for UI engineers. |\n| **Quality Gates** | **[The Grumpy Tech Lead](skills/the-grumpy-tech-lead/SKILL.md)** (`the-grumpy-tech-lead`) | Senior technical reviewer. Uses Socratic questioning to expose architectural vulnerabilities and systemic risks. |\n| **Quality Gates** | **[Adversarial QA](skills/adversarial-qa/SKILL.md)** (`adversarial-qa`) | Executes adversarial boundary and security testing, returning structured JSON verdicts. |\n| **Optimization** | **[Harness Tracer](skills/harness-tracer/SKILL.md)** (`harness-tracer`) | Records structured execution traces to `docs/harness-history/traces/`. |\n| **Optimization** | **[Harness Evaluator](skills/harness-evaluator/SKILL.md)** (`harness-evaluator`) | Computes composite quality scores and identifies Pareto frontier harness configurations. |\n| **Optimization** | **[Meta-Harness](skills/meta-harness/SKILL.md)** (`meta-harness`) | Diagnoses failure patterns across sessions and proposes targeted skill prompt improvements. |\n\n### Expert Agents (`/agents`)\n\n| Agent | Role | Focus |\n| --- | --- | --- |\n| **[Software Architect](agents/software-architect.md)** | System Design & Refinement | DDD modeling, architectural decisions, and tactical planning. |\n| **[Developer Backend](agents/developer-backend.md)** | Backend Engineering | Robust APIs, database modeling, and server-side logic with TDD. |\n| **[Developer Frontend](agents/developer-frontend.md)** | Frontend Engineering | UI/UX implementation, accessibility, and client-side performance with TDD. |\n| **[Developer Debugging](agents/developer-debugging.md)** | Root Cause Specialist | Systematic bug investigation using the \"5 Whys\" methodology. |\n| **[Harness Tech Lead](agents/harness-tech-lead.md)** | Automated Code Review | Evaluates systemic risks, scalability, security, and design patterns. |\n| **[Harness QA](agents/harness-qa.md)** | Quality Assurance | Edge-case probing, contract validation, and adversarial QA testing. |\n| **[Meta-Harness Agent](agents/meta-harness-agent.md)** | Harness Optimizer | Analyzes trace history and coordinates prompt harness evolution. |\n| **[CTO](agents/cto.md)** | Autonomous Strategy | High-level execution strategy and loop governance. |\n\n---\n\n## 📖 Deep-Dive Documentation\n\nExplore the complete knowledge base inside `docs/workflow/`:\n\n* **[Workflow Index](docs/workflow/README.md)** — Main navigation index for documentation.\n* **[Daily Use Playbook](docs/workflow/PLAYBOOK-DAILY-USE.md)** — Step-by-step tactical guide and command flows for daily development.\n* **[Autonomous Loop Orchestration](docs/workflow/AUTONOMOUS-ORCHESTRATOR.md)** — Complete guide for running sovereign execution loops and hot-interception.\n* **[Conceptual & Architectural Foundation](docs/workflow/META-HARNESS.md)** — 3-layer architecture, prompt engineering principles, and continuous optimization.\n\n---\n\n## 💡 Philosophy\n\n* **Harness Engineering** — Reliability comes from controls and constraints, not raw model size.\n* **Foundation First** — Strong architecture memory + DDD domain modeling + strict TDD make autonomous execution viable.\n* **Test-Driven Development** — Write tests first. Always. No exceptions.\n* **Domain-Driven Design** — Model the problem space before writing code.\n* **Socratic over Prescriptive** — Ask questions that force root-cause understanding rather than shallow copy-paste answers.\n* **Continuous Self-Improvement** — Measure every session and evolve prompts empirically.\n\n---\n\n## Support HarnessKit\n\nHarnessKit is an open-source project. If it helps your development workflow,\nconsider supporting its continued development.\n\n[Sponsor HarnessKit](https://github.com/sponsors/romabeckman)\n\nYour support helps fund maintenance, documentation, research, and new features.\n\n## Contributing & Community\n\n* **Issues & Feedback:** <https://github.com/romabeckman/harness-kit/issues>\n* **Author:** [Romario Beckman](https://www.linkedin.com/in/romabeckman/)\n* **Contributors:** [@lnonatto98](https://github.com/lnonatto98), [@correriadev](https://github.com/correriadev)\n* **License:** MIT License — see [LICENSE](LICENSE) for details.\n\n### References\n* 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](https://arxiv.org/abs/2603.28052).\n* Birgitta Böckeler (2026). [Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html).\n",
  "bytes": 15615,
  "sha": "be406bf41079b024007a0b42616a4c2c73e0510503aae38cf1fe8267cc53d17b",
  "repo_slug": "romabeckman/harness-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_romabeckman_harness_kit_harness_kit_cd892dda/readme"
}