Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / build-release-and-validation

Build, release, and validation automation

Impeccable uses one delivery system to turn shared skill and detector sources into provider installs, editor packages, CLI bundles, and release artifacts. The system also checks that generated output, hook contracts, package metadata, engine assets, and selected test lanes stay aligned before users receive a build. See Distribution and engineering tooling for the wider delivery model, Plugin packaging and installation for install behavior, and Automated test harness for test execution.

Build system

The build system renders shared skill content for each supported host, then assembles host packages and release archives from those outputs. It keeps source content separate from generated delivery files so each host receives the paths and format it expects.

Provider output

Provider output gives each agent host a usable copy of the same design skill. A provider profile defines the host directory, supported frontmatter, provider-only content, provider-specific agents, and hook shape. The transformer applies that profile while it renders the shared source, resolves placeholders, copies references and scripts, and emits any host-specific agent or plugin payload. The build then creates universal and host-specific packages from the rendered copies. References: scripts/…/factory.js• L180-228, scripts/…/factory.js• L237-475, scripts/…/providers.js• L14-235

The root sync refreshes generated skills without removing project-owned script state. It also refreshes generated commands, hook manifests, agents, and provider plugin payloads while avoiding the Codex root bundle. Engine binaries stay out of generated repository trees. Release archives normally carry the launcher and let it fetch the pinned native engine on first use. An opt-in mode adds available engine binaries to the archives for offline use. References: scripts/…/providers.js• L14-235, scripts/…/utils.js• L5-17, scripts/…/utils.js• L19-47, scripts/build.js• L786-858, scripts/build.js• L991-993

Hook manifests

Hook manifests connect file-edit events to design checks. The build emits a host-shaped manifest for project installs and separate plugin-shaped manifests for installed packages, so each hook finds the launcher inside its own payload.

The manifests use a short edit check and, where the host supports it, a deeper completion check. Missing launchers are harmless, but an existing launcher keeps its real failure status so a blocking design result can reach the host. Cursor uses postToolUse and returns context to the agent, while its stop event is not used as a second pass. References: scripts/…/hooks.js• L20-65, scripts/…/hooks.js• L103-161, scripts/…/hooks.js• L164-185, scripts/…/hooks.js• L248-265, scripts/build.js• L588-600, scripts/build.js• L830-838

Plugin and editor packages

The build stages separate packages for plugin marketplaces and the VS Code extension. These packages reuse provider output but rewrite script paths for their installed location, then add the manifest, hooks, icon, license, and user-facing readme required by each host.

The Cursor package receives its own plugin manifest and hook file. The VS Code package is declarative: it exposes the skill to GitHub Copilot and does not include project-install sidecars. References: scripts/…/cursor-plugin.js• L33-64, scripts/…/vscode-extension.js• L28-64, scripts/build.js• L860-981

Installed path rewriting

Installed packages cannot rely on the project-relative paths used by direct installs. The rewrite stage changes skill and agent instructions to use the package-provided base path, removes plugin-incompatible tool approval data, quotes launchers, and fails when an old path or unresolved placeholder remains.

This boundary prevents a plugin from silently running an older copy from the user's project. It also keeps Windows launcher commands valid when a path contains spaces. References: scripts/…/plugin-paths.js• L5-23, scripts/…/plugin-paths.js• L78-116, scripts/…/plugin-paths.js• L119-215, scripts/…/cursor-plugin.js• L8-30, scripts/…/vscode-extension.js• L11-26

CLI package builds

The CLI is distributed as an npm package. Its package boundary exposes the command runner and detector while optional platform packages provide the native engine for supported systems. The build also creates the browser detector bundle used by browser-facing CLI paths.

The CLI release records the source version in GitHub, while npm publishes the CLI and its matching platform engine packages. References: package.json• L26-50, package.json• L68-81, cli/…/cli.js• L31-80, scripts/build-browser-detector.js• L1-48

Engine launcher validation

