SKILL.md - CodeWhale

SKILL.md

1	---
2	name: contributor-onboarding
3	description: Help a new contributor get productive on this checkout - inspect sync state against main, build, run the repository's exact verification gate, and produce a local what's-new digest. Never fetches, pulls, or modifies a dirty tree on its own. Explicit-only.
4	invocation: explicit-only
5	---
6
7	# Contributor Onboarding
8
9	Requested by @JayBeest in issue #4227: a first-run path for a contributor who
10	has cloned the repo and wants to know *am I current, does it build, does it
11	pass, and what changed while I was away* — without a wall of prose and without
12	anything touching their working tree behind their back.
13
14	## Invocation
15
16	Explicit-only. Loading this skill is not authority to fetch, pull, rebase,
17	push, or write files. Every network or mutating step below is a separate action
18	the contributor must ask for after reading the plan.
19
20	## Non-goals
21
22	- Do not run `git fetch`, `git pull`, `git rebase`, or `git checkout` on your
23	own initiative. Report state; propose the command; wait.
24	- Do not stash, discard, reset, or commit a dirty tree. Ever.
25	- Do not call a model provider. Every step here is a local command with a
26	deterministic result. The digest is built from files and git output, not
27	generated prose.
28	- Do not claim a gate passed that you did not run, and do not summarize a
29	build you did not observe.
30	- Do not privilege any provider. Codewhale is provider-neutral; a dogfood run
31	uses whatever route the contributor already configured, or none.
32
33	## Workflow
34
35	### 1. Inspect (read-only, always safe)
36
37	Run these and report the results verbatim. Nothing here writes:
38
39	```
40	git rev-parse --abbrev-ref HEAD
41	git status --porcelain
42	git rev-list --left-right --count origin/main...HEAD
43	```
44
45	Report three facts plainly:
46
47	- Branch the contributor is on.
48	- Tree state: clean, or the count and paths of dirty entries.
49	- Sync state: `N behind, M ahead` of `origin/main`, or unavailable when
50	`origin/main` is missing or has never been fetched. Unavailable is a real
51	answer — say it rather than guessing zero.
52
53	### 2. Sync — propose, never perform
54
55	If behind, print the exact commands and stop:
56
57	```
58	git fetch origin
59	git rebase origin/main # or: git merge origin/main
60	```
61
62	If the tree is dirty, do not propose a sync at all. Print a recovery plan
63	first, in this order, and let the contributor choose:
64
65	1. `git stash push -u -m "wip before sync"` then sync, then `git stash pop`
66	2. Commit the work on a branch, then sync
67	3. Stay behind and continue — being behind is not an error
68
69	### 3. Build
70
71	```
72	cargo build --release -p codewhale-cli -p codewhale-tui
73	```
74
75	Report the exit status and the first error if it fails. A build failure ends
76	the run: do not proceed to the gate and do not report gate results.
77
78	### 4. Verification gate — the repository's exact CI command
79
80	Run what CI runs, not a paraphrase of it:
81
82	```
83	cargo fmt --all -- --check
84	cargo clippy --workspace --all-features --locked -- \
85	-D warnings \
86	-A clippy::uninlined_format_args \
87	-A clippy::too_many_arguments \
88	-A clippy::unnecessary_map_or \
89	-A clippy::collapsible_if \
90	-A clippy::assertions_on_constants
91	cargo test --workspace
92	```
93
94	These are copied from `.github/workflows/ci.yml`. If that file changes, this
95	list is stale — read the workflow and say so rather than running a command CI
96	no longer uses.
97
98	Known suite papercut: `run_verifiers_background_*` is flaky under full-suite
99	parallelism and passes in isolation. Attribute it to the known flake, not to
100	the contributor's change.
101
102	### 5. What's new — deterministic local digest
103
104	Built only from files already on disk. No network, no model:
105
106	```
107	git log --oneline -n 20 origin/main
108	```
109
110	plus the topmost released section of `CHANGELOG.md`.
111
112	Rules:
113
114	- Cap the digest at 20 commits and 40 lines of changelog. State the cap
115	when you hit it; do not silently truncate.
116	- If `origin/main` is unavailable, digest `HEAD` instead and label it as such.
117	- Quote what the files say. Do not summarize, rank, or editorialize — the
118	point is that two contributors on the same commit get the same digest.
119
120	### 6. Dogfood — optional, staged, confirmed
121
122	Only after the gate has actually passed, and only if the contributor asks.
123	Print the plan and require an explicit yes before running anything:
124
125	```
126	./target/release/codewhale exec --help
127	```
128
129	This is a provider-free smoke check: it exercises the built binary without
130	sending a request anywhere. Anything beyond it — an actual `codewhale exec`
131	turn — needs the contributor's own configured route and their explicit
132	go-ahead. Never select a provider for them and never fall back to a default
133	one.
134
135	## Reporting
136
137	End with a compact status table: branch, tree, sync, build, gate, digest,
138	dogfood. Use `not run` for anything skipped and `unavailable` for anything the
139	environment could not determine. Never write `passed` from inference.
140
141	## Credit
142
143	Requested by @JayBeest (#4227). Preserve that attribution in the changelog
144	entry and in the commit body of any change that lands from this skill.
145

145 lines MARKDOWN