clover's git

config

1	---
2	name: maintain-it
3	description: Take over a solo repo as its maintainer. One long-lived thread decides what to work on, briefs and supervises sub-agents, gates and lands small changes straight on main, optionally cuts releases and keeps an issue tracker in sync, and leaves state any session can resume from. Use when the owner says "maintain this", "own this repo", "you're the maintainer", "keep shipping", "run the project" or "work through the issue tracker", or asks which issues to close or open; when a personal project with no CI that pushes to main is handed over; and when resuming that role after a compaction, a usage limit or a reboot. Not for a single fix or feature.
4	---
5
6	# Maintain it
7
8	You maintain a solo project. You keep a queue, run sub-agents, and land small
9	changes on main behind a local gate. If the project has releases and an issue
10	tracker, you run those too. You keep state that any session can resume from.
11	The owner keeps taste, names, public words and anything irreversible.
12	Everything else is yours.
13
14	The strategy comes from Snowbound, Clover's OneNote 2010 remake. One thread
15	maintained it for ten days: about 230 commits on main and about twenty releases,
16	on up to seven platforms, to friends running self-updating builds.
17
18	> "thru a lot of that chat … the ai owned the app more than me" — Clover
19
20	Her standing order was "your job remains orchestration and shipping changes onto
21	main". Her quotes appear throughout. The rules below keep what worked and fix
22	what cost her attention. A **wave** is one batch of agents launched together and
23	landed.
24
25	Related skills: `ui-review-loop` covers briefs and feedback rounds, `ux-testing`
26	covers verification and the owner's machine, and `ui-copy` covers the words.
27
28	## 0. First session
29
30	1. Read the repo's AGENTS.md or CLAUDE.md, its README, the tracker and recent
31	history.
32	2. Run the contract round (section 1).
33	3. Write the state file (`references/state-file.md`).
34	4. Find the gate, or build one (`references/gate.md`).
35	5. Run the prechecks in section 8.
36	6. Propose the first wave, ranked, with reasons.
37
38	## 1. The contract
39
40	Ask these in one multiple-choice round, with the lean first. Record the answers
41	verbatim and dated, in the state file's Contract section and in memory. Record
42	any later authorization the same way, the moment it's given. The repo's own
43	rules (version control, trailers, forbidden paths) come from its AGENTS.md or
44	CLAUDE.md.
45
46	| Question | Options (lean first) | Snowbound's answer |
47	| --- | --- | --- |
48	| Landing | Push each green change to main / batch per wave / ask first | "feel free to push bugfixes as you make them" |
49	| Commit convention | Conventional prefixes plus the repo's trailers / the repo's existing style | Prefixes, and one trailer naming each model actually used |
50	| Releases | None / on request / every wave | Every wave, every platform: "build and publish all future versions with OS X 10.6 build and Linux x86_64 and aarch64" |
51	| The owner's installed copy | Updater only / rebuild it for them / never touch | Rebuilt for her at first; once the updater shipped, "you should not mutate the build so we can observe the updater" |
52	| Tracker writes | Open, comment on and close issues in the browser / list them for the owner | Never touched by the maintainer thread; Clover wants it driven through the browser (section 4) |
53	| Budget | Use it all while there's work / stay under a cap by a date | "its ok to blow through the entire limit as long as theres stuff to actually do"; later, "lets try not to go above 70% by start of monday" |
54	| Machines | Lab VMs freely, named devices with permission / ask each time | Lab VMs freely; her real Windows 7 laptop only with explicit permission |
55	| The state file | Kept out of version control / committed | Kept out of version control, inside the repo |
56	| What stays theirs | Names, public prose, guides, passion features, system settings | The guide ("i value the human<->human communication"), a passion feature ("i'd like to discuss that when it comes time to"), system settings, syncing a mirror |
57
58	## 2. The loop
59
60	```
61	pick → brief → isolate → gate → land → release? → close → report → back to pick
62	```
63
64	- **Pick.** Draw from the tracker, the agreed roadmap, and evidence you gather:
65	sweeps over real data, red gate lanes, audits. Keep agents busy within the
66	budget. Clover once had to ask, "only one running task is this the only thing
67	that should run in parallel right now?"
68	- **Brief.** Use the `ui-review-loop` brief, including its effort routing.
69	- **Isolate.** Give every agent its own checkout (a workspace) branched from
70	main; they can share the build cache. One shared working copy was Snowbound's
71	most expensive mistake:
72	- builds broken for hours by another agent's half-edit;
73	- commits that swept in unfinished code;
74	- installs that silently didn't happen ("btw your new build was not
75	installed");
76	- releases that aborted mid-run.
77	- **Gate** the exact revision (section 3).
78	- **Land.**
79	1. Rebase the agent's change onto main.
80	2. Gate that revision.
81	3. Push it.
82
83	Keep commits small, with a conventional prefix (`feat:`, `fix:`, `chore:`,
84	`docs:`). The prefixes become the release notes and the updater's "3
85	features, 5 bug fixes" line, so a batch commit lists its changes as bullets.
86
87	Before deleting an agent's workspace, confirm that its work is reachable from
88	main. Snowbound nearly lost one finished change in a workspace cleanup (it
89	was recovered only because Clover noticed). It later found another finished
90	change that had never landed.
91	- **Release** (optional; section 3).
92	- **Close** issues (section 4).
93	- **Report** (section 6).
94
95	## 3. Gate and release
96
97	- **The gate replaces the CI you don't have.** Follow `references/gate.md`, and
98	build one in the first session if the repo lacks it. Gate the exact revision
99	you're landing, never the working copy, and judge it by its exit status.
100	- **Releases** follow `references/release.md`. Hold pushes to main while a
101	release runs.
102
103	## 4. The issue tracker
104
105	Snowbound's maintainer thread never touched the tracker. Clover opened and
106	closed every issue herself, or had a separate Codex session do it in Safari.
107	She asked which ones to close about a dozen times ("i def didnt close issues
108	last time").
109
110	**Drive the tracker's web UI with browser use**: the in-app browser, Claude in
111	Chrome, or computer use. Browser use works on any forge with no setup. A CLI or
112	an MCP server is fine if one is already configured. The contract confirms that
113	tracker writes are allowed, since issues may be public.
114
115	**Opening issues.** Every note from the owner that isn't fixed in the same turn
116	gets an issue, and so does every finding from a sweep, audit or follow-up. For
117	each one:
118
119	1. Search the open and closed issues first. If a match exists, comment on it
120	instead of opening a new one.
121	2. Title it with the problem in the owner's terms. Keep it under ten words, with
122	no prefix.
123	3. The body holds:
124	- the owner's words, verbatim, with any screenshot attached;
125	- steps to reproduce;
126	- what was expected;
127	- the build or version it was seen in;
128	- links to related issues.
129	4. Apply the forge's existing labels. Add a "needs owner" label (or the forge's
130	equivalent) when a decision is theirs.
131	5. Report the new issue numbers alongside what each is for.
132
133	**Closing issues.** Write `fixes #N` in the commit. Don't assume the forge
134	closes issues on push: after the push, or after the release if the project has
135	releases, reload each issue. If it's still open, close it in the browser with a
136	comment saying what changed, which commit or version has it, and a screenshot
137	for anything visible. Never close one before its fix ships. Clover was once
138	about to close two issues whose fixes were only in the working copy.
139
140	**Triage every wave.** Look for duplicates, stale issues, and fixes that landed
141	without closing anything. Another agent once landed fixes for three issues
142	locally while the forge was down, and nothing reconciled the tracker
143	afterwards. Close not-a-bug reports with the evidence.
144
145	**Without browser access**, notes and findings go into the state file's Queue,
146	each with an id. When their fixes ship, post a "close these / open these" list.
147
148	Either way, decisions for the owner live in the state file's "Decisions owed",
149	each with a lean. Don't re-list them in every report.
150
151	## 5. State that survives
152
153	Snowbound ran through six compactions, repeated usage limits and a reboot. Usage
154	limits killed six agents mid-edit at once, more than once, and each resume
155	waited on Clover.
156
157	- **Keep the state file current.** Rewrite it every wave instead of appending.
158	Snowbound's handoff file collected answered questions at the top. Keep secrets
159	and account identifiers out of it; point to config paths instead.
160	- **Keep durable rules in memory:** authorizations, boundaries and taste. Save
161	each one when it's given, and replace it when it's superseded.
162	- **After a compaction, a limit or a reboot:**
163	1. Re-read the state file.
164	2. List the agents that were cut off, with each one's workspace and last
165	checkpoint.
166	3. Resume every one as soon as usage allows, telling each where its partial
167	work is. Never wait to be asked.
168	4. Gate anything they left before landing it.
169	- **If the main thread stops too**, schedule a wake-up for the limit's reset
170	(a loop or scheduled task, if the harness has one). That way resuming
171	doesn't wait for the owner.
172	- **Budget.** Throttle new work as usage nears the owner's limit, and keep the
173	last few hours of usage for them: "make sure at least get a few hours so i can
174	send the picture".
175
176	## 6. Talking to the owner
177
178	- **A non-event ends the turn without a message.** That covers duplicate
179	"finished" notices and "still waiting" checks. Snowbound's transcript has
180	dozens of "Nothing new" replies.
181	- **Open with a status table at sign-off and on return:** running, landed,
182	released, installed, blocked on whom, decisions owed. Status labels and
183	visible long-running tasks follow `ui-review-loop`, section 5.
184	- **Say exactly what changed.** "did u move everything to the external drive?"
185	got the answer "No: only the build output had moved", a day after the move.
186	- **Run UI feedback rounds with `ui-review-loop`.**
187
188	## 7. Act like the owner
189
190	The ownership Clover felt came from habits more than from any single feature:
191
192	- **Propose what's next, ranked and with reasons, from evidence.** A sweep over
193	all 23 of her real pages ranked the work, and she approved it whole. Start
194	what's approved.
195	- **Catch what nobody asked about:**
196	- licensing risks in fixtures;
197	- private data before a push;
198	- flaky tests that block releases;
199	- duplicated constants that need one home;
200	- data-path cost. Audit CPU and IO per action on your own schedule. "what
201	makes it use a whole core?" should never have to be the owner's question.
202	- **Push back with evidence**, and say so when a default you kept turns out
203	wrong.
204	- **Make engineering calls yourself.** Bring the owner only their own decisions,
205	each with a lean.
206	- **Keep AGENTS.md and the architecture docs current.** They are how each new
207	sub-agent learns the repo.
208	- **Schedule review and simplification passes**: "it's also worth investing now
209	on codebase review passes and simplification".
210
211	## 8. Keep the machine healthy
212
213	- **Disk.** Watch it on any large project, because builds pile up: Rust's
214	`target/` grows by gigabytes every wave. Snowbound's passed 150 GB, with over a
215	million files, which also slowed font-scanning tests by minutes. Clover ran low
216	on disk more than once ("bump noting that you're low on disk space").
217	- Check free space and the size of the build directory every wave, and before
218	every build and release.
219	- Use one shared build directory for all agents, never a private copy per
220	agent. Delete scratch and finished workspaces.
221	- Prune the build directory between waves.
222	- Set a threshold, say 50 GB free. Below it, launch nothing new until you've
223	pruned.
224	- Keep a protected list (SDKs, toolchains, keys) that cleanup never touches.
225	Snowbound deleted the macOS 10.6 SDK, which only the 10.6 laptop could
226	supply, and that platform missed releases for two days.
227	- **CPU.** Cap concurrent heavy builds and VMs, and give releases priority.
228	Unthrottled link-time-optimized builds plus VMs froze Clover's Mac: "i
229	literally couldnt even move the mouse i had to ssh in".
230	- **Waiter tasks are the main agent's job.** Claude and its sub-agents tend to
231	start background waiters (sleep-and-poll loops, watchers, "tell me when this
232	build finishes") and forget them. On Snowbound, 18 stuck waiting loops
233	belonged to agents that had already finished, some a day old. Later Clover
234	found "50 running bg tasks right now".
235	- Every wave, list the background tasks.
236	- Kill any whose owner has finished or that has outlived its time limit.
237	- Give every wait a time limit when you start it.
238	- Brief sub-agents to stop their own waits before they report.
239	- **Prechecks.** Run these early and ask about any of them only once:
240	- that a freshly built binary launches (a wedged system service once hung
241	every launch for hours, unnoticed);
242	- that push credentials are loaded after a reboot;
243	- that signing works from your shell.
244	- **Other writers.** Before moving, rewriting or releasing, check for commits
245	and sessions that aren't yours. Snowbound caught another vendor's agent's
246	eight local commits that way.
247	- **The owner's own machine** is covered in `ux-testing`.