AGENTS.md · codewhale-hq/Codewhale

Sections

1. The ponytail method
2. Working rules
3. Landing other people's work
4. Merging under a gate
5. Claiming a test passed
6. Current contracts
7. Code, migrations, and evidence

First lines (shown under the repo's MIT license)

# Codewhale agent guidance

Keep this file durable. Derive changing release, provider, branch, and flake
state from the repository, tests, CI, and current issue tracker rather than from
instructions or memory. The nearest scoped `AGENTS.md` adds path-specific rules.

## The ponytail method

From [dietrichgebert/ponytail](https://github.com/dietrichgebert/ponytail) —
"the laziest senior dev in the room." *He says nothing. He writes one line. It
works.* The best code is the code you never wrote.

Before writing code, walk the decision ladder in order and stop at the first
rung that answers:

1. **Does this need to exist?** → Skip it.
2. **Already in this codebase?** → Reuse it.
3. **Stdlib does it?** → Use it.
4. **Native platform feature?** → Use it.
5. **Installed dependency?** → Use it.
6. **One line?** → One line.
7. **Only then:** the minimum that works.

The ladder runs *after* understanding the problem. Lazy about solutions, never
about reading the code first — a short diff written without reading the call
sites is not ponytail, it is a guess.

**Never cut, at any rung:** trust-boundary validation, data-loss handling,
security, accessibility. Brevity is not a reason to drop a guard.

Rung 2 is the one this repository keeps failing. The `model_*` / `*_config` /
`provider_*` grep rule below is rung 2 with a name; so is "one turn loop, one
base prompt". Two more corollaries earned here:

- **An abstraction must delete caller code.** If adopting it is pure
  obligation — required methods, no default bodies that do work — it gets
  built, adopted once, and abandoned.
- **Migrate the last consumer, or do not start.** Framework, one caller,
  ticket the rest, silence the warning: that ships two systems and a comment
  that is no longer true. If the migration will not fit, narrow the slice —
  never the adoption. The standing `#[allow(dead_code)]` count is the running
  receipt; `scripts/check-dead-code-budget.py` prints it.

## Working rules

- Inspect status and existing consumers before editing. Preserve unrelated,
  dirty, and untracked work.
- Before adding a module named `model_*`, `*_config`, `provider_*`, or
  anything that "bridges", "mirrors", or "stages" an existing thing, grep
  for the existing thing and edit it. A new layer must name the predecessor
  it replaces in its commit message; otherwise edit the original.
- Prefer the simplest implementation that preserves observable contracts. A
  rewrite is acceptable when justified by product intent and observed behavior,
  not as a shortcut around understanding existing code.
- Search for behavior and symbols before reviving work from an old branch. If a
  lane is obsolete, preserve its intent and evidence rather than merging stale
  code mechanically.
- Agent-owned work uses the canonical checkout on current `main`. Do not
  create branches, worktrees, nested clones or task-specific integration lanes
  to handle dirty, stale or conflicting work. When agents share the checkout,
  partition by file and retry an `index.lock` failure. Verified main slices may
  be committed and pushed normally under the rule below; tag, release,
  deployment and destructive cleanup still require their explicit
  authorization.
- **Uncommitted work found in the checkout is the agent's own** (founder,
  2026-10-22). Read it, work out what it was for, prove it with the smallest
  check that covers it, fix what is broken, and commit it in coherent groups
  by explicit path. Do not route around another writer's files or leave them
  dirty. Ownership is not a blind sweep:
  - A file changed in the last 15 minutes, or one a live session or agent is
    editing, is mid-edit: ask that writer to commit now, and commit what
    remains once it goes quiet. Never commit a half-written edit.
  - Never commit secrets, credentials, `.env` files, build output or caches;
    add them to `.gitignore` instead.
  - Check a repository's visibility before pushing. Inference business and
    infrastructure detail stays out of public repositories.
  - Commit by explicit path; never `git add -A`.
  - Work that fails its check and cannot be fixed now is not pushed to `main`.
    Record it and report it instead.
- **Maintainers do not open PR branches** (founder, 2026-10-08: more PRs means
  more CI and slower work). Verified slices land directly on `main` and are
  pushed: run the focused gate, put the real counts in the commit message,
  fetch and rebase onto `origin/main` and retry on rejection. Never force-push
  or rewrite a shared ref. Contributor PRs still merge as PRs.
- When the task is local-only, stay fully offline: no browsing, GitHub or remote
  Git operations, downloads, dependency installation, provider calls, or
  source/diff transmission. Record the missing external receipt and keep working
  locally.
- Public name is **Codewhale**. Compatibility identifiers such as `CodeWhale`,
  `codew`, protocol names, and storage keys change only through an explicit
  migration.
- Keep providers and models first-class and provider-neutral.
- Never rewrite published history, retag a release, force-push a shared ref, or
  publish without explicit authorization. Preserve human contributor credit.
- **Model-visible means logged.** Anything that reaches a model request must be
  reconstructable from the session log, and a new model-visible input needs a
  session event. Live presentation and the persisted record must agree; when they
  disagree the record is right.
- **Misconfiguration fails loud**, at load when it is self-contained, otherwise
  at the earliest point it can be resolved. Never silently skip a missing
  referent.
- **Write down what a design does not do**, beside the behaviour it owns — a
  short known-limitations note in the owning module. A stated limit stops the
  next reader from assuming a capability that was never built.
- **Substantive contributor replies are authorized for the 0.10.2 release**
  (founder, 2026-10-13). Thank people specifically for their reports, diagnosis,
  fixes and testing; link the carrying commit or PR and distinguish candidate
  work from a shipped release. Status, answers and useful questions are welcome;
  repetitive progress posts and bot noise are not. Evidence stays in commits
  and PR bodies; ownership stays in Linear. Outside this release, the previous
  no-comment rule remains, except a one-sentence reason when closing or
  superseding a human contribution. Review workflows remain disabled unless
  the founder separately authorizes enabling them.
- **A user feature lands with its registry row.** A new command, `[features]`
  flag, provider or user-visible feature adds or updates its row in
  `docs/features.toml` in the same change;
  `cargo test -p codewhale-tui --test feature_registry` fails on flag drift.
- **Write `close`/`fix`/`resolve #N` only when you mean it.** GitHub closes the
  issue on merge even inside "does not close #N"; use `Refs #N` otherwise.

## Landing other people's work

An external contributor's branch goes stale because *we* land things, not
because they did anything wrong. Treat their time as more expensive than ours.

**The goal is the contributor's PR merging as itself.** Review it, help it
rebase, or fix it on their branch — that is the default path. Closing their PR
and re-landing the work as our own commit (`auto-close-harvested`) is the
fallback for a branch that truly cannot merge in reasonable time; done
casually it reads as taking the work even when credit is preserved.

- **Never make a contributor rebase around our churn.** If their PR conflicts
  only because main moved, a maintainer resolves it.
- Landing mechanics — merge-base diffing, mid-function conflicts, fork-push
  refusal, the contribution gate — live in `cw-land`. Follow them instead of
  improvising.
- **Preserve credit in the mechanical sense, not just the polite one.** Commit
  authorship and `Co-authored-by` trailers must use the contributor's own
  GitHub-linked address. `AUTHOR_MAP` and `.mailmap` are project conventions —
  GitHub reads neither for the contribution graph.

## Merging under a gate

- **A gate is its artifact.** When a rail says a PR merges only on a passing
  acceptance record, the record must literally say PASS at merge time. "I
  re-ran it and the failures are rows this PR does not own" is a judgement to
  write into the artifact first, not a reason to merge past it.
- **Read the review thread, not the check rollup.** Green checks and an unread
  review with confirmed findings are a merge that ships known bugs.
- **When the artifact is ambiguous, resolve the ambiguity — never the merge.**

## Claiming a test passed

- Quote the real `test result: N passed; M failed` line, and confirm `N > 0`
  for the tests that cover the change. `cargo test <filter>` exits 0 having run
  zero tests when the filter matches nothing, and an exit code alone has
  already been mistaken for a pass here.
- Prefer proving a regression test fails without the fix. A test that passes
  either way pins the implementation, not the defect.
- Audit any hand-rolled scorer before trusting its score: quote the counts it