20 KiB
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-promptrepoherdrMario; nic namain. - Zmiany w
~/.config/herdr-apptylko: junctionmods/ovis-composer,layouts/ovis-composer.json, wpis wkeys.json. Przed każdą zmianą kopia zapasowa (<plik>.bak-20261119). - Moduły czyste (
state,delivery,storage,suggest,catalog,attachments,view, nowehistory,clipboard,keys) nie importujągpui-kit,gpui-base,herdr. - Klucz kontekstu = adres agenta (
AgentInfo.address, np.t2); tożsamość terminala =address+created_mszhc 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-composerbez błędów +herdr-app statusz"errors": [].
Review Focus
- Fokus w terminalu + Ctrl+V /
//@/ Enter → composer nic nie robi (Task 2: testkeyIntentzhasKeyboard:false→"none"). - Restart Herdr w trakcie
sending→ po starcie wpisuncertain, nigdy automatycznie wysłany (Task 4: testonRestart+ countdown nie startuje dlauncertain). - Nowy terminal dostaje stary adres → kolejka cała
held, draft z komunikatem (Task 3: testrestoreForz innymcreated_ms). - Schowek pusty / tylko HTML bez tekstu / pliki z Eksploratora → odpowiednio komunikat / tekst / ścieżki (Task 6: testy
parseClipboardResult). - Ścieżka ze spacjami i polskimi znakami w
@mentioni whc put(Task 6: testmention("D:\\Dev ws\\zrzut ęą.png")zgodny zremoveMention).
Task 1: Repo, junction, testy bazowe
Files:
- Create:
mod/ovis-composer/*(kopia z~/.config/herdr-app/mods/ovis-composer, bezgpui-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;onRestartzamieniasending→uncertain;saveHistoryobcina do 500;detect("ala /re",7)wykrywa/;validate({bytes:33*2**20})→ błąd „Plik przekracza limit 32 MiB”;targetAgentpofocused.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, debugnotice("dbg down…")w pętlinextCommand;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 (brakkeys.js). -
Step 3: Zaimplementuj
keyIntentwkeys.js. -
Step 4:
npm test→ PASS. -
Step 5:
main.js: usuńwatchFocus,reclaim,focus()winititimer.after(600…), debug notice; usuń wiązaniectrl-c(Ctrl+C = kopiuj); dodajbind_keysw kontekścieInput:ctrl-r→ovis-composer.panel,ctrl-enter→ovis-composer.send_now,alt-enter→ovis-composer.hold,escape→ovis-composer.escape; obsługa w pętlinextCommandprzezkeyIntent(tylko gdythis.hasKeyboard); komendafocus→this.textarea.focus(). -
Step 6:
install.ps1: dopisz dokeys.json→"global": {"ctrl-shift-space": "ovis-composer.focus"}(merge JSON, backup). Sprawdźkeys.errornie 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); typDraft = {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}→ gdyidentity.created_msróż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_draftz innymcreated_ms→ kolejkaheld+ 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 pochangei natychmiast przy zmianie agenta; przysyncAgentodczytcreated_ms(cache per adres) irestore_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 polemleft:number. Akcjestate.js:{type:"countdown_start", agent, id}(tylko pierwszyqueued, tylko gdy brakcountdown/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:truetylko dlaworking|blocked → idle|donei!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_startgdy istniejeuncertainjako pierwszy → startuje od pierwszegoqueued,uncertainnietknięty;countdown_cancel→held;hold_all;onRestartzcountdown→held(po restarcie nic nie wysyła się samo), zsending→uncertain; etykiety. -
Step 2: FAIL → Step 3: implementacja → Step 4: PASS.
-
Step 5:
main.js: zegar 1 s dlacountdown(cx.timer.every), poleft==0→ istniejący drain/send; przycisk „Anuluj” na wierszu; Stop/Esc (hc interrupt) ustawiastoppedByComposerdla najbliższego przejścia ihold_all+ notice „Przerwano agenta. Kolejka wstrzymana — nic nie wyśle się samo.”; Enter przyblockedwysył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/createdAtmalejąco); pustyquery→ wszystko. -
toggleFavorite(favs:Favorite[], text:string, now:number) → Favorite[](potext.trim(), limit 100);isFavorite(favs, text) → boolean. -
Migracja:
loadHistoryakceptuje stare wpisy bezspace/agentName(pola →""). -
Step 1: Testy: duplikaty; limit 500;
search("TEST")znajduje „uruchom testy” zranges[[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 pohc sendz kodem 0 i bezerrorw JSON (hcOk), zspace_nameitab_namezAgentInfo. -
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): najpierwClipboard::GetFileDropList()→ wypiszFILES\t<path>na linię; inaczejClipboard::GetImage()→ zapisz<outDir>\paste-<stamp>.png→IMAGE\t<path>; inaczejNONE. -
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 → kafelekadding→hc put <agent> <path> --json→ready+mention/error+ Ponów. -
Step 0 (spike, ręcznie, przed kodem): tymczasowy
on("paste_other", …)znotify; skopiuj obraz z przeglądarki, Snipping Tool i Eksploratora (plik) → czy zdarzenie odpala? Zmierz czasexec powershellze skryptem. Jeślipaste_othernie odpala w którymkolwiek przypadku → STOP, raport do Opus. -
Step 1: Testy: parse
IMAGE\tC:\…\paste-1.png;FILESz dwiema ścieżkami (spacje, polskie znaki);NONE; kod ≠ 0 →errorzestderr; picker anulowany →[];staleFiles(6 dni zostaje, 8 dni usunięte);supportsImages("claude-code"),supportsImages("aider")===false;mention/removeMentiondla ś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ątaniepaste/przy starcie; ostrzeżenie przy wysyłce obrazu do agenta bezsupportsImages: „{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…”, listav_virtual_list(wysokość stała z kontenera), wiersz: tekst 2 linie z podświetleniemranges, metaDD.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
Textareacofareplace; 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 →
replacew 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); blokcomposerwlayouts/ovis-composer.json→"size": {"px": 260},"min": 120,"max": 520i rodzicworkz"resizable": true(ręczna zmiana wysokości przeciąganiem granicy); po zmianielayout.errornie istnieje. - Step 6:
herdr-app checkOK;herdr-app shotkaż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-composerbez błędów; restart Herdr w trakciesending→uncertain. - Step 3: Dowód braku rekompilacji:
git -C <herdr>nie dotyczy — w raporcieherdr-app --versionprzed 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), statusAPPROVED/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"}'.