# Build Processes in Arc-Kit: A Complete Guide to the Multi-AI Distribution Pipeline

> Explore Arc-Kits automated five-stage build pipeline. Transform your Claude repo into distributions for Gemini, Copilot, Codex, OpenCode, and Paperclip efficiently.

- Repository: [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
- Tags: how-to-guide
- Published: 2026-04-19

---

**Arc-Kit transforms a single Claude-centric source repository into platform-specific distributions for Gemini, Copilot, Codex, OpenCode, and Paperclip through an automated five-stage build pipeline.**

The **build processes in arc-kit** convert raw commands, agents, and templates from the `arckit-claude/` source directory into optimized artifacts for each supported AI platform. This mono-repo architecture ensures version consistency across all distributions while maintaining a single source of truth for feature development.

## Core Build Pipeline Components

The build pipeline consists of five distinct stages managed by scripts in the `scripts/` directory. Each stage handles a specific transformation or distribution task.

### Package Compilation

The foundation of the build process creates an installable Python wheel for the `arckit-cli` package. The [`pyproject.toml`](https://github.com/tractorjuice/arc-kit/blob/main/pyproject.toml) file defines the project metadata, dependencies, and Hatch build backend.

```bash

# Install in editable mode for development

pip install -e .

# Build the distribution wheel

python -m build

# or: uv build

```

This generates a wheel in `dist/arckit_cli-<version>.whl` and registers the `arckit` CLI entry point defined in [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py).

### Command Conversion

The [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) script serves as the central transformation engine. It reads source files from `arckit-claude/commands/` and `arckit-claude/agents/`, then strips Claude-specific front-matter and rewrites content for each target platform.

**Conversion outputs include:**

- **Markdown prompts** for Codex and OpenCode
- **TOML agents** for Gemini
- **Prompt files** for GitHub Copilot
- **JSON configurations** for Paperclip

The script also copies supporting templates, scripts, and guides into each extension directory (`arckit-gemini/`, `arckit-codex/`, `arckit-copilot/`, `arckit-opencode/`). Running `python scripts/converter.py` is idempotent—executing it after any command change regenerates all downstream artifacts without manual intervention.

### Version Management

The [`scripts/bump-version.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/bump-version.sh) script ensures version consistency across the entire mono-repo. It accepts a semantic version string as input and updates every version reference in a single atomic operation.

```bash

# Bump all version strings to 4.6.14

scripts/bump-version.sh 4.6.14

```

**Modified files include:**

- `VERSION` (root version file)
- [`pyproject.toml`](https://github.com/tractorjuice/arc-kit/blob/main/pyproject.toml) (package version)
- Every [`README.md`](https://github.com/tractorjuice/arc-kit/blob/main/README.md) badge
- All extension `VERSION` files
- Claude plugin manifest

The script validates the semver format before execution and prints a verification summary upon completion.

### Release Notes Generation

The [`scripts/generate-release-notes.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/generate-release-notes.sh) script automates Keep-a-Changelog formatting by parsing Git history between tags.

```bash

# Generate notes from the last tag

scripts/generate-release-notes.sh v4.6.13

```

The script walks the Git log, groups commits into standard sections (Added, Fixed, Changed, Breaking), and appends the formatted output to [`CHANGELOG.md`](https://github.com/tractorjuice/arc-kit/blob/main/CHANGELOG.md). This ensures release documentation remains consistent with the codebase evolution.

### Extension Publishing

The [`scripts/push-extensions.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/push-extensions.sh) script synchronizes generated extension directories to their dedicated GitHub repositories.

```bash

# Push specific extensions

scripts/push-extensions.sh gemini codex copilot opencode

```

**Execution flow:**

1. Clones each target repository (e.g., `arckit-gemini`)
2. Synchronizes the generated directory contents
3. Commits changes with descriptive messages
4. Pushes to origin

The script respects the `GH_TOKEN` environment variable for authentication, enabling automated CI/CD pipelines to publish distributions without interactive login.

## The Build Execution Flow

Developers typically execute the build pipeline in this sequence during a release cycle:

```bash

# 1. Install the CLI package

pip install -e .

# 2. Build the wheel

python -m build

# 3. Convert commands to all target formats

python scripts/converter.py

# 4. Bump version (example: 4.6.14)

scripts/bump-version.sh 4.6.14

# 5. Generate release notes from previous tag

scripts/generate-release-notes.sh v4.6.13

# 6. Verify markdown formatting

npx markdownlint-cli2 "**/*.md"

# 7. Push extensions to their repositories

scripts/push-extensions.sh gemini codex copilot opencode

```

## Key Build Files and Their Roles

| File | Purpose |
|------|---------|
| [`pyproject.toml`](https://github.com/tractorjuice/arc-kit/blob/main/pyproject.toml) | Declares package metadata, Hatch build backend, and shared data paths |
| [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py) | CLI entry point exposing `arckit init` and `arckit check` commands |
| [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) | Core transformation engine for multi-platform command conversion |
| [`scripts/bump-version.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/bump-version.sh) | Atomic version updater across all mono-repo artifacts |
| [`scripts/generate-release-notes.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/generate-release-notes.sh) | Keep-a-Changelog generator from Git history |
| [`scripts/push-extensions.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/push-extensions.sh) | Multi-repository synchronization and publishing tool |
| `arckit-claude/` | Source directory containing Claude-specific commands, agents, templates, and plugin manifest |
| `.markdownlint-cli2.jsonc` | Linting configuration ensuring consistent Markdown formatting across generated outputs |

## How the Build Process Supports Extensibility

The **build processes in arc-kit** implement several architectural patterns that enable rapid platform expansion:

- **Single source of truth** – All commands reside in `arckit-claude/commands/`. The [`converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/converter.py) script guarantees that Claude, Gemini, Copilot, Codex, and OpenCode distributions remain functionally identical despite format differences.

- **Automation-first design** – The conversion pipeline is idempotent. Developers modify source files once, and the build system regenerates every downstream artifact without manual copying or editing.

- **Version consistency** – [`bump-version.sh`](https://github.com/tractorjuice/arc-kit/blob/main/bump-version.sh) eliminates version drift between the CLI package, VS Code plugin, and platform-specific extensions by applying atomic updates across all `VERSION` files, [`pyproject.toml`](https://github.com/tractorjuice/arc-kit/blob/main/pyproject.toml), and manifests.

- **Release reproducibility** – The combination of [`generate-release-notes.sh`](https://github.com/tractorjuice/arc-kit/blob/main/generate-release-notes.sh) and the CI-driven lint step creates a deterministic pipeline where every release tag produces identical, verifiable artifacts across all target repositories.

## Summary

- **Arc-kit** transforms Claude-centric source code into multi-AI distributions through a five-stage build pipeline.
- **[`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py)** serves as the central engine, rewriting commands for Gemini, Copilot, Codex, OpenCode, and Paperclip formats.
- **[`scripts/bump-version.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/bump-version.sh)** maintains semantic version consistency across the CLI, plugin, and all extension repositories.
- **[`scripts/push-extensions.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/push-extensions.sh)** automates publication to dedicated GitHub repos using the `GH_TOKEN` environment variable.
- The build supports **editable installation** via `pip install -e .` and wheel generation through `python -m build`.

## Frequently Asked Questions

### What is the primary script responsible for converting ArcKit commands to other AI platforms?

The [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) file serves as the central transformation engine. It reads source files from `arckit-claude/commands/` and `arckit-claude/agents/`, strips Claude-specific front-matter, and generates platform-specific outputs including TOML agents for Gemini, JSON for Paperclip, and Markdown prompts for Codex and OpenCode.

### How does ArcKit maintain version consistency across multiple repositories?

The [`scripts/bump-version.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/bump-version.sh) script provides atomic version updates by accepting a semantic version string (e.g., `4.6.14`) and updating every reference simultaneously. It modifies the root `VERSION` file, [`pyproject.toml`](https://github.com/tractorjuice/arc-kit/blob/main/pyproject.toml), all [`README.md`](https://github.com/tractorjuice/arc-kit/blob/main/README.md) badges, extension `VERSION` files, and the Claude plugin manifest, then prints a verification summary.

### What environment variable is required for publishing extensions to their respective GitHub repositories?

The [`scripts/push-extensions.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/push-extensions.sh) script requires the `GH_TOKEN` environment variable for authentication. This token enables the script to clone target repositories (such as `arckit-gemini`), synchronize generated extension contents, commit changes, and push to origin without interactive login prompts.

### Can the ArcKit build process be run incrementally during development?

Yes, developers can install the package in editable mode using `pip install -e .` to test changes without rebuilding the wheel. The [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) script is idempotent, meaning it can be run repeatedly after any command or template modification to regenerate all downstream artifacts without side effects.