pbakaus/impeccable / .hermes/skills/impeccable
impeccable
UnverifiedUse when the user wants to design, redesign, shape, critique, audit, polish, simplify, harden, animate, or otherwise improve a frontend interface: websites, landing pages, dashboards, product UI, components, forms, settings, onboarding, empty states, and native iOS or Android screens. Handles UX review, hierarchy, layout, typography, color, motion, UX copy, accessibility, responsive behavior, edge cases, and capturing or documenting design systems (DESIGN.md, tokens). Also for making bland UI bolder, loud UI quieter, or ambitious visual effects. Not for backend-only or non-UI tasks.
scripts/impeccable
View on GitHub#!/bin/sh
# Impeccable launcher. Runs the platform binary shipped next to this script:
# <this dir>/bin/<os>-<arch>/impeccable
# Order: $IMPECCABLE_BIN, the sibling binary, ~/.impeccable/bin/impeccable,
# the version-pinned cache, then `impeccable` on PATH. Never needs Node.
# The unversioned home binary and the PATH candidate are validated with the
# engine-probe handshake first: the retired 3.x npm CLI also installed a bin
# named `impeccable`, and exec'ing it would fail every verb with
# "Unknown command". The sibling binary must also report the version in
# VERSION: it is gitignored, so a skill upgrade that copies files over this
# directory leaves the old engine in place. A local build of the same version
# passes, which is why it is not hashed. IMPECCABLE_BIN is the operator's
# explicit choice and is exec'd without a probe. The version-pinned cache and
# the download are verified against engine-checksums.txt (next to this
# script), never against anything published beside the binary; a
# <binary>.verified stamp holding the manifest digest and the binary's size
# skips rehashing until either changes or the binary is newer than the stamp.
# No path hashes on every run: hooks run this launcher on every edit.
set -eu
# True when the candidate answers the engine handshake (prints
# "impeccable-engine <version>", exit 0). Quiet and fast (<100ms).
# IMPECCABLE_LAUNCHER_PROBE marks the child as a probe: a copy of this
# launcher reached recursively (e.g. symlinked onto PATH as `impeccable`)
# then skips its own probes and refuses to download, so probing stays cheap
# and can never loop.
probe_ok() {
probe_out=$(IMPECCABLE_LAUNCHER_PROBE=1 "$1" engine-probe 2>/dev/null) || return 1
case "$probe_out" in
impeccable-engine*) probe_version=${probe_out#impeccable-engine }; return 0 ;;
esac
return 1
}
probing=${IMPECCABLE_LAUNCHER_PROBE:-}
# Space, tab and CR, made once: hooks run this launcher on every edit and turn
# end, and every process it starts before the engine costs real time on a busy
# Windows machine (#1237), so the hot path below sticks to shell builtins.
ws=$(printf ' \t\r')
# Sets $digest_out to the digest engine-checksums.txt records for engine
# version $1 and asset $2 (lines are "<version> <asset> <sha256>"), empty when
# there is none.
# A CR is a separator too (CRLF checkouts), and a last line with no newline
# still counts.
manifest_digest() {
digest_out=""
[ -f "$manifest" ] || return 0
while IFS="$ws" read -r m_version m_asset m_sum _ || [ -n "$m_version" ]; do
case "$m_version" in ''|'#'*) continue ;; esac
if [ "$m_version" = "$1" ] && [ "$m_asset" = "$2" ]; then
digest_out=$m_sum
return 0
fi
done < "$manifest"
return 0
}
# Sets $expected (and, on Windows on ARM, which runs x64 binaries,
# $expected_x64) from engine-checksums.txt.
read_expected() {
manifest_digest "$version" "$asset"
expected=$digest_out
expected_x64=""
if [ "$os" = windows ] && [ "$arch" = arm64 ]; then
manifest_digest "$version" impeccable-windows-x64.exe
expected_x64=$digest_out
fi
}
# Sets $size to the byte count of the cached binary (BSD wc pads it).
cached_size() {
size=$(wc -c < "$cached") || size=""
size=${size##* }
}
# Sets $actual to the sha256 of $1, empty when no hash tool works.
hash_file() {
actual=""
if command -v shasum >/dev/null 2>&1; then
if digest=$(shasum -a 256 "$1" 2>/dev/null); then actual=${digest%% *}; fi
elif command -v sha256sum >/dev/null 2>&1; then
if digest=$(sha256sum "$1" 2>/dev/null); then actual=${digest%% *}; fi
fi
}
# This script's directory without dirname or a subshell: what dirname "$0"
# gives, made absolute by a cd there and back.
case $0 in
*/*) dir=${0%/*} ;;
*) dir=. ;;
esac
[ -n "$dir" ] || dir=/
caller_pwd=$PWD
CDPATH= cd -- "$dir" || { echo "impeccable: cannot enter the launcher directory $dir" >&2; exit 127; }
dir=$PWD
skill_dir=${dir%/*}
[ -n "$skill_dir" ] || skill_dir=/
cd -- "$caller_pwd" || { echo "impeccable: cannot return to $caller_pwd" >&2; exit 127; }
# VS Code syncs a plugin without the executable bit. Its hooks run this through
# sh, so restore the bit for the commands the skill runs directly (#1249).
[ -x "$0" ] || chmod +x "$0" 2>/dev/null || :
manifest="$dir/engine-checksums.txt"
# What the binary needs to know about its home: the skill directory (for
# reference/*.md and command-metadata.json) and how to name itself in the
# commands it prints. Exported BEFORE any exec below, including the
# IMPECCABLE_BIN override: an engine binary reached with no IMPECCABLE_SKILL_DIR
# cannot find reference/*.md (so native platform refs never inline) or read its
# own version (so UPDATE_AVAILABLE never fires). Setting it here covers every
# candidate the launcher can exec.
: "${IMPECCABLE_SKILL_DIR:=$skill_dir}"
: "${IMPECCABLE_SELF:=$0}"
export IMPECCABLE_SKILL_DIR IMPECCABLE_SELF
if [ -n "${IMPECCABLE_BIN:-}" ] && [ -x "${IMPECCABLE_BIN}" ]; then
exec "${IMPECCABLE_BIN}" "$@"
fi
# Windows names itself in the environment, which saves a process there; one
# uname covers the rest. PROCESSOR_ARCHITECTURE is what impeccable.cmd reads,
# so both launchers pick the same cached engine (AMD64 under x64 Git Bash on
# ARM64, as uname -m reported before).
if [ "${OS:-}" = Windows_NT ]; then
sys="Windows_NT ${PROCESSOR_ARCHITECTURE:-unknown}"
else
sys=$(uname -sm 2>/dev/null) || sys="unknown unknown"
fi
case "${sys%% *}" in
Darwin) os=darwin ;;
Linux) os=linux ;;
MINGW*|MSYS*|CYGWIN*|Windows_NT) os=windows ;;
*) os=unknown ;;
esac
case "${sys##* }" in
arm64|aarch64|ARM64) arch=arm64 ;;
x86_64|amd64|AMD64) arch=x64 ;;
*) arch=unknown ;;
esac
version=""
[ -f "$dir/VERSION" ] && { IFS="$ws" read -r version _ < "$dir/VERSION" || :; }
bin="$dir/bin/$os-$arch/impeccable"
[ "$os" = windows ] && bin="$bin.exe"
# Lost the executable bit in transit (zip extraction, some copiers).
if [ -f "$bin" ] && { [ -x "$bin" ] || chmod +x "$bin" 2>/dev/null; }; then
if [ -n "$probing" ] || [ -z "$version" ] || { probe_ok "$bin" && [ "$probe_version" = "$version" ]; }; then
exec "$bin" "$@"
fi
echo "impeccable: skipping $bin: it reports engine ${probe_version:-unknown} but this skill pins $version; delete it to stop this warning" >&2
fi
# On Windows (an MSYS/Git Bash shell) the cached names carry .exe so this
# launcher and impeccable.cmd share one cache.
exe=""
[ "$os" = windows ] && exe=".exe"
home_bin="${HOME:-/nonexistent}/.impeccable/bin/impeccable$exe"
if [ -z "$probing" ] && [ -x "$home_bin" ] && probe_ok "$home_bin"; then
exec "$home_bin" "$@"
fi
# Version-pinned user cache, filled by the download below or by `impeccable update`.
cache_root="${IMPECCABLE_HOME:-${HOME:-/nonexistent}/.impeccable}"
cached="$cache_root/bin/$version/impeccable$exe"
asset="impeccable-$os-$arch"
[ "$os" = windows ] && asset="$asset.exe"
if [ -n "$version" ] && [ -x "$cached" ]; then
read_expected
cached_size
stamp=""
stamp_size=""
{ IFS="$ws" read -r stamp stamp_size _ < "$cached.verified"; } 2>/dev/null || :
if [ -n "$stamp" ] && [ "$stamp_size" = "$size" ] && { [ "$stamp" = "$expected" ] || [ "$stamp" = "$expected_x64" ]; } && [ ! "$cached" -nt "$cached.verified" ]; then
exec "$cached" "$@"
fi
hash_file "$cached"
if [ -n "$actual" ] && { [ "$actual" = "$expected" ] || [ "$actual" = "$expected_x64" ]; }; then
{ echo "$actual $size" > "$cached.verified"; } 2>/dev/null || :
exec "$cached" "$@"
fi
echo "impeccable: cannot verify the cached engine $cached against $manifest; not using it" >&2
fi
if [ -z "$probing" ] && command -v impeccable >/dev/null 2>&1 && probe_ok impeccable; then
exec impeccable "$@"
fi
# Last resort: fetch this version's binary for the current platform from the
# public release channel into the user cache. Needs network; sandboxes without
# egress preinstall the binary on PATH instead.
setup_help() {
echo "Engine $version setup needs network access and write permission to $cache_root/bin/$version." >&2
echo "Run this launcher ($0) with engine-probe in a terminal that has those permissions, then retry the original command." >&2
echo "Alternatively, set IMPECCABLE_HOME to a writable cache location, or IMPECCABLE_BIN to a preinstalled engine binary." >&2
}
fetch_url() {
http_status=""
download_host=""
if command -v curl >/dev/null 2>&1; then
fetch_result=0
metadata=$(curl -fsSL --retry 2 -w '%{http_code} %{url_effective}' -o "$tmp" "$1" 2>/dev/null) || fetch_result=$?
http_status=${metadata%% *}
effective_url=${metadata#* }
# Only the authority is needed, never the signed storage URL's query.
download_host=${effective_url#*://}
download_host=${download_host%%/*}
download_host=${download_host##*@}
case "$download_host" in
\[*) download_host=${download_host%%]*}] ;;
*) download_host=${download_host%%:*} ;;
esac
download_host=$(printf '%s' "$download_host" | tr '[:upper:]' '[:lower:]')
return "$fetch_result"
elif command -v wget >/dev/null 2>&1; then
wget -q -O "$tmp" "$1" 2>/dev/null
else
return 1
fi
}
check_download() {
download_file=${1:-$tmp}
if [ ! -f "$download_file" ]; then
echo "impeccable: download completed but the file was removed before execution: $url; check your antivirus quarantine or logs. Refusing to continue; do not disable protection." >&2
exit 127
fi
if [ ! -s "$download_file" ]; then
rm -f "$download_file"
echo "impeccable: downloaded file is empty: $url; refusing the unverified download" >&2
exit 127
fi
}
if [ -n "$probing" ]; then
# Inside another launcher's probe: no download, fail fast and quiet.
exit 127
fi
if [ -n "$version" ] && [ "$os" != unknown ] && [ "$arch" != unknown ]; then
base="${IMPECCABLE_DOWNLOAD_BASE:-https://github.com/pbakaus/impeccable/releases/download}"
url="$base/engine-v$version/$asset"
read_expected
# Fail closed before any network traffic or cache write.
if [ -z "$expected" ] && [ -z "$expected_x64" ]; then
echo "impeccable: no checksum for engine $version ($asset) in $manifest; refusing the unverified download" >&2
exit 127
fi
tmp="$cache_root/bin/$version/.impeccable.part.$$"
# An interrupted download (Ctrl-C, a hook timeout) would otherwise leave the
# PID-named staging file behind for good. The handlers must exit explicitly.
cleanup() { rm -f "$tmp" 2>/dev/null || :; }
trap 'cleanup; exit 129' HUP
trap 'cleanup; exit 130' INT
trap 'cleanup; exit 143' TERM
if ! mkdir -p "$cache_root/bin/$version" 2>/dev/null; then
echo "impeccable: engine $version is not installed; cannot create cache directory: $cache_root/bin/$version" >&2
setup_help
exit 127
fi
# Check the actual staging file, not just directory existence: a cache from
# an earlier run can be readable but no longer writable inside a sandbox.
if ! (umask 077; : > "$tmp") 2>/dev/null; then
echo "impeccable: engine $version is not installed; cannot write to cache directory: $cache_root/bin/$version" >&2
setup_help
exit 127
fi
fetched=0
if [ -n "$expected" ] && fetch_url "$url"; then
fetched=1
elif [ -n "$expected_x64" ]; then
# Windows on ARM runs x64 binaries; fall back when no arm64 asset exists.
url="$base/engine-v$version/impeccable-windows-x64.exe"
expected=$expected_x64
fetch_url "$url" && fetched=1
fi
if [ "$fetched" = 1 ]; then
check_download
# No sha256 tool refuses the download too.
hash_file "$tmp"
check_download
if [ -z "$actual" ]; then
rm -f "$tmp"
echo "impeccable: cannot verify $url (no sha256 tool, or hashing failed); refusing the unverified download" >&2
exit 127
fi
if [ "$actual" != "$expected" ]; then
rm -f "$tmp"
echo "impeccable: checksum mismatch downloading $url" >&2
exit 127
fi
check_download
if ! chmod +x "$tmp" 2>/dev/null; then
check_download
rm -f "$tmp"
echo "impeccable: could not make the verified download executable: $url" >&2
exit 127
fi
check_download
if ! mv -f "$tmp" "$cached" 2>/dev/null; then
check_download
rm -f "$tmp"
echo "impeccable: could not cache the verified download: $url" >&2
exit 127
fi
check_download "$cached"
cached_size
{ echo "$actual $size" > "$cached.verified"; } 2>/dev/null || :
exec "$cached" "$@"
fi
rm -f "$tmp" 2>/dev/null
case "$http_status" in
5[0-9][0-9])
case "$download_host" in
github.com|*.github.com|githubusercontent.com|*.githubusercontent.com)
echo "impeccable: could not download engine $version: GitHub's downloads are failing right now (HTTP $http_status from $download_host). This is an outage on GitHub's side, not a problem with your setup or the CLI, so updating won't help. Check https://www.githubstatus.com and run the same command again once GitHub has recovered." >&2 ;;
*)
echo "impeccable: could not download engine $version: $download_host is failing right now (HTTP $http_status), a server error on $download_host's side. Try again later." >&2 ;;
esac
exit 127 ;;
esac
echo "impeccable: could not download engine $version from $url; check network access, the release URL, and curl or wget availability." >&2
setup_help
exit 127
fi
echo "impeccable: no engine binary for $os-$arch found (looked in $bin, $cached, PATH)." >&2
echo "Download impeccable-$os-$arch from https://github.com/pbakaus/impeccable/releases (tag engine-v$version) into $cache_root/bin/$version/impeccable$exe (then chmod +x), or set IMPECCABLE_BIN to a preinstalled engine binary. Docs: https://impeccable.style" >&2
exit 127
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |