Scaffold: agent starter kit (seeded from Ebb)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.claude/memory-seed/MEMORY.md

@@ -0,0 +1,13 @@
+- [Orchestrator never codes](orchestrator-never-codes.md) — every repo change via an Opus agent; a slip is kept, never reverted
+- [Subagents are Opus only](subagents-opus-only.md) — smaller models only for owner-requested read-only scans
+- [Relay HUMAN steps in chat](relay-human-steps-in-chat.md) — exact headings and button labels, expected result; owner reads no md files
+- [Pull numbers yourself](pull-numbers-yourself.md) — adb pull / run-as / logcat and a summary script; owner reads nothing off the phone
+- [Do installs yourself](do-installs-yourself.md) — package check and installDebug without asking when the phone is attached
+- [Ask owner to tap](ask-owner-to-tap.md) — no adb force-runs or broadcasts on the real-data app
+- [Phone install safety](phone-install-safety.md) — confirm ids; never clear real data; one agent on the phone
+- [Local builds only](local-builds-only.md) — no CI; openjdk@25 via PATH; adb full path
+- [Stay inside the project folder](stay-inside-project-folder.md) — ask once for anything outside the repo
+- [Gradle disk hygiene](gradle-disk-hygiene.md) — caches may be deleted; init script at 7 days; clean-builds.sh
+- [Owner-only files](human-todo-owner-only.md) — never read the owner's personal todo
+- [One source of truth](one-source-of-truth.md) — one rules file, one handoff, one decisions log
+- [Landing protocol](landing-protocol.md) — ff-only, gate, install, remove worktree; numbering in briefs

.claude/memory-seed/ask-owner-to-tap.md

@@ -0,0 +1,12 @@
+---
+name: ask-owner-to-tap
+description: Trigger on-phone actions through the owner's taps, never through adb force-runs, broadcasts or am start
+metadata:
+  type: feedback
+---
+
+Carried over from Ebb: permissions, sign-ins, vendor prompts and anything that changes app state on the owner's real-data install are the owner's taps. Agents may read (pull, logcat) but not drive the app.
+
+**Why:** forced runs bypassed permission prompts and produced states the owner could not reproduce.
+
+**How to apply:** write the step with exact labels and the expected result and wait. See [[relay-human-steps-in-chat]].

.claude/memory-seed/do-installs-yourself.md

@@ -0,0 +1,12 @@
+---
+name: do-installs-yourself
+description: Run adb checks, installs and pulls yourself when the phone is attached; HUMAN steps are for taps only
+metadata:
+  type: feedback
+---
+
+Owner (Ebb, 2026-10-17): "these things you can do yourself, don't ask me to do things you can do."
+
+**Why:** asking the owner to type adb or Gradle commands wastes their time.
+
+**How to apply:** when the phone is attached: `adb shell pm list packages | grep <id>`, then `installDebug` from main without asking; keep [[phone-install-safety]]. If not attached, say so once and install when it appears. See [[ask-owner-to-tap]].

.claude/memory-seed/gradle-disk-hygiene.md

@@ -0,0 +1,10 @@
+---
+name: gradle-disk-hygiene
+description: Parallel agent builds fill the disk; owner allowed deleting ~/.gradle caches; init script keeps caches at 7 days; run tools/clean-builds.sh after removing a worktree
+metadata:
+  type: feedback
+---
+
+Ebb, 2026-10-17: disk hit zero with three agents building (11 GB stale Gradle version cache, 7 GB transforms, local build cache). Owner: "You're allowed to delete the gradle cache."
+
+**How to apply:** check `df -h /System/Volumes/Data` before spawning parallel builders; under ~5 GB free, delete `~/.gradle/caches/build-cache-1` and old `~/.gradle/caches/<version>` dirs, then `tools/clean-builds.sh`. An agent that hit ENOSPC is resumed, not respawned; its commits survive. The user-level init script `~/.gradle/init.d/cache-retention.gradle.kts` already exists on this MacBook.

