hmbown--codewhale/AGENTS.md

Repository Agent Guidance

Where to work right now (read this first)

• Repo: Hmbown/CodeWhale. This repo lives on multiple devices, so work in whichever local checkout you have — keep paths here device-agnostic and always confirm with git branch --show-current before editing.
• Active branch: start from live truth. Confirm the current fix/integration branch from the latest handoff/objective file and git branch --show-current; recent work has landed on main through small PRs rather than a long-lived codex/... integration branch, so verify a named integration branch still exists before relying on it.
• Workspace version: read it from Cargo.toml ([workspace.package] version); it advances per release lane, so treat that file as the source of truth over any memorized number. Bump versions deliberately, keeping a bump to its own commit.
• Milestone guidepost: use the current release milestone named in the active handoff and list it live, e.g. gh issue list --repo Hmbown/CodeWhale --milestone "<current milestone>" --state open.
• Default branch is main. Committing directly to main is fine for release-lane work — keep each commit to one reviewable concern with a real body. A fresh codex/... branch or worktree is still the right call for an isolated or risky change, opened as a PR when that reads better for review.
• Always run before pushing a change: cargo fmt, then the targeted tests for the area (cargo test -p codewhale-tui --bin codewhale-tui --locked <filter>, cargo test -p codewhale-config, cargo test -p codewhale-protocol, …). Full gate: cargo test --workspace. Release build: cargo build --release -p codewhale-cli -p codewhale-tui.
• Known suite papercuts (pre-existing, not regressions): run_verifiers_background_* is flaky under full-suite parallelism but passes in isolation. Attribute it to the known flake, not to your change. (The old config_command_allow_shell_* failures on machines with default_mode = "yolo" were fixed by pinning the command-test app to Agent mode.)

Continuous agent work conventions

