Files
herdrMario/docs/superpowers/plans/2026-11-19-unified-prompt.md
2026-11-19 10:49:54 +01:00

20 KiB
Raw Permalink Blame History

Herdr Unified Prompt Experience — plan implementacji

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Rozbudować mod ovis-composer o zaakceptowany Unified Prompt Experience (fokus „tam, gdzie klik”, trwałe drafty, History|Favorites, jeden potok załączników z Ctrl+V i „+”, kolejka z odliczaniem, kontekst) bez rekompilacji Herdr.

Architecture: Logika w czystych modułach ES (bez gpui-kit/herdr), testowana w Node (node --test). main.js tylko wiąże je z GPUI i hc. Źródła w repo herdrMario/mod/ovis-composer, podpięte do ~/.config/herdr-app/mods/ovis-composer przez junction. Layout ovis-composer (klon main) i wpis w keys.json.

Tech Stack: gpui-kit / gpui-base (TextareaState, openOverlay, v_virtual_list), API herdr (agents, focused, hc, exec, shared/setShared, nextCommand), PowerShell 5 (schowek, OpenFileDialog), Node ≥ 20 (node --test).

Spec: docs/superpowers/specs/2026-11-19-unified-prompt-design.md · Makieta (zaakceptowana, bramka B): docs/mockups/herdr-unified-prompt.html

Role: zadania wykonuje Fast (sub-agent, model Sonnet); Opus (ta sesja) robi review każdego zadania i review całej gałęzi. Fast nie zmienia architektury ani UX — problem spoza zadania → STOP i raport do Opus.

