zob-harness

name	zob-harness
description	Use when working inside the ZOB Pi harness, designing agentic workflows, creating specialist prompts, adding Pi extensions, or turning repeated tasks into software factories.

ZOB Harness Skill

When to use

Use this skill for any task involving:

• Pi extensions, prompt templates, skills, or agent definitions.
• Multi-agent delegation workflows.
• Agent Factory design: ZAgents, ZTeams, tmux launchers, kickoff files, visible coms, workgraphs, and oracle gates.
• Safety gates and damage-control policy.
• Software-factory design from repeated manual workflows.
• Runtime tool/command routing via .pi/capabilities/zob-public-runtime-capabilities.json.

For routing behavior, load zob-tool-router before non-trivial or tool-ambiguous work. For compaction/recovery behavior, load zob-compaction-policy before changing compaction hooks or resuming from a compacted long-running goal. For active context discovery/search backend behavior, load zob-context-discovery and prefer zob_context_search when available, with ColGREP as the preferred ready backend at context pivot points and grep/find/read as exact-verification fallback. For domain behavior, load the domain skill named by the registry instead of inlining details here: zob-goal-todo-tree, zob-coms-v2-live, zob-coms-safety, zob-mission-control-coms, zob-autonomous-runtime, zob-factory, zob-sandbox, zob-oracle, or zob-spec as applicable.

Agent Factory posture

Treat ZOB as a governed Agent Factory when the owner wants persistent local agent roles rather than one transient assistant. An Agent Factory may include:

• ZAgent role definitions and prompts;
• ZTeam topology, rooms, aliases, entry agent, and communication policy;
• optional tmux launchers for manual local startup/attach/status/close;
• startup kickoff files passed as pi @kickoff.md, not post-start pane paste as the primary transport;
• run artifacts such as run-manifest.json, workgraph/status/iteration logs, validation reports, and kickoff-dispatch.json;
• oracle/no-ship gates before completion claims.

Communication is a core deliverable. Prefer one parent-visible control room by default; use lanes/tags/artifact sections instead of hidden worker rooms unless the owner explicitly approves a bounded route. The generic teaching example lives in examples/agent-factory-tmux-comms/.

Operating model

1. Classify the task as one of: explore, plan, implement, oracle, factory, orchestrator. When .pi/routing/intent-classifier.json enables an optional model classifier, treat it as advisory intent routing only; regex fallback and deterministic safety hard-blocks remain authoritative. autoSwitchIntents controls which detected intents switch mode directly; this project enables all ZOB modes by default. Use /intent-classifier status|regex|model-strict|model-fallback|test (alias /intent) to switch/test routing without editing JSON by hand.
2. For non-trivial or tool-ambiguous work, apply zob-tool-router: classify applicable families, then use/delegate/skip each with a reason.
3. Use orchestrator when the task needs Chief Vision coordination, multi-agent decomposition, Lead/Worker routing, goal/TODO graph governance, or parent-owned dispatch; the root should delegate substantive work rather than do it directly.
4. Check .pi/capabilities/zob-public-runtime-capabilities.json for the relevant tool/command family, mode allowlist, skill refs, and no-ship notes. For exploratory/natural-language context tasks, start with the active backend via zob_context_search; use ColGREP when ready before broad grep/find, and reuse it at context pivot points (new subsystem/domain, ambiguous file area, fallback_status suggesting narrower paths, repeated low-signal grep/find, unfamiliar code before edits, or unknown validation/test failure). If zob_context_search is not exposed but bash is available, run npm run --silent zob:context:query -- --query "<query>" --max-results 6 --max-context-lines 1 before rg/grep. Use grep/find/read for fallback plus exact verification and when exact identifiers/paths are already known. Never broad-grep .pi without pruning .pi/sessions and .pi/agent-sessions.
5. If broad or risky, use the delegate_agent tool before editing.
6. For delegated work, use the six-part contract:
   • TASK
   • EXPECTED OUTCOME
   • REQUIRED TOOLS
   • MUST DO
   • MUST NOT DO
   • CONTEXT
