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 / distribution-and-engineering-tooling

Distribution and engineering tooling

Impeccable packages shared design guidance and detection behavior for several delivery channels. The CLI, agent plugin, skill, and browser extension each serve a different host, while shared build, validation, test, and release controls keep their behavior aligned.

Delivery model

Impeccable uses separate delivery forms because a local command tool, an agent host, and a browser accept different package contracts. The CLI provides the user entry point and reaches a platform engine. The skill and plugins provide agent-facing commands and guidance. The extension delivers browser-safe detection behavior.

Product boundaries

Each product has its own release boundary, even when it uses shared source behavior. The root npm package is the public CLI entry point. Plugin metadata defines agent-host identity and version signals. The engine ships as platform packages, and the extension ships as browser archives. (package.json• L1-44, plugin/…/plugin.json• L1-12, plugin/…/plugin.json• L1-20, extension/manifest.json• L1-42)

The npm package remains a small CLI shim. Its supported Node floor is >=18.19.0, while repository work uses a newer development runtime. Optional platform packages carry the engine version that the CLI can resolve for the user's system. (package.json• L26-35, package.json• L86-91)

References: package.json• L1-44 package.json• L86-91 plugin/…/plugin.json• L1-12 plugin/…/plugin.json• L1-20 extension/manifest.json• L1-42

Installation and update flow

Agent setup normally starts with npx impeccable install. The CLI selects the host and install scope, then places the matching skill files. The skill launcher selects or downloads the pinned engine, verifies its identity, and keeps normal skill use independent of a separate Node runtime.

The same delivery path supports updates and plugins. Update checks compare the installed skill tree so source and script changes remain visible even when a version does not change. Provider-specific hooks stay with the host that runs them, which keeps project, plugin, and user installs aligned with their host rules.

References: cli/…/skills.mjs• L617-649 cli/…/skills.mjs• L694-730 cli/…/skills.mjs• L981-1020 plugin/…/SKILL.md• L17-23 plugin/…/impeccable• L79-149 scripts/…/hooks.js• L20-23 scripts/…/hooks.js• L45-59

Build pipeline

The build pipeline turns shared skill and detector sources into host packages and release artifacts. It applies host rules at build time so one source model can serve multiple agent hosts, the CLI, and browser environments.

Provider transformation

Provider transformation creates host-shaped skill output from shared source material. A provider definition supplies the host metadata, command form, agent format, hook location, and provider-specific text that the target can load. The result matches the host contract instead of requiring every host to understand every source field.

The same transformation model supports native agent files, nested agent forms, and simpler inline references. It also carries script execution details into generated output so launchers remain usable after packaging.

References: scripts/…/providers.js• L14-44 scripts/…/providers.js• L69-110 scripts/…/providers.js• L183-219 scripts/…/factory.js• L181-228 scripts/…/factory.js• L237-347 scripts/…/factory.js• L352-397 scripts/…/utils.js• L90-123

Artifact assembly

Provider output becomes the universal bundle used by CLI installation and downloads. The build also refreshes committed provider trees, agent plugin payloads, browser archives, editor plugin packages, and review assets when those targets are selected. Generated-output automation rebuilds relevant paths and checks that they stay in sync.

Skill archives normally contain the launcher and fetch the pinned engine on first use. An explicit release option can stage available engine binaries for offline use, but the default keeps archives small enough for the download path. The extension build creates the detector bundle, checks all manifest and worker references, and produces separate Chrome and Firefox archives. The engine release is built separately for supported platforms and supplies the binaries, checksums, and platform packages consumed by the other delivery paths. (scripts/build.js• L634-670, scripts/build.js• L997-1030, scripts/build-extension.js• L44-69, scripts/build-extension.js• L119-172)

This diagram shows how shared sources become host packages and release artifacts.

flowchart LR
    S[Shared skill source] --> P[Provider transforms]
    P --> U[Universal skill bundle]
    P --> G[Agent plugins and host trees]
    U --> C[CLI install and downloads]
    D[Detector source] --> E[Browser archives]
    R[Review assets] --> A[Review package]
    W[Engine workspace] --> B[Platform engine packages]
    H[Checksums] --> C
    H --> B

