Forge for Agents

Operating contract for AI agents using the forge subsystem.

When to use forge

Use forge when you need a new native skill and:

  • The skill's requirements can be expressed as a text brief.
  • The topology is within forge's design envelope (up to ~30 nodes).
  • You want the skill to inherit harness verification and checkpointing.

Do NOT use forge when:

  • You are building a harness-internal or meta skill (use hand-authoring instead).
  • The skill requires custom harness modifications.
  • The topology exceeds forge's complexity ceiling.

Operating rules

  1. Write a clear brief. Forge's output quality is proportional to brief quality. Include: what the skill does, trigger conditions, input/output contract, topology hints, constraints, and acceptance criteria.
  2. Choose the right profile. Use power for production skills, standard for general use, minimal for prototypes.
  3. Verify the output. After forge emits, run:
  4. Hand-correct if needed. Forge's topology design is good but not perfect. Review the emitted graph.json and modules for correctness. Topology corrections are expected, especially for complex skills.
  5. Do not re-forge when you can correct. If forge emitted 90% of a correct skill, fix the 10% by hand rather than re-running forge with a different brief.
  6. Test with real inputs. Smoke tests validate structure; real invocations validate behavior.
bash 
1
2
goatcs-harness verify <skill>/graph.json
goatcs-harness wiring-check <skill>/ --contract wiring-contract.yaml

The non-clobber re-forge path

If you need to re-forge a skill that has been hand-corrected:

python 
1
2
from goatcs_harness.tools import reconcile_forge
reconcile_forge(skill_dir="./my-skill/", new_brief="...")

This preserves hand-authored corrections while integrating new forge output.