Skip to content

Commit f956e6f

Browse files
wesbillmanCarl
andauthored
docs: refresh agent development guidance (#6049)
## Summary - allow agents to build and run Flutter when it provides relevant implementation or validation evidence - keep mobile iteration fast by reusing simulators, incremental builds, and configured staging or production communities - correct stale CLI, E2E, CI, worktree formatting, and mobile launch guidance - point community singleton reset guidance at the canonical implementation instead of duplicating a drifting inventory ## Validation - `git diff --check origin/main..HEAD` - `cargo run -q -p buzz-cli -- --format compact messages thread --help` - `cargo run -q -p buzz-cli -- --format compact messages search --help` - `just desktop-tauri-fmt-check` from the worktree - pre-commit: mobile Dart formatting and `flutter analyze` - pre-push: branch-skew check and full mobile test suite (1,465 tests) Signed-off-by: Wes <[email protected]> Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
1 parent d8281b9 commit f956e6f

2 files changed

Lines changed: 39 additions & 34 deletions

File tree

‎AGENTS.md‎

Lines changed: 37 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -109,8 +109,9 @@ See CONTRIBUTING.md for full setup details and dependency requirements.
109109

110110
## Quality Gates
111111

112-
Run `just ci` before every PR — it runs `fmt` + `clippy` + desktop lint +
113-
unit tests + builds. Clippy passing does not mean fmt passes; run both.
112+
Run `just ci` before every PR — it runs repository-wide formatting, lint,
113+
and static checks; Rust, Tauri, desktop, and mobile tests; and desktop and web
114+
builds. Clippy passing does not mean fmt passes; run both.
114115

115116
Run `just test` for integration tests if you touched `buzz-relay`,
116117
`buzz-db`, or `buzz-auth` — these require a running Postgres and Redis.
@@ -204,7 +205,7 @@ or invoke with the full path.
204205
thread. To read the linked thread:
205206

206207
```bash
207-
buzz messages thread --channel <uuid> --event <hex> --format compact
208+
buzz --format compact messages thread --channel <uuid> --event <hex>
208209
```
209210

210211
Extract `channel` and `id` from the URL query parameters. The optional
@@ -235,7 +236,9 @@ E2E tests live in `crates/buzz-test-client/tests/`:
235236
- `e2e_media_extended.rs` — extended media scenarios
236237
- `e2e_nostr_interop.rs` — Nostr interop (NIP-50 search, NIP-10 threads, NIP-17 gift wraps)
237238

238-
Desktop E2E: `cd desktop && pnpm exec playwright test`
239+
Desktop E2E: `cd desktop && pnpm test:e2e:smoke` for mock-bridge smoke
240+
coverage, or `pnpm test:e2e:integration` for relay-backed coverage. These
241+
scripts build the required E2E bridge before running Playwright.
239242

240243
See [TESTING.md](TESTING.md) for the full multi-agent E2E guide.
241244

@@ -446,11 +449,10 @@ description. See [PR #803](https://github.com/block/buzz/pull/803).
446449

447450
1. **Kind `39000` for channel metadata, not `41`** — kind 41 is NIP-01 (unused). All kinds defined in `buzz-core/src/kind.rs`.
448451
2. **Relay queries must specify `kinds`** — omitting `kinds` triggers the p-gate (403). Always include explicit kind filters.
449-
3. **`messages search` must include `--kinds`** — an open-ended search (no kinds) hits the relay p-gate and returns 403. Pass at least `--kinds 9,45001,45003` to scope the query.
452+
3. **`messages search` chooses its own supported kinds** — do not add a `--kinds` option; the current command does not accept one. This differs from raw relay filters, which still need explicit kinds.
450453
4. **Worktrees: `cd` in the same command** — shell CWD doesn't persist between tool calls. Use `cd /path && cargo build` as one command.
451454
5. **Desktop crate excluded from root workspace** — `cargo test` at repo root does NOT run desktop tests. Use `cargo test --manifest-path desktop/src-tauri/Cargo.toml` explicitly.
452-
6. **Desktop Tauri fmt fails in worktrees and blocks commits** — the pre-commit hook runs `just desktop-tauri-fmt`, which fails in git worktrees because `cargo fmt` resolves workspace paths relative to the worktree root. Run `just desktop-tauri-fmt` from the main checkout to apply the fix, then re-stage and commit. CI is unaffected.
453-
7. **React render perf: `React.memo` is all-or-nothing** — it only skips a re-render when *every* prop is reference-stable; one unstable prop (inline arrow/JSX, or a hook returning a fresh `{}`/`[]`/`Map` each render) defeats it. Two repeat offenders: (a) React Query results (`useMutation`/`useQuery`) are a **new object each render** — depend on the stable method (`mutation.mutateAsync`), not the object; (b) derived `Map`/array state that recomputes on a version bump — wrap in a content-equality ref cache (`shared/hooks/useStableReference.ts`). When chasing interaction lag, **measure with DevTools closed and no perf probes** (an open Web Inspector + per-keystroke `console.log` inflate the numbers), and isolate by removing one suspect at a time rather than guessing.
455+
6. **React render perf: `React.memo` is all-or-nothing** — it only skips a re-render when *every* prop is reference-stable; one unstable prop (inline arrow/JSX, or a hook returning a fresh `{}`/`[]`/`Map` each render) defeats it. Two repeat offenders: (a) React Query results (`useMutation`/`useQuery`) are a **new object each render** — depend on the stable method (`mutation.mutateAsync`), not the object; (b) derived `Map`/array state that recomputes on a version bump — wrap in a content-equality ref cache (`shared/hooks/useStableReference.ts`). When chasing interaction lag, **measure with DevTools closed and no perf probes** (an open Web Inspector + per-keystroke `console.log` inflate the numbers), and isolate by removing one suspect at a time rather than guessing.
454456

455457
---
456458

@@ -511,27 +513,12 @@ class instances, cached promises) survive across remounts. Every community-scope
511513
singleton needs a reset function wired into `resetCommunityState()` in
512514
`desktop/src/features/communities/useCommunityInit.ts`.
513515

514-
Current singletons that are reset on relay boundary changes (same-relay
515-
reconnects preserve pending avatar verification work):
516-
- `relayClient.disconnect()` — WebSocket teardown + promise rejection
517-
- `resetRateLimitGate()` — clears any active rate-limit window from the old relay
518-
- `clearAllDrafts()` — message draft cache
519-
- `resetAgentObserverStore()` — agent observer relay store
520-
- `resetActiveAgentTurnsStore()` — active agent turn timers
521-
- `resetAgentWorkingSignal()` — agent working indicator signal
522-
- `resetAvatarProfileSync()` — pending verified-avatar profile writes
523-
- `resetAvatarPresentations()` — avatar probes, previews, and Retry toasts
524-
- `resetSidebarRelayConnectionCardState()` — sidebar relay card dismiss state
525-
- `resetMediaCaches()` — proxy port and relay origin caches
526-
- `resetVideoPlayerState()` — video player singleton
527-
- `resetRenderScopedReactionHydration()` — reaction hydration cache
528-
- `clearSearchHitEventCache()` — search result event cache
529-
- `clearMarkdownNodeCache()` — markdown parse-node cache
530-
- `resetLinkPreviewTitleCache()` — link preview title cache (Buzz entity titles come from relay events)
531-
532-
**If you add a new module-level cache, Map, or class instance that holds
533-
community-scoped data, you must add its reset to `resetCommunityState()`.**
534-
Failure to do so causes data from the old community to leak into the new one.
516+
`resetCommunityState()` is the canonical inventory of community-scoped
517+
singletons. **If you add a new module-level cache, Map, or class instance that
518+
holds community-scoped data, add its reset there in the same change.** Failure
519+
to do so causes data from the old community to leak into the new one. Avoid
520+
duplicating its complete reset list here; the implementation is the source of
521+
truth.
535522

536523
Key files:
537524
- `desktop/src/app/App.tsx` — community key, init gate, remount boundary
@@ -556,9 +543,23 @@ The mobile app lives in `mobile/` — a Flutter app using Riverpod + Hooks.
556543

557544
- **NEVER use `StatefulWidget`** — favor Riverpod for state and always use
558545
`HookConsumerWidget` or `ConsumerWidget` with `flutter_hooks` for local state.
559-
- **NEVER run `flutter run`, `flutter build`, `flutter clean`, or
560-
`flutter upgrade`** — only `flutter test`, `flutter analyze`, and
561-
`dart format` are safe for agents to run.
546+
- Agents may build and run the Flutter app when it materially helps implement,
547+
debug, or validate mobile changes. Prefer the smallest relevant command and
548+
reuse an already-running simulator/emulator and the app's configured staging
549+
or production community when that is sufficient. Do not start or rebuild
550+
local relay services unless the task specifically requires relay-side or
551+
isolated integration behavior.
552+
- For iOS runtime validation, prefer `just mobile-dev`; it applies the
553+
worktree-specific debug identity and runs `flutter run`. Direct `flutter run`
554+
or IDE workflows are also allowed. Use `just mobile-build-android` only when
555+
an APK build is relevant to the task.
556+
- Do not rebuild, reinstall, or relaunch merely for ceremony. Preserve Flutter's
557+
incremental build cache and use hot reload/restart where appropriate. Use
558+
`flutter clean` only when stale build artifacts are a credible cause. Run
559+
`flutter upgrade` only when the task explicitly requires a toolchain change.
560+
- For user-visible or integration changes, exercise the affected workflow in a
561+
real app when practical and report the device/simulator, connected community,
562+
and workflow actually tested.
562563
- **Do NOT use `print()`** — use `debugPrint()` or structured logging.
563564
- Prefer `context.colors` and `context.textTheme` (via theme extensions)
564565
over raw `Theme.of(context)` calls.
@@ -584,12 +585,16 @@ flutter test
584585

585586
Or from repo root: `just mobile-fmt` (auto-fix), `just mobile-check` (lint + fmt check), `just mobile-test` (tests).
586587

587-
To run the app locally (starts Docker, relay, iOS simulator automatically):
588+
To run the app locally with a worktree-specific debug identity and a
589+
started or reused iOS Simulator:
588590

589591
```bash
590592
just mobile-dev
591593
```
592594

595+
This runs `flutter run` against the app's configured community; it does not
596+
start Docker or local relay services.
597+
593598
When run from a git worktree, `just mobile-dev` (and `just
594599
mobile-build-android`) give the debug build a per-worktree app identifier
595600
(keyed to the worktree directory name) and a branch-labelled app name via

‎mobile/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ flutter pub get
1212
## Run
1313

1414
```bash
15-
# From repo root (recommended — starts Docker, relay, and simulator):
15+
# From repo root (applies a worktree-isolated debug identity and starts/reuses Simulator):
1616
just mobile-dev
1717

18-
# Direct (requires services and relay already running):
18+
# Direct (uses the app's configured community; apply worktree overrides first):
1919
cd mobile && flutter run
2020
```
2121

0 commit comments

Comments
 (0)