References: scripts/build.js• L752-830 scripts/build.js• L860-971 scripts/build.js• L983-1017 scripts/build-extension.js• L44-69 scripts/build-extension.js• L119-172 .github/…/sync-generated-output.yml• L3-15 .github/…/sync-generated-output.yml• L75-145 .github/…/release-engine.yml• L12-19 .github/…/release-engine.yml• L26-80 .github/…/release-engine.yml• L141-175 plugin/…/engine-checksums.txt• L1-9

Validation model

Validation protects the contracts between source, generated output, host loaders, and release systems. Local build checks, CI jobs, and release checks overlap so stale output, invalid host metadata, missing assets, and incomplete releases fail before distribution.

Build gates

Build gates check the package metadata, generated output, version links, plugin shape, guidance placeholders, prose rules, and archive contents. They also check generated Windows launchers because a package can build successfully yet fail when a target host installs or runs it.

The published CLI package uses the lower Node floor declared in package.json, while the repository's build and test work uses the newer development floor. This split keeps the public package contract distinct from the workspace toolchain. (package.json• L26-35, package.json• L45-84)

References: scripts/build.js• L171-220 scripts/build.js• L445-480 scripts/build.js• L495-539 scripts/build.js• L1001-1065 scripts/…/utils.js• L49-87 package.json• L26-35 package.json• L45-84

Generated output checks

CI selects the needed test groups from the changed paths and runs the core build matrix on supported development Node versions. It checks provider and plugin trees for drift, packages the extension when detector inputs change, and builds and tests the engine when Rust changes.

The extension path checks that tracked rule data matches detector inputs. The release path checks that the pinned engine release has all platform binaries, checksums, matching digests, and npm platform packages. These checks protect the install and first-run paths that depend on those assets.

References: .github/…/ci.yml• L35-180 .github/…/ci.yml• L190-301 .github/…/ci.yml• L351-380 scripts/check-engine-release.mjs• L107-150 scripts/test-suites.mjs• L16-43 package.json• L26-35

CLI smoke validation

The CLI smoke paths test the public user journey against a real service without using a developer's normal home or repository. The launch smoke covers production or staging sign-in, account state, detection, optional uploads, and agent connection. The staging end-to-end path adds a seeded sign-in, project installation, engine dispatch, design-health checks, session refresh, and MCP setup.

Both paths use disposable files and bounded cleanup. Staging consent comes from a separate pristine checkout, so the test does not pass session data through the test script. Their output uses explicit pass or fail results so release operators can distinguish an unavailable staging service from a product failure. (scripts/launch-smoke.sh• L1-22, scripts/launch-smoke.sh• L47-80, scripts/launch-smoke.sh• L85-121, scripts/launch-smoke.sh• L123-203, scripts/staging-cli-e2e.sh• L1-22, scripts/staging-cli-e2e.sh• L34-56, scripts/staging-cli-e2e.sh• L60-115, scripts/staging-cli-e2e.sh• L117-286)

References: scripts/launch-smoke.sh• L1-22 scripts/launch-smoke.sh• L47-80 scripts/launch-smoke.sh• L85-121 scripts/launch-smoke.sh• L123-203 scripts/staging-cli-e2e.sh• L1-22 scripts/staging-cli-e2e.sh• L34-56 scripts/staging-cli-e2e.sh• L60-115 scripts/staging-cli-e2e.sh• L117-286

Test strategy

The test harness checks the system at several distances from its source. Fast checks cover build and transform contracts. Higher-level suites check the boundaries that users, agent hosts, browsers, and release systems consume.

Suite selection

Named suites run through one shared runner. The default group covers core build and provider contracts, engine behavior, detector packaging, live helpers, framework fixtures, and plugin loading. Opt-in groups cover remote checks, browser sweeps, native review flows, model-backed skill behavior, completed workflows, and provider-backed adapters.

Suite metadata maps changed paths to the suites that own them. Test files also trigger their own suites, so a test change cannot silently remove its coverage from CI. The CLI remote lane remains available as a named compatibility path even though its active remote coverage now lives with the engine. Provider-backed jobs skip when their required key is absent instead of treating an unauthenticated CI run as a product failure. (scripts/test-suites.mjs• L4-14, scripts/test-suites.mjs• L16-43, scripts/test-suites.mjs• L76-99, scripts/test-suites.mjs• L101-192, scripts/test-suites.mjs• L198-227, scripts/test-suites.mjs• L229-383, scripts/test-suites.mjs• L389-454)

