Harness engineering culture

Build environments where agents execute and humans steer—through legible tooling (CLI, MCP, hooks, skills) and docs that agents can navigate without a monolithic manual.

Primary reference: Harness engineering (OpenAI).
Local patterns: CLI vs MCP separation (dual interfaces), schema and adapter registries.

Core beliefs

1. Missing capability → harness gap — When an agent fails, ask what is not legible or enforceable, then add CLI command, MCP tool, linter, or skill—not “try harder.”
2. Ambiguous design → decision checkpoint — Before coding a fork (CLI vs MCP split, new tool surface, schema shape), use adr-records layer 0 (decision checkpoints); record accepted ADR after agreement—not drive-by architecture.
3. CLI + MCP = thin interfaces; core = logic — MCP and CLI are agent-facing APIs only. Domain logic, schemas, and registries live in core packages; both surfaces call the same entrypoints. CLI for CI/doctor/contracts; MCP for chat. Divergence is a bug (core pattern).
4. Docs are the system of record — Versioned markdown in git; Slack/docs outside repo are invisible to agents. AGENTS.md is a map (~100 lines), not an encyclopedia.
5. Mechanical enforcement — Linters, make check-*, pnpm run validate, schema validation at boundaries—error messages teach the agent how to fix.
6. Progressive disclosure — Router → ADR / DESIGN_FAQ (why) → DX_FAQ (how) → skills (procedures) → code (behavior SSOT).

Skill Steward skill stack (use together)