# How Impeccable Assembles the Universal Bundle from Provider Outputs

> Learn how Impeccable's build system assembles the universal bundle from provider outputs using the assembleUniversal function, creating ready-to-distribute bundles for AI assistants.

- Repository: [Paul Bakaus/impeccable](https://github.com/pbakaus/impeccable)
- Tags: internals
- Published: 2026-03-09

---

**Impeccable's build system aggregates provider-specific configuration folders into a single `universal` directory using the `assembleUniversal` function in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js), which maps each AI assistant's output into a ready-to-distribute bundle with optional prefixed skill variants.**

The `pbakaus/impeccable` repository transforms canonical skill definitions into provider-native formats for Cursor, Claude Code, Gemini, Codex, Agents, and Kiro. To distribute these efficiently, the build pipeline must assemble the universal bundle from provider outputs, co-locating all supported configurations into a single, self-documented package. This process ensures users receive a consistent installation experience across every supported AI toolchain.

## The Assembly Pipeline

The core logic resides in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js), where the `assembleUniversal` function orchestrates the consolidation of disparate provider builds into one distributable structure.

### Preparation and Cleanup

The function accepts a `distDir` path and an optional `suffix` parameter (used to distinguish regular and prefixed variants). It first constructs the target directory path and removes any existing universal folder to ensure clean output.

```javascript
function assembleUniversal(distDir, suffix = '') {
  const universalDir = path.join(distDir, `universal${suffix}`);

  // Clean previous output
  if (fs.existsSync(universalDir)) {
    fs.rmSync(universalDir, { recursive: true, force: true });
  }

```

This initialization prevents stale files from contaminating new builds, critical for reproducible distribution artifacts.

### Provider Mapping Strategy

An explicit mapping array defines the relationship between internal provider names and their emitted configuration directories. This hardcoded registry in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js) lines 42-48 ensures the build system knows exactly which dot-folders to collect.

- **Cursor** maps to `.cursor`
- **Claude Code** maps to `.claude`
- **Gemini** maps to `.gemini`
- **Codex** maps to `.codex`
- **Agents** maps to `.agents`
- **Kiro** maps to `.kiro`

This declarative approach makes it trivial to add new providers by extending the `providerMappings` array.

### Directory Copying Logic

For each mapping, the script constructs source and destination paths dynamically. When the `suffix` is `-prefixed`, it targets directories like `dist/cursor-prefixed/.cursor` instead of the standard `dist/cursor/.cursor`. The helper `copyDirSync` recursively transfers the entire directory tree only if the source exists.

```javascript
const providerMappings = [
  { provider: 'cursor',      configDir: '.cursor' },
  { provider: 'claude-code', configDir: '.claude' },
  { provider: 'gemini',      configDir: '.gemini' },
  { provider: 'codex',       configDir: '.codex' },
  { provider: 'agents',      configDir: '.agents' },
  { provider: 'kiro',        configDir: '.kiro' },
];

for (const { provider, configDir } of providerMappings) {
  const src = path.join(distDir, `${provider}${suffix}`, configDir);
  const dest = path.join(universalDir, configDir);
  if (fs.existsSync(src)) {
    copyDirSync(src, dest);
  }
}

```

This loop ensures that even if a specific provider build is missing, the universal bundle assembly continues for the remaining platforms.

### Documentation Generation

Because the assembled folders are hidden dot-directories (e.g., `.cursor`, `.claude`), the build script generates a [`README.txt`](https://github.com/pbakaus/impeccable/blob/main/README.txt) file inside the universal directory to guide installation. When the `suffix` indicates a prefixed bundle, the README includes a special note that **skill IDs are prefixed with `i-`** to avoid collisions.

```javascript
const prefixNote = suffix ? '\nSkills in this bundle are prefixed with i- …\n' : '';
fs.writeFileSync(
  path.join(universalDir, 'README.txt'),
  `Impeccable — Design fluency for AI harnesses\nhttps://impeccable.style\n${prefixNote}…`
);

```

This self-documentation eliminates ambiguity for end users unpacking the archive into their projects.

## Build Integration and Packaging

The universal assembly integrates into the main build flow through explicit orchestration and subsequent compression.

### Dual Bundle Generation

The `build()` function in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js) invokes `assembleUniversal` twice to create both distribution variants:

```javascript
// Inside build()
assembleUniversal(DIST_DIR);                // regular bundle
assembleUniversal(DIST_DIR, '-prefixed');   // prefixed bundle

```

This dual-pass approach generates `universal/` and `universal-prefixed/` directories side-by-side in the `dist` folder, accommodating users who need namespaced skill identifiers.

### ZIP Archive Creation

After assembly, the `createAllZips` function in [`scripts/lib/zip.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/zip.js) compresses these directories into `universal.zip` and `universal-prefixed.zip`. This final step transforms the assembled directories into single-file artifacts ready for GitHub releases or direct download.

```javascript
await createAllZips(DIST_DIR);  // Creates universal.zip & universal-prefixed.zip

```

According to the source code in [`scripts/lib/zip.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/zip.js), this utility specifically targets the universal directories alongside individual provider packages, ensuring the aggregated bundles receive the same distribution treatment as standalone builds.

## Summary

- **Clean slate approach**: `assembleUniversal` always removes existing `universal` directories before copying to prevent stale artifacts.
- **Explicit provider registry**: The `providerMappings` array in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js) hardcodes the six supported AI assistants and their respective config folder names.
- **Suffix-driven variants**: Passing `'-prefixed'` as the suffix parameter triggers alternative source paths and modified README documentation.
- **Recursive file operations**: The `copyDirSync` helper handles deep directory trees, while `fs.rmSync` with `recursive: true` ensures clean deletion.
- **Self-documenting output**: Generated [`README.txt`](https://github.com/pbakaus/impeccable/blob/main/README.txt) files explain the bundle contents and prefixing behavior directly within the distribution archive.

## Frequently Asked Questions

### What is the universal bundle in Impeccable?

The universal bundle is a consolidated directory containing configuration folders for all six supported AI providers (Cursor, Claude Code, Gemini, Codex, Agents, and Kiro) in their native formats. It allows users to copy a single `universal` folder into their project to enable Impeccable skills across every supported toolchain simultaneously.

### How does the build script handle prefixed vs regular bundles?

The `assembleUniversal` function accepts a `suffix` parameter that defaults to an empty string. When called with `'-prefixed'`, it sources files from directories like `cursor-prefixed/` instead of `cursor/`, and injects a note into the README explaining that all skill IDs carry the `i-` prefix. The build script runs the function twice—once without and once with the suffix—to generate both variants.

### Where are the provider-specific configuration files stored?

Individual provider builds reside in `dist/{provider}/` (e.g., `dist/cursor/.cursor`, `dist/claude-code/.claude`). The `assembleUniversal` function aggregates these into `dist/universal/` by copying each provider's dot-folder into the combined structure according to the mappings defined in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js).

### What utility functions support the universal assembly process?

The process relies on ** `copyDirSync`** for recursive directory copying and ** `fs.rmSync`** with the `recursive: true` option for cleanup. Additionally, the ** `createAllZips`** function in [`scripts/lib/zip.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/zip.js) handles the final compression of the assembled universal directories into distribution-ready ZIP archives.