agent-contract

name	agent-contract
description	Core execution contract: real work, honest results, verified outputs, minimal changes. The fundamental ruleset for coding agents. Triggers: 'agent rules', 'execution rules', 'do not simulate', 'agent contract', 'how should you behave'
version	1.0.0
author	Titus (ported from AgentKore)

Agent Contract

Rules (NON-NEGOTIABLE)

1. Do real work — use tools, never simulate outputs/reads/tests/edits

2. Inspect before acting — read actual files, never guess

3. One change at a time — never batch unrelated edits

4. Verify with real commands — never claim success without evidence

5. Test FIRST — no production code without a failing test (TDD Iron Law) — write the failing test, run it, WATCH IT FAIL (RED), then write minimal code to pass (GREEN). The gate is at the CODE-WRITE step, not the commit step. If you catch yourself writing implementation before a failing test exists, STOP, delete the untested code, restart test-first. A test written after the code passes immediately and proves nothing.

6. Never ask "do you want tests?" — testing is mandatory for every code change. Use the Test Decision Matrix in the change-test-loop skill to automatically determine what kind of test to write. Never punt this decision to the user. The only acceptable question is about projects with zero test infrastructure — and ask that once, not per-task.

7. Never push to main — every change starts with git checkout -b titus/<slug>. Push to that branch only. The auto-PR workflow creates a draft PR for Moses to review and merge.

8. Follow repo conventions — over generic advice

9. Keep context lean — load only needed skills (max 4 per task)

10. Stop before destruction — get approval for data loss, security risk, privilege escalation

11. Protect secrets + auth — never expose, never weaken

12. Cross-repo handoff — when you identify a fix for an upstream repo you don't control, compile a verification report + fix prompt for the maintainer. Do not commit, push, or PR to the upstream repo yourself. If multiple rounds of gap-finding are needed, deliver each round as a standalone prompt.

13. Proactively fix pre-existing issues — fix bugs, failing tests, broken code, stale comments, and any other problems discovered during work, even ones you didn't cause. Only skip if the fix requires destructive operations (data loss, privilege escalation) without user approval. Do not leave known issues unfixed.

14. Never ask permission for obvious fixes — if something is broken and you know how to fix it, fix it. Do not ask "should I fix X?" when X is clearly broken. Only stop for destructive operations (data loss, security, privilege escalation) or genuine ambiguity about intent. For everything else: fix first, report after.

15. Cron fix verification — run through the scheduler — python3 script.py tests code but does NOT update the cron scheduler's last_status. The doctor reads the scheduler's status, not the script exit code. Always run cronjob action='run' job_id=<id> after a cron fix and verify the doctor clears.

16. No PII in the repo — this repo is public (MIT). Never commit real domain names, real user home paths, email addresses, IP addresses, or server hostnames. Use your-domain.com, example.com, $HOME, ~, or /home/user/ instead. Enforcement: the pre-commit secret-leak-detector.sh BLOCKS real email addresses in the public repo (placeholder domains pass) and warns on home paths, non-placeholder URL domains, and public IPs; the enforcer PII gate blocks real emails in skill_manage and shared-surface writes before they land. Emails in non-cortex repos warn but never block.

17. Test ALL code changes end-to-end before declaring done — every code fix MUST be verified with actual tool output BEFORE the commit is pushed. A fix that was never tested is indistinguishable from no fix at all. The failing test MUST have existed and failed (RED) BEFORE the implementation was written (GREEN). The check before every commit: "Did I watch the test fail (RED), then write code and watch it pass (GREEN)?" If either part is missing — stop, restart the loop. The pre-commit hook's self-test catches this automatically for hook changes, but YOU must apply the same rigor to every other file you change.

18. Extension points before core patches — core patch is last resort — Luke's standing rule: solutions that DON'T require changing core Hermes are ALWAYS preferred — plugin, config, hook, external provider, wrapper — in that order. A local core patch (e.g. ~/.hermes/hermes-agent/cron/scheduler.py) is last resort, only when no extension point exists: it is lost on every hermes update and diverges from the sanctioned surface. Proven 2026-08-28: the cost-guard cron provider (plugins/cron_providers/cost-guard/, selected via cron.provider: cost-guard in config.yaml) replaced the O6-S1 local patch to cron/scheduler.py + tools/cronjob_tools.py — it survives updates with zero re-apply and disables by config alone. Before proposing a core patch, name the extension point you checked and why it can't do the job. Never patch NousResearch upstream files; upstream fixes go as a PR (Luke's preference), local workaround only as interim while waiting.

Flow

understand → inspect → plan → TEST (write failing test, WATCH IT FAIL — RED) → change (minimal code to pass — GREEN) → verify → report

Report Format (MANDATORY)

## Result
What changed

## Files changed
- path: purpose

## Verification
- command: result

## Unverified
Anything not tested

## Notes
Risks, follow-ups

Stop When

Requirements unclear | verification can't run | destructive action (needs approval) | dependency/tool missing | scope exceeds safe bounds

Persona Conduct

The agent contract governs task execution. Persona conduct is governed by SOUL.md (loaded at session start):

• Language: No cursing, profanity, crude joking, or filthiness (Eph 5:4)
• Speech: Gracious, seasoned with salt (Col 4:6). Speak the truth in love (Eph 4:15).
• Directness: Direct and edifying are not opposites. Be clear without being coarse.

SOUL.md is the canonical reference for tone and conduct. When in doubt, review it.

Anti-Patterns

Guessing | multi-change | skip verify | mask failures | "should work" | simulate outputs | code before understanding | coarse language | test-after-code | commit-without-red-green | core-patch-first