AGENTS.md

1# Repository Agent Guidance
2 
3Durable rules only. Perishable lane state — branch, milestone, known flakes,
4closed investigations — lives in the private `codewhale-ops` repo, not here.
5Read it there; don't trust memory of it.
6 
7## Intent is the artifact
8 
9Writing the code again is cheaper than recovering the code we wrote. Act on
10that.
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 
25Limits: `main` stays protected and releases reproducible (never rewrite
26published history, retag a shipped release, or force-push a shared ref);
27contributor credit carries onto the rewrite; the do-not-delete guardrail below
28still binds; and don't rewrite to avoid understanding.
29 
30The four bullets above are the authoritative statement of this rule. Don't
31restate them elsewhere — link here. (`docs/AGENT_ETHOS.md` is about stewardship
32and workflow, not about this; it is not a longer form of this section.)
33 
34## Build and test
35 
36Always before pushing: `cargo fmt`, then targeted tests for the area.
37 
38```sh
39cargo test -p codewhale-config
40cargo test -p codewhale-protocol
41cargo test --workspace                                    # full gate
42cargo build --release -p codewhale-cli -p codewhale-tui   # release build
43```
44 
45Crate-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 
49Default branch is `main`. Committing directly to `main` is fine for release-lane
50work — one reviewable concern per commit, with a real body. A fresh `codex/...`
51branch or worktree is still right for an isolated or risky change.
52 
53Commit as **WIP** unless you actually verified the behavior — built the binary,
54ran the test, reproduced the fix. "Fixed" without evidence is worse than an
55honest WIP.
56 
57## Do-not-delete guardrail
58 
59These are actively imported and have been repeatedly misflagged as dead code;
60deleting them broke the build. Verify consumers with `rg` before believing any
61dead-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
68store in `tui/src/native_memory.rs` is the surviving system; `tools/remember.rs`
69is its capture path and stays.)
70 
71## Surfaces that exist today
72 
73Build only on these — removed machinery stays gone. The model-facing sub-agent
74surface is **`agent` only**: the `agent_open`/`agent_eval`/`agent_close`/
75`delegate_to_agent` variants, capacity/coherence/runtime-tag systems, lifecycle
76tools, and runtime prompt/tag injection were all removed. The constitution
77(`BASE_PROMPT` in `tui/src/prompts/text.rs`) is the sole base prompt.
78Configurable sub-agent depth stays; add a new limit only when clearly needed,
79and explain why.
80 
81## Stewardship
82 
83CodeWhale started as a DeepSeek-only harness; it is now about building the best
84possible coding harness with an open-source community. Keep CodeWhale branding
85and 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 
96Full ethos: `docs/AGENT_ETHOS.md`. Issue-triage standard, release queue, and
97harvest procedure live in the private `codewhale-ops` repo — they are
98maintainer process, not contributor-facing contract.
99