.claude/memory-seed/human-todo-owner-only.md

@@ -0,0 +1,8 @@
+---
+name: human-todo-owner-only
+description: A file the owner keeps for themselves (e.g. human-todo.md) is never read or edited by agents; status lives in docs/HANDOFF.md
+metadata:
+  type: feedback
+---
+
+Carried over from Ebb. If such a file exists here, treat it the same way. See [[relay-human-steps-in-chat]].

.claude/memory-seed/landing-protocol.md

@@ -0,0 +1,10 @@
+---
+name: landing-protocol
+description: How the orchestrator lands an agent branch: ff-only merge, gate on main, install, remove worktree, delete branch; agents never land; numbering handed out in briefs
+metadata:
+  type: project
+---
+
+Pattern that worked on Ebb (2026-10): agent works in `.claude/worktrees/agent-<id>`, starts with `git reset --hard main`, copies git-ignored `local.properties` and vendor binaries, builds only via `tools/gradle-serial.sh`, commits, rebases on main, gates, reports (branch, head, gate lines, one line per item, owner steps). Orchestrator: `git merge --ff-only`, gate on main, `installDebug` if the phone is attached, `git worktree remove --force --force` (fallback `rm -rf` + `git worktree prune`), `git branch -d`. Bulk `git rm`/`git branch -D` can be blocked by the permission classifier: ask the owner to run it with `!`.
+
+**How to apply:** two parallel agents get disjoint decision/spec numbers in their briefs; the second to land renumbers on rebase. Tell a running agent when main moves. See [[orchestrator-never-codes]], [[gradle-disk-hygiene]].

.claude/memory-seed/local-builds-only.md

@@ -0,0 +1,10 @@
+---
+name: local-builds-only
+description: Everything builds locally on the MacBook; no CI, no remote build service; JDK via Homebrew openjdk@25, adb at /opt/homebrew/share/android-commandlinetools/platform-tools/adb
+metadata:
+  type: project
+---
+
+Carried over from Ebb (2026-10). Gradle runs as `PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH tools/gradle-serial.sh …`; the shell's `java` is a macOS stub. Never set JAVA_HOME. `adb` is not on PATH.
+
+**How to apply:** do not add CI or hosted runners; report real gate lines from local runs only.

.claude/memory-seed/one-source-of-truth.md

@@ -0,0 +1,10 @@
+---
+name: one-source-of-truth
+description: Owner wants exactly one working-rules file, one handoff, one decisions log; delete superseded copies the same day
+metadata:
+  type: feedback
+---
+
+Owner (Ebb, 2026-10-17): "Remove anything old (agent.md etc) we should only have one source of truth."
+
+**How to apply:** when a document is superseded, fold it into the survivor and delete it in the same commit; repoint references with `git grep`. Stale status lines in reports get a dated new line with the old one struck through.

.claude/memory-seed/orchestrator-never-codes.md

@@ -0,0 +1,12 @@
+---
+name: orchestrator-never-codes
+description: The orchestrator session never writes code or repo changes itself; every change, however small, goes through an Opus subagent; a slip is kept and handed over, never reverted
+metadata:
+  type: feedback
+---
+
+Owner rule (Ebb, 2026-10-17): "you are not allowed to code, only opus subagents are." And: "if you slip up, no need to undo the work. that is just stupid and wasteful."
+
+**Why:** implementation, review and verification run on Opus agents with their own worktree and gate; the orchestrator keeps the overview, lands, installs and talks to the owner.
+
+**How to apply:** for any repository change, including docs, decisions and config comments, spawn an Opus agent with a brief. The orchestrator may read, run gates, fast-forward main, run adb and answer questions. A change started by mistake is kept and handed to an agent to own. See [[subagents-opus-only]], [[do-installs-yourself]].

