ZOB Harness

A governed Pi harness for human-controlled agentic engineering.

ZOB Harness turns an open-ended coding-agent chat into a governed engineering loop: clear contracts, specialist agents, mode-aware workflows, safety gates, evidence reports, skeptical oracle review, and repeatable software factories.

It is for developers and evaluators who want agents to help with real repository work without losing the plot, touching secrets, silently committing, or declaring victory without proof.

Human intent
  -> six-part contract
  -> scoped mode and tools
  -> specialist agent or local implementation
  -> validation evidence
  -> oracle review / no-ship decision
  -> reusable workflow when the pattern repeats

ZOB is not an “unleash the agent” project. It is a control plane for making agent work reviewable, bounded, and repeatable.

Why ZOB exists

Normal coding-agent sessions can be impressive and still fail in predictable ways:

• The agent drifts from the task or expands scope.
• Research, planning, implementation, and review blur together.
• Delegated work comes back without enough evidence.
• Generated artifacts mix with source files.
• Safety rules live in prose instead of enforceable gates.
• “Done” is claimed before commands, diffs, and blockers are visible.

ZOB adds an operating layer around Pi so each step has a job, a boundary, and an audit trail.

What you get

1. Contract-first delegation

Every delegated task can be expressed as a six-part contract:

1. TASK: [atomic goal]
2. EXPECTED OUTCOME: [observable deliverable/verdict]
3. REQUIRED TOOLS: [allowed tools only]
4. MUST DO: [positive constraints]
5. MUST NOT DO: [hard stops]
6. CONTEXT: [paths, prior evidence, downstream use]

This keeps child work bounded and makes review easier: what changed, what was verified, what remains risky, and what should stop shipment.

2. Mode-aware engineering loops

ZOB separates the work into explicit modes:

• Explore — inspect and map facts without editing.
• Plan — turn evidence into a bounded implementation path.
• Implement — change the smallest safe file set and verify it.
• Oracle — review skeptically and surface no-ship blockers.
• Factory — convert repeatable workflows into manifests, checkpoints, sentinels, and smoke gates.
• Orchestrator — coordinate goals, TODO graphs, and specialist handoffs without bypassing safety.

For non-trivial work, the default loop is:

Explore -> Plan -> Implement -> Oracle

3. Specialist agents and domain skills

The repo includes reusable operating assets for focused work:

• .pi/agents/ — specialist roles for exploration, planning, implementation, QA, oracle review, synthesis, ProjectDNA, and more.
• .pi/skills/ — domain instructions for commits, coms, factories, sandboxing, ProjectDNA, autonomy checks, goal/TODO trees, oracle review, and harness routing.
• .pi/output-contracts/ — structured completion contracts for child results and other governed outputs.
• .pi/capabilities/ — runtime capability registry that maps public tools/commands to modes, skills, docs, and no-ship notes.

The goal is not to make prompts longer. The goal is to route the right instructions only when a task needs them.

4. Evidence-gated completion

A ZOB result should make review straightforward. Agents are expected to report:

• exact files changed;
• exact commands run;
• command outcomes;
• evidence references;
• unresolved risks and blockers;
• compliance with forbidden paths, commit policy, and scope.

That evidence posture is built into the project instructions in AGENTS.md, the source map in SOURCE_INDEX.md, and the validation helpers in scripts/README.md.

5. Safety-first local operation

ZOB is deliberately conservative around risky actions:

• no .env, private key, SSH, AWS, or credential reads;
• no destructive shell/git operations without explicit approval;
• no direct commits, pushes, tags, or force pushes by default;
• governed commits go through /zcommit only when explicitly authorized;
• generated reports, ledgers, sessions, and local coordination state stay local;
• autonomy checks are supervised evidence, not a claim of unrestricted autonomy.

The safety posture is backed by .pi/damage-control-rules.json, .pi/git-policy.json, the child-safety extension, and smoke scripts under scripts/.

6. Factories for repeatable work

