{"_id":"@boyangjiao/headless-harness-kit","name":"@boyangjiao/headless-harness-kit","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@boyangjiao/headless-harness-kit","version":"0.1.0","description":"A headless methodology for AI-assisted software engineering: spec-driven development, a layered quality harness, cross-session memory, and multi-model handoff. Ships no runtime — your AI agent is the head that reads, adapts, and runs it. Borrow-first.","type":"module","bin":{"headless-harness-kit":"bin/cli.mjs","hhk":"bin/cli.mjs"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"test":"node bin/cli.mjs --version >/dev/null && echo ok","version":"node -e \"const fs=require('fs');fs.writeFileSync('VERSION',JSON.parse(fs.readFileSync('package.json')).version+'\\n')\" && git add VERSION"},"keywords":["ai","agent","harness","spec-driven-development","sdd","claude-code","cursor","methodology","llm"],"license":"MIT","author":{"name":"Boyangjiao"},"repository":{"type":"git","url":"git+https://github.com/boyangjiao/headless-harness-kit.git"},"_id":"@boyangjiao/headless-harness-kit@0.1.0","gitHead":"e656a3bdfe67a60614d60cf14880e8eafdb6eeac","bugs":{"url":"https://github.com/boyangjiao/headless-harness-kit/issues"},"homepage":"https://github.com/boyangjiao/headless-harness-kit#readme","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-+3RB6w9Kwla//KeLk7IsIMfgFWngUOdDzYwPjcGBnGs3KpvGDu2sG6Fxw1KGfOPnMOpKjR+N/iYvqx9A9jVaHw==","shasum":"5ccbafeeb343ecaa4d49ade7171bca5eae8771bb","tarball":"https://registry.npmjs.org/@boyangjiao/headless-harness-kit/-/headless-harness-kit-0.1.0.tgz","fileCount":23,"unpackedSize":83002,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICtFk+pDWVCCV16t3zgXzQhDdcN2jZHkvVTlfuAAPtXpAiEA7erh8QhG354bV9LkxK4SQLLq20jET22wdVqHS6RXkEE="}]},"_npmUser":{"name":"boyangjiao","email":"cyberjby@gmail.com"},"directories":{},"maintainers":[{"name":"boyangjiao","email":"cyberjby@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/headless-harness-kit_0.1.0_1780469760843_0.6109851815180931"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T06:56:00.614Z","0.1.0":"2026-06-03T06:56:00.981Z","modified":"2026-06-03T06:56:01.210Z"},"maintainers":[{"name":"boyangjiao","email":"cyberjby@gmail.com"}],"description":"A headless methodology for AI-assisted software engineering: spec-driven development, a layered quality harness, cross-session memory, and multi-model handoff. Ships no runtime — your AI agent is the head that reads, adapts, and runs it. Borrow-first.","homepage":"https://github.com/boyangjiao/headless-harness-kit#readme","keywords":["ai","agent","harness","spec-driven-development","sdd","claude-code","cursor","methodology","llm"],"repository":{"type":"git","url":"git+https://github.com/boyangjiao/headless-harness-kit.git"},"author":{"name":"Boyangjiao"},"bugs":{"url":"https://github.com/boyangjiao/headless-harness-kit/issues"},"license":"MIT","readme":"# Headless Harness Kit\n\n> A portable methodology for **AI-assisted software engineering**: spec-driven\n> development (SDD), a layered quality \"harness\", cross-session memory, and\n> multi-model / multi-tool handoff — extracted from a real production project\n> and stripped of all business semantics.\n>\n> It is **headless**: it ships no runtime, no UI, no execution engine of its own.\n> Your AI coding agent is the \"head\" that reads it, adapts it to your repo, and\n> runs it. Even the stack-coupled layers are headless — the kit doesn't bundle\n> implementations; it has the agent pick the best off-the-shelf framework *at\n> install time* (borrow-first, build-the-gap).\n\nThis kit is **not** a boilerplate to copy verbatim. It is a **methodology core +\nan agent-run installer**. You hand it to your project's AI agent; the agent\nreads your codebase, asks a few questions, and *generates* the stack-specific\nglue adapted to your language, package manager, and CI — instead of inheriting\nsomeone else's stack.\n\n---\n\n## Why this shape (and not a template repo or a philosophy doc)\n\nThe pieces of an AI engineering harness sit on a **coupling spectrum**:\n\n| Tier | Examples | Coupling | How it travels |\n| :--- | :--- | :--- | :--- |\n| **A — Pure methodology** | SDD structure, model routing, handoff protocol, checkpoint mechanism, the \"layered harness\" mental model | Zero. True for a Rust CLI, a Go service, a data pipeline | **Copied 1:1** (templated) |\n| **B — Pattern, needs filling** | prompt-only skills (checkpoint, smart-commit, find-bugs), ADR / session-state templates, hook *logic* | Structure portable, *commands* specific | **Template + placeholders** |\n| **C — Stack-welded** | exact husky config, CI YAML, property tests, lint rules, secret-scan regexes | Strong. Meaningless on a different stack | **Not copied — regenerated** from a recipe |\n\nA template-repo strategy ships Tier C as if it were the answer → the receiving\nagent cargo-cults a foreign stack and the template rots. A pure-philosophy-doc\nstrategy throws away the hard-won Tier B artifacts → the agent re-walks every\ntrap you already mapped.\n\n**This kit keeps the seam explicit**: Tier A & B ship as files, Tier C ships as\nan *agent-runnable recipe*. This is the same \"stable core, swappable adapter\"\nprinciple good codebases already apply to vendor APIs — applied to your tooling.\n\n**For Tier C, the kit delegates before it builds.** It does not want to own hook\nconfigs or CI YAML long-term — those belong to mature, fast-moving open-source\nframeworks (spec tooling, hook managers, CI, test libraries). So the installer's\njob is **borrow-first, build-the-gap**: research the best off-the-shelf framework\n*at install time*, adopt it, and wrap the kit's methodology around it; hand-roll\nonly where nothing fits. The kit ships the *decision procedure*\n(`core/methodology/framework-delegation.md`) and a *judgment rubric* — not a\nfrozen list of \"recommended\" frameworks, because such a list rots. The named\nexamples in it are a dated, non-exhaustive snapshot (抛砖引玉), and the installing\nagent is told explicitly to do its own current research instead of trusting them.\n\n---\n\n## What's inside\n\n```\nheadless-harness-kit/\n├── README.md                 ← you are here (human-facing overview)\n├── INSTALL.md                ← ⭐ the meta-prompt you hand to the receiving agent\n├── VERSION / CHANGELOG.md    ← the kit versions *itself*; installs are stamped with it\n├── LICENSE                   ← MIT\n│\n├── core/                     ← Tier A — pure methodology, zero business semantics\n│   ├── AGENTS.md.tmpl        ← single entry point shared by all AI tools\n│   ├── model-routing.md      ← route tasks to the right model; never auto-switch\n│   ├── handoff-protocol.md   ← clean handoff between sessions/tools (no model pinning)\n│   ├── methodology/\n│   │   ├── spec-driven.md         ← the \"why\" of SDD (constitution / invariants / specs)\n│   │   ├── harness-layers.md      ← the 6-layer harness mental model\n│   │   └── framework-delegation.md ← borrow-first procedure: pick the best off-the-shelf framework at install time\n│   └── templates/            ← fill-in-the-blank skeletons\n│       ├── constitution.tmpl.md\n│       ├── invariants.tmpl.md\n│       ├── feature-spec.tmpl.md\n│       ├── session-state.tmpl.md\n│       └── adr.tmpl.md\n│\n├── skills/                   ← Tier B — portable prompt-only skills\n│   ├── README.md             ← what's portable vs. what's third-party (don't redistribute)\n│   └── checkpoint/SKILL.md   ← cross-session state snapshotting\n│\n└── adapters/                 ← Tier C — recipes, NOT fixed implementations\n    ├── hooks-recipe.md       ← what session/git hooks should enforce + Node/TS sample\n    ├── ci-recipe.md          ← what the CI gate should check + Node/TS sample\n    └── context-packaging.md  ← optional cold-start context bundling (skippable)\n```\n\n---\n\n## How to use it (two paths)\n\n### Path 1 — Install via the CLI, then hand off to your agent (recommended)\n\n```sh\n# in the target repo\nnpx @boyangjiao/headless-harness-kit init              # fresh project\nnpx @boyangjiao/headless-harness-kit init --existing   # existing project (agent extends, won't clobber)\n```\n\nThe CLI does the mechanical part — places the methodology into `.harness-kit/`\nand writes a `.harness-kit-version` stamp — then prints the prompt to paste into\nyour AI coding tool. The agent then:\n\n1. Surveys the repo and interviews you (≤5 questions).\n2. Generates an adapted harness: a real `constitution.md`, a `session-state.md`,\n   a model-routing table fit to *your* task taxonomy, and — **borrow-first** —\n   the best off-the-shelf frameworks for hooks/CI/specs it can find *at install\n   time* (falling back to the kit's recipes only for the gap).\n3. Review the generated files. Commit (keep `.harness-kit-version`; you may delete\n   `.harness-kit/`).\n\nLater, when the kit publishes a new version: `npx @boyangjiao/headless-harness-kit upgrade`\nreads the stamp, prints the methodology delta, and drives an agent re-sync.\n\n> No CLI? Drop this folder into the repo and tell your agent *\"follow\n> INSTALL.md\"* — same outcome, manual placement.\n\n### Path 2 — Read it yourself first\n\nIf you want to understand the philosophy before installing, read in this order:\n\n1. [`core/methodology/spec-driven.md`](core/methodology/spec-driven.md) — the contract layer\n2. [`core/methodology/harness-layers.md`](core/methodology/harness-layers.md) — the safety net\n3. [`core/methodology/framework-delegation.md`](core/methodology/framework-delegation.md) — borrow-first: how the installer picks frameworks\n4. [`core/model-routing.md`](core/model-routing.md) + [`core/handoff-protocol.md`](core/handoff-protocol.md) — the multi-model workflow\n\nThen run Path 1.\n\n---\n\n## The five mechanisms this kit transplants\n\n1. **Spec-Driven Development** — a small set of read-time contracts (constitution,\n   invariants, per-feature specs) that every agent must honor before writing code.\n2. **The layered harness** — session hooks → git hooks → CI gate → automated tests,\n   each catching a class of mistake earlier than the last.\n3. **Cross-session memory** — a single live `session-state.md` + a `checkpoint`\n   ritual, so any new session (any model, any tool) resumes cold with zero loss.\n4. **Model self-routing** — match the task to the right-cost model; suggest a\n   switch on mismatch, **never switch unilaterally**.\n5. **Tool-agnostic handoff** — one canonical rule set, mirrored to each tool;\n   handoffs describe the *task*, never pin the model.\n\n---\n\n## Design rules for this kit (so it stays reusable)\n\n- **No business nouns.** If a rule only makes sense for one domain, it belongs in\n  the *generated* constitution, not in this kit.\n- **Recipes over implementations for Tier C.** Never ship a hook that assumes a\n  package manager. Ship the *intent* + one reference sample, clearly labeled.\n- **Every template marks its blanks** with `<<PLACEHOLDER>>` so the installer (and\n  a human) can see exactly what must be filled.\n- **The kit is the source; the install is a fork.** Generated files live in the\n  target repo and evolve there. This kit only changes when the *methodology* does.\n","readmeFilename":"README.md","_rev":"1-f0423a11e5e0456f1911883ced54fc92"}