SKILL.md - CodeWhale

SKILL.md

1	---
2	name: cw-dogfood
3	description: "Use when a Codewhale change needs proving in the real product, or when asked to build/install/dogfood the local binaries: stamped release build, atomic install, fresh-shell verification, and the manual QA that gates cannot cover."
4	---
5
6	# cw-dogfood
7
8	Green gates prove the code compiles and asserts. They do not prove the product
9	works. Freezes, route contamination, focus theft, streaming cadence, and
10	approval-flow regressions all live in the runtime, where no unit test looks.
11	This stage puts the actual binary on your PATH and makes you use it.
12
13	Stage 4 of the loop: [cw-orient](../cw-orient/SKILL.md) →
14	[cw-slice](../cw-slice/SKILL.md) → [cw-gates](../cw-gates/SKILL.md) →
15	dogfood → [cw-land](../cw-land/SKILL.md) → [cw-handoff](../cw-handoff/SKILL.md).
16
17	## When to use
18
19	- The change is user-visible: TUI layout, motion, streaming, model or Fleet
20	selection, approvals, commands, install paths.
21	- Before landing a release candidate, or before claiming a runtime behavior is
22	fixed.
23	- Hunter asks to "install the build", "dogfood this", or "get this on my machine".
24
25	## Workflow
26
27	1. Gate first. Run [cw-gates](../cw-gates/SKILL.md) to the rung the change
28	deserves. Never install an ungated build.
29
30	2. Build stamped. Local builds are unstamped (`(dev)`) since #5245, and the
31	installer refuses an unstamped binary on purpose — the stamp is what proves
32	the thing on your PATH is the thing you just built:
33	```bash
34	CODEWHALE_BUILD_SHA=$(git rev-parse HEAD) \
35	cargo build --release --locked -p codewhale-cli -p codewhale-tui
36	```
37
38	3. Install atomically. Use the script; do not hand-copy:
39	```bash
40	scripts/release/install-dogfood.sh # defaults to target/release
41	```
42	It refuses a dirty source tree (override deliberately with
43	`CODEWHALE_ALLOW_DIRTY_DOGFOOD=1`, and then say so wherever you report the
44	install), verifies the binary embeds current HEAD, installs `codewhale` and
45	`codew` into `~/.cargo/bin` and `~/.local/bin` (override with
46	`CODEWHALE_INSTALL_DIRS`), re-signs ad-hoc on macOS, and verifies resolution
47	from a fresh login shell.
48
49	Never `cp` over a running binary. On Apple Silicon that poisons the
50	kernel's code-signature cache for the inode, and later execs hang until
51	reboot. The installer does tmp-copy plus atomic `mv` for exactly this reason.
52
53	4. Verify from a fresh shell, not this one. A correct `target/release`
54	binary and a stale `codew` on PATH is the classic false pass:
55	```bash
56	zsh -lc 'type -a codew codewhale; codew --version'
57	```
58	The version string must contain the short HEAD SHA you just built.
59
60	5. Use the product. Run it in a real terminal and exercise what you changed.
61	`crates/tui/AGENTS.md` is the authority on what to look at; pick the terminal
62	sizes relevant to the change from `40x12`, `60x16`, `80x24`, `100x32`,
63	`140x40`. Judge motion from repeated frames, never a single screenshot, and
64	check it against `docs/MOTION_CONTRACT.md`. Remove inherited `NO_COLOR`,
65	`TERM=dumb`, and tmux motion overrides when they would invalidate what you
66	are looking at.
67
68	Scenarios worth exercising when they are in scope:
69	- Liveness under fanout — spawn several workers; typing, render, cancel,
70	and the roster stay live throughout, and Esc cancels mid-fanout.
71	- Route isolation — multiple terminals on distinct provider/model routes,
72	zero cross-terminal contamination, no provider+model mismatch.
73	- Running-turn input — during a busy turn, Enter queues a follow-up, an
74	empty Enter promotes the oldest, Ctrl+Enter steers, Shift+Enter newlines.
75	- Approvals — ordinary tool approval vs. repository-law approval; the
76	screen must name the repository constitution where it applies, and
77	decorative motion must go still when the user owns the next action.
78	- Empty, narrow, and first-run states — compact layouts remove chrome
79	before content.
80
81	6. Headless surfaces, when the change touches them. `codewhale exec` is the
82	one-shot worker path; `codewhale app-server` is the local control/API surface.
83	They must agree about routing, permissions, and event states — a disagreement
84	is a runtime bug, not a QA note.
85	```bash
86	scripts/release/app-server-smoke.sh
87	codewhale exec --auto --output-format stream-json --model <model> "Reply PONG"
88	```
89	Provider calls spend tokens. Ask before running the paid ones.
90
91	7. Record what you saw. Dimensions, inputs, visible state, side effects. A
92	screenshot proves layout and color; only live observation or a recording
93	proves motion and continuity.
94
95	## Red flags / don't
96
97	- Don't `cp` a binary over a running one. Use `install-dogfood.sh`.
98	- Don't verify in the shell that already has the old binary resolved.
99	- Don't claim animation or cadence quality from a still image.
100	- Don't substitute a full-screen assertion harness for looking at and using the
101	product.
102	- Don't install from a dirty tree without saying so in the report — the version
103	stamp will not show the dirt.
104	- Don't delete `target/dogfood/*` bundles if the lane keeps them: they are
105	release evidence.
106	- Don't spend provider tokens on smoke runs without approval.
107
108	## Output
109
110	- The exact build command, including the `CODEWHALE_BUILD_SHA` stamp.
111	- The installer's destinations and its fresh-shell verification result.
112	- `codew --version` from a fresh login shell, with the SHA visible.
113	- Per scenario: terminal size, what you did, what you observed — and which
114	scenarios you did not exercise.
115

115 lines MARKDOWN