Headless Harness Kit

A portable methodology for AI-assisted software engineering: spec-driven development (SDD), a layered quality "harness", cross-session memory, and multi-model / multi-tool handoff — extracted from a real production project and stripped of all business semantics.

It is headless: it ships no runtime, no UI, no execution engine of its own. Your AI coding agent is the "head" that reads it, adapts it to your repo, and runs it. Even the stack-coupled layers are headless — the kit doesn't bundle implementations; it has the agent pick the best off-the-shelf framework at install time (borrow-first, build-the-gap).

This kit is not a boilerplate to copy verbatim. It is a methodology core + an agent-run installer. You hand it to your project's AI agent; the agent reads your codebase, asks a few questions, and generates the stack-specific glue adapted to your language, package manager, and CI — instead of inheriting someone else's stack.

Why this shape (and not a template repo or a philosophy doc)

The pieces of an AI engineering harness sit on a coupling spectrum:

| Tier | Examples | Coupling | How it travels | | :--- | :--- | :--- | :--- | | 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) | | B — Pattern, needs filling | prompt-only skills (checkpoint, smart-commit, find-bugs), ADR / session-state templates, hook logic | Structure portable, commands specific | Template + placeholders | | 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 |

A template-repo strategy ships Tier C as if it were the answer → the receiving agent cargo-cults a foreign stack and the template rots. A pure-philosophy-doc strategy throws away the hard-won Tier B artifacts → the agent re-walks every trap you already mapped.

This kit keeps the seam explicit: Tier A & B ship as files, Tier C ships as an agent-runnable recipe. This is the same "stable core, swappable adapter" principle good codebases already apply to vendor APIs — applied to your tooling.

For Tier C, the kit delegates before it builds. It does not want to own hook configs or CI YAML long-term — those belong to mature, fast-moving open-source frameworks (spec tooling, hook managers, CI, test libraries). So the installer's job is borrow-first, build-the-gap: research the best off-the-shelf framework at install time, adopt it, and wrap the kit's methodology around it; hand-roll only where nothing fits. The kit ships the decision procedure (core/methodology/framework-delegation.md) and a judgment rubric — not a frozen list of "recommended" frameworks, because such a list rots. The named examples in it are a dated, non-exhaustive snapshot (抛砖引玉), and the installing agent is told explicitly to do its own current research instead of trusting them.

What's inside

headless-harness-kit/
├── README.md                 ← you are here (human-facing overview)
├── INSTALL.md                ← ⭐ the meta-prompt you hand to the receiving agent
├── VERSION / CHANGELOG.md    ← the kit versions *itself*; installs are stamped with it
├── LICENSE                   ← MIT
│
├── core/                     ← Tier A — pure methodology, zero business semantics
│   ├── AGENTS.md.tmpl        ← single entry point shared by all AI tools
│   ├── model-routing.md      ← route tasks to the right model; never auto-switch
│   ├── handoff-protocol.md   ← clean handoff between sessions/tools (no model pinning)
│   ├── methodology/
│   │   ├── spec-driven.md         ← the "why" of SDD (constitution / invariants / specs)
│   │   ├── harness-layers.md      ← the 6-layer harness mental model
│   │   └── framework-delegation.md ← borrow-first procedure: pick the best off-the-shelf framework at install time
│   └── templates/            ← fill-in-the-blank skeletons
│       ├── constitution.tmpl.md
│       ├── invariants.tmpl.md
│       ├── feature-spec.tmpl.md
│       ├── session-state.tmpl.md
│       └── adr.tmpl.md
│
├── skills/                   ← Tier B — portable prompt-only skills
│   ├── README.md             ← what's portable vs. what's third-party (don't redistribute)
│   └── checkpoint/SKILL.md   ← cross-session state snapshotting
│
└── adapters/                 ← Tier C — recipes, NOT fixed implementations
    ├── hooks-recipe.md       ← what session/git hooks should enforce + Node/TS sample
    ├── ci-recipe.md          ← what the CI gate should check + Node/TS sample
    └── context-packaging.md  ← optional cold-start context bundling (skippable)

How to use it (two paths)

Path 1 — Install via the CLI, then hand off to your agent (recommended)

# in the target repo
npx @boyangjiao/headless-harness-kit init              # fresh project
npx @boyangjiao/headless-harness-kit init --existing   # existing project (agent extends, won't clobber)

The CLI does the mechanical part — places the methodology into .harness-kit/ and writes a .harness-kit-version stamp — then prints the prompt to paste into your AI coding tool. The agent then:

1. Surveys the repo and interviews you (≤5 questions).
2. Generates an adapted harness: a real constitution.md, a session-state.md, a model-routing table fit to your task taxonomy, and — borrow-first — the best off-the-shelf frameworks for hooks/CI/specs it can find at install time (falling back to the kit's recipes only for the gap).
3. Review the generated files. Commit (keep .harness-kit-version; you may delete .harness-kit/).

Later, when the kit publishes a new version: npx @boyangjiao/headless-harness-kit upgrade reads the stamp, prints the methodology delta, and drives an agent re-sync.

No CLI? Drop this folder into the repo and tell your agent "follow INSTALL.md" — same outcome, manual placement.

Path 2 — Read it yourself first

If you want to understand the philosophy before installing, read in this order:

1. core/methodology/spec-driven.md — the contract layer
2. core/methodology/harness-layers.md — the safety net
3. core/methodology/framework-delegation.md — borrow-first: how the installer picks frameworks
4. core/model-routing.md + core/handoff-protocol.md — the multi-model workflow

Then run Path 1.

The five mechanisms this kit transplants

1. Spec-Driven Development — a small set of read-time contracts (constitution, invariants, per-feature specs) that every agent must honor before writing code.
2. The layered harness — session hooks → git hooks → CI gate → automated tests, each catching a class of mistake earlier than the last.
3. Cross-session memory — a single live session-state.md + a checkpoint ritual, so any new session (any model, any tool) resumes cold with zero loss.
4. Model self-routing — match the task to the right-cost model; suggest a switch on mismatch, never switch unilaterally.
5. Tool-agnostic handoff — one canonical rule set, mirrored to each tool; handoffs describe the task, never pin the model.

Design rules for this kit (so it stays reusable)

• No business nouns. If a rule only makes sense for one domain, it belongs in the generated constitution, not in this kit.
• Recipes over implementations for Tier C. Never ship a hook that assumes a package manager. Ship the intent + one reference sample, clearly labeled.
• Every template marks its blanks with <<PLACEHOLDER>> so the installer (and a human) can see exactly what must be filled.
• The kit is the source; the install is a fork. Generated files live in the target repo and evolve there. This kit only changes when the methodology does.