References: scripts/test-suites.mjs• L4-14 scripts/test-suites.mjs• L16-43 scripts/test-suites.mjs• L76-99 scripts/test-suites.mjs• L101-192 scripts/test-suites.mjs• L198-227 scripts/test-suites.mjs• L229-383 scripts/test-suites.mjs• L389-454 .github/…/ci.yml• L35-66

Coverage layers

Core tests protect build, provider, hook, plugin, release, and component-review contracts. Oracle tests replay fixed engine behavior. Detector tests protect browser packaging and reports. Framework and live end-to-end tests exercise real development servers and browser interaction across fixtures.

The live flow stages a fixture, starts the engine and development server, injects live mode, drives the browser, accepts a variant, and checks both source and rendered output. Model-backed suites check skill setup, routing, reference loading, native-platform guidance, and activation boundaries. Expensive completed workflows run only through explicit dispatch with a prepared browser and retained traces.

References: tests/…/lib.mjs• L1-25 tests/live-e2e.test.mjs• L1-20 tests/live-e2e.test.mjs• L80-103 tests/…/session.mjs• L93-123 tests/…/session.mjs• L214-263 tests/…/fixture.json• L1-63 tests/…/README.md• L1-29 tests/…/README.md• L38-68 .github/…/ci.yml• L727-790

Release paths

Skill, CLI, extension, and engine releases use separate policies because they publish different artifacts. Release preflight checks the component version, repository state, changelog, and required artifact before it creates a tag and GitHub release. The engine workflow then produces the platform assets that dependent paths consume.

Component versions

Each product reads its release version from its own source of truth. The CLI uses the root package. Agent hosts use plugin metadata. The launcher uses the pinned engine version, and the engine workspace defines the native package version. Related skill and plugin versions must agree so installation and marketplace signals describe one release.

The engine tag, workspace version, launcher pin, platform package versions, and checksum records form one dependency chain. A change to one link is incomplete until the matching assets exist. The root package keeps its platform package pins aligned with the engine version so the CLI can resolve a matching binary. (package.json• L86-91)

References: scripts/release.mjs• L18-81 scripts/release.mjs• L123-205 scripts/release.mjs• L459-474 scripts/…/validate-plugin-versions.js• L1-20 plugin/…/plugin.json• L1-12 plugin/…/plugin.json• L1-20 plugin/…/VERSION• L1 Cargo.toml• L4-12 ENGINE_VERSION• L1 package.json• L86-91 plugin/…/engine-checksums.txt• L1-9

Release safeguards

Release preflight refuses a dirty tree, an unpushed commit, an existing tag, a missing changelog entry, or a missing artifact. Engine-dependent skill and CLI releases also stop when the pinned engine release is incomplete or when engine source changed after that engine tag.

The engine workflow checks that the tag and workspace version match. A manual workflow run rehearses the platform builds and smoke checks without signing or publishing. A tag run publishes only after target builds finish and the Windows binary passes its protected signing checks. Release assets include per-file checksums, which gives the launcher and later release checks a stable trust boundary.

The extension release is independent of the engine because it carries its detector code and does not run the engine binary. Skill releases sign the universal bundle before tagging, while CLI and extension releases publish their package or browser archives through their own follow-up channels. (scripts/release.mjs• L60-73, scripts/release.mjs• L210-325, scripts/release.mjs• L331-381)

References: scripts/release.mjs• L60-73 scripts/release.mjs• L136-205 scripts/release.mjs• L208-325 scripts/release.mjs• L331-381 scripts/release.mjs• L459-534 scripts/check-loop-release.mjs• L15-82 scripts/check-loop-release.mjs• L84-92 scripts/cli-pro-release-keys.json• L1 .github/…/release-engine.yml• L12-19 .github/…/release-engine.yml• L41-80 .github/…/release-engine.yml• L81-140 .github/…/release-engine.yml• L141-175 tests/release-engine-workflow.test.js• L11-81 plugin/…/impeccable• L106-253

