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

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 file defines the project metadata, dependencies, and Hatch build backend.

# 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.

Command Conversion

The 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 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.

# Bump all version strings to 4.6.14

scripts/bump-version.sh 4.6.14

Modified files include:

• VERSION (root version file)
• pyproject.toml (package version)
• Every 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 script automates Keep-a-Changelog formatting by parsing Git history between tags.

# 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. This ensures release documentation remains consistent with the codebase evolution.

Extension Publishing

The scripts/push-extensions.sh script synchronizes generated extension directories to their dedicated GitHub repositories.

# 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:

# 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	Declares package metadata, Hatch build backend, and shared data paths
src/arckit_cli/__init__.py	CLI entry point exposing arckit init and arckit check commands
scripts/converter.py	Core transformation engine for multi-platform command conversion
scripts/bump-version.sh	Atomic version updater across all mono-repo artifacts
scripts/generate-release-notes.sh	Keep-a-Changelog generator from Git history
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 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 eliminates version drift between the CLI package, VS Code plugin, and platform-specific extensions by applying atomic updates across all VERSION files, pyproject.toml, and manifests.

• Release reproducibility – The combination of 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 serves as the central engine, rewriting commands for Gemini, Copilot, Codex, OpenCode, and Paperclip formats.
• scripts/bump-version.sh maintains semantic version consistency across the CLI, plugin, and all extension repositories.
• 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 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 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, all 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 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 script is idempotent, meaning it can be run repeatedly after any command or template modification to regenerate all downstream artifacts without side effects.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}