AGENTS.md

AGENTS.md — Harness Kit

Harness Kit is the harness source repo. Keep this file terse: repo-specific contracts only. Put workflow detail in skills; put generated/runtime state on disk; do not restate obvious filesystem facts.

What This Repo Is

Harness Kit — the ad-hoc operator harness: judgment skills, vendored external skills, shared doctrine, and harness configs, installed to every harness (~/.claude, ~/.codex, ~/.pi, antigravity) by the Rust bootstrap. Event-driven automation (CI-native review, incident response, outer loops) is Mode B and lives in bitterblossom, not here; the boundary contract is meta/CONTRACTS.md.

Structure

harness-kit/
├── skills/         # Judgment skills (deliver, groom, qa, code-review, …)
│   └── .external/  # Vendored third-party skills, pinned via registry.yaml
├── harnesses/      # Per-harness configs, hooks, shared AGENTS.md doctrine
├── meta/           # Cross-repo contracts (Mode B boundary, trailers)
├── registry.yaml   # External source provenance: repo, pin, license notes
├── crates/harness-kit-checks/  # Bootstrap, gates, hooks, sync, telemetry
└── bootstrap.sh    # curl-compatible launcher for the Rust bootstrap

Non-Negotiables

• Project direction lives in VISION.md. Read it before changing strategy, primitive scope, provider defaults, or the Mode A/Mode B boundary; do not duplicate its prose here.
• Base branch: master.
• Gate: cargo run --locked -p harness-kit-checks -- check --repo .. Green means the Rust-owned local gate passed; /ci owns the exact lane list in crates/harness-kit-checks/src/ci_check.rs.
• Clean-tree closeout: shared Closeout applies; see harnesses/shared/AGENTS.md (Closeout). Harness Kit additionally treats untracked backlog.d/NNN-*.md as signal unless the user explicitly says scratch/delete.
• index.yaml and docs/site are generated (regenerated by the pre-commit hook). Never edit either by hand.
• harnesses/claude/settings.json is copied by bootstrap (Claude mutates it at runtime); changes require re-bootstrap.
• Skill scripts/libs/references live under the skill they serve. Code outside a skill must serve only this source repo's maintenance, generated artifacts, bootstrap/install, or harness configuration.
• Durable repo/install tooling is Rust in crates/harness-kit-checks. The only allowed non-Rust implementation surface is bootstrap.sh as the curl-compatible Rust launcher. Every gate must name a real failure it catches; gates that enforce prose structure are the historical failure mode here.
• Harness Kit source skills live only in skills/. Do not commit source-repo .agents/skills/, .codex/skills/, .claude/skills/, .pi/skills/, or .antigravitycli/skills/ bridges; those duplicate the global install here.
• Bootstrap from a stable checkout, not a disposable worktree — worktree symlinks make global skills vanish when the worktree dies.
• External skills are vendored at pins; edit one and it's a fork — mark it in registry.yaml and stop syncing it.

Primitive Test

Before adding anything, run the primitive test (full version in skills/harness-engineering/SKILL.md): local prompt = "what I'd retype and does not deserve repo source"; skill = "changes what a frontier model does or must be app-discoverable"; doctrine line = "worth paying for every session"; event-triggered = Mode B, not here. Most "new skills" are task prompts or doctrine lines, but Codex app-visible reusable invocations need to be skills. Skills encode judgment, not procedures — if the model already knows how, delete it.

Workflow

backlog.d/ → /groom → /shape (when the idea needs it) → /deliver → /ship

/deliver is the spine: context-first, docs→tests→code, live QA, three-altitude refactor, diverse-provider review, adversarial pre-ship thinking. It stops at merge-ready unless asked to ship.

Roster

The delegation floor lives in harnesses/shared/AGENTS.md (Roster). Harness Kit resolves providers from .harness-kit/agents.yaml or ~/.harness-kit/agents.yaml, records sanitized receipts in .harness-kit/traces/delegations.jsonl, and reports receipt-grounded roster evidence instead of raw transcripts.

Backlog

• Active: backlog.d/NNN-*.md.
• Closed: backlog.d/_done/NNN-*.md.
• Closure signal: Closes-backlog: / Ships-backlog: trailers, or an explicit backlog move committed with the work. /ship injects trailers and archives; /groom sweeps for drift.
• Open high-signal debt starts at backlog.d/023-*.md; do not mirror the debt table here. Read the directory.

Positioning

Before answering whether to hand this repo to a client, enterprise, department, executive, procurement reviewer, security reviewer, or nontechnical team, read docs/positioning.md. Harness Kit is implementation substrate for technical operators, not the buyer-facing governed workflow package or admin-control plane.

Harness Work

This repo is Mode A only: the ad-hoc operator harness. Event-driven workflows (CI-native review, incident response, outer loops) belong to bitterblossom; see meta/CONTRACTS.md. Do not define static project subagents here. Spawn roster/ad-hoc lanes from the active skill with a role, scope, output shape, and boundaries. New primitives pass the primitive test above (prompt vs skill vs doctrine line vs Mode B).

Principles

See harnesses/shared/AGENTS.md — one file, symlinked to every harness.

• Thin harness, strong models — judgment and context, not process machinery. Phase prose the model already knows is railroading.
• Cross-harness first — filesystem + SKILL.md is the primary layer; harness-native features are optimizations.
• Gotchas > instructions; description is the trigger; map, not manual — AGENTS/CLAUDE point at skills, never contain them.
• Telemetry before catalog changes — harness-kit-checks telemetry; usage evidence beats vibes in both directions.

Hot Paths

• harnesses/shared/AGENTS.md — shared cross-harness doctrine.
• meta/CONTRACTS.md — Mode B boundary, trailer canon, shared disk state.
• cargo run --locked -p harness-kit-checks -- bootstrap — system-wide install (skills, prompts, configs); externals are vendored at registry pins.
• cargo run --locked -p harness-kit-checks -- telemetry — skill/prompt usage summarizer; consult before catalog changes.
• bootstrap.sh — curl-compatible launcher for the Rust bootstrap command.

Red Lines

Harness Kit architecture constraints:

• Open-model harnesses first for peer lanes: Pi, Goose, and OpenCode through OpenRouter when smoke-tested. Codex remains a lead/implementation surface; Claude, Antigravity, Cursor, and Grok are conditional tools, not the default roster bias.
• Skills are self-contained: scripts/libs/references live under the skill.
• No claim primitives under skills/.
• No semantic workflow engine around provider CLIs.
• No generated repo harness layer unless a shaped ticket proves it earns its complexity.