Detailed plugin assembly belongs in Plugin packaging and installation. Build, release, and CI automation belongs in Build, release, and validation. Suite ownership and test contracts belong in Automated test harness.

Change checklist

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

  • Changes to shared skill source or provider placeholders can require regenerated provider trees, plugins, and the universal bundle.
  • Changes to provider metadata, agent formats, hook paths, or provider payloads need checks for host loader contracts and generated copies.
  • Changes to generated scripts must preserve launcher executable modes and Windows batch line endings.
  • Changes to detector inputs can require updated rule data and both browser archives.
  • Changes to the engine version need matching platform binaries, npm packages, launcher pins, and checksum records before dependent releases.
  • Changes to live accept controls, session recovery, or cleanup need matching skill guidance, browser code, and end-to-end contracts.
  • New test files need suite ownership and an effective change trigger in the suite registry.
  • Changes to skill activation text need both the model-backed behavior suite and the separate activation suite.
  • Changes to provider-backed tests must keep private key loading and child-process key filtering intact.
  • Changes to CLI sign-in, account uploads, or agent connection need both production and staging smoke paths checked with disposable credentials and homes.

Important failure modes

TriggerConsequenceGuard
Generated provider output is not rebuiltInstall paths receive different skill behaviorCI drift checks and generated-output synchronization
A provider transform emits the wrong metadata or hook pathThe host installs the package but cannot invoke itProvider transforms and manifest checks
A generated launcher loses its executable mode or Windows line endingsUnix installs fail or Windows cannot run the launcherMode preservation and build validation
A plugin or skill version changes in only one manifestMarketplace and update signals describe different releasesRelated-version validation
Detector source changes without extension packagingThe extension runs stale detector codeDetector checks and extension build validation
The pinned engine release lacks a binary, digest, or platform packageInstall and first-run downloads stopEngine readiness and checksum checks
Engine source changes after the pinned engine tagA release can claim a binary that does not match its sourceEngine source guard in release preflight
A test file has no suite triggerCI can pass without running the changed testSuite self-trigger validation
A provider key reaches a fixture child processFixture code can read a developer or CI credentialFiltered child environments
Live accept leaves temporary wrappers or markersSource or the browser keeps stale runtime stateCleanup and completion checks
Windows signing or artifact transfer is bypassedAn unsigned or wrong-run binary can enter the public releaseProtected signing and same-run artifact checks
A smoke run uses a normal home or real repositoryThe test can alter user state or upload unintended dataFresh homes, throwaway repositories, and bounded cleanup
Staging consent or service assets are not readyThe end-to-end run reports a setup failure instead of product behaviorService preflight and separate staging consent

Key files

FileWhy to read it
package.jsonDefines the public CLI boundary, Node floors, platform package pins, and build, test, and release commands.
ENGINE_VERSIONPins the engine release consumed by skill and CLI delivery.
scripts/build.jsShows how shared skill content becomes provider output, plugins, bundles, and checked artifacts.
scripts/build-extension.jsShows how detector output is checked and packaged for Chrome and Firefox.
scripts/…/providers.jsDefines host-specific package contracts.
.github/…/ci.ymlShows change-based suite selection, build gates, generated-output checks, engine readiness, and browser checks.
.github/…/sync-generated-output.ymlShows how generated provider output is rebuilt and synchronized.
.github/…/release-engine.ymlShows cross-platform engine builds, protected signing, checksums, and publication.
scripts/check-engine-release.mjsChecks that pinned engine assets and platform packages exist before dependent releases.
scripts/test-suites.mjsDefines suite coverage, opt-in groups, and change triggers.
scripts/launch-smoke.shExercises the production or staging CLI journey in a disposable environment.
scripts/staging-cli-e2e.shExercises staging sign-in, install, engine dispatch, account flows, and agent setup.
scripts/release.mjsDefines component release policies and preflight safeguards.
cli/…/skills.mjsShows the user-facing install, update, bundle, and provider-selection flow.
plugin/skills/impeccable/scripts/impeccableDefines engine selection, verification, caching, and download behavior.
tests/live-e2e.test.mjsDefines the user-visible live browser flow from start through accepted source.
tests/…/harness.mjsDefines disposable workspaces and model-driven skill checks.