From a4cf7366dd1e8ea1e1e3eb0254c999efcb905d9b Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 17 Oct 2026 22:56:17 +0100 Subject: [PATCH] docs: per-area agent maps for the Android app, the TUI and the server --- android/AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++ internal/server/AGENTS.md | 51 ++++++++++++++++++++++++++++++ internal/tui/AGENTS.md | 46 +++++++++++++++++++++++++++ 3 files changed, 162 insertions(+) create mode 100644 android/AGENTS.md create mode 100644 internal/server/AGENTS.md create mode 100644 internal/tui/AGENTS.md diff --git a/android/AGENTS.md b/android/AGENTS.md new file mode 100644 index 00000000..f6dddbd2 --- /dev/null +++ b/android/AGENTS.md @@ -0,0 +1,65 @@ +# The Android app — working map + +Read this before touching `android/`. It is the project-specific half; how Android projects in +general are built, tested and reviewed belongs to the pipeline that started you. + +## Build and test (offline, never with the daemon) + +This checkout has no `gradlew`; the toolchain uses the installed distribution: + +```sh +export JAVA_HOME='/Applications/Android Studio.app/Contents/jbr/Contents/Home' +export ANDROID_HOME="$HOME/Library/Android/sdk" +GRADLE=/Users/alan/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/bin/gradle +"$GRADLE" --offline --no-daemon :app:assembleDebug # ~7 s incremental +"$GRADLE" --offline --no-daemon :app:testDebugUnitTest # 400+ tests, ~8-13 s +``` + +Always `--no-daemon`: a leftover daemon is what makes these look slow. Add **one** test class at a +time while iterating — the full suite is for the end. + +## The dev device + +The only device is the operator's **Pixel 9 Pro XL, serial `47241FDAS00DLK`**. The operator's +Pixel 10 Pro Fold (`58281FDCG000JF`) is theirs: use it only where an item's brief explicitly allows +it, and never make it a default. **Never start or use an emulator.** + +Before any capture: `svc power stayon usb`, `settings put global stay_on_while_plugged_in 7`, +`input keyevent KEYCODE_WAKEUP`, `wm dismiss-keyguard`. Capture with +`adb -s shell screencap -p /sdcard/shot.png` then `adb pull` — never `exec-out > file`. +Wide layout: `wm size 2000x2244`; the fold's unfolded shape is `wm size 2076x2152`; `wm size reset` +afterwards either way. + +## Geometry is tokenised, and a test enforces it + +Every dimension comes from `ui/theme/Dimens.kt` (plus the layout itself) — no new hardcoded `dp`, no +percentages. `DimensTest` fails the build for a raw literal outside that file, so a value that +genuinely needs a new token goes there, named for its purpose. + +## Where things are + +- `ui/PipelinesApp.kt` — the app shell: destinations, the floating pill, the omni-search morph. +- `ui/chat/` — the chat: `ChatScreen`/`ChatTranscript`/`ChatComposer` (list, transcript, composer), + `ChatStore` (multi-conversation state), `ChatFormat` (parts → rendering), `ChatOverrides` (local + rename/hide), `Markdown`, `ChatScroll`. +- `ui/screens/` — `PipelineListScreen`, `PipelineDetailScreen`, `RunHistoryScreen`, `RunDetailScreen`, + `SettingsScreen`, `Timeline`. +- `ui/graph/` — the workflow graph, stage panes, artifacts gallery and viewer. +- `ui/components/` — `ListRow`, `DetailTabs`, `PaneIdentity`, `RunStatus`, `AttentionSurface`. +- `data/` — `PipelinesRepository` (the socket client) and `data/protocol/` (wire shapes). +- The app talks to the Pipelines server over the websocket in `data/PipelinesRepository.kt`; live run + state arrives as pushed `run_event` frames, and every view that shows run state folds them. + +## Publishing a build + +Copy the APK into the running run's artifacts directory as `pipelines-debug-wip-.apk` and +report the LAN URL. After any install, leave the operator's phone on **main's** build: +`/private/var/folders/jp/q0qvjyg54fl_c5vhhk1ylz2m0000gn/T/opencode/deploy-app.sh main`. + +## Traps + +- A build made in a worktree that is behind main is missing features main has — sync before building, + and say which revision you built. +- Changing the app's server URL for a test (a stub) must be undone: `ws://10.0.0.75:8080/connect`, + workspace `/Users/alan/repos/pipelines`, then force-stop and relaunch. +- `mStayOn`/screen timeout are already set; do not "fix" the device by locking or sleeping it. diff --git a/internal/server/AGENTS.md b/internal/server/AGENTS.md new file mode 100644 index 00000000..efbef4a3 --- /dev/null +++ b/internal/server/AGENTS.md @@ -0,0 +1,51 @@ +# The Pipelines server — working map + +Read this before touching `internal/server/`, `internal/stage/`, `internal/pipeline/` or +`internal/protocol/`. The generic half — how a Go service is built, tested and reviewed — belongs to +the pipeline that started you. + +## Build and test + +```sh +go build ./... && go vet ./... +go test ./internal/server # ~10-15 s +go test ./internal/stage ./internal/pipeline ./internal/protocol +go test ./... # ~1 min for everything; `gofmt -l .` must print nothing +``` + +## Where things are + +- `internal/server/websocket.go` — the `/connect` transport and the request dispatch. Envelope + validation lives here; every command returns its own typed reply. +- `internal/server/runner.go` — run execution: the stage loop, stage outcomes, budgets, retries, + ownership and settlement. This is where a run's state changes. +- `internal/server/runevents.go` — the push hub: subscriptions scoped per workspace, per-run frames, + coalescing. Live clients fold these instead of polling. +- `internal/server/chat_*.go` — the chat broker: `chat_sessions`, claims, the stream, permissions, + session registry. +- `internal/stage/` — one client per harness and stage type: `opencode.go` (native sessions), + `pi.go` (RPC), `model.go`, `agent.go`, `human.go` (decision stages), `ntfy.go` (notifications), + `result_repair.go` (the strict-envelope repair ladder), `budget.go` (usage accounting). +- `internal/pipeline/` — the store: definitions and immutable versions, runs and steps, the + operator-session registry, retention, search. +- `internal/protocol/` — every wire shape. A new command means a message field here, documentation in + `docs/cli.md`, and tests both sides. +- `cmd/pipelines-server/main.go` — flags and wiring, including which OpenCode endpoint chat brokers + from (`-opencode-endpoint`, `PIPELINES_OPENCODE_ENDPOINT`, or the recorded choice). + +## Checking behaviour without disturbing the live server + +`scripts/run-local-server.sh` starts a scratch server, and the binary takes `-addr` and `-db`, so a +live check runs against a **scratch database and a free loopback port**. The operator's deployment is +`~/.local/share/pipelines` with the service on `0.0.0.0:8080` and ntfy on `8090`. + +## Hard rules + +- **Never restart, rebuild or redeploy the deployed server, ntfy or a running run** to test a change: + a restart kills every run in flight. Deploying is the operator's step. +- Commit locally only, never push. +- One run per workspace at a time — the server refuses a second one rather than sharing a tree. +- The service is durable: sessions, runs and definitions live in SQLite, so a migration must open an + existing database cleanly (see the `migrateRun*`/`addColumnIfMissing` pattern). +- Artifacts are inventoried with bounds (`internal/server/artifacts.go`: file count, per-file and total + size); a large file is served by direct URL, not by growing the inventory. diff --git a/internal/tui/AGENTS.md b/internal/tui/AGENTS.md new file mode 100644 index 00000000..09886d5b --- /dev/null +++ b/internal/tui/AGENTS.md @@ -0,0 +1,46 @@ +# The TUI — working map + +Read this before touching `internal/tui/`. The generic side — how a Go CLI/TUI project is built, +tested and reviewed — belongs to the pipeline that started you. + +## Build and test + +```sh +go build ./... +go test ./internal/tui # fast (~2-4 s); the whole tree is ~1 min +go vet ./... +``` + +No device, no capture, no network: a TUI change is verified by unit tests plus a rendered frame. + +## How the TUI is put together + +- `model.go` — the `Model`, the key map (`keys`), and `Update`/`View` dispatch. Key bindings are + declared in one place; a new binding goes there, not inline. +- `dashboard.go`, `pipeline.go`, `runs.go`, `run_detail.go` — the screens. A run's detail is built + from sections, and a section can open as its own pane in the sliding stack. +- `context_footer.go` — the footer for the current mode. A modal's footer replaces the page's; never + inherit shortcuts that the modal does not honour. +- `theme.go` / `style.go` — colours and text styles. Status colour comes from one vocabulary so a + state looks the same in every screen. +- `linetext.go`, `graph.go` — line building and the stage graph rendering. +- Human decision stages are answered in the TUI: `↑/↓ choose · Tab feedback · Enter decide · Esc + cancel`. + +## Reviewing a TUI change without a terminal + +The pinned frames in `internal/harness/tmp/ui-review/render/` (`empty-catalog-*`, `filter-no-match-*`, +`narrow-long-model-*`, `plain-nocolor-*`, `wide-focused-*`, in dark and light) are the reference +renders. Compare against them when a change alters layout, spacing, colour or the footer, and add a +frame when you introduce a new state worth pinning. A change that alters a pinned frame and does not +say why is a review finding. + +## Conventions and traps + +- No polling: state arrives from the server; do not add a ticker to look busy. +- The footer and the pane stack are shared surfaces — a change there affects every screen, so say what + you checked. +- Terminal width matters: verify at a narrow width as well as a wide one, and never assume colour + support (`plain-nocolor-*` exists for a reason). +- Do not restart the deployed server, the lanes or ntfy to test a TUI change: run the binary against a + scratch server or use the fixtures.