From 89ac517cab9b6ed4681e3247a0bae1d851fe0b2a Mon Sep 17 00:00:00 2001 From: Factor Date: Fri, 20 Nov 2026 08:49:14 +0100 Subject: [PATCH] docs: plan for agent profiles in the / menu Co-Authored-By: Claude Opus 5.5 --- .../plans/2026-11-20-agent-profiles.md | 184 ++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-20-agent-profiles.md diff --git a/docs/superpowers/plans/2026-11-20-agent-profiles.md b/docs/superpowers/plans/2026-11-20-agent-profiles.md new file mode 100644 index 0000000..f168243 --- /dev/null +++ b/docs/superpowers/plans/2026-11-20-agent-profiles.md @@ -0,0 +1,184 @@ +# Profile agentów dla menu `/` — plan implementacji + +> **Dla wykonawcy (Ovis Fast):** zadania wykonuj po kolei, każde osobnym commitem. Kroki mają checkboxy (`- [ ]`). + +**Cel:** menu `/` podpowiada komendy dowolnego agenta. Wiedza o agencie pochodzi z profilu: domyślnego w kodzie albo z pliku `composer-agents.json` użytkownika. Do tego dochodzą komendy wysłane wcześniej do tego agenta, wzięte z historii. + +**Architektura:** +- Nowy czysty moduł `profiles.js`: domyślne profile, parsowanie i walidacja pliku, wybór profilu dla `agentName`. +- `catalog.js` przestaje znać Claude Code: czyta źródła, które daje profil, a komendy z historii buduje osobną funkcją. +- `main.js` w tle trzyma plik profili i cache źródeł `home` per `id` profilu, a pod pozycjami menu pokazuje wiersze informacyjne. + +**Stack:** JS (ESM), GPUI z `gpui-kit`, testy `node --test` (`npm test`). + +**Spec:** `docs/superpowers/specs/2026-11-20-agent-profiles-design.md`. Przeczytaj cały plik przed startem. + +## Ograniczenia globalne +- Nie zmieniamy Herdr ani jego plików. Pracujemy tylko na gałęzi `feature/composer-dock`. Bez push. +- Logika testowalna siedzi w czystych modułach (`profiles.js`, `catalog.js`; `exec` i `readText` wstrzyknięte). GPUI jest tylko w `main.js`. +- Ścieżki do skryptów PowerShell trafiają wyłącznie przez `decode()` z `powershell.js` (Base64). +- Menu `/` dla Claude Code (bez historii) daje **identyczną** listę jak przed zmianą: te same `key`, `group`, `insert`, `desc` i kolejność. +- Plik: `[appHome(), "composer-agents.json"].join("\\")`. Brak pliku jest normalny i nie jest błędem. +- TTL odświeżania pliku i źródeł `home`: 60 s (obecne `GLOBAL_TTL_MS`). +- Teksty dla użytkownika dosłownie: + - `GROUP_HISTORY = "Z historii"`; + - nieznany agent: ``Nieznany agent `` – dodaj profil w ~/.config/herdr-app/composer-agents.json`` (gdzie `` to `agentName`); + - problem z plikiem: `` `composer-agents.json`: ``. + +## Review Focus +1. `agentName` w innej wielkości liter niż `match` (np. `Kiro-CLI`): profil ma pasować. Test w Task 1. +2. Plik z BOM, CRLF albo komentarzem-śmieciem: BOM jest usuwany, zły JSON daje domyślne profile i powód. Test w Task 1. +3. Wpis historii zaczynający się ścieżką (`/c/Users/x`), samym `/` albo `/ cos` nie jest komendą. Test w Task 2. +4. Dwa panele z różnymi agentami: menu codex nie pokazuje komend `~/.claude`, bo cache jest per `id`. Test cache w Task 3 (czysta funkcja). +5. Profil z pliku nadpisujący `claude-code` bez `claude-plugins` nie pokazuje pluginów, a ścieżka `..` lub bezwzględna jest odrzucana. Test w Task 1. + +--- + +### Task 1: `profiles.js`, czyli domyślne profile, parsowanie i wybór + +**Pliki:** +- Utwórz: `herdr/herdr-composer/mods/herdr-composer/profiles.js` +- Zmień: `herdr/herdr-composer/mods/herdr-composer/catalog.js` (przenieś `BUILTINS` i `AGENT_ALIASES` do `profiles.js`, w `catalog.js` zostaw `export { BUILTINS } from "./profiles.js"`) +- Test: `tests/profiles.test.mjs` + +**Interfejsy (produkuje):** +- Typy (JSDoc): + - `Source = {scope:"project"|"home", path:string, pattern:"*.md"|"*/SKILL.md", prefix:string}`, albo `{scope:"home", kind:"claude-plugins"}`; + - `Profile = {id:string, match:string[], builtins:{key:string, desc:string}[], sources:Source[]}` (wszystko znormalizowane: `desc` domyślnie `""`, `prefix` domyślnie `"/"`). +- `export const PROFILES_FILE = "composer-agents.json"` +- `export const BUILTINS`: bez zmian treści. +- `export const DEFAULT_PROFILES: Profile[]`: + - `claude-code`: `match ["claude-code","claude"]`, builtins = `BUILTINS["claude-code"]`, sources w tej kolejności: + 1. project `.claude/commands` `*.md`; + 2. project `.claude/skills` `*/SKILL.md`; + 3. home `.claude/commands` `*.md`; + 4. home `.claude/skills` `*/SKILL.md`; + 5. `{scope:"home", kind:"claude-plugins"}`. + - `codex`: `match ["codex"]`, builtins = `BUILTINS.codex`, `sources []`. +- `export function parseProfiles(text: string|null|undefined): {profiles: Profile[], problem: string|null}` + - `null`/`undefined` (brak pliku) daje `{profiles: [], problem: null}`. + - Usuwa BOM. Zły JSON daje `{profiles: [], problem: "nieczytelny JSON"}`. + - Brak `agents` albo `agents` nie jest tablicą: `problem: "brak listy agents"`. + - Profil bez `id` (string) albo bez niepustego `match` (lista stringów) jest pomijany. Źródło z `path` bezwzględnym (`/x`, `C:/x`, `C:\x`, `\\x`) lub z segmentem `..`, nieznanym `scope` albo nieznanym `pattern` jest pomijane. Builtin bez `key` (string) jest pomijany. + - Coś pominięto, a reszta działa: `problem: "pominięto wpisów"`, gdzie `n` to liczba pominiętych profili, źródeł i builtinów razem. +- `export function resolveProfile(userProfiles: Profile[], agent: string): Profile|null`: najpierw `userProfiles`, potem `DEFAULT_PROFILES`; pierwszy, którego `match` zawiera `agent` (bez rozróżniania wielkości liter, po `trim()`). `""` i `"default"` dają `null`, chyba że ktoś jawnie wpisał je w `match`. + +- [ ] **Krok 1: testy (RED)** w `tests/profiles.test.mjs`: + - `resolveProfile([], "claude")` i `resolveProfile([], "Claude-Code")` → `id === "claude-code"`; `resolveProfile([], "codex").id === "codex"`; `resolveProfile([], "kiro-cli") === null`; `resolveProfile([], "default") === null`. + - Profil z pliku `{id:"claude-code", match:["claude-code"], builtins:[{key:"x"}]}` wygrywa z domyślnym: `builtins` to tylko `x`, a `sources` jest puste (brak `claude-plugins`). + - `parseProfiles(null)` → `{profiles:[], problem:null}`. + - `parseProfiles("\uFEFF{\"agents\":[{\"id\":\"kiro\",\"match\":[\"kiro-cli\"],\"sources\":[{\"scope\":\"home\",\"path\":\".kiro/prompts\",\"pattern\":\"*.md\",\"prefix\":\"@\"}]}]}\r\n")` → jeden profil, źródło z `prefix:"@"`, `problem:null`. + - `parseProfiles("{nope")` → `problem:"nieczytelny JSON"`, `profiles:[]`. + - `parseProfiles('{"agents":{}}')` → `problem:"brak listy agents"`. + - Profil z dwoma źródłami `{path:"../x"}` i `{path:"C:/x"}` oraz jednym dobrym → zostaje 1 źródło, `problem:"pominięto 2 wpisów"`. + - Profil bez `match` jest pominięty, drugi dobry zostaje. + - `pattern:"**/*.md"` jest odrzucony. + - `DEFAULT_PROFILES[0].builtins` ma te same klucze co `BUILTINS["claude-code"]`. +- [ ] **Krok 2:** `npm test` daje FAIL (brak modułu). +- [ ] **Krok 3:** zaimplementuj `profiles.js` i przenieś `BUILTINS` z re-eksportem w `catalog.js`. +- [ ] **Krok 4:** `npm test` daje PASS, łącznie z dzisiejszymi 190 testami. +- [ ] **Krok 5: commit** `feat: agent profiles describe each agent's commands` + +--- + +### Task 2: `catalog.js` czyta źródła profilu i komendy z historii + +**Pliki:** +- Zmień: `herdr/herdr-composer/mods/herdr-composer/catalog.js`, `herdr/herdr-composer/mods/herdr-composer/suggest.js` +- Test: `tests/catalog.test.mjs` + +**Interfejsy:** +- Konsumuje z Task 1: `Profile`, `Source`, `DEFAULT_PROFILES`, `resolveProfile`. +- Produkuje: + - `suggest.js`: `export const GROUP_HISTORY = "Z historii"`, w `GROUPS` po `GROUP_PLUGIN`, przed `GROUP_TERMINAL`. + - `commands(cwd, exec, options)` z `options = {profile?: Profile|null, snippets?, global?: Item[], history?: Item[], onReadError?}`: + - `profile` null lub brak: tylko `snippets` i `history`, bez `exec`; + - w przeciwnym razie kolejność: builtins profilu, źródła `project` profilu (czytane przez `exec` w `cwd`), `global`, `snippets`, `history`; + - deduplikacja po `key`: pierwszy wygrywa; + - `insert` = `source.prefix + key + " "`. + - Źródła `project` listuje **jedno** `exec` (sh, a PowerShell jako zapas, jak dziś `listProjectFiles`). Ścieżki i wzorce idą jako argumenty (sh) lub przez `decode()` (PS), nie są sklejane w skrypt. Nazwa skilla projektu: zawsze nazwa folderu, bez filtra `user-invocable` (jak dziś). + - `globalCommands(home, exec, readText, options)` z `options = {sources: Source[], onReadError?}`: + - czyta tylko źródła `scope:"home"` z `sources`; `kind:"claude-plugins"` daje dzisiejszą logikę pluginów (`~/.claude/settings.json` itd.); + - źródło `home` `{path, pattern}` daje dzisiejszy spec `md` / `skills` dla `${home}/${path}`; + - nazwy i filtr `user-invocable` jak dziś; `insert` z `prefix` źródła (plugin: `"/"`); + - brak `sources` lub pusta lista: `[]` bez `exec`. + - `export function historyCommands(history: HistoryEntry[], agent: string): Item[]`: + - wpisy z `agentName` równym `agent` (bez wielkości liter, `trim`), od najnowszego `sentAt`; + - pierwszy token `text.trimStart()` pasujący do `/^\/[A-Za-z0-9][\w:.-]*$/`; + - `key` bez `/`, `desc: ""`, `group: GROUP_HISTORY`, `insert: "/"+key+" "`; + - bez duplikatów. + - `export function unknownAgentMessage(agent: string): string` oraz `export function profileProblemMessage(problem: string): string`: teksty z Ograniczeń globalnych. + - Usuń `isClaudeCode` i `LIST_SH`/`LIST_PS` na sztywno. Test `isClaudeCode` zastępują testy `resolveProfile` z Task 1, więc usuwasz go. + +- [ ] **Krok 1: test „CC bez zmian” PRZED zmianą kodu.** Na obecnym kodzie, na fałszywej maszynie z testów (`machine(...)`) z plikami: + - projekt `.claude/commands/a.md`, `.claude/skills/s/SKILL.md` (z `name: inna`); + - home `~/.claude/commands/handoff.md`; + - jeden plugin. + + Wywołaj `commands(cwd, exec, {agent:"claude-code", global: await globalCommands(...)})` i wpisz wynik (lista `{key, group, insert, desc}`) jako literał `EXPECTED_CC` w teście. Commit tylko testu: `test: pin the / menu of Claude Code before profiles`. `npm test` daje PASS. +- [ ] **Krok 2: przepisz ten test na nowe API** (`profile: resolveProfile([], "claude-code")`, `globalCommands(..., {sources: profile.sources})`) z tym samym `EXPECTED_CC`. Dodaj testy (RED): + - `commands` z `profile: null`, `history: [h]` daje `[h]` i `exec` nie zostaje wywołane; + - profil `kiro` ze źródłem project `.kiro/prompts` `*.md` `prefix:"@"` daje `{key:"review", insert:"@review ", group:"Projekt"}`; + - `globalCommands` z `sources: []` daje `[]`, bez `exec`; + - `globalCommands` ze źródłem home `.kiro/prompts` daje grupę `Użytkownik`; + - `historyCommands`: wpisy `"/clear"`, `" /superpowers:brainstorming x"`, `"/c/Users/x"`, `"/ cos"`, `"/"`, `"hej /clear"` oraz wpis innego agenta dają dokładnie `["superpowers:brainstorming","clear"]` (gdy `brainstorming` jest nowszy), w grupie `Z historii`; + - `commands` z builtin `clear` i historią `clear` daje jedno `clear` z grupy `Wbudowane`; + - `GROUPS` zawiera `"Z historii"` zaraz po `"Pluginy"`; + - istniejące testy `globalCommands` dostają mechanicznie `{sources: DEFAULT_PROFILES[0].sources}`. +- [ ] **Krok 3:** `npm test` daje FAIL na nowych testach. +- [ ] **Krok 4:** zaimplementuj. +- [ ] **Krok 5:** `npm test` daje PASS, z `EXPECTED_CC` bez zmian. +- [ ] **Krok 6: commit** `feat: the / menu reads the sources of the agent's profile and its history` + +--- + +### Task 3: `main.js`, czyli plik profili, cache per profil, wiersze informacyjne i README + +**Pliki:** +- Zmień: `herdr/herdr-composer/mods/herdr-composer/main.js` (`updateSuggestions` ~2213, `refreshGlobal` ~2228, `loadSuggestions` ~2275, `renderMenu` ~2824, stan w `init` ~199), `herdr/herdr-composer/mods/herdr-composer/catalog.js` (jedna czysta funkcja niżej), README moda (sekcja „Inni agenci”) +- Test: `tests/catalog.test.mjs` + +**Interfejsy:** +- Konsumuje: `parseProfiles`, `resolveProfile`, `PROFILES_FILE` (Task 1); `commands`, `globalCommands`, `historyCommands`, `unknownAgentMessage`, `profileProblemMessage` (Task 2). +- Produkuje w `catalog.js`: `export function menuNotes({profile, agent, profilesLoaded, problem}): string[]`: + - `[profileProblemMessage(problem)]`, gdy `problem`; + - plus `unknownAgentMessage(agent)`, gdy `!profile && profilesLoaded`; + - kolejność: najpierw nieznany agent, potem problem. +- Stan w `main.js`: + - `this.userProfiles = []`, `this.profileProblem = null`, `this.profilesLoaded = false`; + - `this.globalCommands = new Map()` (klucz `profile.id`, wartość `Item[]`) i `this.globalLoadedAt = new Map()`, zamiast dzisiejszych pojedynczych pól; + - flaga `this.globalLoading` jak dziś. +- `refreshGlobal(cx)`: + 1. gdy minęło 60 s od ostatniego odczytu pliku: `readTextFile([appHome(), PROFILES_FILE].join("\\"))`, potem `parseProfiles` i ustawienie trzech pól oraz `profilesLoaded = true`; + 2. `profile = resolveProfile(this.userProfiles, agentName(target))`; gdy profil ma źródła `home` i cache dla `profile.id` jest pusty lub starszy niż 60 s, `globalCommands(home(), exec, readTextFile, {sources: profile.sources, onReadError})` zapisuje wynik pod `profile.id`; + 3. po zakończeniu, gdy menu `/` jest otwarte, przeładuj menu tak jak dziś. + + W `updateSuggestions` wołaj `refreshGlobal` dla **każdego** agenta przy `/` (usuń warunek `isClaudeCode`). `checking()` blokuje jak dziś. +- `loadSuggestions`, gałąź `/`: + - `profile = resolveProfile(this.userProfiles, agentName(agent))`; + - `commands(cwd, exec, {profile, snippets: [], global: this.globalCommands.get(profile?.id) ?? [], history: catalog.historyCommands(storage.loadHistory(this.store), agentName(agent)), onReadError})`; + - `this.menu.notes = catalog.menuNotes({...})`. +- `renderMenu`: `notes` jako szare (`t.dim`, `text_size(11.5)`) wiersze **pod** pozycjami, w tej samej przewijanej liście. Nie da się ich wybrać, a indeksy pozycji i `scroll_to_item` się nie zmieniają. Komunikat „Żadna komenda nie pasuje” nie pojawia się, gdy pozycji nie ma, a są `notes` z nieznanym agentem. +- README: sekcja „Inni agenci”: + - klucz bierzesz z wiersza „Nieznany agent …”; + - ścieżka pliku i format (pola z tabeli w specu); + - że plik nadpisuje profil o tym samym `id` w całości; + - przykład dla kiro z nagłówkiem „przykład niesprawdzony”. + +- [ ] **Krok 1: testy (RED)** `menuNotes`: + - `{profile:null, agent:"kiro-cli", profilesLoaded:true}` daje 1 wiersz zawierający `` `kiro-cli` ``; + - to samo przy `profilesLoaded:false` daje `[]`; + - profil plus `problem:"nieczytelny JSON"` daje `["`composer-agents.json`: nieczytelny JSON"]`; + - `profile:null`, `problem` i `profilesLoaded:true` dają 2 wiersze, najpierw nieznany agent. +- [ ] **Krok 2:** `npm test` daje FAIL. +- [ ] **Krok 3:** zaimplementuj `menuNotes`, zmiany w `main.js` i README. +- [ ] **Krok 4:** `npm test` daje PASS. `grep -n isClaudeCode herdr/herdr-composer/mods/herdr-composer/*.js` nic nie znajduje. +- [ ] **Krok 5: commit** `feat: the composer reads agent profiles from composer-agents.json` + +--- + +## Po wykonaniu (Ovis Opus, nie wykonawca) +- Instalacja: `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1`, potem `herdr-app status` musi dać `"errors": []`. +- GUI: menu `/` w CC wygląda tak jak przed zmianą. +- Plik testowy `composer-agents.json` z profilem `codex` ze źródłem home `.claude/commands` daje `handoff` w menu codex w ciągu 60 s. +- Uszkodzony plik daje wiersz z powodem. Po teście usuń plik.