# Harness Kit Codebase Map

Harness Kit is the ad-hoc operator harness: judgment skills, saved prompts,
vendored external skills, shared doctrine, and the Rust tooling that
installs and guards them across Claude Code, Codex, Pi, and Antigravity.

The shortest accurate mental model:

```text
skills + prompts + shared doctrine + vendored externals
        |
        v
bootstrap symlinks everything system-wide into each detected harness
        |
        v
backlog.d work flows through /groom -> /shape -> /deliver -> /ship
        |
        v
cargo run --locked -p harness-kit-checks -- check --repo .  guards the catalog
```

## Source Of Truth

| Surface | Path | Owns |
|---|---|---|
| Skills | `skills/<name>/SKILL.md` (+ optional `references/`, `scripts/`, `templates/`) | Judgment and context a frontier model can't derive |
| Prompts | `prompts/<name>.md` | Saved invocations — installed as slash commands, no machinery |
| Externals | `skills/.external/<alias>/` | Vendored third-party skills at the pins in `registry.yaml` |
| Doctrine | `harnesses/shared/AGENTS.md` | Always-loaded operating rules, symlinked into every harness |
| Harness configs | `harnesses/{claude,codex,pi,…}/` | Per-runtime settings and hooks |
| Contracts | `meta/CONTRACTS.md` | Mode A / Mode B boundary, trailer canon, shared disk state |
| Work queue | `backlog.d/NNN-*.md`, `backlog.d/_done/` | Open and closed work |

Generated surfaces (never hand-edit): `index.yaml` and `docs/site/`, both
regenerated by the pre-commit hook and checked for drift by the gate.
`skills/.external/_checkouts/` is a local clone cache, gitignored.

## The Rust Crate

`crates/harness-kit-checks` exists for things prose cannot enforce. Each
module names its consumer:

- `bootstrap` — system-wide symlink install (skills, prompts, configs,
  roster, CLI binary); prunes stale links.
- `git_hooks` + `claude_hooks` — pre-commit regeneration, pre-push gate,
  permission auto-approve, destructive-command guard, skill-invocation
  tracker.
- `ci_check` — the gate lane list (`check --repo .`).
- `frontmatter`, `generate_index`, `docs_site`, `lint_gates` — catalog
  hygiene and the generated site.
- `backlog` — trailer parsing and archive moves (used by /groom and /ship).
- `external_sync` + `external_skill_lint` — registry-pinned vendoring.
- `agent_roster` + `lane_harness` + `source_refs` + `summarize_delegations`
  — roster provider dispatch and delegation receipts
  (`.harness-kit/traces/delegations.jsonl`).
- `skill_invocation_analytics` — the `telemetry` command.
- `pr_reviews` — PR review ingestion for review work.

The historical failure mode of this crate is deterministic scaffold that
enforces prose structure. Every gate must name a real failure it catches;
no answer means delete it.

## Workflow Lifecycle

`backlog.d/` is the single source of truth for work. `/groom` keeps it
honest (and audits each repo's own harness for gaps). `/shape` produces a
context packet with an acceptance oracle when the work needs one.
`/deliver` takes a ticket end to end. `/ship` (prompt) squash-merges to
master with `Closes-backlog:` trailers and archives tickets to `_done/`.

Mode B — event-driven workflows (review on PR-ready, incident response,
unattended outer loops) — lives in bitterblossom and communicates with this
repo only through the disk contracts in `meta/CONTRACTS.md`.

## Known Sharp Edges

- Symlink mode against a stable local checkout is the development path;
  remote bootstrap is a convenience. Never bootstrap from a disposable
  worktree.
- `pre-push` is local and Rust-owned; if it gets slow, fix `ci_check.rs`
  rather than adding container orchestration back.
- Archived backlog and `_done/` tickets describe historical architecture
  (Dagger CI, flywheel, settle, work ledgers, verdict refs). Treat
  `AGENTS.md`, `README.md`, and the live tree as current.
