Skip to content
This repository was archived by the owner on Jul 10, 2026. It is now read-only.

CODEBASE.md

Latest commit

 

History

History
99 lines (81 loc) · 4.66 KB

CODEBASE.md

File metadata and controls

99 lines (81 loc) · 4.66 KB
Raw

Harness Kit Codebase Map

Harness Kit is the ad-hoc operator harness: judgment skills, 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:

skills + 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
Vision VISION.md Project north star, strategic bets, non-goals, and what Harness Kit should become
Skills skills/<name>/SKILL.md (+ optional references/, scripts/, templates/) Judgment and context a frontier model can't derive
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 Crates

Three crates under crates/, split from one grab-bag harness-kit-checks (backlog 129) into gate-callers / hook-runtime / dispatcher audiences. The CLI binary (harness-kit-checks) depends on the other two as libraries; the dependency never runs the other way.

crates/harness-kit-checks — gates, bootstrap, install, catalog integrity. Exists for things prose cannot enforce. Each module names its consumer:

  • bootstrap + cli_install — system-wide symlink install (skills, configs, roster, CLI binary); prunes stale links, including a disposable-worktree self-heal (backlog 114).
  • git_hooks — pre-commit regeneration, pre-push gate dispatch (the Claude-specific hook bodies live in harness-kit-hooks, below).
  • ci_check — the gate lane list (check --repo .).
  • frontmatter, generate_index, docs_site, lint_gates, quality_gates, eval_coverage, template_check — catalog hygiene, the generated site, and the one-core-many-faces template's own build/boot proof.
  • premise_source — the /shape premise-source verifier (backlog 113).
  • backlog — trailer parsing and archive moves (used by /groom and /ship).
  • external_sync + external_skill_lint — registry-pinned vendoring.
  • skill_invocation_analytics — the telemetry command.
  • pr_reviews — PR review ingestion for review work.

crates/harness-kit-hooks — the Claude-specific hook runtime: claude_hooks (permission auto-approve, destructive-command guard, skill-invocation tracker, and the rest of the claude-hook <name> dispatch table) + invocation_kind (direct-vs-routed skill-use classification).

crates/harness-kit-roster — agent orchestration: agent_roster + lane_harness (roster provider dispatch, lane-harness projection) + source_refs + summarize_delegations (delegation receipts, .harness-kit/traces/delegations.jsonl).

The historical failure mode of these crates 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 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.