The skill launcher is the common entry point for packaged design commands. It first uses a bundled or configured engine, then a verified user cache, then a compatible executable on PATH, and finally downloads the pinned release asset. The checksum manifest is the trust boundary for both cached and new binaries, while a verification stamp avoids hashing the same cache on every hook run.

The shell and Windows launchers share this contract. Windows also supports an x64 fallback on ARM and requires CRLF batch files so command labels work in cmd.exe. The build keeps the binary directory out of source skill reads, then stages binaries only for an opt-in offline release. References: .github/skills/impeccable/scripts/impeccable#L1-L15, .github/skills/impeccable/scripts/impeccable#L97-L139, .github/skills/impeccable/scripts/impeccable#L171-L239, .github/skills/impeccable/scripts/impeccable.cmd#L1-L20, .github/skills/impeccable/scripts/impeccable.cmd#L79-L149, .github/…/engine-checksums.txt• L1-9, scripts/…/utils.js• L13-17, scripts/build.js• L615-650

Extension package builds

The extension build turns detector code and rule data into browser extension archives. It checks generated pieces and referenced manifest and service-worker files before it creates separate Chrome and Firefox outputs.

The Chrome manifest is the source form. The build derives a Firefox form with browser-specific startup and store metadata, so both archives share detector behavior while following their host's distribution rules. References: scripts/build-extension.js• L39-64, scripts/build-extension.js• L66-120, scripts/build-extension.js• L122-188, scripts/test-suites.mjs• L123-146

Build gates

Build gates compare generated facts with the source and public delivery surfaces. They check counts, versions, manifest shape, frontmatter limits, user-facing prose, provider placeholder sentence boundaries, Windows batch line endings, and skill context budgets before the build exits successfully. The context budget check covers each LLM-facing skill file and the files loaded before common first edits, so content growth remains visible during a build.

The gates run after package staging because a source file can look valid while its generated form has a broken path, stale claim, or invalid loader contract. The detection count comes from a readable rule registry when one is available; an absent registry is reported as an unchecked count rather than guessed. References: scripts/build.js• L41-125, scripts/build.js• L127-169, scripts/build.js• L171-220, scripts/build.js• L223-233, scripts/build.js• L432-480, scripts/build.js• L483-509, scripts/build.js• L518-540, scripts/build.js• L1001-1063, scripts/…/token-budget.js• L1-76

Release flow

The release flow treats the skill, CLI, extension, and native engine as related but separate products. Each product has its own version source, tag, artifact, and publication path, while engine readiness is checked before products that depend on it can ship.

Product artifacts

The main release products map to distinct outputs:

ProductRelease identityMain delivery path
Skillskill-v<version>Signed universal skill archive
CLIcli-v<version>npm package and platform engine packages
Extensionext-v<version>Chrome and Firefox archives
Engineengine-v<version>Platform binaries and checksum files

The release command reads the matching version and changelog entry, checks the expected artifact, signs the skill archive when needed, and creates the GitHub release. The engine workflow then builds and publishes native assets for its tag. References: scripts/release.mjs• L26-80, scripts/release.mjs• L254-323, scripts/release.mjs• L329-354, .github/…/release-engine.yml• L1-25, .github/…/release-engine.yml• L141-175

Release readiness

Release preflight requires a clean and pushed source tree, a new tag, valid release notes, and the expected artifact. Engine-gated releases also require the engine source to match the published engine tag. Skill and CLI releases require the pinned engine binaries, checksums, and npm platform packages to be public before users can fetch them.

The engine readiness check acts as a release-script check and an always-on CI gate. It verifies the five engine assets, their checksum sidecars, and the matching npm platform packages for the pinned ENGINE_VERSION. The engine tag flow also checks that the platform package pins and at least one valid Pro release key are ready before it tags the engine. After a skill release, the flow checks the version served by the public site. A mismatch warns maintainers because update users may still receive an older bundle, but it does not undo the GitHub release. References: scripts/release.mjs• L136-206, scripts/release.mjs• L457-490, scripts/check-engine-release.mjs• L13-20, .github/…/ci.yml• L361-380, .github/…/engine-checksums.txt• L1-9, scripts/cli-pro-release-keys.json• L1-3