.claude/memory-seed/phone-install-safety.md

@@ -0,0 +1,10 @@
+---
+name: phone-install-safety
+description: Confirm package ids before installing; never clear or uninstall an install that holds the owner's real data; one agent on the phone at a time
+metadata:
+  type: feedback
+---
+
+Carried over from Ebb, where a data-collecting spike app lived on the same phone and a wrong id would have cost days.
+
+**How to apply:** `adb shell pm list packages | grep <id>` before the first install of a session; installs keep data; "clear data" or uninstall of a real-data build needs the owner's yes; the brief names which agent may touch the phone. See [[do-installs-yourself]].

.claude/memory-seed/pull-numbers-yourself.md

@@ -0,0 +1,12 @@
+---
+name: pull-numbers-yourself
+description: Never ask the owner to read numbers, tables or logs off the phone; pull them over USB (adb pull, run-as cat, logcat -d) and summarise with a script, aggregates only
+metadata:
+  type: feedback
+---
+
+Owner (Ebb, 2026-10-17), when asked to read timing tables aloud: "are you kidding me? Either you read it or make it so that I can export a report… very disappointed honestly."
+
+**Why:** the owner's phone time is for taps and yes/no observations only.
+
+**How to apply:** every debug feature writes a file under the app's external files dir; the orchestrator pulls it (`adb pull /sdcard/Android/data/<pkg>/files/...`, `adb shell run-as <pkg> cat files/...`, `adb logcat -d -s <tag>`) into the scratchpad and summarises with a script (medians, counts; never content). See [[relay-human-steps-in-chat]], [[do-installs-yourself]].

.claude/memory-seed/relay-human-steps-in-chat.md

@@ -0,0 +1,12 @@
+---
+name: relay-human-steps-in-chat
+description: The owner never reads HUMAN steps in md files; every owner action is spelled out in the chat reply with exact section headings and button labels and the expected result
+metadata:
+  type: feedback
+---
+
+Owner (Ebb, 2026-10-17): "never read these [md files], you need to always tell me clearly what you expect me to do." And on an imprecise label: "your instructions must be much more clear. They must be exactly what I should press."
+
+**Why:** a step that lives only in a report is never done, and work waits on it silently; a vague label makes the owner do the wrong thing.
+
+**How to apply:** numbered list in the reply, each step = where (heading verbatim) + what to press (label verbatim) + expected result. Read the strings or composables first when unsure. Keep a `docs/debug-screen.md` map of every heading and button, kept true by a test. See [[pull-numbers-yourself]], [[ask-owner-to-tap]].

.claude/memory-seed/stay-inside-project-folder.md

@@ -0,0 +1,10 @@
+---
+name: stay-inside-project-folder
+description: Nothing outside the repository without an explicit allowance; no unasked side tasks
+metadata:
+  type: feedback
+---
+
+Carried over from Ebb. Exceptions the owner granted there: reading `~/.android/debug.keystore` for a signature hash (asked first), writing `~/.gradle/init.d/cache-retention.gradle.kts`, deleting `~/.gradle/caches` when the disk was full.
+
+**How to apply:** ask once, in one line, when a task needs a file outside the repo; keep the allowance scoped to that file.

.claude/memory-seed/subagents-opus-only.md

@@ -0,0 +1,12 @@
+---
+name: subagents-opus-only
+description: Subagents are Opus; Haiku or Sonnet only for a read-only scan the owner explicitly asks for that way
+metadata:
+  type: feedback
+---
+
+Owner rule carried over from Ebb: every implementation, review and verification agent is Opus. One task per agent, each in its own worktree, briefed with goal, files to read, established facts, numbers it may use, setup, gate and report format.
+
+**Why:** smaller models produced work that had to be redone; the owner would rather pay for one correct pass.
+
+**How to apply:** `model: opus` on every Agent call unless the owner names another model for a specific read-only job. See [[orchestrator-never-codes]].