# How to Contribute to ArcKit: Enterprise Architecture Governance Toolkit Development Guide

> Contribute to the ArcKit enterprise architecture governance toolkit. Fork the repo, add commands or docs, sync extensions, and submit a pull request. Easy developer guide to join development.

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

---

**To contribute to arc-kit, fork the repository, create a feature branch, add your command or documentation to `arckit-claude/commands/` or `docs/guides/`, run `python scripts/converter.py` to sync multi-AI extensions, and submit a pull request with updated changelog entries.**

ArcKit is an open-source Enterprise Architecture Governance and Vendor Procurement toolkit that functions as a Claude Code plugin while generating compatible extensions for Codex, Gemini, OpenCode, and Copilot. Contributing to arc-kit involves adding new slash commands, improving documentation, fixing bugs, or enhancing the conversion scripts that maintain synchronization across all AI targets.

## Understanding the ArcKit Repository Structure

The codebase is organized into distinct areas that separate the core Claude plugin from multi-AI converters and documentation.

### Core Plugin (`arckit-claude/`)

Contains the source of truth for Claude Code commands and agents. Commands live in `arckit-claude/commands/` as Markdown files with YAML front-matter. Agents for heavy web research reside in `arckit-claude/agents/`.

### Converter Script ([`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py))

Generates Codex, Gemini, OpenCode, and Copilot assets from the Claude plugin sources. This ensures all AI extensions remain synchronized when commands are added or modified.

### Templates (`arckit-claude/templates/`)

Markdown document templates used by commands to generate compliant architecture artifacts.

### CLI Package (`src/arckit_cli/`)

Implements the `arckit init` command that scaffolds new projects with the `.arckit/`, `.agents/`, `.codex/`, `.opencode/`, and `docs/` directory structure.

### Documentation (`docs/guides/`)

Human-readable guides explaining command usage and integration patterns.

## Step-by-Step Contribution Workflow

### 1. Fork and Clone the Repository

Start by forking the repository on GitHub, then clone your local copy:

```bash
git clone https://github.com/YOUR-USERNAME/arc-kit.git
cd arc-kit

```

### 2. Create a Feature Branch

Use descriptive branch names that indicate the change type:

```bash
git checkout -b feature/your-feature-name

```

According to [`CONTRIBUTING.md`](https://github.com/tractorjuice/arc-kit/blob/main/CONTRIBUTING.md), branch naming conventions help maintainers identify the scope of changes during review.

### 3. Implement Your Changes

#### Adding a New Command

Create a Markdown file in `arckit-claude/commands/` following the front-matter template from [`CONTRIBUTING.md`](https://github.com/tractorjuice/arc-kit/blob/main/CONTRIBUTING.md):

```markdown
---
description: Brief description of what the command does
---

# Command Title

## Purpose

Detailed explanation of the command's function.

## When to Run

Specific context or phase when this command should be invoked.

## What It Generates

- List of artifacts created
- File formats produced
- Compliance mappings

```

#### Improving Documentation

Add or modify files in `docs/guides/` to explain use cases, integration points, or examples. Documentation updates should follow the existing Markdown structure and include practical examples.

### 4. Synchronize Multi-AI Extensions

Run the converter script to regenerate assets for Codex, Gemini, OpenCode, and Copilot:

```bash
python scripts/converter.py

```

This step is critical because [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) reads the source Markdown, rewrites paths, extracts agents, and emits the various output formats required by different AI platforms.

### 5. Test Your Changes

Verify your command works in Claude Code:

```text
/plugin marketplace add tractorjuice/arc-kit
/arckit.your-new-command "Test description"

```

For other AI platforms, test using their respective CLI tools:

```bash

# Gemini CLI example

gemini
/arckit:your-new-command Test description

```

### 6. Update the Changelog

Add an entry under the "Unreleased" section in [`CHANGELOG.md`](https://github.com/tractorjuice/arc-kit/blob/main/CHANGELOG.md) describing your change following the existing format.

### 7. Commit and Push

Use Conventional Commits format as specified in [`CONTRIBUTING.md`](https://github.com/tractorjuice/arc-kit/blob/main/CONTRIBUTING.md):

```text
feat(commands): add /arckit.my-new-command

```

Push your branch to your fork:

```bash
git push origin feature/your-feature-name

```

### 8. Open a Pull Request

Submit a PR against the `main` branch. The PR template requires verification that you have:
- Run the converter script
- Updated relevant documentation
- Added changelog entries
- Tested the command in at least one AI environment

## Key Files Every Contributor Should Know

| File | Purpose | Location |
|------|---------|----------|
| [`CONTRIBUTING.md`](https://github.com/tractorjuice/arc-kit/blob/main/CONTRIBUTING.md) | Complete contribution guidelines including fork workflow, branch naming, and commit conventions | Repository root |
| `arckit-claude/commands/` | Source of truth for slash commands (Markdown with YAML front-matter) | `arckit-claude/commands/` |
| `arckit-claude/agents/` | Heavy-research agents invoked via `/task` | `arckit-claude/agents/` |
| [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) | Generates multi-AI extensions (Codex, Gemini, OpenCode, Copilot) from Claude sources | [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) |
| `arckit-claude/templates/` | Markdown templates for compliant architecture artifacts | `arckit-claude/templates/` |
| `docs/guides/` | Human-readable documentation and integration guides | `docs/guides/` |
| [`CHANGELOG.md`](https://github.com/tractorjuice/arc-kit/blob/main/CHANGELOG.md) | Version history and release notes | Repository root |
| `VERSION` | Single source of truth for package version | Repository root |

## Summary

- **Fork and branch**: Create a feature branch from your fork of `tractorjuice/arc-kit`.
- **Add commands**: Create Markdown files in `arckit-claude/commands/` with proper front-matter.
- **Sync extensions**: Always run `python scripts/converter.py` to update Codex, Gemini, OpenCode, and Copilot assets.
- **Test thoroughly**: Verify commands in Claude Code and other AI environments before submitting.
- **Document changes**: Update [`CHANGELOG.md`](https://github.com/tractorjuice/arc-kit/blob/main/CHANGELOG.md) and relevant guides in `docs/guides/`.
- **Follow conventions**: Use Conventional Commits and descriptive branch names.

## Frequently Asked Questions

### How do I add a new slash command to ArcKit?

Create a new Markdown file in `arckit-claude/commands/` with YAML front-matter containing a description field, followed by the command content. After creating the file, run `python scripts/converter.py` to generate the corresponding assets for Codex, Gemini, OpenCode, and Copilot platforms.

### What is the purpose of the converter script in arc-kit?

The [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) file serves as the synchronization engine that reads the Claude Code plugin source files, rewrites paths, extracts agent definitions, and emits compatible extension formats for multiple AI platforms including Codex, Gemini, OpenCode, and Copilot.

### Do I need to test my changes in all AI environments before submitting a PR?

While the PR template requires verification that you have tested your changes, you should at minimum test in Claude Code using `/arckit.your-command`. If possible, also verify in Gemini CLI or other available environments to ensure the converter script properly generated compatible assets.

### Where should I document new features or commands for arc-kit?

Add human-readable guides to `docs/guides/` explaining use cases, integration points, and practical examples. Additionally, ensure the command file in `arckit-claude/commands/` contains comprehensive documentation within the Markdown content describing purpose, when to run, and generated artifacts.