Engine publication

The engine tag flow first validates the pinned platform packages and the compiled Pro release key. The engine workflow then builds the supported native targets, checks the tag against both ENGINE_VERSION and the Cargo workspace version, and smokes each target that can run on its build host. A manual workflow run rehearses the build matrix and uploads temporary artifacts without signing or publishing. Tag runs sign the Windows binary in a protected job, verify its publisher and timestamp, and publish immutable assets with checksums.

The published target set covers macOS arm64 and x64, Linux x64 and arm64, and Windows x64. The cross-built Linux arm64 target skips the local smoke command, while the other targets must report the expected engine version. The workflow rejects a tag that does not match the pinned engine version and refuses to replace an asset that already exists. The release is created with all assets in one publish step, so a public release is not left with only part of its asset set. References: scripts/release.mjs• L457-532, .github/…/release-engine.yml• L12-19, .github/…/release-engine.yml• L26-80, .github/…/release-engine.yml• L81-140, .github/…/release-engine.yml• L141-175, scripts/check-engine-release.mjs• L66-99

CI validation

CI first turns the event and changed paths into a test plan. It then runs core build checks and adds native, browser, live, framework, oracle, skill, or provider-backed lanes when their rules select them.

Suite selection

The suite registry defines what each lane protects, which files trigger it, and which command files run it. Every suite adds exact triggers for its own test files so changing a test cannot leave its suite unselected.

The default plan covers core, oracle, detector, live, framework, and plugin end-to-end checks. Other lanes are opt-in because they need a browser, an external service, billing, or a longer run. References: scripts/test-suites.mjs• L4-27, scripts/test-suites.mjs• L29-99, scripts/test-suites.mjs• L101-220, scripts/test-suites.mjs• L222-373, scripts/test-suites.mjs• L375-408

Test-plan generation

The test planner maps the GitHub event and changed files to Boolean workflow outputs. Pushes and pull requests select focused lanes. Scheduled runs select the full live end-to-end sweep, while manual runs can add the billed skill workflow.

The workflow keeps the pull request smoke matrix separate from the broader scheduled and manual live matrix. It tests the workspace on Node 22.18 and 24, marks CI traffic as test traffic, and keeps nightly runs in their own concurrency group so a push to main cannot cancel the full sweep. Pull requests into main are limited to release or hotfix paths; normal work targets next. Credential-gated lanes remain visible when they skip, and the billed completion workflow runs only when a maintainer selects it. References: scripts/ci-test-plan.mjs• L6-59, scripts/ci-test-plan.mjs• L61-109, .github/…/ci.yml• L3-34, .github/…/ci.yml• L68-84, .github/…/ci.yml• L373-380, .github/…/ci.yml• L430-509, .github/…/ci.yml• L505-586, .github/…/ci.yml• L727-790

Validation lanes

The selected plan drives a Node matrix that tests source behavior, rebuilds generated products, validates the editor and browser packages, and compares generated files with the checkout. Native workspace jobs run on Linux and Windows when Rust changes select them. Separate guards cover the Windows launcher, the CLI's published Node floor, and oracle behavior built from the current checkout.

Remote CLI checks and live end-to-end checks build the engine from the current source, so they do not silently test the last published binary. Pull requests use a small live smoke matrix, while scheduled and manual runs use a wider fixture sweep against next for the nightly path. Provider-backed regressions skip when their credentials are absent, and the expensive completed skill workflow runs only when manually selected. The detector lane also rebuilds the extension, lints the Firefox package, and checks the tracked rule registry after its source inputs change. CI uploads packaged build output while excluding the unpacked Chrome and Firefox staging trees, then uploads live failure traces when those checks fail. References: .github/…/ci.yml• L68-188, .github/…/ci.yml• L190-301, .github/…/ci.yml• L303-380, .github/…/ci.yml• L395-428, .github/…/ci.yml• L430-586, .github/…/ci.yml• L588-725, .github/…/ci.yml• L727-790

