# Workflow (https://docs.vitrinka.ai/cs/dev/skills/workflows) ## Co je workflow [#what] Vedle skillů přinášejí dva pluginy šest workflow pro Claude Code: plugin core `vitrinka` nese `map`, `review-loop` a `code-loop` (`vitrinka:map`, …) a jednoho subagenta, `vitrinka-publisher`; volitelný plugin `vitrinka-experimental` nese `build-idea`, `test` a `cleanup` (`vitrinka-experimental:build-idea`, …). Workflow je skript z fází, jejichž agenti běží bez obsluhy: během běhu se vás na nic nezeptá, takže každé rozhodnutí, které potřebuje, musí padnout předem, a jediný způsob, jak se ozve, je oznámení o dokončení. Spouštějí je tři skilly — `make-idea`, `test` a `cleanup`, všechny v experimentálním pluginu. Potřebují běhové prostředí workflow v Claude Code; Codex žádné nemá, takže experimentální plugin je jen pro Claude Code a instaluje se přes `vitrinka setup --experimental` nebo `vitrinka setup modules enable experimental`. ## Od nápadu k pull requestu [#make-idea] `/vitrinka-experimental:make-idea ` dovede nápad k draft pull requestu. Rozhodujete dvakrát — v brainstormu a ve chvíli, kdy máte funkci před sebou; všechno mezi tím běží samo, ve worktree, který session už má. ```bash /vitrinka-experimental:make-idea "Hosté si u pokladny rozdělí účet" ``` 1. **Mapa** — `map` zmapuje terén, na kterém nápad stojí: routy, model a dveře, komponenty a testy, na které sáhne, body, na kterých se dá stavět, co by nápad zdvojil, a otevřené otázky — jeden artefakt terénu na nástěnce. 2. **Brainstorm** — [skill brainstorming](/cs/dev/skills/authoring#brainstorming) běží s terénem v ruce: jeho otevřené otázky jsou první kolo a každé riziko zdvojení se stane rozhodnutím — rozšířit, nebo nahradit, nikdy potichu obojí. Skončí epikem, rozhodovacím logem a commitnutým briefem. Bez briefu žádná stavba. 3. **Stavba** — `build-idea` rozdělí brief nejvýš do čtyř disjunktních řezů, každý implementuje jeden agent, spustí brány, udělá jednu rychlou kontrolu „funguje to?" — každou změněnou routu jednou na desktopu, hlavní cestu jednou, jedna malá nástěnka — otevře draft pull request a úkol předá zpátky s běžící aplikací, zaparkovaným stavem a tím, na co sáhnout. Žádná sada zařízení, žádná review smyčka, žádná smyčka nad kódem: průchod zařízeními není rozhodnutí stavby, takže `cap`, `severity`, `matrix` a `lanes` tu odmítne. 4. **Podívat se, pak otestovat** — podíváte se na funkci; `/vitrinka-experimental:test` položí jednu dávkovou otázku (lanes, důkladnost, cap, severity) a projde zařízení: nafotí zvolené lanes — viewporty, simulátory, iOS 26 Safari — s usertestem vedle každé, každou lane publikuje jako vlastní záložku jedné nástěnky běhu, zreviduje, přijme, opraví a přefotí až do capu, každou lane zapíše dveřmi běhu, pustí `code-loop` nad diffem a pull request označí jako připravený. Merge děláte vy. | Argument (`test`) | Co nastavuje | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cap` | Počet průchodů, 1–6. Výchozí 2. | | `severity` | Nejnižší úroveň vady, kterou smyčka sama přijme a opraví: `blocker`, `major` (výchozí) nebo `minor`. Všechno pod ní zůstane na nástěnce odložené pro vás; návrhy se nikdy nepřijímají automaticky. | Sada zařízení i checklist pro review patří repozitáři, ne jednomu běhu. Ve výchozím stavu se řídí typem projektu — iPhone, iPad a desktop pro web, simulátory iOS a Androidu pro Expo — a repozitář je přepíše v `.claude/vitrinka-workflows.json` (`projectType`, `matrix`, `checklist`, `exclude`, `board`, `baseUrl` a `run.web` — `auto`, `devbox` nebo `local` — pro to, kde se aplikace spustí), nikdy ve vyvolání. ## Fáze samostatně [#stages] | Workflow | Co dělá | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `map` | Čtyři průzkumníci jen pro čtení, jeden na každou vrstvu, a pak jeden artefakt terénu: body pro rozšíření, rizika zdvojení, otevřené otázky. `scope: "idea"` před brainstormem, `scope: "app"` před průchodem review. | | `review-loop` | Nafotí každou routu na každém zařízení matice a vedle toho proběhne průchod usertestu, průchod publikuje jako sekci jedné nástěnky běhu, zreviduje každou obrazovku proti checklistu a založí nálezy, přijme ty na prahu závažnosti a nad ním, opraví je a spustí brány — dokud není průchod čistý nebo se nedosáhne limitu. Samostatně ho spusťte na průchod responzivity nebo UX nad existující plochou. | | `code-loop` | Code review s aplikovanými opravami, hlídané testovacími sadami, dokud diff neprojde čistý; co aplikovat nedokáže, skončí jako jeden komentář k pull requestu pro vás. Pak pull request otevře — nikdy nemerguje. | | `build-idea` (experimentální) | Plán, implementace, jedna rychlá kontrola, dodání — draft pull request a předání, od commitnutého briefu. Bez průchodu zařízeními. | | `test` (experimentální) | Průchod zařízeními na dotaz: zvolené lanes nafocené a zrevidované až do capu, jedna nástěnka běhu se záložkou na lane, každá lane zapsaná dveřmi běhu, pak `code-loop` a pull request. | ## Smyčka ladění UI [#ui-loop] Když má `vybava.config.ts` repozitáře sekci `uiLoop`, řídí `map` a `review-loop` applet Výbavy `ui-loop` a routy nefotí. Applet vlastní manifest obrazovek, záznam, publikování a skóre. Workflow vlastní úsudek. * **`map`** se `scope: "screens"` rozšíří typovaný manifest obrazovek (`/screens/.ts`). Se `scope: "app"` udělá totéž, kdykoli je `uiLoop` nastavený. Pokryje každou routu, záložku, překryv a stav, každou s receptem, který se na ni dostane. Recept najde ovládací prvek podle role a přístupného názvu (krok `action` harnessu), ne podle řetězce CSS selektorů nebo indexu `nth=`. Obrazovka, na kterou se se seed daty nedá dostat, dostane `unreachable`, a obrazovka s mrtvým kódem, nenainstalovaným pluginem nebo vypnutou funkcí `retired`: ta se nikdy nefotí ani nepočítá. Průzkumníci položky jen přidávají a žádnou nepřepisují. Běh končí příkazy `vybava ui-loop check` a `vybava ui-loop map`. Argument `areas` omezí mapování jen na některé oblasti. * **`review-loop`** udělá v jednom běhu jednu fázi průchodu, aby žádný běh nepotřeboval víc než deset agentů. Fáze jsou `capture`, `review`, `fix` a `verify`. Každý běh začne jedním agentem s nízkým úsilím, který předá výstup `vybava ui-loop state` a `vybava ui-loop doctor` (Výbava s kontraktem stavu ui-loop 10 nebo novějším; starší verze nebo neúspěšná kontrola doctoru běh zastaví dřív, než cokoli změní), takže výchozí `stage: "auto"` naváže tam, kde podle souborů práce skončila, i po přerušení. Všechny seznamy vlastní příkazy Výbavy: obrazovky, dávky revize, backlog, dráhy oprav i checkpointy oprav. Žádný agent je nemá vyjmenovávat a obsah položek si agenti čtou z disku podle klíče. Běh vrátí `next`, tedy argumenty dalšího běhu. Když je `next` `null`, smyčka zkonvergovala nebo potřebuje vás. Dokud běží nafocení, každá fáze hned skončí jako `wait` a nespustí žádného agenta: smyčku dál vede běh, který fotí. Dokud je smyčka pozastavená (`vybava ui-loop pause`), každá fáze skončí jako `paused` s `next` `null` a s `resume`, tedy argumenty, které spustíte, až pauzu zruší `vybava ui-loop resume`; fáze, která už běží, se zastaví na nejbližší hranici (po kole revizorů, před syntézou, mezi drahami oprav nebo před Settle) a co udělala, ponechá. Fázi, o kterou požádáte, běh nikdy nezamění za jinou: když se aplikace od nafocení změnila, `review` se zastaví, vypíše změněné cesty a vrátí nafocení, které je třeba spustit, a běh omezený na `areas` nikdy nefotí. Průchod, který stav neumí datovat (nafocený dřív, než průchody zapisovaly svou revizi, nebo v revizi, kterou tento klon nemá), se nikdy nereviduje ani neověřuje: běh vrátí nafocení, které je třeba spustit, nebo pojmenuje fetch, který revizi vrátí. | Fáze | Co dělá | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `capture` | Spustí `vybava ui-loop run` na Devboxu, stáhne průchod zpět, rozdělí ho a publikuje a pak ho rozloží na nástěnku každé oblasti. Sada ve vitrince je nástěnka a `ui-loop publish` drží pro každou oblast jednu sadu napříč všemi průchody, takže každá oblast má právě jednu nástěnku. Každý průchod do ní přidá své sekce `Pass N · viewport · theme` a jednu kartu s obrazovkami, které se nepodařilo nafotit, s jedním řádkem a důvodem pro každou. Pokud nejnovější průchod nebyl nikdy publikován, dokončí ho. Pak `vybava ui-loop triage` seskupí nepovedené snímky podle příčiny a obrazovky, které selhaly na infrastruktuře (výpadek sítě, stránka, která zůstala prázdná), vrátí jako jeden příkaz `vybava ui-loop run --retake …` v problémech běhu. | | `review` | `vybava ui-loop batches` určí dávky v `review/batches.json`. Každý běh si příkazem `vybava ui-loop batches --claim` zabere nejvýš čtyři dávky a jejich revizoři posoudí každou obrazovku proti `uiLoop.spec`. Každou otevřenou položku z minulého průchodu také ohodnotí jako splněnou, částečně splněnou nebo nesplněnou. Každá dávka uloží svůj výsledek do `review/raw/.json`, jakmile skončí, a další běh zreviduje jen dávky, které ještě chybí. Velký průchod reviduje několik stejných běhů najednou: běh, který předává další review, vrátí `parallel`, tedy kolik takových běhů zbylé dávky využijí (každý z nich pak pokračuje jako jeden běh, takže se běhy nenásobí), a běh, který najde všechny zbylé dávky zabrané jiným během, skončí. Každá dávka nese otisk každé své obrazovky a revizor zapíše otisky obrazovek, které opravdu prohlédl, takže přefocení několika snímků znovu otevře jen tyto obrazovky. Revizor, kterého zastaví watchdog, se započítá jako zaseknutí: při druhém zaseknutí se dávka rozdělí na poloviny a stejný běh je zreviduje agenty, kteří mu zbyli, a polovina, která se zasekne dvakrát, se zablokuje: její obrazovky zůstanou neposouzené, objeví se v problémech běhu a nikdy nezastaví syntézu průchodu. Obrazovka, jejíž snímky se od minulého průchodu nezměnily, se přenese: ponechá si svá zjištění a hodnocení a nepatří do žádné dávky. Když jsou hotové všechny dávky, `vybava ui-loop merge-review` je složí do konceptu. Jeden agent pak vyřeší jen klíče, které koncept označí, a zapíše `review/backlog.json`. Dělá to jen běh, který získá zámek syntézy průchodu, a ten také vyvěsí skóre; každý jiný běh tu skončí. Jeho seznam `reviewed` jmenuje obrazovky, které revizor opravdu posoudil, tedy každou obrazovku uložené dávky kromě těch, které její revizor označil jako neposouzené, a k tomu každou přenesenou obrazovku. Jen ty se ve skóre můžou počítat jako čisté (Výbava v0.24.1 nebo novější). Obrazovka, která se nafotila, ale revizor ji nedokáže posoudit (snímek chybí, je prázdný nebo ukazuje jinou stránku), dostane vlastní nález, takže kolo oprav opraví její recept a verify ji nafotí znovu. Obrazovka bez jediného použitelného snímku (nedosažitelná, se selhaným receptem nebo s chybou) nepatří do žádné dávky, nereviduje se a nepočítá se do pokrytí: její recept opraví dráha rig v kole oprav, pokud ji manifest neoznačí jako nedosažitelnou se seed daty, a obrazovky, které ani tak nemají snímek, když průchod dojde k závěrečné kontrole, běh jmenuje v jednom řádku problémů a průchod nemůže skončit jako hotový. Jedna chyba aplikace, kterou triáž najde za několika obrazovkami, dostane JEDEN nález závažnosti broken, který je všechny vyjmenuje. Skóre se pak vyvěsí jako callout do první sekce průchodu na nástěnce každé oblasti. | | `fix` | `vybava ui-loop lanes` naplánuje dráhy podle vlastnictví: každá dráha vlastní celé adresáře, takže souběžné dráhy nikdy neupravují stejný soubor. Nejdřív běží dráhy primitiv. Pak se jejich adresáře zmrazí a běží nejvýš čtyři dráhy oblastí, položku po položce, a sdílený dev server přitom zůstává zelený. Položka, jejíž oprava potřebuje soubor jiné dráhy, se odloží i se změnou, kterou v něm potřebuje, a po drahách oblastí ji opraví dráha přepracování, která vlastní obojí. Každá hotová položka nechá checkpoint v `fix/.json`, který se nikdy necommituje. Katalogy i18n nevlastní nikdo: dráhy si zapíšou potřebné texty a závěrečný agent Settle je doplní, zapíše checkpointy položkám, jejichž oprava patří do jiného repozitáře, a zkontroluje typy celého kola. Nakonec dráha rig opraví recepty nafocení: názvy, které `vybava ui-loop check --labels` nenajde v žádném zdroji popisků, obrazovky, které průchod vůbec nenafotil, ty, jejichž recept v tomto průchodu selhal, a ty za skupinou recipe-drift z triáže (text, který recept hledá, z aplikace zmizel). Obrazovku s mrtvým kódem nebo vypnutou funkcí vyřadí a každou opravu ověří příkazem `vybava ui-loop run --probe` dřív, než zapíše checkpoint, takže ověřovací průchod obrazovku nafotí znovu. Průchod, jehož revize už nemá otevřenou položku, dostane kolo oprav jen s dráhou rig a po něm nafocení obrazovek, které opravila. Položky blokované něčím mimo repozitář, i ty z dráhy rig, vrátí běh, který kolo oprav dokončí, jako jeden seznam `ownerQuestions`, na který vlastník odpoví najednou; recept, který dráha rig neopraví bez změny aplikace, jmenuje v `reworkStuck`. | | `verify` | Nafotí nový průchod přesně s obrazovkami, které vybere `vybava ui-loop state`: se všemi, které mají ještě otevřenou položku, s těmi, na které sáhlo kolo oprav, a s těmi, jejichž zdrojové soubory se změnily. Když se změní sdílené primitivum, nafotí znovu všechny obrazovky. Po něm následuje běh `review`. | Fáze řetězte ze session, jedno volání Workflow za druhým, a vždy beze změny předejte `next.args` z výsledku. Poslední volání opakujte s `next.args`, dokud `next` není `null`: ```js { name: "vitrinka:map", args: { scope: "screens" } } { name: "vitrinka:review-loop", args: { mode: "ui-loop", stage: "capture" } } { name: "vitrinka:review-loop", args: { mode: "ui-loop", repo: "/abs/path/to/app/.worktrees/ui-polish" } } { name: "vitrinka:review-loop", args: { mode: "ui-loop" } } ``` `repo` (absolutní cesta, pro `review-loop` v režimu ui-loop a `map` se `scope: "screens"`) přišpendlí běh k jednomu checkoutu. Agenti workflow začínají v adresáři session, která je spustila, takže bez něj běh spuštěný z hlavního klonu pracuje tam. S `repo` začíná zadání každého agenta pokynem, ať se tam nejdřív přesune (`cd`), první agent ohlásí repozitář, ve kterém opravdu běžel, a pokud to není `repo`, běh skončí dřív, než cokoli změní. Předává se dál v `next.args`. Další argumenty: `apps`, `only`, `viewports`, `themes` a `workers` jdou do záznamu. `batch` (obrazovek na revizora, výchozí 14) a `reviewers` (dávky, které si běh zabere, nejvýš 4) řídí review; `areas` ho už nezužuje. `primitives` je seznam předpon adresářů se sdílenými primitivy. Za primitivum se počítá i adresář, který sdílejí položky dvou oblastí. `cap` je limit průchodů (výchozí 6). `test` vždy předá `mode: "routes"`, takže průchod zařízeními při stavbě funkce zůstane smyčkou rout a zařízení. Provozní pravidla, která dostane každý agent, pocházejí z `lib/uiloop.js`. ## Úklid backlogu [#cleanup] `/vitrinka-experimental:cleanup [project]` udělá jeden bezobslužný průchod otevřenými úkoly projektu: soupis, seskupení — duplicity, rozporné stavy, sirotci mimo svůj epik, epiky, které nikdo neuzavřel, zatuchlá práce — ověření každého příznaku proti kódu, pull requestům a záznamu QA, provedení toho, co je prokázané, návrh zbytku a jedna stránka s reportem. Rozhodujete dvakrát: úroveň důvěry před během, návrhy po něm. | Důvěra | Co se provede | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `evidence` (výchozí) | Jen prokázané opravy — smergovaný pull request, úspěšný běh, trailer commitu, věc, která viditelně existuje nebo zmizela. Pravděpodobná zavření a sloučení se stanou návrhy. | | `all` | I pravděpodobné opravy. | | `none` | Nic — běh nanečisto; prokázané i pravděpodobné změny se stanou návrhy. | Každá provedená změna jde vlastními dveřmi enginu a na svém úkolu nechá jeden komentář s důkazem. Nic se nemaže: duplicita se propojí a zruší a přeživší úkol si ponechá historii. Úsudky přistanou jako návrhy plánu v [příjmu návrhů](/cs/pm/intake) k vašemu verdiktu, nová práce jako návrhy v intake. Sahá jen na úkoly, chyby, stories a epiky — nikdy na todo, plány QA, cesty ani schůzky — a repozitář může v `.claude/vitrinka-workflows.json` chránit štítky a nastavit práh zatuchlosti (výchozí 45 dní). Opakovaný běh téhož dne přehraje fáze z mezipaměti, takže běh `none` napřed a běh `evidence` po přečtení reportu stojí jen jedno provedení navíc, ne druhý soupis. Jen Claude Code, jako zbytek experimentálního pluginu. ## Agent publisher [#publisher] `vitrinka-publisher` je subagent pluginu core na publikování nástěnek. Session ho po dokončeném záznamu pošle na pozadí a on udělá práci na nástěnce, která stojí nejvíc tokenů — strukturu cesty, sekce kroků, souhrnné karty, vyprávění provázení, sady nástěnek, psaní artefaktů — a vrátí adresu nástěnky, kterou vydal server. Nikdy nepořizuje snímky, necommituje a nenasazuje posluchače a nástěnky napojí na plán QA funkce, aniž by zakládal úkoly. `review-loop` ho používá k publikování každého průchodu.