@xgent-ai/skills 0.1.0 → 0.4.0

package/vendor/impeccable/bundle/blobs/add1bee76f897f989166a5b9ad1b38d9173248e29d668d5c885ae9a0eff73861

@@ -0,0 +1,105 @@
+> **Additional context needed**: quality bar and shipping constraints.
+
+Polish is refinement, never concealed redesign. Preserve the incumbent visual world, content, behavior, and everything outside scope. If the concept itself is wrong, say so and recommend redesign or `bolder` instead of smuggling in a replacement.
+
+A detector result is defect evidence, not proof of quality. Inspect the rendered experience and real interaction path.
+
+## 1. Establish the system
+
+Read DESIGN.md and representative tokens, shared components, patterns, and neighboring flows. If no formal system exists, use coherent project conventions.
+
+Classify each drift before fixing it:
+
+- **missing token:** the system needs a reusable value;
+- **one-off implementation:** an existing shared component or pattern should replace it;
+- **conceptual mismatch:** the flow, information architecture, or hierarchy differs from comparable product areas;
+- **local defect:** the implementation is simply incomplete or inconsistent.
+
+Fix the cause at the narrowest correct level. Ask when a binding system principle cannot be inferred.
+
+## 2. Gather the evidence
+
+Use the feature yourself at the surface's representative sizes: desktop and mobile on the web; on a native platform (`ios` / `android` / `adaptive`), the shipped device classes on the simulator, emulator, or hardware, captured per the platform reference's Verifying the build section. Determine:
+
+- whether the path is functionally complete;
+- the intended quality bar and time available;
+- known constraints or deliberately unfinished work;
+- the states, content lengths, roles, and input methods users will actually encounter.
+
+If a prior critique exists, use it as one input:
+
+```bash
+.kiro/skills/impeccable/scripts/impeccable critique-storage latest "<resolved target>" --json
+```
+
+Exit 0 returns JSON with the latest snapshot's `body` and an exact `snapshot_file` identity. Retain `snapshot_file` until the end of the pass. For a local file target, the helper compares the file's exact current content fingerprint with the fingerprint captured by critique. Unchanged staged, unstaged, or untracked content remains current; any byte change, deletion, or replacement with a non-file closes the backlog it identified while preserving its trend history and exits 2. A URL target has no local fingerprint and remains current until explicitly closed. When current, incorporate relevant P0/P1 findings from `body` and name the snapshot read. Exit 2 means none exists or the target changed. Perform an independent pass either way.
+
+## 3. Triage
+
+Separate functional defects from cosmetic ones and fix in this order:
+
+1. broken or blocked tasks, data loss, misleading state, and inaccessible paths;
+2. missing loading, empty, error, success, disabled, and permission states;
+3. flow, hierarchy, responsive, and design-system drift;
+4. visual and motion inconsistencies;
+5. code and asset cleanup.
+
+Do not perfect one corner while leaving the rest below the same quality bar.
+
+## 4. Polish the whole path
+
+### Flow and hierarchy
+
+- Match neighboring mental models, terminology, disclosure, routing, save behavior, and optimistic or pessimistic patterns.
+- Make the primary task and current state obvious without flattening every element to equal weight.
+- Ensure arrival, transition, empty, and recovery paths connect instead of behaving as isolated screens.
+
+### Layout and type
+
+- Align to the project's grid and spacing scale; fix optical as well as mathematical alignment.
+- Group related content tightly and separate distinct groups generously.
+- Keep same-role typography consistent; test measure, wrapping, localization expansion, zoom, and font loading.
+- Verify every supported viewport rather than correcting only the current screenshot.
+
+### Color, imagery, and icons
+
+- Use semantic tokens and stable color meanings across themes.
+- Verify text, control, and focus contrast in every state.
+- Keep icon families, stroke/weight, sizing, and optical alignment coherent.
+- Prevent image layout shift; use correct aspect ratios, responsive sources, and useful alt text.
+
+### Interaction and state
+
+- Every control needs appropriate default, hover, focus, active, disabled, loading, error, and success behavior.
+- Preserve visible keyboard focus, logical tab order, labels, and platform-appropriate touch targets.
+- Keep motion coherent, interruptible, and performant. Do not add animation merely to make polish visible.
+- Validate long, missing, localized, offline, slow, and permission-limited content where the product can encounter it.
+
+### Content and code
+
+- Keep terminology, capitalization, punctuation, and factual copy consistent. Ask before changing claims.
+- Remove debug output, dead code, unused imports, obsolete styles, and polish-created duplication.
+- Replace custom implementations with shared components where the system owns the pattern.
+- Promote genuinely reusable values to tokens; do not create a system abstraction for one local exception.
+
+## 5. Verify and finish
+
+Walk the complete path again with mouse, keyboard, and touch where applicable. Check:
+
+- mobile, intermediate, and wide layouts on the web; phone and tablet size classes in both supported orientations on native;
+- loading, empty, error, success, disabled, long-content, and missing-content states;
+- zoom, contrast, focus, semantics, and screen-reader names;
+- console errors, layout shift, interaction latency, and image loading everywhere; supported browsers on the web; supported OS versions, runtime warnings, and dropped frames on native;
+- agreement with DESIGN.md, neighboring features, and the user's scope.
+
+Follow the quality guidance supplied by `impeccable context` and hooks, then run any other relevant QA commands. Context requests a manual scan only when no automatic detector is active; never add another detector pass. Fix real defects and document only narrow intentional exceptions. A clean scan does not replace visual judgment.
+
+Finish with a source diff: remove accidental churn, orphaned code, redundant values, and temporary artifacts. Ship only when the feature is functionally complete and consistently finished across the path.
+
+When this pass clears every Priority Issue it took from a snapshot, close that snapshot:
+
+```bash
+.kiro/skills/impeccable/scripts/impeccable critique-storage close "<resolved target>" "<snapshot_file returned by latest>"
+```
+
+This closes only the snapshot this pass actually processed; if a newer critique landed meanwhile, its backlog stays live. Do not close when no snapshot was read, when `snapshot_file` was not retained, or when Priority Issues remain.