Global Constraints

  • Bez rekompilacji Herdr; nie edytować plików shipped (layouts/main.json, mods/<shipped>/*, frame/).
  • Praca tylko na gałęzi feature/unified-prompt repo herdrMario; nic na main.
  • Zmiany w ~/.config/herdr-app tylko: junction mods/ovis-composer, layouts/ovis-composer.json, wpis w keys.json. Przed każdą zmianą kopia zapasowa (<plik>.bak-20261119).
  • Moduły czyste (state, delivery, storage, suggest, catalog, attachments, view, nowe history, clipboard, keys) nie importują gpui-kit, gpui-base, herdr.
  • Klucz kontekstu = adres agenta (AgentInfo.address, np. t2); tożsamość terminala = address + created_ms z hc get <t> --json.
  • Komunikaty UI po polsku, zgodne z makietą (dosłowne teksty w zadaniach).
  • Limity: plik 32 MiB, 100 plików na akcję, 20 000 znaków (attachments.LIMITS); historia 500, ulubione 100 (storage).
  • Obrazy ze schowka: ~/.config/herdr-app/data/ovis-composer/paste/, sprzątanie plików starszych niż 7 dni przy starcie modu.
  • Odliczanie przed automatyczną wysyłką z kolejki: 3 s.
  • Programy obsługujące obrazy (AgentInfo.app): claude-code, codex, gemini, opencode.
  • Każde zadanie kończy: node --test tests/ zielone + herdr-app check C:\Users\Factor\.config\herdr-app\mods\ovis-composer bez błędów + herdr-app status z "errors": [].

Review Focus

  1. Fokus w terminalu + Ctrl+V / / / @ / Enter → composer nic nie robi (Task 2: test keyIntent z hasKeyboard:false → "none").
  2. Restart Herdr w trakcie sending → po starcie wpis uncertain, nigdy automatycznie wysłany (Task 4: test onRestart + countdown nie startuje dla uncertain).
  3. Nowy terminal dostaje stary adres → kolejka cała held, draft z komunikatem (Task 3: test restoreFor z innym created_ms).
  4. Schowek pusty / tylko HTML bez tekstu / pliki z Eksploratora → odpowiednio komunikat / tekst / ścieżki (Task 6: testy parseClipboardResult).
  5. Ścieżka ze spacjami i polskimi znakami w @mention i w hc put (Task 6: test mention("D:\\Dev ws\\zrzut ęą.png") zgodny z removeMention).

Task 1: Repo, junction, testy bazowe

Files:

  • Create: mod/ovis-composer/* (kopia z ~/.config/herdr-app/mods/ovis-composer, bez gpui-kit.d.ts), package.json ({"type":"module","private":true,"scripts":{"test":"node --test tests/"}}), .gitignore (mod/ovis-composer/gpui-kit.d.ts, node_modules/), layouts/ovis-composer.json (kopia), scripts/install.ps1, README.md (instalacja/wycofanie)
  • Test: tests/state.test.mjs, tests/delivery.test.mjs, tests/storage.test.mjs, tests/suggest.test.mjs, tests/attachments.test.mjs, tests/view.test.mjs

Interfaces: Produces: ścieżki importu w testach ../mod/ovis-composer/<modul>.js; scripts/install.ps1 (idempotentny: backup mods\ovis-composer → mods\ovis-composer.bak-20261119 jeśli nie jest junction, cmd /c mklink /J, kopia layoutu, wpis klawisza z Task 2; przełącznik -Uninstall — patrz „Wycofanie”).

  • Step 1: Skopiuj mod i layout do repo; dodaj package.json, .gitignore.
  • Step 2: Testy charakteryzujące obecne zachowanie modułów czystych (min. 3 na moduł, m.in.: decide("idle")→send, decide("working")→queue; onRestart zamienia sending→uncertain; saveHistory obcina do 500; detect("ala /re",7) wykrywa /; validate({bytes:33*2**20}) → błąd „Plik przekracza limit 32 MiB”; targetAgent po focused.terminal).
  • Step 3: Run npm test → PASS (testy opisują stan obecny; jeśli któryś pada, to błąd w teście — popraw test, nie moduł).
  • Step 4: scripts/install.ps1; uruchom; sprawdź cmd /c dir C:\Users\Factor\.config\herdr-app\mods → <JUNCTION> ovis-composer.
  • Step 5: herdr-app do layout.switch '{"name":"ovis-composer"}'; herdr-app check …\mods\ovis-composer → OK; herdr-app status → "layout": "ovis-composer", "errors": [].
  • Step 6: Commit chore: import ovis-composer into repo with baseline tests.

Task 2: Fokus „tam, gdzie klik” i klawisze

Files:

  • Create: mod/ovis-composer/keys.js · Test: tests/keys.test.mjs
  • Modify: mod/ovis-composer/main.js (init: bind_keys, focus()/timer.after(600…), watchFocus, reclaim, debug notice("dbg down…") w pętli nextCommand; key(); submitted()), scripts/install.ps1 (klawisz)

Interfaces:

  • Produces: keyIntent(e: {key:string, shift:boolean, ctrl:boolean, alt:boolean, composing:boolean}, ctx: {hasKeyboard:boolean, menuOpen:boolean, panelOpen:boolean, empty:boolean, status:Status|null}) → "none"|"send"|"send_now"|"hold"|"newline"|"interrupt"|"close_menu"|"close_panel"|"open_panel"|"menu_up"|"menu_down"|"menu_accept".

  • Step 1: Testy keys.test.mjs: hasKeyboard:false → zawsze "none" (Enter, v+ctrl, Escape); composing:true → "none"; Enter→send; Shift+Enter→newline; Ctrl+Enter→send_now; Alt+Enter→hold; Escape+menuOpen→close_menu; Escape+panelOpen→close_panel; Escape+empty+working→interrupt; Escape+niepuste+working→none; Ctrl+R→open_panel; Tab+menuOpen→menu_accept; ArrowUp+menuOpen→menu_up; ArrowUp bez menu→none.

  • Step 2: npm test → FAIL (brak keys.js).

  • Step 3: Zaimplementuj keyIntent w keys.js.

  • Step 4: npm test → PASS.

  • Step 5: main.js: usuń watchFocus, reclaim, focus() w init i timer.after(600…), debug notice; usuń wiązanie ctrl-c (Ctrl+C = kopiuj); dodaj bind_keys w kontekście Input: ctrl-r→ovis-composer.panel, ctrl-enter→ovis-composer.send_now, alt-enter→ovis-composer.hold, escape→ovis-composer.escape; obsługa w pętli nextCommand przez keyIntent (tylko gdy this.hasKeyboard); komenda focus → this.textarea.focus().

  • Step 6: install.ps1: dopisz do keys.json → "global": {"ctrl-shift-space": "ovis-composer.focus"} (merge JSON, backup). Sprawdź keys.error nie istnieje.

  • Step 7 (ręcznie, raport ze zrzutami herdr-app shot): klik w terminal → pisanie trafia do terminala, composer nie odzyskuje fokusu przez 10 s; Ctrl+Shift+Space → fokus w composerze; Ctrl+C w composerze kopiuje zaznaczenie.

  • Step 8: Commit feat: focus follows click, composer key intents.

Task 3: Trwałe drafty i tożsamość agenta

Files: Modify: mod/ovis-composer/storage.js, state.js, main.js (syncAgent, changed) · Test: tests/storage.test.mjs, tests/state.test.mjs

Interfaces:

  • Produces (storage.js): KEYS.draft = "ovis-composer.draft"; draftKey(agent:string) → "ovis-composer.draft:<agent>"; loadDraft(store, agent) → Draft|null; saveDraft(store, agent, draft:Draft); typ Draft = {text:string, caret:number, attachments:Attachment[], identity:{created_ms:number|null, app:string|null}, savedAt:number}.

  • Produces (state.js): akcja {type:"restore_draft", agent, draft, identity} → gdy identity.created_ms różne od zapisanego: draft przywrócony, notice = {text:"Szkic z poprzedniej sesji agenta", level:"warn"}, cała kolejka agenta → held; gdy zgodne: przywrócony bez komunikatu.

  • Consumes: hc(["get", address, "--json"]) → created_ms (zmierzone 2026-11-19).

  • Step 1: Testy: round-trip saveDraft/loadDraft; śmieci w store ("x", []) → null; restore_draft z innym created_ms → kolejka held + notice; zgodny → bez notice; tekst > 20 000 znaków zachowany w całości (limit dotyczy wysyłki, nie draftu).

  • Step 2: FAIL → Step 3: implementacja → Step 4: PASS.

  • Step 5: main.js: zapis draftu z opóźnieniem 500 ms po change i natychmiast przy zmianie agenta; przy syncAgent odczyt created_ms (cache per adres) i restore_draft.

  • Step 6 (ręcznie): wpisz tekst → zamknij i otwórz Herdr → tekst wraca; przełącz agenta i wróć → tekst i kursor wracają.

  • Step 7: Commit feat: persistent per-agent drafts with identity check.

Task 4: Kolejka — blocked, odliczanie, stop

Files: Modify: delivery.js, state.js, view.js (queueLabel), main.js (watch, interrupt, renderQueue*) · Test: tests/delivery.test.mjs, tests/state.test.mjs, tests/view.test.mjs

Interfaces:

  • decide(status): blocked → {kind:"send"} (zmiana; kolejka i tak nie startuje — patrz niżej).

  • Nowy stan wpisu "countdown" z polem left:number. Akcje state.js: {type:"countdown_start", agent, id} (tylko pierwszy queued, tylko gdy brak countdown/sending), {type:"countdown_tick", agent, id} (left−1), {type:"countdown_cancel", agent, id} → held, {type:"hold_all", agent} (queued/countdown → held).

  • delivery.shouldDrain(prev:Status, next:Status, stoppedByComposer:boolean) → boolean: true tylko dla working|blocked → idle|done i !stoppedByComposer.

  • queueLabel(item): queued→„Następna tura”, held→„Wstrzymana — wyślij ręcznie”, sending→„Wysyłanie…”, uncertain→„Nie potwierdzono”, countdown→„Wysyłam za {left} s”.

  • Step 1: Testy: shouldDrain (tabela 4×4 + flaga); countdown_start gdy istnieje uncertain jako pierwszy → startuje od pierwszego queued, uncertain nietknięty; countdown_cancel → held; hold_all; onRestart z countdown → held (po restarcie nic nie wysyła się samo), z sending → uncertain; etykiety.

  • Step 2: FAIL → Step 3: implementacja → Step 4: PASS.

  • Step 5: main.js: zegar 1 s dla countdown (cx.timer.every), po left==0 → istniejący drain/send; przycisk „Anuluj” na wierszu; Stop/Esc (hc interrupt) ustawia stoppedByComposer dla najbliższego przejścia i hold_all + notice „Przerwano agenta. Kolejka wstrzymana — nic nie wyśle się samo.”; Enter przy blocked wysyła od razu.

  • Step 6 (ręcznie, Claude Code w Herdr): 2 wiadomości w kolejce podczas pracy → po turze odliczanie 3 s → wysyłka pierwszej, druga czeka na następną turę; Anuluj → wstrzymana; Ctrl+C w terminalu → odliczanie się pojawia; Stop z composera → kolejka held.

  • Step 7: Commit feat: queue countdown, hold on stop, reply when blocked.

Task 5: Historia i ulubione — model

Files: Create: mod/ovis-composer/history.js · Modify: storage.js · Test: tests/history.test.mjs

Interfaces:

  • HistoryEntry = {id, text, sentAt:number, agent:string, agentName:string, space:string, spaceName:string}; Favorite = {id, text, createdAt:number}.

  • record(list:HistoryEntry[], entry) → HistoryEntry[] (duplikaty zachowane, limit 500, najstarsze wypadają).

  • search(list, query:string) → {item, ranges:[start,end][]}[] — bez wielkości liter, fragmenty, wszystkie wystąpienia, kolejność od najnowszych (sentAt/createdAt malejąco); pusty query → wszystko.

  • toggleFavorite(favs:Favorite[], text:string, now:number) → Favorite[] (po text.trim(), limit 100); isFavorite(favs, text) → boolean.

  • Migracja: loadHistory akceptuje stare wpisy bez space/agentName (pola → "").

  • Step 1: Testy: duplikaty; limit 500; search("TEST") znajduje „uruchom testy” z ranges [[8,12]]; dwa wystąpienia → dwa zakresy; polskie znaki ("ŁÓDŹ" vs "łódź"); pusta lista; toggle dodaje/usuwa; stare wpisy.

  • Step 2: FAIL → Step 3: implementacja → Step 4: PASS.

  • Step 5: main.js: wpis do historii po hc send z kodem 0 i bez error w JSON (hcOk), z space_name i tab_name z AgentInfo.

  • Step 6: Commit feat: history and favorites model.

Task 6: Jeden potok załączników + Ctrl+V + „+”

Files: Create: mod/ovis-composer/clipboard.js · Modify: attachments.js, main.js (drop → addFiles) · Test: tests/clipboard.test.mjs, tests/attachments.test.mjs

Interfaces:

  • clipboardScript(outDir:string, stamp:string) → string — PowerShell (-NoProfile -STA): najpierw Clipboard::GetFileDropList() → wypisz FILES\t<path> na linię; inaczej Clipboard::GetImage() → zapisz <outDir>\paste-<stamp>.png → IMAGE\t<path>; inaczej NONE.

  • parseClipboardResult({code, stdout, stderr}) → {kind:"image", paths:[string]}|{kind:"files", paths:string[]}|{kind:"none"}|{kind:"error", message:string}.

  • pickerScript() → string (OpenFileDialog, Multiselect=$true, wypisuje ścieżki po linii; Anuluj → pusto); parsePickerResult(res) → string[].

  • staleFiles(entries:{path, mtimeMs}[], now:number, maxAgeMs=7*864e5) → string[].

  • supportsImages(app:string|null) → boolean (lista z Global Constraints).

  • main.js: addFiles(paths:string[], origin:"drop"|"paste"|"picker", cx) — jedyne wejście; walidacja → kafelek adding → hc put <agent> <path> --json → ready + mention / error + Ponów.

  • Step 0 (spike, ręcznie, przed kodem): tymczasowy on("paste_other", …) z notify; skopiuj obraz z przeglądarki, Snipping Tool i Eksploratora (plik) → czy zdarzenie odpala? Zmierz czas exec powershell ze skryptem. Jeśli paste_other nie odpala w którymkolwiek przypadku → STOP, raport do Opus.

  • Step 1: Testy: parse IMAGE\tC:\…\paste-1.png; FILES z dwiema ścieżkami (spacje, polskie znaki); NONE; kod ≠ 0 → error ze stderr; picker anulowany → []; staleFiles (6 dni zostaje, 8 dni usunięte); supportsImages("claude-code"), supportsImages("aider")===false; mention/removeMention dla ścieżki ze spacją i ęą (Review Focus 5).

  • Step 2: FAIL → Step 3: implementacja → Step 4: PASS.

  • Step 5: main.js: paste_other → exec("powershell", ["-NoProfile","-STA","-Command", clipboardScript(...)]) → addFiles(..., "paste"); none → notice „Schowek nie zawiera tekstu ani obrazu, który można wkleić.”; przycisk „+” → pickerScript → addFiles(..., "picker"); on_drop → addFiles(..., "drop"); sprzątanie paste/ przy starcie; ostrzeżenie przy wysyłce obrazu do agenta bez supportsImages: „{program} może nie obsługiwać obrazów — obraz trafi do agenta tylko jako ścieżka w tekście.” + [Anuluj] [Wyślij mimo to].

  • Step 6 (ręcznie, end-to-end): Ctrl+V zrzutu ekranu w composerze → miniatura → wyślij do Claude Code z pytaniem „co jest na obrazie?” → agent poprawnie opisuje treść (zrzut odpowiedzi w raporcie). To samo dla Drag & Drop i „+”. Ctrl+V tekstu działa jak dotąd. Ctrl+V z fokusem w terminalu — composer nic nie dodaje.

  • Step 7: Commit feat: unified attachment pipeline with clipboard image and file picker.

Task 7: UI — panel Historia | Ulubione, podgląd obrazu, kontekst

Files: Create: mod/ovis-composer/panel.js (widok panelu: GPUI, bez logiki), Modify: main.js (renderCard, renderFiles, renderContext, przycisk 🕘 i ☆) · Test: brak nowych czystych testów (logika w history.js); weryfikacja ręczna + herdr-app shot

Interfaces: Consumes: search, toggleFavorite, isFavorite (Task 5); keyIntent (Task 2). Wstawianie: this.textarea.replace(text) (zastępuje zaznaczenie / wstawia w kursorze), potem focus().

  • Step 1: Panel nad composerem (wzór: makieta, pop hist): zakładki „Historia N | Ulubione N”, pole „Szukaj w historii…”, lista v_virtual_list (wysokość stała z kontenera), wiersz: tekst 2 linie z podświetleniem ranges, meta DD.MM HH:MM · przestrzeń · agent / zapisano DD.MM HH:MM, gwiazdka; stopka ze skrótami. Stany: „Historia jest pusta”, „Brak ulubionych”, „Brak wyników dla „{q}”” + „wyczyść wyszukiwanie”.
  • Step 2: Klawisze w panelu: ↑/↓, Enter → wstaw w miejscu zapamiętanego kursora (nie wysyła) + notice „Wstawiono w miejscu kursora — nic nie zostało wysłane. Ctrl+Z cofa.”, Tab → przełącz zakładkę, Esc → zamknij i przywróć kursor. Sprawdź, czy Ctrl+Z w Textarea cofa replace; jeśli nie — usuń „Ctrl+Z cofa.” z komunikatu i zgłoś w raporcie (odstępstwo od makiety → decyzja Opus).
  • Step 3: Przycisk ☆ przy edytorze (toggle bieżącego tekstu), „Edytuj” w kolejce → replace w kursorze (Task 4 wiersz).
  • Step 4: Miniatury image(localPath) 36×36, klik → overlay podglądu (fit: contain, nazwa · rozmiar · „Esc zamyka”).
  • Step 5: Pigułka kontekstu: kropka statusu + nazwa karty + słowo statusu + 📎N; pasek: przestrzeń · folder · ⑂ gałąź (z panes()); fokus na terminalu nie-agenta → pole nieaktywne, placeholder „Ten terminal nie jest agentem. Wybierz agenta z listy, aby pisać.”, draft zachowany.
  • Step 5a: Edytor: set_auto_grow(1, 10) (dziś 1–6); blok composer w layouts/ovis-composer.json → "size": {"px": 260}, "min": 120, "max": 520 i rodzic work z "resizable": true (ręczna zmiana wysokości przeciąganiem granicy); po zmianie layout.error nie istnieje.
  • Step 6: herdr-app check OK; herdr-app shot każdego stanu (pusty, wpisany, panel historii, brak wyników, załączniki, kolejka z odliczaniem, nie-agent) → raport do porównania z makietą.
  • Step 7: Commit feat: history/favorites panel, image preview, context strip.

Task 8: Regresja i weryfikacja końcowa (Fast), review gałęzi (Opus)

Files: Create: docs/superpowers/verification/2026-11-19-unified-prompt.md (wyniki)

  • Step 1: npm test — pełny wynik w raporcie.
  • Step 2: Lista ręczna (z wynikiem i zrzutem): scenariusze 1–7 z makiety; terminal PowerShell: pisanie, Ctrl+C, Ctrl+V tekstu, wklejanie obrazu do Claude Code wprost w terminalu (natywne zachowanie Herdr nietknięte); przełączenie layoutu main ↔ ovis-composer bez błędów; restart Herdr w trakcie sending → uncertain.
  • Step 3: Dowód braku rekompilacji: git -C <herdr> nie dotyczy — w raporcie herdr-app --version przed i po (ta sama wersja) + lista zmienionych plików w ~/.config/herdr-app (tylko junction, layout, keys.json).
  • Step 4: Commit raportu. Opus: niezależny review całej gałęzi (superpowers:requesting-code-review), status APPROVED / CHANGES_REQUIRED / BLOCKED.

Wycofanie

scripts/install.ps1 -Uninstall: usuń junction, przywróć mods\ovis-composer.bak-20261119, przywróć keys.json.bak-20261119, herdr-app do layout.switch '{"name":"main"}'.