7. For parallel owner micro-worker pools, split broad TODOs into owned leaves before dispatch; use zob_worker_pool_plan/zob_worker_pool_status only to create/read metadata-only owned/write/read-across coordination records, then dispatch actual children parent-owned through delegate_task/delegate_agent with explicit TODO linkage and repo-relative owned/write grants. zob_worker_pool_owner_request/zob_worker_pool_owner_decision record body-free Goal Room owner arbitration only; they never apply changes, mutate TODOs, or dispatch children.
8. Use Goal Room as the canonical parent-visible coordination record; ZPeer is transient/local and cannot replace typed decisions, evidence, or owner arbitration.
9. For code changes, verify with the smallest relevant command first.
10. End with evidence and a compliance line.

Planning in auto-mode

When the user asks for a plan:

• Produce exactly one plan for the request.
• If you already produce the plan in the current response, do not emit a mode="plan" intent.
• Emit a mode="plan" intent only when deliberately deferring the actual detailed plan to the next turn; keep that response to a short handoff.
• Never both: full plan content and mode="plan" intent in the same response.
• If a prior assistant response already contained a complete plan for the same request, do not restate it; summarize that the plan exists and ask whether to refine, save, or implement it.
• The harness may auto-capture complete plans into plans/; do not manually duplicate that artifact unless the user asks.
• Complete implementation plans should end with exactly one ZOB_PLAN_TODOS fenced JSON block (schema: "zob.plan-todos.v1", objective, todos, key, title, optional done_when/checks/children). This makes the saved plan launchable by sidecar instead of forcing a future LLM to recreate TODOs from prose.
• If a legacy or malformed captured plan lacks that block, the harness uses deterministic Markdown list fallback when possible and records todo_manifest_source=markdown_fallback; fallback is recovery, not the preferred contract.
• When the user says to go/run/do a saved plan, inspect/launch with zob_plan_launch or /plan launch and use the .todos.json sidecar as canonical. Do not restate or recreate the TODO tree from the human Markdown unless launch reports needs_manifest/invalid_manifest and the user asks for repair. If a non-complete runtime goal already exists, the plan launcher defaults to safe auto-attach; use active_goal_strategy=block or /plan launch ... --block-active-goal only when strict blocking is intentionally required.

Project files

• Extension: .pi/extensions/zob-harness/index.ts
• Agents: .pi/agents/*.md
• Prompt templates: .pi/prompts/*.md
• Capability registry: .pi/capabilities/zob-public-runtime-capabilities.json
• Damage rules: .pi/damage-control-rules.json
• Optional intent classifier config: .pi/routing/intent-classifier.json
• Architecture docs: docs/
• Goal TODO tree plan: docs/ZOB_GOAL_TODO_TREE_PLAN.md

Safety reminders

• Never read .env or secrets. Ask the user instead.
• Never run destructive git/shell commands without explicit approval.
• Do not commit unless explicitly requested.
• Delegation/orchestration allowed_paths are repo-relative-only grants; do not use absolute/home/traversal/broad-root paths. Represent external context through repo-local reports/... snapshots or context_ref artifacts. forbidden_paths stay deny-only and may use specific absolute/home patterns when safe.
• Stop-on-blocker: when a human-decision blocker is already visible on a paused goal (score >=90, no nextAgent), report once and wait for /goal resume or resume_goal; do not repeat the ask, redispatch, auto-resume, or bypass oracle/no_ship/evidence gates.
• Parallel owner pools are supervised: worker-pool tools are metadata/coordination only; actual worker launch remains parent-owned through delegation tools. No child-spawns-child, no child parent-TODO mutation, no direct main-workspace apply/merge, no stale/offline delivery success, and no completion without validation/oracle evidence when required.

Bash timeouts

Every bash call MUST set a timeout scaled to the action (small reads/greps: ~5-30 s; repo-wide greps/finds: ~60 s; npm/build/install: ~300 s). On timeout, first narrow the command (scope, glob, depth); only retry with a larger timeout when the narrow form is correct but genuinely slow, and stay reasonable — never set timeout: 0.