MetaHarness example for pi.dev: one command scaffolds an AGENTS.md-ready harness with host config, MCP registry, and a doctor check. Minimal, portable, ready to commit. npx @metaharness/pi-dev@latest my-bot

gist-metaharness-pi-dev.md

@metaharness/pi-dev — pi.dev AGENTS.md harness in one command

Intro

@metaharness/pi-dev is a one-shot scaffolding package for the pi.dev agent runtime. It uses the metaharness generator under the hood to drop a clean, minimal, ready-to-commit project layout that pi.dev workers can immediately pick up. The scaffold gives you the canonical AGENTS.md contract that AGENTS.md-aware hosts read on startup, plus a pi.dev-specific host config, an empty-but-valid MCP server registry, and a single starter agent you can rename or fork.

It is deliberately minimal. It does not bake in a multi-agent topology, a domain vertical (healthcare, finance, etc.), or an evaluation harness. If you want any of those, pick a vertical metaharness package instead. If you want a clean working directory you can iterate on, you're in the right place.

Usage details

The whole flow is a single command:

npx @metaharness/pi-dev@latest my-bot

That creates ./my-bot/. From there:

cd my-bot
npm install
harness doctor

npm install is needed because the scaffold's package.json pins metaharness and the harness CLI shim as dev dependencies — that's what makes harness doctor and harness validate available locally without another npx roundtrip.

harness doctor is the first thing you should run. It parses your AGENTS.md, your .pi/config.json, your mcp.json, and your harness.config.json, and prints a green checklist if everything resolves. If doctor complains, the message tells you exactly which file and which key is wrong.

You can pass any extra flag through to the underlying metaharness generator: npx @metaharness/pi-dev@latest my-bot --git --no-install works because everything after the project name is forwarded untouched.

Features

• AGENTS.md contract: the portable, host-agnostic file that pi.dev and other AGENTS.md-aware runtimes (Codex, Cursor agents) read on boot. It declares rules, allowed tools, file boundaries, and agent entrypoints.
• .pi/config.json: pi.dev-specific config — model defaults, sandbox policy (workspace-write by default), working directory. Other hosts ignore this file.
• mcp.json: an empty but schema-valid MCP server registry. Add servers with harness mcp add <name> or by editing directly.
• agents/main.md: one starter agent stub. Duplicate or rename as your team grows.
• harness.config.json: tells the harness CLI where things live. Used by doctor and validate.
• Minimal package.json + .gitignore: no lockfile churn, no opinionated dependency tree, ready to git init && git commit -am init.

Advanced

Three things real teams reach for once the scaffold is in place:

1. Strict validation before commit.

   harness validate --strict

   This resolves every file path and tool name referenced from AGENTS.md and fails on dangling references. Wire it into a pre-commit hook.

2. Dry-run a pi.dev session against the local scaffold.

   pi-dev run --plugin-dir . --dry-run

   pi.dev's CLI loads your AGENTS.md, prints which agent it would launch, and exits without executing. Useful in CI to confirm the contract still parses after a refactor.

3. Iterate on the AGENTS.md contract. When you tweak rules, tools, or agent files, re-run harness doctor — it's a sub-second op and catches the common breakages (missing tool name, stale agent path, malformed MCP entry) immediately.

The scaffold deliberately stays out of your way after generation: there's no runtime, no daemon, no background worker. Everything you run is explicit and stateless. That makes it cheap to delete and re-scaffold while you're still finding the shape of your harness.

Source: built on metaharness. MIT licensed.