| 1 | # TUI agent guidance |
| 2 | |
| 3 | Scope: the terminal UI, its embedded runtime engine, and user-visible behavior. |
| 4 | Read the repository guidance first. |
| 5 | |
| 6 | ## UI contracts |
| 7 | |
| 8 | - One owner per fact: mode, permission and live counts in the posture bar |
| 9 | (`phase_strip.rs`, row 1 under the composer); model, context and the |
| 10 | session metrics — cost, ttft, tok/s, output tokens — in the metrics line |
| 11 | (`infoline.rs`, row 2); the roster and to-do in the work surface; receipts, |
| 12 | the active row and the phase in the transcript. Key hints come from the |
| 13 | `shell_key_routing` binding table, never from a string literal. |
| 14 | - Status-bar ink goes through `codewhale_palette::grammar` (`docs/design/STATUS_BAR_COLOR_GRAMMAR.md`). |
| 15 | Do not invent an eighth semantic or spend Failure red on non-failure chrome. |
| 16 | - Derive state from typed enums such as `ShellPhase` and `OceanTreatment`. |
| 17 | Renderers must not infer state from English strings or invent lifecycle state. |
| 18 | - Keep settled output still. Motion is semantic, bounded, and fully disabled by |
| 19 | reduced-motion settings. |
| 20 | - Route notices through the toast system, with typed level and lifetime; do not |
| 21 | add new writes to the legacy `status_message` sink. |
| 22 | - Compact layouts remove chrome before content. Selectable rows need recorded |
| 23 | hitboxes, visible focus, keyboard/mouse parity, and confirmation for |
| 24 | destructive actions. |
| 25 | - User-visible prose uses `tr(locale, MessageId::...)`. Commands, key names, and |
| 26 | glyphs are composed in code. Follow `locales/AGENTS.md` for string changes. |
| 27 | |
| 28 | ## Verification |
| 29 | |
| 30 | Select the smallest evidence that answers the actual risk. Direct PTY or |
| 31 | terminal behavior is stronger evidence for visible UX than an assertion over |
| 32 | render internals. Use a focused existing test for safety, data integrity, |
| 33 | protocol, or a reproduced regression when useful. Do not add tests by default, |
| 34 | and do not require both full suites or workspace Clippy for an unrelated leaf |
| 35 | change. These are available release/cross-cutting gates, not per-edit ritual: |
| 36 | |
| 37 | ```sh |
| 38 | cargo test -p codewhale-tui --lib --locked |
| 39 | cargo test -p codewhale-tui --tests --locked |
| 40 | cargo clippy --workspace --all-targets --locked -- -D warnings |
| 41 | ``` |
| 42 | |
| 43 | `--lib` and `--tests` are disjoint; choose the target that owns the behavior. |
| 44 | Use both or the workspace gate only when the risk genuinely spans both. |
| 45 | `scripts/dev-test.sh <area|path> [filter]` prints and runs the fastest |
| 46 | targeted invocation for a source path (for example |
| 47 | `scripts/dev-test.sh crates/tui/src/elapsed.rs`). It uses `cargo nextest |
| 48 | run` when nextest is installed (`CODEWHALE_DEV_NEXTEST=0` forces libtest) |
| 49 | and applies `scripts/dev-cache.sh` so a new worktree gets an isolated |
| 50 | Cargo build-dir. For PTY |
| 51 | failures, reproduce the behavior directly before changing it. Script one input |
| 52 | at a time and capture after the UI settles. Choose the terminal sizes relevant |
| 53 | to the change from 40x12, 60x16, 80x24, 100x32, and 140x40; judge motion from |
| 54 | repeated frames, not a single screenshot. Remove inherited `NO_COLOR`, |
| 55 | `TERM=dumb`, and tmux motion overrides when they would invalidate the |
| 56 | observation. |
| 57 |