{"_id":"@ahmontero/agent-harness","_rev":"2-3c11ede9639457f2efa36a1695f78f10","name":"@ahmontero/agent-harness","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@ahmontero/agent-harness","version":"1.0.0","keywords":["ai","agent","agentic-coding","antigravity","claude-code","cursor","codex","tdd","spec-driven-development","developer-tools"],"author":{"name":"Antigravity & Open Source Community"},"license":"MIT","_id":"@ahmontero/agent-harness@1.0.0","maintainers":[{"name":"ahmontero","email":"antoniohm2004@gmail.com"}],"homepage":"https://github.com/ahmontero/agent-harness#readme","bugs":{"url":"https://github.com/ahmontero/agent-harness/issues"},"bin":{"agh":"bin/agh","harness":"bin/harness","agent-harness":"bin/agent-harness"},"dist":{"shasum":"528af3009a0ba979df2db3f27f065140e222ef78","tarball":"https://registry.npmjs.org/@ahmontero/agent-harness/-/agent-harness-1.0.0.tgz","fileCount":51,"integrity":"sha512-XiWITFHLK6sPhc4ouDXbYUbthrUbJI5HPi3l7eS44R7Zim4HQtIK5dSdowT9f/bPUM7xOgtg1/9oiFbI2aWwog==","signatures":[{"sig":"MEUCIER2MigpoRXh7JuqnhUJTAxTT6NAhEgLwvUPdwhYAzotAiEA4gEAq0rE9DuFBR7Alq1aZ84thYQuYpklx3+IpKx7Fz0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":92452},"main":"bin/harness","gitHead":"687617082ac79023003a06d863afe2a1eb6c45c4","scripts":{"test":"bash test/test_cli.sh","verify":"bash setup --verify"},"_npmUser":{"name":"ahmontero","email":"antoniohm2004@gmail.com"},"repository":{"url":"git+https://github.com/ahmontero/agent-harness.git","type":"git"},"_npmVersion":"11.19.0","description":"The Universal Engineering Harness & Quality Floor for AI Coding Agents","directories":{},"_nodeVersion":"26.7.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/agent-harness_1.0.0_1787756919893_0.16785792640245756","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@ahmontero/agent-harness","version":"2.0.0","description":"The Universal Engineering Harness & Quality Floor for AI Coding Agents","main":"bin/harness","bin":{"harness":"bin/harness","agh":"bin/agh","agent-harness":"bin/agent-harness"},"scripts":{"test":"bash test/test_cli.sh && bash test/test_transaction_lib.sh && bash test/test_install_transaction.sh","test:cli":"bash test/test_cli.sh","test:transaction":"bash test/test_transaction_lib.sh && bash test/test_install_transaction.sh","lint":"find bin core/scripts test -type f \\( -name '*.sh' -o -name 'harness' -o -name 'agh' -o -name 'agent-harness' \\) -print0 | xargs -0 shellcheck -S warning install.sh setup","verify":"bash setup --verify"},"repository":{"type":"git","url":"git+https://github.com/ahmontero/agent-harness.git"},"bugs":{"url":"https://github.com/ahmontero/agent-harness/issues"},"homepage":"https://github.com/ahmontero/agent-harness#readme","keywords":["ai","agent","agentic-coding","antigravity","claude-code","cursor","codex","tdd","spec-driven-development","developer-tools"],"author":{"name":"Antigravity & Open Source Community"},"license":"MIT","gitHead":"1c7333fcf1001bb4a16acd97d1fffe886de92ce9","_id":"@ahmontero/agent-harness@2.0.0","_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-E+4cDsNciQvqbEC5esSbGUA2tDMrfHnwXtWgzPSuFpPe6orIu3WMbYNtb8pnrbg9Pc3S6YUB+p8CijJ6uSASLQ==","shasum":"d0fc0d9d57c0e49a3b2c442f0aa05e3052ef4931","tarball":"https://registry.npmjs.org/@ahmontero/agent-harness/-/agent-harness-2.0.0.tgz","fileCount":61,"unpackedSize":160429,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDsuoZBhKRzyBXoPwQJQKZ2iNLdzfbLty+NOgpyA1/5jwIhALvCrFLqmZe63jHw1JTeGV9EMlAoOKzhwtRREJPPK98K"}]},"_npmUser":{"name":"ahmontero","email":"antoniohm2004@gmail.com"},"directories":{},"maintainers":[{"name":"ahmontero","email":"antoniohm2004@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-harness_2.0.0_1788979250889_0.20875477106736384"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-26T15:08:39.700Z","modified":"2026-09-09T18:40:51.437Z","1.0.0":"2026-08-26T15:08:40.015Z","2.0.0":"2026-09-09T18:40:51.014Z"},"bugs":{"url":"https://github.com/ahmontero/agent-harness/issues"},"author":{"name":"Antigravity & Open Source Community"},"license":"MIT","homepage":"https://github.com/ahmontero/agent-harness#readme","keywords":["ai","agent","agentic-coding","antigravity","claude-code","cursor","codex","tdd","spec-driven-development","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/ahmontero/agent-harness.git"},"description":"The Universal Engineering Harness & Quality Floor for AI Coding Agents","maintainers":[{"name":"ahmontero","email":"antoniohm2004@gmail.com"}],"readme":"# ๐Ÿš€ agent-harness\n\n

\n \"Version\"\n \"CI\n \"License:\n \"Multi-Harness\"\n \"PRs\n \"Conventional\n

\n\n```text\n ___ __ __ __ \n / _ | ___ _ ___ ___ / /_ / // / ___ _ ____ ___ ___ ___ ___\n / __ |/ _ `/ -_)/ _ \\ / __/ / _ / / _ `/ __// _ \\/ -_)(_-<(_-<\n/_/ |_|\\_, / \\__/ /_//_/ \\__/ /_//_/ \\_,_//_/ /_//_/\\__//___//___/\n /___/ \n```\n\n> **The Universal Engineering Harness & Quality Floor for AI Coding Agents.** \n> Stop AI agents from breaking production. Enforce strict Red-Green TDD, 6-phase deterministic debugging, living delta specs, and pre-commit landmine scanners across **Google Antigravity**, **Claude Code**, **OpenAI Codex**, **Cursor**, and standard `.agents`.\n\n

\n \"agent-harness\n

\n\n---\n\n## ๐Ÿ“‘ Table of Contents\n\n- [โš–๏ธ Why agent-harness? (The Agent Quality Gap)](#๏ธ-why-agent-harness-the-agent-quality-gap)\n- [๐ŸŒ Universal Multi-Harness Compatibility](#-universal-multi-harness-compatibility)\n- [โšก 10-Second Quickstart](#-10-second-quickstart)\n- [๐Ÿšฆ Three Engineering Workflows](#-three-engineering-workflows)\n- [๐Ÿง  Internal Engineering Protocols](#-internal-engineering-protocols)\n- [๐Ÿ›ก๏ธ Injecting Domain Rules & Landmines](#๏ธ-injecting-domain-rules--landmines)\n- [๐Ÿ’ป Multi-Call CLI Dispatcher (`harness`)](#-multi-call-cli-dispatcher-harness)\n- [๐Ÿณ Ready-to-Use Recipes](#-ready-to-use-recipes)\n- [๐Ÿ›๏ธ Architecture & System Design](#๏ธ-architecture--system-design)\n- [๐Ÿ™ Acknowledgements & Provenance](#-acknowledgements--provenance)\n- [๐Ÿค Contributing & Community](#-contributing--community)\n\n---\n\n## โš–๏ธ Why agent-harness? (The Agent Quality Gap)\n\nAutonomous AI coding agents are exceptionally capable, but without a strict engineering harness, they inevitably degrade codebases:\n\n```\nโŒ Without agent-harness:\n 1. The agent immediately edits source code without creating reproduction tests (Violating TDD).\n 2. Modifies code directly in your active branch, leaving untracked experimental debris.\n 3. Rationalizes cutting corners (\"this fix is too simple for tests/specs\", over-mocking).\n 4. Introduces unindexed database queries or raw SQL, bypassing historical architectural invariants.\n 5. Blindly patches symptoms upon error without isolating the deterministic root cause.\n 6. Dumps walls of conversational text and wanders off on unrelated tangents.\n\nโœ… With agent-harness:\n 1. Strictly enforced Red-Green-Refactor loop (`/harness-tdd`) with Anti-Rationalization Gates.\n 2. Automatic branch/worktree isolation (`/harness-worktree`) keeps your workspace clean.\n 3. Anti-Rationalization Matrices cut off LLM excuses across all critical engineering skills.\n 4. Static JSON AST/regex scanner (`/harness-scan`) prevents known landmines before commit.\n 5. Matt Pocock-inspired 6-Phase Deterministic Debugging (`/harness-bug`) with tagged probe instrumentation.\n 6. Action-First & State-Anchored communication with automatic debt harvesting (`/harness-debt`).\n```\n\n---\n\n## ๐ŸŒ Universal Multi-Harness Compatibility\n\n`agent-harness` unifies your engineering standards across every major agent runtime:\n\n| AI Runtime / IDE | Auto-Linked Skills | Quality Floor & Rules | Pre-Commit Scanner | Worktree Isolation | Sub-Second Context (<1s) |\n| :--- | :---: | :---: | :---: | :---: | :---: |\n| **Google Antigravity** | โœ… (`.gemini/skills`) | โœ… (`.gemini/rules`) | โœ… | โœ… | โœ… (`harness context`) |\n| **Claude Code** | โœ… (`.claude/skills`) | โœ… (`.claude/rules`) | โœ… | โœ… | โœ… (`harness context`) |\n| **Cursor Agent** | โœ… (`.agents/skills`) | โœ… (`.cursor/rules`) | โœ… | โœ… | โœ… (`harness context`) |\n| **OpenAI Codex** | โœ… (`.codex/skills`) | โœ… (`.codex/rules`) | โœ… | โœ… | โœ… (`harness context`) |\n| **Generic (.agents)** | โœ… (`.agents/skills`) | โœ… (`.agents/rules`) | โœ… | โœ… | โœ… (`harness context`) |\n\nThe installation contract is exercised as an eight-cell Ubuntu/macOS matrix covering target and global installation in both default and expert modes. See [Verified Compatibility](docs/COMPATIBILITY.md) for the exact assertions, evidence artifacts, and reproducible commands.\n\n---\n\n## โšก 10-Second Quickstart\n\n### 1. One-Line Global Installation\n\n```bash\n# โšก Install globally without a language runtime or package bundle\ncurl -fsSL https://raw.githubusercontent.com/ahmontero/agent-harness/main/install.sh | bash\n\n# Or via npm\nnpm install -g @ahmontero/agent-harness\n```\n\n*Or via local clone:*\n```bash\ngit clone https://github.com/ahmontero/agent-harness.git\ncd agent-harness\n./setup --global\n\n# Optional: expose advanced primitive skills as standalone commands\n./setup --global --expert\n```\n\nEvery installation is transactional. Each mutation is journaled before it is applied, a failure part-way through restores the previous filesystem state automatically, and a completed installation can be undone:\n\n```bash\n./setup --rollback\n```\n\nJournals live under `$XDG_STATE_HOME/agent-harness` (or `~/.local/state/agent-harness`) and are created with `umask 077`. Set `HARNESS_STATE_DIR` to relocate them.\n\n### 2. Initialize in Any Existing Project\n\n```bash\ncd ~/projects/my-awesome-app\n\n# Run with harness CLI (or npx @ahmontero/agent-harness)\nharness init\n```\n\n`harness` will automatically:\n- Detect your language and test runner (`pytest`, `vitest`, `jest`, `cargo`, `go`).\n- Generate `stack.config.json` and a starter `rules/` directory.\n- Install the three curated workflow bundles through `.gemini`, `.claude`, `.codex`, and `.agents`, plus runtime-specific rule directories including `.cursor/rules`.\n\n---\n\n## ๐Ÿšฆ Three Engineering Workflows\n\nMost work starts with one of three intent-level workflows. Their private protocol bundles preserve the underlying engineering gates without exposing every primitive as a user command:\n\n```text\n/harness-implement Build or change behavior through spec-aware TDD, QA, and review.\n/harness-fix Reproduce, prove root cause, add a regression test, and apply a surgical fix.\n/harness-investigate Gather evidence, compare options, recommend, and stop without editing.\n```\n\nThe `harness-` namespace is used consistently in Gemini, Claude, Codex, and `.agents`, preventing collisions with generic or third-party skill names. CLI commands remain unchanged (`harness qa`, `harness scan`, and so on).\n\n`/harness-implement` and `/harness-fix` produce verified working-tree changes but never publish them without an explicit request. `/harness-investigate` is read-only and cannot silently transition into implementation.\n\n### Local execution receipts\n\nThe workflows record a small JSONL lifecycle receipt inside the repository's private Git metadata. Nothing is added to the working tree or sent remotely, and the schema does not accept prompts, code, file paths, secrets, or free-form evidence.\n\n```bash\nrun_id=\"$(harness receipt start implement --issue PROJ-123)\"\nharness receipt phase \"${run_id}\" tdd passed\nharness receipt phase \"${run_id}\" qa passed\nharness receipt finish \"${run_id}\" completed\n```\n\nReceipts live under `.git/agent-harness/runs/`, are shared across the repository's worktrees, and provide the input contract for future local statistics.\n\n### Progress ledger and the bounded review loop\n\nA receipt is a closed schema, so anything that needs words goes to the run's ledger instead. `/harness-implement` opens one at start, keyed by the same run ID, and uses it to survive a compacted context and to record every decision it took on your behalf.\n\n```bash\nharness ledger start \"${run_id}\"\nharness ledger append \"${run_id}\" phase \"round 2/3 (3 addressed, 1 open)\"\nharness ledger append \"${run_id}\" parked \"reviewer disputed the awk filter โ€” Ruling: the code stands\"\nharness ledger rulings \"${run_id}\"\n```\n\nThe ledger makes the review gate terminate. Minor findings never enter the fix loop; Critical and Important ones do, for at most three rounds. At the cap the agent must adjudicate every finding still open, either parking it with a recorded ruling or declaring it load-bearing, in which case the run ends `blocked` rather than reporting success over a known defect. Discarding a finding without a ledger line is forbidden, and `harness ledger rulings` is reproduced in full in the agent's final message.\n\nLedgers live under `.git/agent-harness/ledgers/`, are readable only by their owner, and never leave the repository.\n\n---\n\n## ๐Ÿง  Internal Engineering Protocols\n\nDefault installations expose only `/harness-implement`, `/harness-fix`, and `/harness-investigate`. The protocols below are bundled privately inside those workflows, so agents still apply TDD, debugging, specs, QA, and review without adding those primitives to the normal command surface.\n\nAdvanced users can expose the supported primitives as standalone skills with `./setup --global --expert` or `./setup --target --expert`. This mode is optional; operational CLI commands such as `harness qa`, `harness commit`, and `harness pr` remain available in both modes.\n\n
\n1. ๐Ÿ› Deterministic Debugging (/harness-bug <issue> <slug>)\n\nEnforces a 6-phase root-cause analysis cycle inspired by Matt Pocock and engineering superpowers:\n1. **Red Command**: Isolate single reproduction test or curl command.\n2. **Control & Blast Radius**: Inspect recent commits, touched files, and architectural blast radius.\n3. **Hypothesis**: Formulate a single falsifiable hypothesis before writing fixes.\n4. **Targeted Instrumentation**: Inject tagged `[DEBUG-xxxx]` probes.\n5. **Root-Cause Confirmation**: Inspect variable state and confirm causal chain.\n6. **Minimal Fix & Probes Cleanup**: Apply atomic fix, remove debug probes, and verify clean git status.\n
\n\n
\n2. ๐Ÿ”ด Strict TDD Loop (/harness-tdd <test_path>)\n\nEnforces the Red-Green-Refactor protocol:\n- **RED**: Write a failing unit/integration test capturing new requirements. Verify it fails for the right reason.\n- **GREEN**: Write minimal code necessary to make the test pass.\n- **REFACTOR**: Clean up implementation without altering observable behavior.\n
\n\n
\n3. ๐Ÿ›ก๏ธ Static Landmine Scanner (/harness-scan [--staged])\n\nScans code against custom JSON regex rules (`rules/landmines.json`):\n- Detects unindexed queries, raw SQL, client-side secret leaks, and unhandled promise rejections.\n- Install as a pre-commit hook via `harness scan --install-hook`.\n
\n\n
\n4. ๐Ÿ“ Living Delta Specs (/harness-spec <create|status>)\n\nLightweight Spec-Driven Development (OpenSpec):\n- Creates living specifications (`specs/-/harness-spec.md`).\n- Records architectural requirements, edge cases, and explicit non-goals.\n
\n\n
\n5. ๐Ÿฉบ Self-Healing Doctor (/harness-doctor [--fix])\n\nDiagnoses environment health:\n- Verifies required executables, target repository health, and Git configuration.\n
\n\n
\n6. ๐ŸŒณ Worktree Isolation (/harness-worktree <create|list>)\n\nManages isolated `git worktree` directories per ticket:\n- Enables agents to work in parallel on separate features without dirtying your main workspace or switching active branches.\n
\n\n
\n7. ๐Ÿงช QA Orchestrator (/harness-qa <test|tdd|all>)\n\nUnified interface for running test runners (`pytest`, `vitest`, `jest`, `cargo`, `go test`), linters, and type-checkers based on active project profiles.\n
\n\n
\n8. โš–๏ธ Two-Axis Code Review (/harness-review)\n\nPerforms automated two-axis code reviews:\n- **Axis 1 (Engineering Standards)**: Invariants, landmines, error handling, performance regressions.\n- **Axis 2 (Spec Conformance)**: Verifies all requirements in the ticket / delta spec are met.\n
\n\n
\n9. ๐Ÿ”€ Conflict Resolver (/harness-conflicts)\n\nResolves git merge and rebase conflicts systematically by tracing the original commit intent from branch logs.\n
\n\n
\n10. ๐Ÿ“‹ Discovery Questionnaire (/harness-questionnaire)\n\nTransforms technical blockers or ambiguous domain decisions into structured discovery forms for external stakeholders.\n
\n\n
\n11. ๐ŸŒพ Debt Harvester (/harness-debt [--json])\n\nAudits and indexes pragmatic technical debt markers (`# pragmatism:`, `# defer:`) across the codebase.\n
\n\n
\n12. โœ๏ธ Conventional Commit (/harness-commit <build|msg>)\n\nFormats semantic Conventional Commits (`feat:`, `fix:`, `refactor:`, `chore:`) automatically associated with ticket IDs.\n
\n\n
\n13. ๐ŸŽฏ Architectural Task Planner (/harness-task <issue> <slug>)\n\nDiscovers requirements, identifies deep module seams, drafts delta specs, and sets up isolated branches.\n
\n\n
\n14. ๐Ÿงน Code Simplifier & Complexity Reducer (/harness-simplify [path])\n\nAudits generated code to strip speculative abstractions, shallow wrappers, dead types, and over-engineering (YAGNI & Deep Modules) while maintaining GREEN tests.\n
\n\n
\n15. ๐Ÿ’ฌ Socratic Requirement Interrogator (/harness-interview [topic])\n\nResolves architectural ambiguity by asking exactly **one structured multiple-choice question at a time** with a recommended option before drafting specs.\n
\n\n---\n\n## ๐Ÿ›ก๏ธ Injecting Domain Rules & Landmines\n\nIn your target repository, define custom domain rules in `rules/`:\n\n### 1. `rules/floor.md` (Unbreakable Quality Floor)\n```markdown\n# Quality Floor Invariants\n1. No unindexed database queries in API routes.\n2. All external API integrations must use circuit breakers and retries.\n3. Every database mutation must emit an audit event.\n```\n\n### 2. `rules/landmines.json` (Automated Pre-Commit Scanner)\n```json\n[\n {\n \"id\": \"NO_RAW_SQL\",\n \"name\": \"SQL Injection Risk\",\n \"pattern\": \"(cursor\\\\.execute\\\\(f[\\\"']|raw_query\\\\(f[\\\"'])\",\n \"fileExtensions\": [\".py\", \".ts\"],\n \"level\": \"error\",\n \"message\": \"Raw f-string SQL query detected. Always use parameterized queries.\"\n }\n]\n```\n\nInstall as pre-commit guard:\n```bash\nharness scan --install-hook\n```\n\n---\n\n## ๐Ÿ’ป Multi-Call CLI Dispatcher (`harness`)\n\nThe single `harness` executable acts as a multi-call dispatcher (like `busybox` or `git`) without a language-runtime package bundle. It expects standard shell tooling plus Git and `jq`; `curl` is required for optional AI and network integrations.\n\n- **Primary command:** `harness ` (aliases: `agh`, `agent-harness`).\n- **Dynamic profile resolution:** Auto-detects the active profile based on the current directory or explicit `--profile `.\n- **Custom aliases:** Define a custom alias in `stack.config.json` (e.g. `\"cliAlias\": \"backend\"`):\n - Typing `backend doctor` or `backend qa` automatically targets that specific profile.\n\n### ๐Ÿš Shell Autocompletion (Zsh & Bash)\n\nEnable instant tab completion for `harness` / `agh`:\n```bash\nharness completion install\n```\n\n---\n\n## ๐Ÿณ Ready-to-Use Recipes\n\nJumpstart your stack with production-ready presets:\n- ๐Ÿ **`recipes/python-fastapi/`**: Async discipline, Pydantic v2 validation, SQLAlchemy patterns.\n- ๐Ÿ”ท **`recipes/typescript-fullstack/`**: Strict null checks, Zod boundary validation, immutable state.\n- ๐Ÿน **`recipes/go-microservices/`**: Context propagation, explicit error wrapping, goroutine safety.\n\n*See [docs/RECIPES.md](docs/RECIPES.md) for how to use and contribute new recipes.*\n\n---\n\n## ๐Ÿ›๏ธ Architecture & System Design\n\nFor a deep dive into sub-second context signals, multi-harness synchronization, and POSIX core architecture, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n---\n\n## ๐Ÿ™ Acknowledgements & Provenance\n\n`agent-harness` is an independent implementation that synthesizes proven ideas from the open-source agent engineering community. In particular:\n\n- **[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)** โ€” workflow-oriented skills, explicit verification gates, and anti-rationalization safeguards.\n- **[obra/superpowers](https://github.com/obra/superpowers)** โ€” strict Red-Green-Refactor discipline, systematic debugging, and isolated worktree workflows.\n- **[mattpocock/skills](https://github.com/mattpocock/skills)** โ€” tight red-capable feedback loops, ranked falsifiable hypotheses, and tagged diagnostic instrumentation.\n- **[Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)** โ€” Spec-Driven Development, living specifications, and delta-based requirements.\n- **[ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd)** โ€” action-first communication, visible state anchors, and cognitive-load reduction.\n\nThese projects are sources of inspiration and adapted engineering patterns; they are not runtime dependencies of `agent-harness`. See [Provenance and Acknowledgements](docs/PROVENANCE.md) for the exact relationships, source snapshots, and licensing policy.\n\n---\n\n## ๐Ÿค Contributing & Community\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.\n\n```bash\n# Verify all scripts and skill frontmatter\n./setup --verify\n\n# Lint every shell entry point\nnpm run lint\n\n# Run the full test suite (CLI, transaction library, transactional installer)\nnpm test\n```\n\n---\n\n## ๐Ÿ“„ License\n\nDistributed under the [MIT License](LICENSE).\n","readmeFilename":"README.md"}