Files
herdrMario/docs/superpowers/plans/2026-11-20-agent-profiles.md
2026-11-20 08:49:14 +01:00

15 KiB
Raw Permalink Blame History

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 `<nazwa>` – dodaj profil w ~/.config/herdr-app/composer-agents.json (gdzie <nazwa> to agentName);
    • problem z plikiem: `composer-agents.json`: <powód>.

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 <n> 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.