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

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)

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:

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:

git checkout -b feature/your-feature-name

According to 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:

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

python scripts/converter.py

This step is critical because 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:

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

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

# Gemini CLI example

gemini
/arckit:your-new-command Test description

6. Update the Changelog

Add an entry under the "Unreleased" section in CHANGELOG.md describing your change following the existing format.

7. Commit and Push

Use Conventional Commits format as specified in CONTRIBUTING.md:

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

Push your branch to your fork:

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	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	Generates multi-AI extensions (Codex, Gemini, OpenCode, Copilot) from Claude sources	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	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 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 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.

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