kvitt/prompts/README.md

Start prompts

One ready-to-paste start prompt per plan (PLAN-<id>.md at the repository root), plus ORCHESTRATOR-prompt.md. Before pasting, the orchestrator fills {{NEXT_DECISION}}, {{SPEC_VERSION}}, {{SCHEMA_VERSION}} (disjoint ranges for agents that run in parallel, CLAUDE.md › Numbering) and {{ORCHESTRATOR_NOTES}} (answers to the plan's open points, phone assignment, overrides). U2.md also takes {{OWNER_PICK_AND_COMMENTS}}. U1 and U2 run in the owner's own Claude session in ~/orca/workspaces/kvitt/UX-sprint on branch UX-sprint. The numbers are for proposed entries in agents' reports: implementation agents never edit SPEC.md or docs/decisions.md; a docs agent records what the orchestrator accepts (CLAUDE.md › Orchestration).

Dependencies follow SPEC §11.1 and §11.2 (v0.22). Status as of 2026-10-19: M0 done, M1 landed (c6df2ab), M2c-dev landed (c885aba), M2a landed (06f48ef), M2b landed (c277ee3), M3 landed (7869ec4), M5 landed (8f0e156), M4 landed (15056dc), M9 landed (50339ae); SPEC v0.7 landed (86e08a1); M12a landed (aa765bb); SPEC v0.8 landed (d39eb2c); M12c landed (b09f322); M12b landed (6eaccec); U1 and U2 landed (6da6b1b, owner approved); SPEC v0.9 landed (e676812); M12d landed (557af7e); M6 landed (7730a31); SPEC v0.10 landed (9ee67d4); M7a landed (1ea752c), M7e (ea7d494), M7d (7380e50), M7b (0e1d99d), M7c (0b140aa), M7f (c4ab35f); M6b :core:design fixes landed (b24c8b5); SPEC v0.11 landed (f4dc10c, the M7 and M6b outcomes, D-069 to D-080); M7g feature cleanups landed (3dda414, no prompt file; brief by the orchestrator); M8 landed (cb832a7, 3d9eea8), its on-phone test still to run; SPEC v0.12 records the M8 outcomes (D-081 to D-085); the M12e contract pass (no prompt file; brief by the orchestrator) landed (8c60715, b7b7483); SPEC v0.13 records its outcomes (D-086 to D-095, server schema 3) and landed (51d6ff8); the Vico removal (a312758), the FCM fid target (f56dcbe) and the Pi image arm64 check (3e6c337) landed; SPEC v0.14 records them (D-096); the M8 phone test ran on 2026-10-18 and M8b UI fixes landed (328c466, D-097) with the fid follow-up (6eb3f85); SPEC v0.15 records them and D-100 (M2c-pi as an owner-run bundle) and D-101 (keystore at the repository root). The plans' open points are resolved in SPEC v0.3 and recorded in each plan's §4; v0.4 records the M2a and M2b decisions (D-005 to D-014); v0.5 the M3 and M5 decisions (D-026 to D-034, D-040 to D-043); v0.6 the M4 decisions (D-035 to D-039); v0.7 the M9 decisions (D-044 to D-046); v0.8 the owner's UX-session decisions (D-047 to D-054) and the milestone group M12; v0.9 D-055 to D-059 and M12d; v0.10 D-060 to D-068; v0.11 D-069 to D-080; v0.12 D-081 to D-085; v0.13 D-086 to D-095; v0.14 D-096; v0.15 D-097, D-100, D-101; after v0.15 M8c (75b549f, a0c25b0, 7c453d8; goldens in three variants at 1x, the S-22 licences row removed), the R8 release build (c30a49e) and M8d (bacbd18, S-7 editor rows) landed; SPEC v0.16 records them (D-098, D-099, D-102) and landed (bfc3acb); the M2c-pi bundle (2476667, D-103 to D-106), M8e (a59abeb, D-107), the Dockerfile CARGO_BUILD_JOBS argument (b4d9467), M8f (956908a, D-108, instant navigation) and the chips cleanup (1328afe) landed; SPEC v0.17 records them (D-103 to D-108); what remains of M2c-pi is the owner running the bundle on the Kvitt Pi, then M10; v0.16 D-098, D-099, D-102; v0.17 D-103 to D-108; after v0.17 the history rewrite and first push to origin (18c527f, all later hashes in this file are the rewritten ones), the infra overhaul (2fac1ec to e70fe0d), the server gap pass (8660b7f, D-113), the infra security fixes (7fb86f5, D-117) and M12f (dc7a296 to a0259ab, D-109 to D-112, D-116; no prompt file, orchestrator brief) landed; SPEC v0.18 records them with the AC-coverage audit and the security review (docs/validation/); the server overhaul (8103dae to b985ce9, D-114, D-115) landed too and is recorded in v0.18; the Android overhaul (e4e6e5d to c582363, D-118; no prompt file, orchestrator brief) landed and was pushed to origin at c582363; SPEC v0.19 records it (3ef2c15); the APK download rate limit (96e4cbd, D-119; no prompt file, orchestrator brief) landed and was pushed to origin; SPEC v0.20 records it with the owner's security-review answers; cargo audit joined the server gate (f1abb0d); the NPM rework (4f69ae0, d05f13a, 62f5279, 9231a1d, D-120; no prompt file, orchestrator brief) replaced Caddy and cert-sync with an Nginx Proxy Manager proxy host on the Home Assistant Pi and reshaped the M2c-pi bundle (PLAN-M2c-pi.md carries a superseded-in-part note); the Android host property (d090c6c, D-121; no prompt file, orchestrator brief) landed; SPEC v0.21 records them (4bcff2c); the D-121 follow-ups (4a4e45f S-22's release server, 4b1ae0c infra/publish-apk.sh host, D-122), the server's host defaults and the OpenAPI {host} server (c9abd24, e381e37, D-123), the temporary workflow diagnostic step (dd07ca4) and the install.sh step number (ac17b41) landed (no prompt files, orchestrator briefs) and were pushed to origin at ac17b41; SPEC v0.22 records them with the owner's Kvitt host name kvitt.suorra.duckdns.org (HANDOFF). What remains is the owner's M2c-pi run on the Kvitt Pi (deferred by the owner until he moves over), then M10 and M11.

Dependency order and waves

Plans in the same wave can run in parallel (they own disjoint paths, SPEC §14.7). Android agents share one Gradle build at a time (tools/gradle-serial.sh) and one agent on the phone at a time.

Wave	Plan	Prompt	Depends on	Parallel with
0	M1 Contracts and vectors	M1.md	M0	done (c6df2ab)
0	U1 UX directions	U1.md	M0	done (6da6b1b)
1	M2a Server skeleton and kvitt-domain	M2a.md	M1	done (06f48ef)
1	M2b Android skeleton and :domain	M2b.md	M1	done (c277ee3); installDebug on the phone outstanding
1	M2c-dev Infra for development	M2c-dev.md	M0 (its health check needs M2a's image)	done (c885aba)
1	U2 UX design spec	U2.md	U1 and the owner's pick	done (6da6b1b)
2	M3 Server core API	M3.md	M2a	done (7869ec4)
2	M4 Server sync, audit, push, scheduler	M4.md	M2a; lands after M3 (D-015)	done (15056dc)
2	M5 Android data layer	M5.md	M1, M2b	done (8f0e156)
2	M12a Category contract v2: contracts	M12a.md	M1, SPEC v0.8	done (aa765bb)
2	M12b Category contract v2: server	M12b.md	M12a (M3, M4, M9 landed)	done (6eaccec)
2	M12c Category contract v2: Android	M12c.md	M12a (M2b, M5 landed)	done (b09f322)
2	M12d UI contract additions (UX-9)	M12d.md	M12c, SPEC v0.9	done (557af7e)
2	M6 Design system	M6.md	U2 approved, M2b, M12c, the §9.7 colour spec change (v0.9)	done (7730a31)
3	M7a Feature onboarding	M7a.md	M6, M12d	done (1ea752c)
3	M7b Feature home and account	M7b.md	M6, M12d	done (0e1d99d)
3	M7c Feature expense	M7c.md	M6, M12c, M12d	done (0b140aa)
3	M7d Feature settle	M7d.md	M6, M12d	done (7380e50)
3	M7e Feature analytics	M7e.md	M6, M12d	done (ea7d494)
3	M7f Feature settings	M7f.md	M6, M12d	done (c4ab35f)
3	M9 Splitwise importer	M9.md	M2a, M4	done (50339ae)
3	M6b Design-system fixes after M7	none (orchestrator brief)	M7a to M7f	done (b24c8b5)
4	M7g Feature cleanups	none (orchestrator brief)	M7a to M7f, M6b	done (3dda414)
4	M8 App integration	M8.md	M3, M4, M5, M7a to M7f, M2c-dev	done (cb832a7, 3d9eea8); on-phone test run 2026-10-18; M8b fixes 328c466; M8c 75b549f, a0c25b0, 7c453d8; M8d bacbd18; M8e a59abeb; M8f 956908a; chips cleanup 1328afe (no prompt files; briefs by the orchestrator)
4	M12e Contract pass	none (orchestrator brief)	M8, SPEC v0.12 (§11.3 list)	done (8c60715, b7b7483)
4	M12f Audit and security follow-ups (Android)	none (orchestrator brief)	M8f, AC-coverage audit, security review	done (dc7a296, 5b2ed37, 2bd6b58, c366fbd, a0259ab; D-109 to D-112, D-116)
4	Server gap pass; infra overhaul; infra security	none (orchestrator briefs)	M2c-pi bundle, security review	done (8660b7f, D-113; 2fac1ec to e70fe0d; 7fb86f5, D-117); server overhaul 8103dae to b985ce9 (D-114, D-115); Android overhaul e4e6e5d to c582363 (D-118); APK download rate limit 96e4cbd (D-119); cargo audit f1abb0d; NPM rework 4f69ae0 to 9231a1d (D-120); Android host property d090c6c (D-121); its follow-ups 4a4e45f, 4b1ae0c (D-122); server host defaults c9abd24, e381e37 (D-123)
5	M2c-pi Infra on the Pi (bundle infra/pi/, D-100)	M2c-pi.md	M2c-dev, M8; runs last, after the app is proven	bundle done (2476667, D-103 to D-106); reshaped by the NPM rework (4f69ae0 to 9231a1d, D-120; the plan is superseded where it names Caddy and cert-sync); the owner's run on the Pi remains, deferred by the owner
6	M10 First release	M10.md	M2c-pi, M3, M4, M8	none
7	M11 Import history	M11.md	M9, M10	none

Constraints the orchestrator must keep in mind

• M3 and M4 (D-015): M2a provides next_occurrence_date, the AuditWriter/PushQueue traits with no-op implementations and tasks::start; M3 writes the recurring generation function and calls the traits; M4 replaces the implementations, its scheduler calls M3's function, and M4 lands after M3.
• M2a and M2b create shell files and modules in later milestones' paths (D-004); ownership passes on when they land.
• M7a to M7f (landed) follow the feature convention of SPEC §6.2 (D-017) and take the ledger rows and expense editor fields from M6's :core:design (D-019); their readings are D-069 to D-074 and D-080, the shared fixes went into M6b (b24c8b5, D-075 to D-079). Their contract requests are on the M12e list in SPEC §11.3.
• M8 (landed) wired the navigation of SPEC §13.2 (D-071) and deleted the debug fakes module; both variants bind :data (D-081). Its outcomes are D-081 to D-085; its contract requests are on the M12e list in SPEC §11.3.
• M6 landed 7730a31 (D-063 to D-066): charts on Canvas, Expressive fallbacks against material3 1.4.0, formatting tables in code, one golden per sheet × theme × language (+200 %), which M7a to M7f follow. Its M8 contract requests are in SPEC §11.3.
• M12 (D-054): done; the importer test category_table_matches_the_spec is green again since M12b (6eaccec). M12d (D-059) landed 557af7e (D-060 to D-062); M7a to M7f run on top of both.
• Phone: M2b (one installDebug), M5 (only if instrumented tests), M8 and M10 use the phone; only one at a time, named in the notes. M8's on-phone test was run by the orchestrator with the owner on 2026-10-18; M12e did not use the phone; its APK needs a schema-3 server (SPEC §14.8), and the dev server already runs it.
• Outside the repository: M2c-dev (D-022, done), M2c-pi needs none: it writes the infra/pi/ bundle and the owner runs it on the Pi (D-100, revises D-023); M8 (dev server on the Mac), M10 and M11 (production) need the owner's allowance in the notes.