|
|
|
@@ -2,7 +2,7 @@
|
|
|
|
|
|
|
|
|
|
Operating guide for AI agents and humans working on **Kvitt**. This is the only working-rules file; it says how to work here, not what the product is. For the product, read `SPEC.md`. It was seeded on 2026-10-17 from the Ebb project's rules after a year of running Opus agents in parallel; keep what fits, delete what does not, but keep one file.
|
|
|
|
|
|
|
|
|
|
> **Fill in before the first plan:** the one-paragraph product description, the module layout under "Repository layout", the application ids under "The phone" (if this is an Android app), and the fast checks in `tools/git-hooks/pre-commit`.
|
|
|
|
|
**The product in one paragraph.** Kvitt is a Splitwise-style shared-expense app for exactly two people, the owner (Jacob, admin) and his spouse, in Sweden. A native Android app (Kotlin, Compose) keeps a full offline copy of the household's expense accounts, expenses, settlements and audit log in Room and syncs with a small Rust server (axum, SQLite) that runs in Docker on a Raspberry Pi 3 at home, reachable at `https://icehack.asuscomm.com:8443`. Money is SEK in integer öre. The phone computes balances, settle-up proposals and spending analytics itself; the server stores, syncs, schedules recurring expenses, sends push notifications and hosts the APK for in-app updates. Everything else is in `SPEC.md`.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
@@ -20,20 +20,26 @@ Operating guide for AI agents and humans working on **Kvitt**. This is the only
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
SPEC.md, PLAN-*.md what to build; prompts/ holds a ready-to-paste start prompt per plan and the orchestrator prompt
|
|
|
|
|
contracts/ openapi.yaml, test-vectors/*.json, sync and push examples: the cross-team contracts (SPEC §14)
|
|
|
|
|
docs/HANDOFF.md state of the work and how it is run
|
|
|
|
|
docs/decisions.md decisions that changed or refined the spec
|
|
|
|
|
docs/ux/ the UX sprint deliverables (SPEC §13)
|
|
|
|
|
docs/spikes/, docs/validation/ what the device and the data showed (reports are deliverables)
|
|
|
|
|
tools/ gradle-serial.sh, clean-builds.sh, install-git-hooks.sh, dependency-report/latest.py
|
|
|
|
|
(root) the app: one Gradle project, modules as in SPEC
|
|
|
|
|
android/ the Android app: one Gradle project (settings.gradle.kts, gradle/libs.versions.toml), modules as in SPEC §14.7
|
|
|
|
|
server/ the Rust backend: one Cargo workspace, crates kvitt-domain, kvitt-server, kvitt-import (SPEC §14.7)
|
|
|
|
|
infra/ docker compose stack for the Pi (caddy, server, cert-sync, backup), image build scripts, ops runbooks
|
|
|
|
|
tools/ gradle-serial.sh, clean-builds.sh, install-git-hooks.sh, git-hooks/, dependency-report/latest.py
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Who owns which directory during parallel work is in SPEC §14.7. An agent edits only the paths its plan owns.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## ORCHESTRATION: HOW WORK IS RUN
|
|
|
|
|
|
|
|
|
|
The owner talks to one **orchestrator** session. The orchestrator plans, briefs, lands, gates, installs and answers; it **never writes code or repository changes itself**, however small (docs and config included). Every change goes through an **Opus** implementation agent. If the orchestrator slips and edits something, it keeps the work and hands it to an agent to own; it never reverts or redoes it.
|
|
|
|
|
|
|
|
|
|
* **One Opus agent per task, in its own git worktree** (`.claude/worktrees/agent-<id>`, branch of the same name). The agent's first step is `git reset --hard main`, then copying `local.properties` (and any git-ignored vendor binaries) from the main checkout. It commits on its branch, rebases on `main`, runs the gate, and reports; it never lands, pushes or removes its worktree.
|
|
|
|
|
* **One Opus agent per task, in its own git worktree** (`.claude/worktrees/agent-<id>`, branch of the same name). The agent's first step is `git reset --hard main`, then copying `android/local.properties`, `android/app/google-services.json` and anything in `infra/secrets/` it needs (all git-ignored) from the main checkout. It commits on its branch, rebases on `main`, runs the gate, and reports; it never lands, pushes or removes its worktree.
|
|
|
|
|
* **The orchestrator lands:** `git merge --ff-only <branch>` in the main checkout, re-runs the gate on `main`, installs on the phone if attached, removes the worktree (`git worktree remove --force --force`, falling back to `rm -rf` + `git worktree prune`) and deletes the branch. No merge commits. Never rebase `main`.
|
|
|
|
|
* **Briefs are the whole context an agent has.** A brief states: the goal, what to read first (file paths), what is already established, the exact numbers it may use (next free decision, spec version, schema), the setup steps, the gate, what to report. If the orchestrator cannot write a clear brief, it does not understand the task yet.
|
|
|
|
|
* **Agents' reports are not shown to the owner.** The orchestrator extracts the decision: one line per finding, fixed or not, and relays every owner step in chat.
|
|
|
|
@@ -54,13 +60,15 @@ The owner talks to one **orchestrator** session. The orchestrator plans, briefs,
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## THE PHONE (if this is a device app)
|
|
|
|
|
## THE PHONE
|
|
|
|
|
|
|
|
|
|
Two phones: the owner's Samsung Galaxy S26 and the spouse's Galaxy S26+, both Android 16. Agents only ever touch the phone attached to this MacBook over USB, which is the owner's unless the brief says otherwise.
|
|
|
|
|
|
|
|
|
|
| App | Application ID |
|
|
|
|
|
|---|---|
|
|
|
|
|
| Real app, release | `<id>` |
|
|
|
|
|
| Real app, debug | `<id>.debug` |
|
|
|
|
|
| Instrumented-test APKs | `<id>.<module>.test` |
|
|
|
|
|
| Real app, release | `se.hagstedt.kvitt` |
|
|
|
|
|
| Real app, debug | `se.hagstedt.kvitt.debug` |
|
|
|
|
|
| Instrumented-test APKs | `se.hagstedt.kvitt.<module>.test` |
|
|
|
|
|
|
|
|
|
|
* `adb` is at `/opt/homebrew/share/android-commandlinetools/platform-tools/adb` on this MacBook; it is not on the shell PATH.
|
|
|
|
|
* Use `adb` **only for this project's apps**. Do not browse, copy or change anything else on the device.
|
|
|
|
@@ -74,24 +82,32 @@ The owner talks to one **orchestrator** session. The orchestrator plans, briefs,
|
|
|
|
|
|
|
|
|
|
Everything builds **locally on this MacBook**. No hosted CI, no remote build service.
|
|
|
|
|
|
|
|
|
|
**JDK.** Gradle runs on JDK 25 (current LTS): `gradle/gradle-daemon-jvm.properties` asks for 25 and `gradle.properties` points Gradle at Homebrew's `openjdk@25` (auto-download off). The shell's `java` is a macOS stub or a newer non-LTS: run Gradle as `PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH tools/gradle-serial.sh <tasks>` and **never set `JAVA_HOME`**. Do not install another JDK or change the pin without asking.
|
|
|
|
|
**Two projects, two gates.** The Android app is the Gradle project in `android/`; the server is the Cargo workspace in `server/`. A change that touches both runs both gates.
|
|
|
|
|
|
|
|
|
|
**Android SDK.** `local.properties` must contain `sdk.dir` (`/opt/homebrew/share/android-commandlinetools` on this MacBook). Add the line if missing; never overwrite the file, it also holds client ids and tokens; never commit it.
|
|
|
|
|
**JDK.** Gradle runs on JDK 25 (current LTS): `android/gradle/gradle-daemon-jvm.properties` asks for 25 and `android/gradle.properties` points Gradle at Homebrew's `openjdk@25` (auto-download off). The shell's `java` is a macOS stub or a newer non-LTS: run Gradle as `PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH tools/gradle-serial.sh <tasks>` and **never set `JAVA_HOME`**. Do not install another JDK or change the pin without asking.
|
|
|
|
|
|
|
|
|
|
**Android SDK.** `android/local.properties` must contain `sdk.dir` (`/opt/homebrew/share/android-commandlinetools` on this MacBook). Add the line if missing; never overwrite the file, it also holds client ids and tokens; never commit it.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
tools/gradle-serial.sh check # THE gate: build, unit tests, lint, architecture rules, screenshot tests
|
|
|
|
|
tools/gradle-serial.sh installDebug # install the debug app on the attached phone
|
|
|
|
|
# Android gate, from android/ (the script finds the repository root itself and runs android/gradlew):
|
|
|
|
|
../tools/gradle-serial.sh check # THE Android gate: build, unit tests, lint, architecture rules, screenshot tests
|
|
|
|
|
../tools/gradle-serial.sh installDebug # install the debug app on the attached phone
|
|
|
|
|
# Server gate, from server/:
|
|
|
|
|
cargo fmt --check && cargo clippy -- -D warnings && cargo test # THE server gate
|
|
|
|
|
# Either directory:
|
|
|
|
|
tools/install-git-hooks.sh # once per checkout
|
|
|
|
|
tools/clean-builds.sh [--dry-run] # delete build output in every checkout and worktree (disk)
|
|
|
|
|
python3 tools/dependency-report/latest.py # version drift of gradle/libs.versions.toml
|
|
|
|
|
tools/clean-builds.sh [--dry-run] # delete Gradle build output in every checkout and worktree (disk)
|
|
|
|
|
python3 tools/dependency-report/latest.py # version drift of android/gradle/libs.versions.toml
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
* **`check` is the single gate.** Every check a plan asks for must be reachable from it. Report gates with the real result lines (BUILD line, actionable tasks, test counts from fresh XML only). Never report a check as passing that you did not run in this session.
|
|
|
|
|
* **One Gradle build at a time.** Parallel builds exhaust memory. Always `tools/gradle-serial.sh`; it waits on a lock in `/tmp` and then runs the wrapper of your worktree.
|
|
|
|
|
* **`tools/gradle-serial.sh check` (Android) and `cargo fmt --check && cargo clippy -- -D warnings && cargo test` (server) are the only gates.** Every check a plan asks for must be reachable from one of them (the OpenAPI match test and the test-vector tests included). Report gates with the real result lines (BUILD line, actionable tasks, test counts from fresh XML only). Never report a check as passing that you did not run in this session.
|
|
|
|
|
* **One Gradle build at a time.** Parallel builds exhaust memory. Always `tools/gradle-serial.sh`; it waits on a lock in `/tmp` and then runs `android/gradlew` of your worktree.
|
|
|
|
|
* **Disk.** Three agents plus the main checkout can fill a disk. `~/.gradle/init.d/cache-retention.gradle.kts` (user-level, outside the repo) keeps `~/.gradle/caches` at 7 days with cleanup on every build; Gradle 9 accepts build-cache retention only there. Run `tools/clean-builds.sh` after removing a worktree or when free space is under about 5 GB. Deleting `~/.gradle/caches/build-cache-1` and old `~/.gradle/caches/<version>` folders is allowed; the next build is a slow full one. An agent that hits "no space left on device" loses only uncommitted work: free space and resume it, do not respawn.
|
|
|
|
|
* **Version drift:** run the dependency report at the start of every plan. A library more than one stable minor behind gets a line in the plan's report; a toolchain component more than one line behind triggers an upgrade plan first.
|
|
|
|
|
* **Screenshots.** Goldens are committed; `check` fails when a render differs. Re-record only for an intended change and **open every changed PNG** before committing. Code that compiles is not evidence of a good screen.
|
|
|
|
|
* **Every schema change gets a migration and a migration test.** User decisions stored in the database are not derived data and must survive every migration.
|
|
|
|
|
* **Every schema change gets a migration and a migration test** (sqlx migration on the server, Room migration on the phone). User data stored in the database is not derived data and must survive every migration.
|
|
|
|
|
* **Contracts are versioned.** A change to any contract file (`contracts/openapi.yaml`, the SQLite schema, the sync protocol, the Room entities, `contracts/test-vectors/*.json`, the push payload) requires a spec version bump and a `docs/decisions.md` entry in the same change. Number both from the brief.
|
|
|
|
|
* **Cargo builds** are not serialised by `gradle-serial.sh`; run at most one `cargo build`/`cargo test` per worktree at a time and never build Docker images for the Pi while a Gradle build runs.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
@@ -99,12 +115,14 @@ python3 tools/dependency-report/latest.py # version drift of gradle/libs.versi
|
|
|
|
|
|
|
|
|
|
Enforced by an architecture check inside `check` where possible. Fill in from SPEC; the shape that worked:
|
|
|
|
|
|
|
|
|
|
* **Layering:** `feature → core:model`, `domain → core:model`, `data → core:model`; only `:app` sees everything. Pure modules (`:core:model`, `:domain:*`) import only `kotlin.*`, `kotlinx.*` and the project's own packages: no `java.time`, no `java.io`, no Android.
|
|
|
|
|
* **Layering (Android):** `feature → core:model, core:design`; `core:design → core:model`; `domain → core:model`; `data → core:model, domain`; `core:fakes → core:model, domain`; `adapter:fcm → core:model`. Only `:app` sees everything and binds the `:data` repositories to the `:core:model` interfaces through Hilt. Features never see `:data` or `:domain` (SPEC §6.2). Pure modules (`:core:model`, `:domain`) import only `kotlin.*`, `kotlinx.*` and the project's own packages: no `java.time`, no `java.io`, no Android.
|
|
|
|
|
* **Vendor SDKs live in one adapter module each** and map to the project's own records inside it. Sources are plugins behind a registry; nothing names a vendor outside its adapter. Source ids are open strings, never enums.
|
|
|
|
|
* **The UI contract is the contract:** features consume `*State` classes through repository interfaces; a contract change is made in the model, the fakes and the real repositories in the same change.
|
|
|
|
|
* **Fakes for every repository**, driven by scenarios, so screens render and screenshot-test without a device. Fakes never reach a release build.
|
|
|
|
|
* **Fast-moving APIs:** confirm current usage from the official documentation at implementation time. Do not rely on memory.
|
|
|
|
|
* **Licences first:** no vendor binary and no model file is committed, bundled or downloaded by a build before the owner has cleared its licence.
|
|
|
|
|
* **Server layering:** `kvitt-domain` has no I/O and depends only on `serde` (and `uuid` for ids); `kvitt-server` and `kvitt-import` depend on it, never the reverse. Money and split rules exist only in `kvitt-domain` and `:domain`, and both pass the same `contracts/test-vectors/*.json`.
|
|
|
|
|
* **No `unwrap()`/`expect()` in server non-test code** except in `main` start-up; no `unsafe`; errors map to the error codes of SPEC §14.3.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
@@ -117,7 +135,7 @@ Enforced by an architecture check inside `check` where possible. Fill in from SP
|
|
|
|
|
* **No hard-coded colours, sizes or strings in feature modules.** Tokens from one design file; strings from resources, every supported language.
|
|
|
|
|
* **No placeholder text** in previews or screenshots.
|
|
|
|
|
* **No assumptions:** read a file before modifying or citing it.
|
|
|
|
|
* **Never commit:** `local.properties`, keystores, `.aar` or other vendor binaries, model files, client ids, tokens, personal data.
|
|
|
|
|
* **Never commit:** `local.properties`, keystores, `.aar` or other vendor binaries, model files, client ids, tokens, personal data, `google-services.json`, service-account keys, TLS keys, SQLite databases, backups, the Splitwise CSV, built APKs.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