This diagram shows how a change moves from path-aware selection to build, package, and install checks.

flowchart TD
    Event[GitHub event and changed files] --> Plan[Test plan]
    Plan --> Core[Core build and contract checks]
    Plan --> Native[Native and engine checks]
    Plan --> Optional[Browser, live, oracle, skill, and provider-backed checks]
    Core --> Artifacts[Generated packages and release readiness]
    Native --> Artifacts
    Optional --> Results[Validation results]
    Artifacts --> Results

Browser validation state

Live browser validation keeps browser findings consistent with CLI and edit-hook checks. It resolves project rule, value, and file waivers against the page being scanned, while durable session state lets the browser recover a live edit without accepting an old result over a newer one.

The browser utility degrades to no filtering when stored data is missing or malformed. It also keeps scroll position and handled session IDs separate from the main session record, so a reload does not lose the user's place or repeat an already handled result. For compiled template sources such as JSX, TSX, and Vue, it waits for the mounted session wrapper instead of parsing raw source. If that wrapper is gone, it retries before discarding the orphaned session, while transient source-read failures keep the session open for a later check. The page cursor is applied through a dedicated style so picking does not change server-rendered root attributes and trigger a hydration warning. References: .github/…/live-browser-ignores.js• L1-36, .github/…/live-browser-ignores.js• L122-173, .github/…/live-browser-ignores.js• L189-245, .github/…/live-browser-session.js• L11-37, .github/…/live-browser-session.js• L43-61, .github/…/live-browser-session.js• L113-179, .github/…/live-browser.js• L68-87, .github/…/live-browser.js• L6517-6583, .github/…/live-browser.js• L6659-6675, .github/…/live-browser.js• L2059-2086

Finish review gate

The finish review gate is the final human-facing validation step for a completed Impeccable build. It checks that the review evidence and build record exist, compares the result with the approved direction and quality bar, checks product truth and banned patterns, and returns one of four dispositions: recapture, rebuild, fix, or ship. A ship result requires no material fixes and no missing or contradicted review item. The degraded reference keeps the same contract when the harness has no subagent support. References: .github/…/impeccable-finish-reviewer.agent.md• L5-11, .github/…/impeccable-finish-reviewer.agent.md• L17-35, .github/…/finish-reviewer.md• L4-10, .github/…/finish-reviewer.md• L16-34

GitHub automation

GitHub workflows keep generated output, release assets, and repository state aligned with source. CI validates changes, generated-output synchronization refreshes committed provider trees, and scheduled stewardship manages pull request and issue state.

Generated output synchronization

The sync workflow rebuilds generated provider and plugin paths after changes to delivery sources such as skills, scripts, package metadata, and lock files. If the rebuilt paths differ, it commits the output to the branch that received the source change.

The workflow uses a non-canceling concurrency group and refetches the branch when it moves during the run. It rebuilds from the new branch state and retries the push with backoff, so generated output is based on the source commit where it lands. References: .github/…/sync-generated-output.yml• L1-50, .github/…/sync-generated-output.yml• L52-88, .github/…/sync-generated-output.yml• L90-147

Pull request stewardship

The PR Sheriff turns open pull request state into planned GitHub actions. It marks failures, conflicts, review blockers, drafts, policy blocks, and maintainer waits, then a scheduled workflow applies those actions after contributor activity ages.

