hmbown--codewhale/AGENTS.md

Repository Agent Guidance

Durable rules only. Perishable lane state — branch, milestone, known flakes, closed investigations — lives in the private codewhale-ops repo, not here. Read it there; don't trust memory of it.

Intent is the artifact

Writing the code again is cheaper than recovering the code we wrote. Act on that.

• Rewriting any part of this project is always in scope, up to the whole thing. Nothing is load-bearing by virtue of existing. Argue a rewrite on merit, not sunk cost.
• Use git; do not be governed by it. A branch 600 commits behind is a note describing something we once wanted, not a debt. Conflict count is a signal to rewrite, not a task list.
• A stranded lane becomes an issue, not a merge. State the intent, the behavior wanted, and evidence worth keeping; reference the dead branch for provenance; abandon the branch; rebuild from current main.
• Verify before you rebuild. Grep for the symbols and behavior — not the commit — to check whether main already does it. Re-landing landed work is the failure mode this ethos creates, and it is the one you own.

Limits: main stays protected and releases reproducible (never rewrite published history, retag a shipped release, or force-push a shared ref); contributor credit carries onto the rewrite; the do-not-delete guardrail below still binds; and don't rewrite to avoid understanding.

The four bullets above are the authoritative statement of this rule. Don't restate them elsewhere — link here. (docs/AGENT_ETHOS.md is about stewardship and workflow, not about this; it is not a longer form of this section.)

Build and test

Always before pushing: cargo fmt, then targeted tests for the area.

cargo test -p codewhale-config
cargo test -p codewhale-protocol
cargo test --workspace                                    # full gate
cargo build --release -p codewhale-cli -p codewhale-tui   # release build

Crate-specific commands live in that crate's AGENTS.md. Environment quirks (Cursor Cloud, keyless providers, dispatcher siblings) live in docs/ENVIRONMENTS.md.

Default branch is main. Committing directly to main is fine for release-lane work — one reviewable concern per commit, with a real body. A fresh codex/... branch or worktree is still right for an isolated or risky change.

Commit as WIP unless you actually verified the behavior — built the binary, ran the test, reproduced the fix. "Fixed" without evidence is worse than an honest WIP.

Do-not-delete guardrail

These are actively imported and have been repeatedly misflagged as dead code; deleting them broke the build. Verify consumers with rg before believing any dead-code audit:

tui/src/context_budget.rs, tui/src/model_registry.rs, tui/src/prompt_zones.rs, tui/src/tools/remember.rs, and the entire config/src/route/ directory.

(tui/src/memory.rs was deliberately deleted in v0.9.4 — the native memory store in tui/src/native_memory.rs is the surviving system; tools/remember.rs is its capture path and stays.)

Surfaces that exist today

Build only on these — removed machinery stays gone. The model-facing sub-agent surface is agent only: the agent_open/agent_eval/agent_close/ delegate_to_agent variants, capacity/coherence/runtime-tag systems, lifecycle tools, and runtime prompt/tag injection were all removed. The constitution (BASE_PROMPT in tui/src/prompts/text.rs) is the sole base prompt. Configurable sub-agent depth stays; add a new limit only when clearly needed, and explain why.

Stewardship

CodeWhale started as a DeepSeek-only harness; it is now about building the best possible coding harness with an open-source community. Keep CodeWhale branding and every model/provider first-class — none privileged.

• Community PRs, issues, repros, logs, and reviews are maintainer evidence, not queue noise. Review from code, tests, linked issues, comments, and checks.
• Credit is CI-enforced. Co-authored-by trailers are for human contributors only — scripts/check-coauthor-trailers.py rejects bot/tool ones (Claude, codex, cursor, noreply@anthropic.com). Use canonical identities from .github/AUTHOR_MAP; note agent assistance in a plain commit body.
• Keep gates warm and dry-run unless Hunter explicitly approves enforcement.
• Leave unrelated edits by other people or agents intact.

Full ethos: docs/AGENT_ETHOS.md. Issue-triage standard, release queue, and harvest procedure live in the private codewhale-ops repo — they are maintainer process, not contributor-facing contract.