| 1 | # Repository Agent Guidance |
| 2 | |
| 3 | Durable rules only. Perishable lane state — branch, milestone, known flakes, |
| 4 | closed investigations — lives in `docs/ops/CURRENT.md`; read it, don't trust |
| 5 | memory of it. |
| 6 | |
| 7 | ## Intent is the artifact |
| 8 | |
| 9 | Writing the code again is cheaper than recovering the code we wrote. Act on |
| 10 | that. |
| 11 | |
| 12 | - **Rewriting any part of this project is always in scope**, up to the whole |
| 13 | thing. Nothing is load-bearing by virtue of existing. Argue a rewrite on |
| 14 | merit, not sunk cost. |
| 15 | - **Use git; do not be governed by it.** A branch 600 commits behind is a note |
| 16 | describing something we once wanted, not a debt. Conflict count is a signal to |
| 17 | rewrite, not a task list. |
| 18 | - **A stranded lane becomes an issue, not a merge.** State the intent, the |
| 19 | behavior wanted, and evidence worth keeping; reference the dead branch for |
| 20 | provenance; abandon the branch; rebuild from current `main`. |
| 21 | - **Verify before you rebuild.** Grep for the symbols and behavior — not the |
| 22 | commit — to check whether `main` already does it. Re-landing landed work is |
| 23 | the failure mode this ethos creates, and it is the one you own. |
| 24 | |
| 25 | Limits: `main` stays protected and releases reproducible (never rewrite |
| 26 | published history, retag a shipped release, or force-push a shared ref); |
| 27 | contributor credit carries onto the rewrite; the do-not-delete guardrail below |
| 28 | still binds; and don't rewrite to avoid understanding. |
| 29 | |
| 30 | The four bullets above are the authoritative statement of this rule. Don't |
| 31 | restate them elsewhere — link here. (`docs/AGENT_ETHOS.md` is about stewardship |
| 32 | and workflow, not about this; it is not a longer form of this section.) |
| 33 | |
| 34 | ## Build and test |
| 35 | |
| 36 | Always before pushing: `cargo fmt`, then targeted tests for the area. |
| 37 | |
| 38 | ```sh |
| 39 | cargo test -p codewhale-config |
| 40 | cargo test -p codewhale-protocol |
| 41 | cargo test --workspace # full gate |
| 42 | cargo build --release -p codewhale-cli -p codewhale-tui # release build |
| 43 | ``` |
| 44 | |
| 45 | Crate-specific commands live in that crate's `AGENTS.md`. Environment quirks |
| 46 | (Cursor Cloud, keyless providers, dispatcher siblings) live in |
| 47 | `docs/ENVIRONMENTS.md`. |
| 48 | |
| 49 | Default branch is `main`. Committing directly to `main` is fine for release-lane |
| 50 | work — one reviewable concern per commit, with a real body. A fresh `codex/...` |
| 51 | branch or worktree is still right for an isolated or risky change. |
| 52 | |
| 53 | Commit as **WIP** unless you actually verified the behavior — built the binary, |
| 54 | ran the test, reproduced the fix. "Fixed" without evidence is worse than an |
| 55 | honest WIP. |
| 56 | |
| 57 | ## Do-not-delete guardrail |
| 58 | |
| 59 | These are actively imported and have been repeatedly misflagged as dead code; |
| 60 | deleting them broke the build. Verify consumers with `rg` before believing any |
| 61 | dead-code audit: |
| 62 | |
| 63 | `tui/src/context_budget.rs`, `tui/src/model_registry.rs`, |
| 64 | `tui/src/prompt_zones.rs`, `tui/src/tools/remember.rs`, and the entire |
| 65 | `config/src/route/` directory. |
| 66 | |
| 67 | (`tui/src/memory.rs` was deliberately deleted in v0.9.4 — the native memory |
| 68 | store in `tui/src/native_memory.rs` is the surviving system; `tools/remember.rs` |
| 69 | is its capture path and stays.) |
| 70 | |
| 71 | ## Surfaces that exist today |
| 72 | |
| 73 | Build only on these — removed machinery stays gone. The model-facing sub-agent |
| 74 | surface is **`agent` only**: the `agent_open`/`agent_eval`/`agent_close`/ |
| 75 | `delegate_to_agent` variants, capacity/coherence/runtime-tag systems, lifecycle |
| 76 | tools, and runtime prompt/tag injection were all removed. The constitution |
| 77 | (`BASE_PROMPT` in `tui/src/prompts/text.rs`) is the sole base prompt. |
| 78 | Configurable sub-agent depth stays; add a new limit only when clearly needed, |
| 79 | and explain why. |
| 80 | |
| 81 | ## Stewardship |
| 82 | |
| 83 | CodeWhale started as a DeepSeek-only harness; it is now about building the best |
| 84 | possible coding harness with an open-source community. Keep CodeWhale branding |
| 85 | and every model/provider first-class — none privileged. |
| 86 | |
| 87 | - Community PRs, issues, repros, logs, and reviews are maintainer evidence, not |
| 88 | queue noise. Review from code, tests, linked issues, comments, and checks. |
| 89 | - **Credit is CI-enforced.** `Co-authored-by` trailers are for human |
| 90 | contributors only — `scripts/check-coauthor-trailers.py` rejects bot/tool ones |
| 91 | (Claude, codex, cursor, `noreply@anthropic.com`). Use canonical identities |
| 92 | from `.github/AUTHOR_MAP`; note agent assistance in a plain commit body. |
| 93 | - Keep gates warm and dry-run unless Hunter explicitly approves enforcement. |
| 94 | - Leave unrelated edits by other people or agents intact. |
| 95 | |
| 96 | Full ethos: `docs/AGENT_ETHOS.md`. Issue triage standard: |
| 97 | `docs/AGENT_READY_ISSUES.md`. Release queue and harvest procedure: |
| 98 | `docs/RELEASE_QUEUE.md`. |
| 99 |