The same automation adds a triage label to new and reopened issues. A dry-run mode lets maintainers inspect changes before GitHub is modified. The scheduled pass warns after seven days and closes after fourteen days under its configured maintainer rules. References: .github/…/sheriff.yml• L1-26, .github/…/sheriff.yml• L28-44, .github/…/sheriff.yml• L46-74

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep provider hook event names, matchers, launcher paths, timeouts, and payload roots aligned across direct installs and package manifests.
  • When changing a generated provider list, update provider rendering, agent formats, plugin staging, package assembly, sync rules, and CI drift paths together.
  • When changing plugin or editor instructions, keep path rewrites, launcher quoting, host manifests, and rewrite verification aligned.
  • When changing engine pins or targets, update release tags, asset names, checksums, platform packages, and readiness checks together.
  • When adding a suite or test file, keep its trigger, output name, workflow condition, runner, and opt-in policy consistent across the planner and CI jobs.
  • When changing CI event or concurrency rules, preserve the separate pull request smoke path and scheduled full-live path. Keep the main release boundary and next development path consistent with the pull request guard.
  • When changing smoke setup or cleanup, preserve the target repository's hook configuration and keep generated smoke files excluded.
  • When changing batch launchers, preserve executable mode and CRLF output in every release path.
  • When changing live-browser waiver or session rules, keep browser resolution aligned with the CLI and edit-hook contract and preserve recovery fencing for newer sessions.
  • When changing live-browser source recovery, keep compiled-template handling, orphan detection, retry behavior, and the hydration-safe page cursor aligned.
  • When changing finish-review rules, keep the source agent contract and the degraded harness reference aligned, especially the conditions for recapture, rebuild, fix, and ship.
  • When changing engine workflow permissions or triggers, preserve the build-only manual path and keep signing and publication limited to tag runs.
  • When changing the engine release key set, keep every key entry valid for the engine parser and ensure the engine tag preflight still rejects a release with no usable Pro key.
  • When changing generated-output inputs or paths, keep the sync workflow trigger list, build command, drift scope, and branch-race recovery aligned.
  • When changing sheriff policy, keep issue triage, dry-run behavior, warning and close windows, and maintainer exceptions aligned with the workflow inputs.
  • When changing skill files or their common load paths, update the matching file and use caps in scripts/token-budget.json so the build gate measures the intended context boundary.

Important failure modes

TriggerConsequenceGuard
A package keeps a project-relative script pathAn installed plugin can run an old project copy or fail to find its launcherPackage rewrites and post-rewrite checks reject the old path
A hook manifest points at the wrong install directoryFile edits produce no design checkProvider-specific manifest builders use the install's own payload root
A quoted Windows launcher lacks the call operatorPowerShell parses the command as an expression and failsShared launcher quoting emits & for .cmd paths
A suite test file has no matching triggerChange-aware CI can skip the suite after a test changeSuite registration adds exact self-triggers
A nightly CI run shares a canceling concurrency group with a pushThe full sweep can stop before it validates mainScheduled runs use a separate concurrency group
A pull request targets main outside a release or hotfix pathWork can bypass the next release staging branchThe test matrix rejects the pull request base and directs it to next
The published Node floor rises without proving the npm shim at that floorUsers below the new floor can receive an older CLI instead of the current oneThe shim-floor job compares engines.node with its proven floor and runs the shim there
A release starts before engine assets are publicInstallers or npm platform packages cannot fetch the pinned engineRelease readiness checks require binaries, checksums, and packages
A downloaded engine has no recorded digest or fails its digest checkThe launcher refuses to run itShell and Windows launchers fail closed against engine-checksums.txt
A smoke run leaves target hooks or fixtures behindThe target repository keeps test state after validationThe smoke tool snapshots configuration and cleans artifacts
A batch launcher has LF line endingsWindows cannot resolve batch labelsBuild validation requires CRLF in generated .cmd files
Generated provider output is staleDirect installs and release archives disagree with sourceCI drift checks and generated-output sync rebuild the output
A live browser applies a stale waiver or session resultThe browser hides a finding or restores an old edit over a newer onePage-scoped ignore resolution and checkpoint revisions fence recovery
A compiled-template session loses its source wrapper during a transient read failureThe browser can discard a live edit that still exists or strand the session in the wrong stateSource recovery retries, distinguishes unreadable files from missing wrappers, and waits for mounted wrappers
The finish reviewer treats a missing or contradicted review item as a successful shipAn incomplete or visibly wrong build can pass the final gateThe ship disposition requires no material fixes and no missing or contradicted matrix row
A release tag or workspace version does not match ENGINE_VERSIONThe published engine can report a different version than the launcher expectsThe engine workflow checks the tag, Cargo version, and target smoke output before publication
A cross-built or unsigned engine reaches publicationUsers can receive an unverified or untested native assetCross-built targets are excluded from local smoke, while Windows is signed and verified before the publish job
A manual engine rehearsal is treated as a releaseMaintainers may expect a public asset that the workflow never publishedManual runs upload only run-scoped artifacts; tag pushes perform signing and publication
The engine release key file is empty or contains a malformed entryPro dispatch is disabled in the released engineEngine tag preflight requires each entry to map an identifier to a 64-character lowercase hex key
Generated output is committed from an old branch headA generated tree can describe source that is no longer at the branch tipThe sync workflow refetches, rebuilds, and retries against the current branch head
A sync push keeps losing races with branch updatesSource changes land without refreshed generated outputThe workflow retries five times and fails clearly when it cannot publish a matching commit
The sheriff runs with write mode when maintainers only want to inspect actionsGitHub labels or pull request state change unexpectedlyManual runs expose a dry-run input and pass the selected mode to the sheriff
A skill file or common use grows past its context budgetThe build can ship guidance that consumes more agent context than the supported use allowsThe build checks every capped file and load set and fails on missing, stale, or exceeded caps

