rastrillo / native Public

Download this file

1	# Working here
2
3	Work and review live at https://amadan.net/rastrillo/native. Use the amadan
4	agent skill and your agent account. Take a worktree and branch, describe it,
5	keep tasks current, and land with `amadan branch merge`. Never squash.
6
7	Run `make ci` before pushing. `.amadan/ci.d` calls the same Make targets.
8	Keep platform-specific dependencies out of the shared Swift target. Add a
9	component only after proving adoption in existing applications. Comments
10	explain the failure prevented; review user-facing English before translating.
11
12	## Work in a worktree, and catch main up first
13
14	Take a worktree for the work. Do not work in the shared checkout.
15
16	git -C <repo> fetch origin
17	git -C <repo> worktree add ../<repo>-<task> -b <branch> origin/main
18
19	Both halves matter, for different reasons.
20
21	**The worktree**, because several sessions share this machine and some
22	share this repository, and a checkout has one HEAD, one index and one
23	working tree between all of them. A branch switch under somebody else's
24	uncommitted work destroys it with nothing on screen to say so, and two
25	sessions editing the same paths disagree quietly instead of conflicting
26	loudly. A worktree gives the work its own HEAD and its own files, and
27	costs a directory.
28
29	**From `origin/main`, after a fetch** — not from whatever the checkout
30	happens to be sitting on. A branch cut from a stale main is a merge
31	conflict scheduled for later, against files somebody else has renamed in
32	the meantime. A branch cut from another task's branch is worse: it
33	carries that task's commits into yours, where they are reviewed as
34	though you wrote them, and the two can only be separated by hand.
35
36	Remove it when the work has landed — `git worktree remove` — so that
37	`git worktree list` keeps saying something true.
38
39	Written down because of 2026-09-17, in `meet`. The shared checkout was
40	sitting on one task's branch while holding a *different* task's feature
41	uncommitted on disk — some four hundred lines, a new migration among
42	them — put there by a session nobody else knew was working in that tree.
43	Two other sessions were meanwhile coordinating over the same checkout by
44	asking each other not to touch it, which is the arrangement a worktree
45	makes unnecessary. Nothing was lost. Nothing about the arrangement would
46	have said so if it had been, and by then the same feature existed twice,
47	once on each side of a rename, because the two sessions had branched
48	from different starting points.
49