• One concern per commit; write a real commit body. Keep unrelated changes in separate commits.
• Commit as WIP unless you have actually verified the behavior (built the binary, ran the test, reproduced the fix). Stating "fixed" without evidence is worse than an honest WIP.
• Build only on the surfaces that exist today (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. constitution.md is the sole base prompt.
• Configurable sub-agent depth stays. Add a new limit only when it's clearly needed, and explain why.
• Do-not-delete guardrail (salvaged from the 0.8.68 handoff; these were repeatedly misflagged as dead code and deleting them broke the build): tui/src/memory.rs, 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 are all actively imported. Verify consumers with rg before believing any dead-code audit.
• The sub-agent TUI freeze reported in older handoffs is resolved by the v0.8.61 cutover (cap-20, persist-debounce, AgentProgress redraw throttle, ListSubAgents coalescing, input-pump-off-render-thread). The leading "blocking I/O starves the worker pool" theory was measured and disproven (git rev-parse ~10ms, 18-core machine). Treat the freeze as closed and spend effort elsewhere rather than on a speculative spawn_blocking fix.

CodeWhale Stewardship

• Treat community contributors as partners. Good-faith PRs, issue reports, repros, logs, reviews, and verification comments are maintainer evidence, not queue noise.
• Keep gates warm and dry-run unless Hunter explicitly approves enforcement. Gate copy should guide contributors clearly and respectfully.
• Credit every harvested PR, issue report, or comment that materially shaped a fix. Preserve authorship when possible; otherwise use mappable GitHub noreply Co-authored-by trailers from .github/AUTHOR_MAP.
• CodeWhale started as a DeepSeek-only harness; it's now about building the greatest possible coding harness with the help of an open-source community. Keep CodeWhale branding and every model/provider first-class — none privileged. When retiring legacy names like deepseek-tui, keep it clear that every model and provider stays fully supported.
• Review PRs from code, tests, linked issues, comments, and check results — let those, rather than the title or labels alone, drive every merge, close, harvest, or defer decision on community work.
• Respect concurrent work in the tree — leave unrelated edits by other people or agents intact.

Release PR Integration

• Use scratch integration branches when triaging a crowded release queue. A branch such as scratch/vX.Y.Z-pr-train-YYYYMMDD may merge or cherry-pick many PR heads to expose conflicts, missing tests, duplicate work, and hidden coupling quickly.
• Treat scratch branches as evidence, not as the artifact to ship. Land work by harvesting the safe resolved hunks or commits back into the release branch in narrow, reviewable commits — keep tags, releases, and fast-forwards off the scratch train.
• Prefer direct GitHub merge only when the PR is clean against the real landing branch, has acceptable checks, and does not cross trust-boundary surfaces. A PR that is clean against main can still conflict with a release branch; test against the actual release head before calling it merge-ready.
• For already approved PRs, start with a scratch merge against the release branch, then decide between direct merge, cherry-pick with conflict resolution, or credited harvest. Maintainer approval is a priority signal, not permission to skip review or tests.
• When harvesting, preserve or add machine-readable credit: keep the original author where possible, add Co-authored-by using .github/AUTHOR_MAP or GitHub numeric noreply identity, and include Harvested from PR #N by @handle in the commit body so the auto-close workflow can close the PR with credit after it reaches main. Merge a PR whose commit carries that line with rebase or a merge commit so the body survives intact — a squash can rewrite it, drop the Harvested from PR line, and silently lose both the machine-readable credit and the auto-close.
• Keep Co-authored-by trailers to human contributors — scripts/check-coauthor-trailers.py rejects bot/tool ones (Claude, codex, cursor, noreply@anthropic.com) on harvest commits. Also refresh the manual credit surfaces that do not auto-populate from trailers: docs/CONTRIBUTORS.md and CHANGELOG.md.
• Close or update issues and PRs only after verifying the landed commit on the relevant branch. If the release branch already contains equivalent behavior, leave a clear note linking the commit and describing any remaining delta.
• For the active release queue, start from the current GitHub release milestone named in the active handoff (gh issue list --repo Hmbown/CodeWhale --milestone "<current milestone>") and refresh state before acting. Older per-version triage docs under docs/ are historical reference only.

Cursor Cloud specific instructions

Standard build/test/run commands are already documented above and in CONTRIBUTING.md; this section only records the non-obvious cloud-VM caveats.

• System build dep: the build needs libdbus-1-dev (pulled in by crates/secrets for the OS keyring). It is installed by the startup update script; if a cargo build fails with a dbus/pkg-config error, that dep is missing.
• rustup default must be set: some tests and runtime paths spawn shells in temp dirs outside this checkout (e.g. run_verifiers_background_*, sub-agent worktrees). Those spawned shells only see the repo's rust-toolchain.toml override while inside /workspace, so without a global default they fail with "rustup could not choose a version of rustc to run". The update script runs rustup default stable to fix this.
• Known env-specific test failures at /workspace (not code bugs): because the checkout sits directly under /, two codewhale-tui subagent tests fail here — git_repo_root_reports_attempted_paths_when_no_repo_found (cannot create a temp dir in the unwritable parent /) and create_isolated_worktree_reports_friendly_error_when_no_repo_found (walking up to / discovers /workspace itself as a repo). Both pass when the repo is checked out under a normal, writable parent. run_verifiers_background_* is the separate pre-existing flake already noted above. Everything else in cargo test --workspace passes (~6384 tests).
• Running the agent without provider API keys: point CodeWhale at any local OpenAI-compatible endpoint via the keyless vllm/ollama/sglang providers, e.g. CODEWHALE_PROVIDER=vllm VLLM_BASE_URL=http://127.0.0.1:8000/v1 VLLM_MODEL=<id> codewhale exec --auto "...". codewhale exec (add --auto for tool use) is the non-interactive path to exercise the full agent loop.
• Dispatcher needs its sibling: the codewhale binary shells out to a sibling codewhale-tui in the same directory (both land in target/debug after a build). If they are not co-located, set DEEPSEEK_TUI_BIN to the codewhale-tui path.