Key files

FileWhy to read it
scripts/build.jsMain source-to-provider build, package staging, archive creation, engine staging, and build gates
scripts/…/factory.jsShared rendering rules for provider skills, references, scripts, agents, hooks, and plugin payloads
scripts/…/providers.jsProvider output profiles and host delivery rules
scripts/…/utils.jsRules for source skill loading, distributable scripts, project-owned artifacts, executable modes, and batch line endings
scripts/…/hooks.jsHook contracts for direct installs and installed packages
scripts/…/plugin-paths.jsInstalled-package path rewriting and rewrite drift checks
scripts/…/cursor-plugin.jsCursor package assembly and hooks
scripts/…/vscode-extension.jsDeclarative VS Code package assembly
.github/skills/impeccable/scripts/impeccableUnix launcher selection, engine download, and checksum verification
.github/skills/impeccable/scripts/impeccable.cmdWindows launcher selection, fallback download, and checksum verification
.github/…/engine-checksums.txtDigests that define trusted engine release assets
scripts/test-suites.mjsSuite purpose, triggers, runners, and opt-in policy
scripts/…/token-budget.jsPer-file and per-use context budget checks used by the build gate
scripts/token-budget.jsonContext limits for LLM-facing skill files and common uses
scripts/smoke-provider-hooks.mjsInstall-level provider smoke flow and cleanup behavior
scripts/release.mjsRelease preflight, engine source and Pro-key checks, tagging, artifact handling, and post-release checks
scripts/cli-pro-release-keys.jsonPro release keys compiled into the engine and checked before an engine tag
scripts/ci-test-plan.mjsEvent and changed-file rules that select CI lanes
.github/…/ci.ymlCI event routing, branch policy, job graph, build checks, release readiness, and optional validation lanes
.github/…/release-engine.ymlNative engine build, manual rehearsal, target checks, signing, checksums, and publication
.github/…/sync-generated-output.ymlAutomatic generated-output refresh, source triggers, race recovery, and push
.github/…/live-browser-ignores.jsBrowser-side project waiver resolution
.github/…/live-browser-session.jsDurable live-session and recovery state
.github/…/live-browser.jsBrowser editing, source recovery, session fencing, and hydration-safe page interaction
.github/…/impeccable-finish-reviewer.agent.mdFinal build review contract and release disposition rules
.github/…/finish-reviewer.mdEquivalent finish review contract for harnesses without subagents
scripts/…/sheriff.mjsPull request state evaluation and GitHub action planning