Herdforge: Instructions file for Codex

Herdforge Agentic Worker Contract

This contract governs all AI agents (Claude, Codex, Grok, AGY, and OpenCode) participating in the Herdforge software factory fleet.

1. Core Engineering Invariants & Rules

1. Fleet-Only Forging (FAC-113, hard invariant):

   • Herdforge forges itself with its own Herdr fleet (configured vendor harnesses in Herdr tabs, driven by herd dispatch/herd send/herd review). This is the entire point of the repo: the product must be exercised on itself.
   • NEVER use Claude subagents (the Agent tool: general-purpose, Explore, etc.) to build, fix, review, or audit anything in this repo. Using them defeats the dogfooding premise and stops testing the actual system.
   • The coordinator dispatches to the fleet and owns git plumbing (harvest → PR → merge → herd approve). Fleet agents commit in their worktree and report; they never push or merge. When an agent stalls, the fix is a firmer packet / herd kick / the completion self-gate (herd verify), never routing around the fleet.

2. Fail-Closed Execution:

   • All CLI tools and internal package functions must propagate non-zero exit codes on error (os.Exit(1) or non-nil error).
   • HTTP responses carrying {"error": ...} JSON bodies returned under 200 OK must be rejected as hard errors.

3. Mutation & Test Non-Vacuity Discipline:

   • Never write a test that passes vacuously.
   • Any negative assertion guard must be manually or programmatically verified failing against an introduced regression before PR approval.

4. Repo-Relative Path Enforcement:

   • Never output absolute file paths (e.g. /Users/... or /tmp/...) inside configuration files, git hooks, or generated artifacts.
   • Use ./ or runtime environment variables ($HERD_ROOT, $HERD_WORKTREE) to ensure worktree portability.

5. Deterministic Task Selection:

   • When listing candidate tasks from Kaneo, GitHub, Linear, Jira, or Azure DevOps, candidate arrays must be sorted deterministically: $$\text{Sort Order} = (\text{Priority DESC}, \text{Ticket Number ASC})$$
   • Agents must check that role labels match their assigned persona (pulse --role <role>) before claiming work.