When a workflow repeats, ZOB can turn it into a factory-shaped process: manifest, checkpoints, sentinels, smoke/pilot/batch gates, artifacts, and oracle review. The repository includes safe scaffolds under .pi/factories/ and validation commands for public, reproducible workflows.

7. Local code knowledge with ProjectDNA

ProjectDNA scaffolding helps turn approved local code scan artifacts into bounded, cited context packs and sample/spec outputs. The public posture is intentionally safe: read-only approved sources, generated artifacts under reports/, and no external knowledge-backend import/sync/embed/write unless explicitly approved.

Quick start

Requirements

• Node.js 22+; Node 24 is recommended.
• npm.
• Pi installed and available on PATH.

Install from npm for normal Pi use

After the package is published to npm, install the pinned Pi package:

pi install npm:zob-harness@0.1.0

Then verify that Pi can load the package extension set and return a deterministic response:

pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"

Expected result:

zob-harness-ok

If pi install cannot find the package, confirm the npm release is visible first:

npm view zob-harness@0.1.0 version

Expected result:

0.1.0

Pi package discovery on pi.dev/packages is based on the npm pi-package keyword and may lag behind npm publication.

Try from a local checkout before publication

Use this path when developing or validating a release candidate before npm publication:

git clone https://github.com/cgarrot/zob-harness.git
cd zob-harness
npm install
npm run check -- --pretty false
npm run pi:check
npm run pack:dry-run

Expected results:

• TypeScript completes with exit code 0 and no diagnostics.
• Pi loads the local configured ZOB extension offline and replies with zob-harness-ok.
• npm pack --dry-run --json lists the Pi manifest, extensions, prompts, skills, agents, and validation scripts in the tarball.

Start Pi with the local harness checkout

npm run pi

Inside Pi, try:

/zmode
/agents
/contract

You should see ZOB modes, specialist agents, and the six-part delegation contract helper.

Public smoke baseline

npm run validate:script-surface
npm run smoke:harness
npm run check -- --pretty false
npm run pack:dry-run

These commands verify the public script surface, core path/child-goal smokes, TypeScript baseline, and npm package surface.

Common workflows

A safe single-agent implementation loop

1. Ask for Explore: inspect files and state a gap verdict.
2. Ask for Plan: name the smallest file set and validation ladder.
3. Ask for Implement: edit only that slice.
4. Ask for Oracle: verify evidence and decide whether no-ship remains.

This keeps implementation from starting before the repo facts and stop conditions are clear.

Delegating work to a specialist

Use /contract to create a bounded handoff, then route to an appropriate specialist agent. A good delegated result should come back with changed files, validation commands, evidence refs, risks, and no-ship status for parent/oracle review.

Goal-linked TODO work

Use /goal, /todo, and /goal_gate when work needs a parent-owned TODO graph. Child agents return claims; the parent decides acceptance. This prevents children from marking parent work done without review.

Governed commits

ZOB does not encourage invisible git operations. When a user explicitly asks for a commit, agents must use /zcommit and follow .pi/git-policy.json. Autocommit and autopush are off by default.

Repeatable factory runs

For recurring tasks, use factory scaffolds rather than ad hoc repetition. Factories should keep manifests, checkpoints, sentinels, generated artifacts, smoke gates, and oracle evidence visible.

Bounded ProjectDNA context

Use ProjectDNA commands and scripts when a task needs cited local code context. Keep scans approved, artifacts local, and writeback proposal-only unless the parent explicitly authorizes more.

Command cheat sheet

Inside Pi:

• /zmode — switch between explore, plan, implement, oracle, factory, and orchestrator.
• /stop — abort current foreground work and local background activity without shutting down Pi.
• /contract — insert the six-part delegation template.
• /agents — list specialist agents.
• /goal, /todo, /todos, /goal_gate — manage goal-linked TODO work and scope anchors.
• /compute or /effort — preview/resolve compute profiles without bypassing safety gates.
• /project-dna — query or operate bounded ProjectDNA context workflows.
• /zcompact — configure proactive context compaction.
• /zcommit — governed commit workflow; no direct git commit/push/tag shortcuts.
• /zpeer — local peer/coms workflow commands where enabled.