package/vendor/impeccable/bundle/blobs/af35b5fb6e45acb6483a5fbb864c3eaa9c57bacc43857f48183c836041c670ae

@@ -0,0 +1,101 @@
+> **Additional context needed**: only the target element, when the request does not name one that resolves uniquely on the page.
+
+Generate is the fast lane into live mode: the user names an element, a direction, and a count in one sentence, and within a minute they are cycling through variants in their browser. One command boots the helper, hands the element to the overlay in the page your harness already shows (it scrolls to it, selects it, and fires the same Go a click fires) and returns the generate event; one edit writes the variants; one call replies and waits for the user's choice, which the helper bakes into source itself. This file owns the lane's plumbing; from the event onward the design work is [live.md](live.md)'s, unchanged, so read it in full now if you have not this session.
+
+**Web only.** Live mode's browser overlay has no native equivalent; on `ios` / `android` / `adaptive` projects, decline this command and offer `bolder` or `quieter` on the source instead.
+
+The plumbing is where the lane saves time: one command starts the session around the page your harness already shows, one call replies and waits, and nothing here is a browser you have to babysit. The design work is not where it saves time. Setup runs as for any command (`impeccable context`, this reference, craft-floor.md before the edit), and the variants are planned, written, and accepted exactly the way a live session plans, writes, and accepts them.
+
+Three prohibitions cover the known ways this command goes wrong:
+
+- **Never run init or document, and never ask for PRODUCT.md or DESIGN.md.** When they exist, the start command prints them under `boot` and you use them. When they do not, it says so (`contextMissing`, `contextNote`) and you extract the identity from the event (Step 3). A missing file is never a reason to interview the user inside this command; offer `init` in one line after the session ends.
+- **Never hand-write a variants wrapper or invent a session id.** Only the browser mints session ids (8 hex characters, at Go). A missing event is fixed by rerunning Step 2, never with a direct source edit.
+- **Do not act on hook findings while live markers are in the file**, and do not restyle variants to appease them; the accept verifies the file once the variant is permanent.
+
+## Step 1: Parse the request
+
+Three parts, all from the user's sentence:
+
+- **A number in the request**: that is the count. **No number**: 3. The protocol caps count at 8.
+- **The direction wording** maps onto the live action vocabulary; never invent a new action value:
+  - **bold, bolder, stronger, punchier**: `bolder`
+  - **quiet, calmer, softer, toned down**: `quieter`
+  - **simpler, minimal, stripped**: `distill`
+  - **refined, tightened, polished**: `polish`
+  - **font and type words**: `typeset`
+  - **color words**: `colorize`
+  - **arrangement and spacing words**: `layout`
+  - **device and breakpoint words**: `adapt`
+  - **motion words**: `animate`
+  - **playful words**: `delight`
+  - **rule-breaking words**: `overdrive`
+  - **Wording that carries intent but no vocabulary word** ("make it feel like a bank", "warmer", "more premium"): `impeccable`, with the user's wording passed as the prompt.
+  - **An action fits AND extra intent rides along** ("bolder, but keep it monochrome"): that action, with the rest as the prompt.
+  - **The wording names no direction at all** ("better", "improve", "nicer", "different", "fresh", "new", "redesign", "fix", "some options", "ideas", "alternatives", or just "variants" with nothing else): Ask the user directly to clarify what you cannot infer. Ask one question, offering the vocabulary: *"Which direction should the variants take? bolder, quieter, simpler (distill), polished, typography (typeset), color (colorize), layout, motion (animate), playful (delight), or rule-breaking (overdrive)."* Map the answer with this list; an answer that is still open ("surprise me", "you pick") is `impeccable` with the user's original wording as the prompt, and Step 2 starts on that answer.
+- **The element description** ("the pricing cards", "the hero heading"): Step 2 resolves it to a selector.
+
+Done when you hold an action from the vocabulary (asked for, when the request named no direction), a count from 1 to 8, and the element description.
+
+## Step 2: Reuse the page, then start
+
+**Reuse** the dev server already running and the tab your harness already shows it in; a second server or a second browser window is the failure this step prevents.
+
+1. **Find the dev server**, cheapest source first, and stop at the first hit: the user's message, a browser tab already on the app (Claude Code: an origin in `tabs_context`), a server your harness started (Claude Code: `preview_list`), a terminal that printed its URL. Its origin is your `--dev-url`. **No hit**: leave `--dev-url` off and run the start command with no wait; the boot probes for a running server and its verdict names the move. `browser_needed` carries the `devUrl` it found: open it as in 2, then rerun with `--dev-url <devUrl> --wait-for-browser 60000`. `no_dev_server` means nothing serves the app: start the dev script the way the verdict says (Claude Code: `preview_start`; Cursor: a background terminal; Codex: an exec you yield from), wait for its URL, then rerun with `--dev-url <url>`.
+2. **Open the page that renders the element in your browser, then start.** The route the request names, else the one `--target` serves; `--dev-url` takes only the origin.
+   - **Cursor** (`browser_navigate`) and **Claude Code** (`navigate`, which opens the Browser pane when it is closed and takes the `tabId` from `tabs_context` when a tab is already on that origin): open the URL, then run the start command with `--dev-url <url> --wait-for-browser 60000`. The boot injects the overlay and the page reloads into it while the command waits. Your browser tool is the only opener on these harnesses; the engine ignores `--open` there.
+   - **No browser tool** (Codex, others): run the start command with `--open --wait-for-browser 120000`; it opens the system browser, and the longer wait covers the user finding the tab. **`browser_open_failed` back**: tell the user the `url` in one line and rerun with `--wait-for-browser 120000`.
+
+```bash
+.cursor/skills/impeccable/scripts/impeccable live-generate --target src/App.jsx --dev-url http://127.0.0.1:5173/ --selector ".pricing-grid" --action bolder --count 3 --boot --wait-for-browser 60000
+```
+
+Run it in the foreground in Cursor and Claude Code (it returns within the wait); on Codex, in an exec you yield from, the way Step 3 runs the poll.
+
+- `--target`: the file that renders the element when the request or the project makes it obvious; skip it otherwise.
+- `--dev-url`: the origin from 1; omit it and the boot probes.
+- `--selector`: a unique class first, then a landmark tag plus class, an id last (every variant mounts a copy of the element, so an id repeats in the DOM). **The request names a repeated component in plural** ("the pricing cards"): target the container that holds the set, so one scoped stylesheet restyles every instance. One read of the source file that renders the element is allowed when the selector is not obvious; `--dry-run` resolves and reports without starting anything when it is not certain.
+- `--boot`: runs the lane's boot (PRODUCT.md and DESIGN.md loaded again for the helper, missing files tolerated, dev URL found, bottom bar hidden for the helper's lifetime) and reuses a helper that is already running. Its result rides along as `boot`.
+- Also available: `--prompt`, `--text` (keep only matches whose visible text contains a snippet), `--index` (1-based pick among matches).
+
+Read the output in this order: `boot` (or `boot.contextMissing` with `boot.contextNote`: the page is the source of truth, per the note), then `event`, the generate event for `sessionId`, with the same `_instructions` a user's Go gets. Every verdict carries `_instructions`, and they win over your recollection of this file; the ones whose move is a decision of yours:
+
+- **`ambiguous`**: the candidates are listed; target their common container, or rerun with `--text "<visible text>"` or `--index <n>`.
+- **`dev_server_gone`**: the dev server stopped answering while the command waited for the page (on Cursor, a server another chat started dies with that chat). Start it the way the verdict says, then rerun with `--dev-url <url>`.
+- **`no_match`**: the tab is on a route that does not render the element (navigate to the right route, rerun), or the selector is wrong (derive a better one from the source, or add `--text`).
+- **`config_missing` / `config_invalid`** under `bootError`: follow [live-setup.md](live-setup.md) first, then rerun.
+- **`event: null`** with `ok: true`: the event was slower than the wait; run `.cursor/skills/impeccable/scripts/impeccable live-poll` once to collect it, then continue.
+
+Done when the output shows `ok: true`, a `sessionId`, and an `event`, reached with at most one server started and one tab opened by you.
+
+## Step 3: Generate
+
+The event is a standard `generate` event: the picked element's context, a preflighted scaffold, and `_instructions` naming the action's reference, the planning section, and the exact splice. Handle it exactly per live.md's **Handle generate**, which owns everything from the identity lock to the done reply: read the action's reference and craft-floor.md as it says, plan per section 4 (identity first, then mode, then three different primary axes, then the squint test), declare knobs per section 7, and deliver per section 6 (a complete replacement of the element per variant, the preview CSS plus every variant in one edit at the scaffold's splice). The lane changes nothing about what a variant may be: the moves a live session would make on this element (a promoted tier, a restructured set, a reordered card, a different surface) are open here too. Never screenshot the page; the overlay preview is the review channel until accept.
+
+**Reply and wait in one call**, with the file you wrote:
+
+```bash
+.cursor/skills/impeccable/scripts/impeccable live-poll --reply EVENT_ID done --file src/App.jsx --then-poll
+```
+
+This replies done (the browser mounts the variants) and then blocks until the user's choice arrives, so run it the way your harness runs a long wait: **Claude Code** in the foreground with your tool's longest timeout (600000 ms), so you are paused until the choice arrives; **Codex** in a yielded foreground exec; **Cursor** in a background terminal with notify on `"type":"(accept|discard|variant_mount_failed|exit)"`. Never pass a short `--timeout=`. While it runs there is nothing else to do: never sleep and never poll its output on a timer; a harness that backgrounds it wakes you when it returns. `{"type":"timeout"}` means the user has not chosen yet: run `live-poll` again and keep waiting. If the edit fails after the browser flipped to GENERATING, `--reply EVENT_ID error "Short reason"` (without `--then-poll`) so the bar resets.
+
+Then tell the user, in one line, where their variants are: *"Three [bolder] variants are live on [the pricing cards]: cycle with the floating bar's arrows, adjust the Tune knobs, and Accept the keeper."*
+
+Outside the replace path, read the matching live.md section before acting: `scaffold.previewMode: "svelte-component"` (Svelte previews are edited as components, and their accept is mechanical), `mode: "insert"`, `variant_mount_failed`, `steer`, `manual_edit_apply`, and any `fallback: "agent-driven"` wrap error.
+
+## Step 4: Accept and close
+
+The call from Step 3 returns the user's choice. **`discard`**: nothing to do. **`accept`**: `_acceptResult.carbonize: true` is the normal case, and the cleanup is live.md's **Required after accept**, unchanged: move the accepted variant's rules into the stylesheet that already owns the element with real selectors, bake the chosen knob values in, unwrap the element and drop every `data-impeccable-*` attribute, delete the inline `<style>` block and both `impeccable-carbonize` markers, then `.cursor/skills/impeccable/scripts/impeccable live-complete --id SESSION_ID` and confirm `phase: "completed"`. (`baked: true` appears only when the accept was run with `--bake`; then the helper already made the variant permanent and no `live-complete` is owed.)
+
+Close without being asked, the moment the choice is handled:
+
+```bash
+.cursor/skills/impeccable/scripts/impeccable live-server stop
+```
+
+Stopping removes the injected script and reloads the page once: the user sees the accepted design with no overlay chrome, still served by their dev server. **Never kill or restart the dev server**, including one you started in Step 2.
+
+- **The user asks for more variants before you closed**: skip the close, run Step 2 again for the next element (the helper is reused), and close after the last choice.
+- **Interrupted or unsure of the state**: `.cursor/skills/impeccable/scripts/impeccable live-status`, then `live-resume`; the journal under `.impeccable/live/sessions/` is canonical.
+
+Done when the helper is stopped and the dev site still answers with the accepted design.

package/vendor/impeccable/bundle/blobs/af5842c4844b692b817319d5375611d4211dc7f459fb12da358baefc3a6cd373

@@ -0,0 +1,63 @@
+# Plan and asset review
+
+Use this checkpoint on comp-led builds once every raster region has its plate and the plates gate has scored them, before any page code exists. The approved comp is the reference. The user reviews two things: the plates that will ship, and the production plan for everything else, meaning which regions code draws. A painted region planned as code is the most expensive mistake a comp-led build makes, and this is where the user catches it. Text, controls and chrome are judged later, in the assembled first viewport.
+
+## Plan, capture, serve
+
+Run `.dsh/skills/impeccable/scripts/impeccable component-review plan`. It writes `.impeccable/review/components.json` from the measured spec, the comp and the plate files, and refuses, naming each one, while any raster region lacks its plate. Never write or edit that file for this stage: the packet is derived from the spec, so every change belongs in the regions file.
+
+If the harness exposes `component_review`, call it with `manifest_path` set to `.impeccable/review/components.json`. The host captures, presents the review and returns the user's decisions. A suspended request is waiting for the user; it is not a failed build or an approval.
+
+Otherwise run `.dsh/skills/impeccable/scripts/impeccable component-review capture --manifest .impeccable/review/components.json`, then start `.dsh/skills/impeccable/scripts/impeccable component-review serve --session <returned session>` in the background. Open the URL it prints in the available browser and wait for the user; `serve` exits 0 once they submit. Read the decisions with `.dsh/skills/impeccable/scripts/impeccable component-review status --session <id>`; `.dsh/skills/impeccable/scripts/impeccable component-review verify --manifest .impeccable/review/components.json` confirms approval and refuses pending, needs-work and stale input. Never submit the page or write a receipt on the user's behalf.
+
+`serve` exits 2 when this session has no browser (the same signal as the decision page) and 4 when it closes after 30 idle minutes without a decision. Either way no one is reviewing: stop waiting, do not approve anything yourself, and do not build past this checkpoint. End the run and report the plan and asset review as pending with its session ID, so the user can resume it. A waiting review is pending work, not a completed build.
+
+## Act on the receipt
+
+Apply the user's decisions as given, never your own favorable verdict in their place.
+
+- **approve**: once every item is approved and the inventory is confirmed, advance to the hero.
+- **revise** (a plate): regenerate that plate at the same path with the user's feedback.
+- **revise with split** (an asset): replace that region in the regions file with its layers: a frame plate with a transparent opening (kind `plate`, same box), the content as its own `image` region at the opening's box, and each moving part (a shutter, a door) as its own plate. Name each layer after the original region, as `<id>-frame`, `<id>-view` or `<id>-shutter-left`, so the next round shows it as part of the user's request. Rerun `.dsh/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>` and produce the plates.
+- **revise** (a plan item): change the regions file as the feedback says (resize or extend a raster region, split material into its own plate region, or adjust the code region), rerun `.dsh/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>`, and produce any new plates.
+- **reclassify** (a code region): in the regions file, change that region's `kind` to the one the user chose and rewrite its `note` to describe the material. Rerun `.dsh/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>`, then produce the new plates, with the asset producer when subagents are available.
+- **missing**: add the region to the regions file, rerun `.dsh/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>`, and produce its plate if it is raster.
+
+Then run `plan`, `capture` and `serve` again. Unchanged decisions carry over, so the user sees only what changed. Any spec change, or a plate replaced after acceptance, needs a new round; the build-phase gate stays closed until the review of the current spec is accepted.
+
+## Assemble and review
+
+Build the first viewport from the approved plates and plan, and run the hero gate. Human review does not waive its integrity checks. After three failed hero attempts, stop iterating and present the first-viewport review with the current build; the user's eye settles what the readings could not.
+
+Present a second manifest at `.impeccable/review/hero.json`. You write this one, and its shape is fixed:
+
+```json
+{
+  "schemaVersion": 2,
+  "stage": "hero",
+  "id": "hero",
+  "title": "First viewport",
+  "comp": {"path": ".impeccable/mocks/comp.png", "width": 1536, "height": 1024},
+  "components": [{
+    "id": "first-viewport",
+    "name": "First viewport",
+    "medium": "HTML / CSS",
+    "note": "Assembled first viewport",
+    "box": {"x": 0, "y": 0, "w": 1, "h": 1},
+    "preview": {"kind": "page", "path": "index.html"},
+    "dependencies": ["styles.css", "assets/plates/sky.png", "fonts/display.woff2"]
+  }]
+}
+```
+
+- `schemaVersion` is 2. Version 3 is the plan review packet and requires stage `components`. `codeRegions` and `specSha256` exist only in version 3 and are refused here. `reviewGroup` is refused too: version 3 rejects it, and any other version accepts it only on a page preview in a `components`-stage manifest, never in a hero manifest.
+- `comp.path` is the `comp` value in `.impeccable/build/spec.json`, and `width` and `height` are that PNG's pixel size.
+- Exactly one component, with `box` exactly `{"x": 0, "y": 0, "w": 1, "h": 1}` and `name`, `medium` and `note` as strings.
+- `preview.path` is the page entry the build gates (`artifact` in `.impeccable/build/state.json`).
+- `dependencies` lists every other file the page loads (stylesheets, scripts, plates, images, fonts) as bare strings. Every path, here and above, is project-relative and plain: no leading `./` or `/`, no `..`, no URL, no `?`, `#`, `%`, `:` or backslash. A request to a file missing from this list, or to another host, fails the capture.
+
+The reference stays the approved comp. Call the same host review tool, or run `capture`, `serve` and `verify` with this manifest. Needs-work feedback starts another assembly round.
+
+Acceptance closes human review for this build: never request plan, asset or assembly approval again. While the page renders what the user accepted, the hero score, the palette check and every numeric reading are advisories; material vetoes still hold (a missing or unreferenced plate, an SVG illustration, an organic clip, a clipped plate, invented ink, failed rendered presence). When the capture no longer matches the accepted screenshot, restore what the user accepted; until then the readings apply. Complete the rest of the page, responsive behavior, finish checks and documentation with the accepted first viewport as the visual direction. This is first-viewport calibration, not a claim that the user reviewed the rest of the page. Shared stylesheet edits do not reopen approval. Preserve the accepted direction; a later explicit user change is a new task.
+
+Assembled-page capture executes inline and declared local scripts from the pinned inputs. Network APIs, frames and workers are unavailable; the initial viewport must settle before capture. Keep the real page and declare its scripts rather than removing behavior to pass review.