elephant.ai AGENTS.md

elephant.ai — Agent Contract

Minimize mandatory reading. Expand context only when triggered.

0. Read Policy

1. Read §1 on every task.
2. Read §2 only when a trigger matches.
3. No trigger? Follow §3 and stop expanding context.

---

1. Mandatory Core

1.1 Identity and priority

• Greet ckl at conversation start.
• Priority: safety > correctness > maintainability > speed.
• User: senior backend/database engineer; values deep reasoning, clean architecture.

1.2 Code style (non-negotiable)

• Max function body: 15 lines. Extract or redesign if exceeded.
• No comments that restate code. Only "why" comments for non-obvious decisions.
• Prefer composition over inheritance. Prefer data transforms over mutation.
• Every abstraction must justify itself: if used <2 places, inline it.
• Delete dead code immediately. No TODOs in committed code.
• Type signatures are documentation. Verbose names > comments.
• Between two correct approaches, pick the one with fewer moving parts.
• Trust type/caller invariants; no unnecessary defensive code.
• No compatibility shims when requirements change; redesign cleanly.
• Modify only relevant files.
• Config examples must be YAML.

Reference density:

const authenticate = (token: string, secret: string): Result<Claims, AuthError> =>
  pipe(
    decode(token),
    chain(verify(secret)),
    mapErr(toAuthError)
  );

No wrapper classes. No builders. No config objects. Transform pipeline.

1.3 Branch safety

• Use worktree for code changes; never edit directly on main.
• On main, run before any edit:
  1. git diff --stat + git log --oneline -10
  2. If suspicious diffs: report to ckl before continuing.

1.4 Delivery

• Prefer TDD for logic changes; cover edge cases.
• Run lint + tests before delivery.
• Code review before commit: python3 skills/code-review/run.py review.
• Fix P0/P1 before commit; follow-up for P2.
• Small, scoped commits. Warn before destructive ops.

---

2. Progressive Disclosure (trigger-gated)