From npm/local checkout:

npm run pi                         # start Pi with configured harness wiring
npm run pi:check                   # offline extension load check
npm run check -- --pretty false    # TypeScript validation baseline
npm run check:ci                   # CI-style TypeScript check
npm run validate:script-surface    # package script/file surface validation
npm run smoke:harness              # path-policy + child-goal-ref smoke
npm run smoke:git-ops              # governed commit policy smoke
npm run smoke:worker-pool          # worker-pool static smoke
npm run smoke:zpeer                # static + local ZPeer smoke
npm run validate:project-dna       # ProjectDNA scaffold validation
npm run pack:dry-run               # npm package dry-run surface check

Published package install/check:

pi install npm:zob-harness@0.1.0
pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"
npm view zob-harness@0.1.0 version

See scripts/README.md for the script family map.

Repository map

• README.md — project landing page and quickstart.
• AGENTS.md — project-local agent operating rules.
• CONTRIBUTING.md — contributor workflow and validation expectations.
• SECURITY.md — security policy.
• SOURCE_INDEX.md — tracked source and local/generated area map.
• package.json — package metadata, Pi wiring, and npm scripts.
• scripts/README.md — public script surface guide.
• .pi/extensions/zob-harness/ — main Pi extension.
• .pi/extensions/zob-child-safety/ — child-agent safety extension.
• .pi/agents/ — specialist agent definitions.
• .pi/skills/ — domain-specific operating instructions.
• .pi/prompts/ — reusable prompt templates.
• .pi/factories/ — safe factory scaffolds.
• .pi/output-contracts/ — structured output contract manifests.
• .pi/capabilities/ — public runtime capability registry.
• scripts/ — local validation, smoke, audit, and proof helpers.

Local/generated areas such as reports/, plans/, .pi/sessions/, .pi/logs/, .pi/tmp/, coms ledgers, workspace claims, worker pools, and merge queues are not part of the normal source surface. See SOURCE_INDEX.md for the current classification.

Current status and limits

ZOB Harness is an early, conservative, governed harness. The public repo is useful for evaluating the operating model, extension wiring, skills, agents, safety posture, and smoke validations. It should not be described as unrestricted autonomy, a production deployment system, or a benchmark-winning agent framework.

Current limits are intentional:

• explicit scoped tools, paths, and stop conditions by default;
• human approval for risky writes and commits;
• no global autonomy claim from dry-run or read-only validation;
• no public claims based on private benchmark artifacts;
• generated reports and local runtime ledgers are kept out of source control;
• advanced runtime moves and broad refactors should be split into reviewed slices.

Validation standard for changes

For a normal README/docs or harness-surface change, start with:

npm run validate:script-surface
git diff --check
npm run check -- --pretty false

When relevant, add:

npm run smoke:harness
npm run smoke:git-ops
npm run smoke:worker-pool
npm run validate:project-dna
npm run pack:dry-run

For a public npm release, maintainers should additionally run:

npm whoami
npm view zob-harness@0.1.0 version || true
npm publish --dry-run
npm publish
npm view zob-harness@0.1.0 version
pi install npm:zob-harness@0.1.0
pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"

npm publish may require npm two-factor authentication in the browser or a one-time password. Do not paste OTPs, tokens, or secrets into issue reports or agent transcripts.

Report exact command outcomes before claiming readiness.

Contributing

Contributions should preserve the ZOB operating style:

• small, reversible changes;
• explicit scope and stop conditions;
• no secret access;
• no hidden commits or pushes;
• no unsupported benchmark/autonomy claims;
• validation evidence attached to every readiness claim.

See CONTRIBUTING.md for the contributor workflow.

License

MIT.