# 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.

```sh
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.