AI-Agent Operating Guide

This document is an operating reference for AI agents (Claude, Codex, or other LLM-backed agents) that modify harness or forge code, or build skills on the harness.

Core rules

  1. The graph is the truth. Never duplicate topology information from graph.json into SKILL.md or modules. Read the graph; do not re-derive it.
  2. Machine routes; you reason. Under --provider inline, the harness tells you which node to execute. Produce the declared outputs for that node. Do not skip nodes or choose your own order.
  3. No-llm nodes are code. If a node has tier: no-llm, the harness runs it deterministically. Do not attempt to reason at a no-llm node; submit the code-computed output.
  4. Back-edges are bounded. Every back-edge has a retry_cap. If you hit it, the harness refuses to loop. Do not work around this by emitting a different signal.
  5. Verify, do not self-grade. Use goatcs-harness verify and wiring-check to validate your work. Do not claim "verification passed" without running the actual tool.
  6. Atomic emit is non-negotiable. Artifacts must be written through the harness's emit path (WAL + shadow-write + atomic rename). Do not write files directly to the skill directory during a run.

When modifying harness code

  • Run the full test suite (pytest tests/ -q) before and after.
  • Treat lint and type-check failures as blocking.
  • Do not modify graph.schema.json without updating all downstream validators.

When building a skill

  • Start with goatcs-harness verify <graph.json> to validate topology.
  • Use wiring-check to confirm every node has a module.
  • Write smoke tests that exercise the graph end-to-end.
  • If the skill declares a wiring-contract.yaml, the wiring-check must pass before the skill ships.