mb-harness

mb-harness — Harness engineering setup

What it does: defines the execution harness around the repo, including commands, gates, and parallel-safe workflow.
Use it when: the repository needs stronger agent guardrails before autonomous or multi-session work.
Input: repository root and the project’s canonical build, test, and lint commands.
Output: documented quality gates, optional Codex config, and a safer harness for agent execution.

Goal

Turn the repo into a reliable “harness” for agents:

clear entry points (AGENTS.md)
reproducible commands (build/test/lint)
mechanical checks (CI + MB lint)
parallel-safe workflow (worktrees)

Process

1) Codex project configuration (optional but recommended)

If you use Codex:

Create .codex/ folder.
Create .codex/config.toml from assets/codex-config.toml.

Usage examples:

default profile (coding): codex
deep review: codex --profile deep-review

2) Document quality gates

In AGENTS.md (keep it short), list the canonical commands (examples):

install deps
lint / typecheck
unit tests
e2e tests

If the repo has UI or browser flows, explicitly document:

Playwright command(s)
agent-browser / browser MCP path (if available)
where screenshots/videos/traces are stored
which flows are considered release-critical

If the repo lacks them, add minimal scripts/Make targets.

3) Worktree workflow (parallel agents)

If multiple agents work in parallel:

create worktrees per agent to avoid file conflicts
merge only after passing gates

Example:

git worktree add ../wt-agent-1 -b agent-1

4) Add deterministic Memory Bank gates

If not already present, install the packaged Memory Bank gate assets:

scripts/mb-lint.mjs from mb-garden/assets/mb-lint.mjs
scripts/mb-doctor.mjs from mb-garden/assets/mb-doctor.mjs
CI workflow coverage for the default health gates

The mb-garden/assets path is the current packaged asset location, not conceptual ownership of the doctor role. mb-lint covers structural/mechanical hygiene. mb-doctor covers workflow/autonomous readiness over mb-lint. Run default mb-doctor for ordinary pre-queue health checks. Run strict mode only after the JSON task queue exists: after /prd-to-tasks, before scheduler execution inside /autonomous, or before /autopilot when the queue is already prepared:

node scripts/mb-lint.mjs
node scripts/mb-doctor.mjs --strict

The harness should treat missing task.tier as a blocking policy error. Task state is JSON-only through .memory-bank/tasks/index.json and indexed TASK-*.task.json records; backlog.md, markdown task cards, and old risk / risk.level routing are unsupported.

4.1) Browser verification for UI projects

If the product has a UI:

prefer Playwright / agent-browser / CDP-driven checks over “manual looks OK”
persist artifacts (screenshots, videos, traces) into .tasks/TASK-XXX/
document canonical browser verification commands in .memory-bank/testing/index.md

5) Optional: skill eval harness

If you iterate on skills heavily:

use codex exec --json runs + deterministic graders (see OpenAI evals guidance)

Definition of done

.codex/config.toml exists (if using Codex) with coding + review profiles.
AGENTS.md lists quality-gate commands.
repo has a documented path for worktrees.
Memory Bank lint exists and passes.
UI repos have a documented browser-driven verification path.