How to Set Up a New Project with Arc-Kit: Complete Initialization Guide

Run arckit init <project-name> --ai <assistant> to scaffold a complete architecture governance project with templates, helper scripts, AI-specific assets, and optional Git initialization in seconds.

Setting up a new project with arc-kit establishes a standardized, version-controlled environment for architecture governance and AI-assisted documentation. The tractorjuice/arc-kit repository provides a CLI tool that automates the entire scaffolding process, copying templates, installing AI assistant configurations, and preparing the directory structure according to the arckit init command logic implemented in src/arckit_cli/__init__.py.

Understanding the arckit init Command Structure

The initialization process is driven by the arckit init command defined in the CLI entry point. When executed, it performs argument validation, displays a banner, and orchestrates the creation of the project skeleton.

AI Assistant Selection and Configuration

The CLI prompts for an AI assistant if none is supplied via the --ai flag. The mapping between assistants and their data folders is controlled by the AGENT_CONFIG dictionary located at lines 44‑62 of src/arckit_cli/__init__.py.

Supported assistants include:

• Codex – Maps to .codex/ directory and MCP configuration
• OpenCode – Maps to .opencode/ directory with command files
• Copilot – Maps to .github/ directory with prompts and agents

Step-by-Step Project Initialization Process

The create_project_structure function at lines 23‑39 orchestrates the directory creation, while specialized functions handle asset installation.

1. Core Directory Skeleton Creation

The function creates the foundational folder structure:

• .arckit/ – Contains shared scripts and templates
• projects/ – Houses architecture governance projects, including a 000-global/ folder
• AI-specific directories (.codex/, .opencode/, or .github/) based on the AGENT_CONFIG mapping

The directory creation loop operates at lines 62‑64 of the source file.

2. Template and Script Provisioning

Default templates are copied from the package data directory to .arckit/templates/ (lines 84‑88). These templates include Markdown structures for requirements, SOBC documents, and risk registers.

Helper Bash scripts are installed to .arckit/scripts/bash/ (lines 94‑100), including utilities like generate-document-id.sh and create-project.sh that commands invoke at runtime.

3. AI Assistant Asset Installation

Depending on the selected assistant, specific configurations are deployed:

For Codex (lines 15‑34):

• Skills copied to .agents/skills/
• Agent configurations to .codex/agents/
• MCP server configuration to .codex/config.toml

For OpenCode (lines 54‑86):

• Command files (arckit.*.md) to .opencode/commands/
• Agent definitions to .opencode/agents/
• .envrc file setting OPENCODE_HOME

For Copilot (lines 92‑104):

• Prompt markdown files to .github/prompts/
• Custom agents to .github/agents/
• copilot-instructions.md for VS Code context

4. Documentation and Version Control Setup

Unless the --minimal flag is passed, the CLI copies documentation guides, README files, dependency matrices, and workflow diagrams (lines 33‑66). Version and changelog files are also installed (lines 68‑74) to enable the project to report its own version.

Git initialization is handled by init_git_repo (lines 0‑5 of that function). If the git executable is present and --no-git is not specified, the function runs git init, adds all files, and creates an initial commit.

Practical Examples for Setting Up a New Project with Arc-Kit

Basic Initialization with Codex

arckit init payment-modernization

This creates the full directory structure including .codex/agents/, .agents/skills/, and a global project folder at projects/000-global/.

Minimal OpenCode Setup

arckit init my-project --ai opencode --minimal

The --minimal flag skips the docs/ directory while still creating .opencode/commands/ and the .envrc configuration.

Copilot-Optimized Scaffold

arckit init my-vendor-procurement --ai copilot

Generates .github/prompts/ with architecture-specific prompt files and .github/agents/ for GitHub Copilot integration.

Git-Disabled Initialization

arckit init research-project --ai codex --no-git

Creates the project structure without initializing a .git/ repository, suitable for environments lacking Git or when integrating into existing version control.

Post-Initialization Usage

After setting up a new project with arc-kit, start your AI assistant and invoke ArcKit commands:

# Codex example

codex
$arckit-principles Create high-level architecture principles

# OpenCode example

opencode
/arckit.principles Create high-level architecture principles

# Copilot example (VS Code Chat)

/arckit-principles Create high-level architecture principles

Core Implementation Details

The initialization logic resides in src/arckit_cli/__init__.py, with specific functions handling distinct aspects of project creation:

Aspect	Implementation	Location
AI Configuration	AGENT_CONFIG dictionary maps assistants to folders and install URLs	Lines 44‑62
Data Path Resolution	get_data_paths() searches source, uv, pip, and platformdirs locations	Lines 47‑70
Directory Creation	create_project_structure() builds .arckit, projects/, and AI folders	Lines 23‑39
Template Installation	Copy loop from package data to .arckit/templates	Lines 84‑88
Script Provisioning	Bash helpers copied to .arckit/scripts/bash	Lines 94‑100
Codex Assets	Skills, agents, and MCP config placed under .agents/ and .codex/	Lines 15‑34
OpenCode Assets	Commands and agents installed to .opencode/	Lines 54‑86
Copilot Assets	Prompt files and agents placed in .github/	Lines 92‑104
Git Initialization	init_git_repo() runs git init and initial commit	Lines 0‑5 of function
Documentation	Guides and README copied unless --minimal flag set	Lines 33‑66

The CLI ensures that setting up a new project with arc-kit requires only a single command while delivering a complete, production-ready governance environment.

Summary

• Single-command initialization: The arckit init command in src/arckit_cli/__init__.py automates the entire setup process.
• AI assistant flexibility: Supports Codex, OpenCode, and Copilot through the AGENT_CONFIG mapping (lines 44‑62), creating appropriate subdirectories for each.
• Complete project structure: Generates .arckit/ for templates and scripts, projects/ for governance artifacts, and AI-specific folders (.codex/, .opencode/, .github/).
• Asset provisioning: Copies templates (lines 84‑88), Bash helper scripts (lines 94‑100), and AI-specific configurations (skills, agents, MCP files).
• Version control ready: Optionally initializes a Git repository with init_git_repo (lines 0‑5) unless --no-git is specified.
• Minimal mode: Use --minimal to skip documentation and create a lightweight scaffold.

Frequently Asked Questions

What is the fastest way to set up a new project with arc-kit?

Run arckit init my-project-name --ai codex (or opencode/copilot). This single command creates the full directory structure, installs AI assistant assets, copies templates and scripts, and initializes a Git repository. The process completes in seconds and requires no manual configuration.

Which AI assistants does arc-kit support during initialization?

ArcKit supports three AI assistants through the AGENT_CONFIG dictionary in src/arckit_cli/__init__.py (lines 44‑62): Codex (creates .codex/ and .agents/skills/), OpenCode (creates .opencode/commands/ and .opencode/agents/), and Copilot (creates .github/prompts/ and .github/agents/). Each assistant receives tailored configuration files and prompts.

How do I prevent arc-kit from creating documentation or initializing Git?

Use the --minimal flag to skip the docs/ directory and associated guides (lines 33‑66), creating only the essential structure. To disable Git initialization, pass the --no-git flag, which prevents the init_git_repo function (lines 0‑5) from running git init and making the initial commit.

Where are the project templates and helper scripts stored after initialization?

Templates are copied from the package data directory to .arckit/templates/ (lines 84‑88), while Bash helper scripts like generate-document-id.sh are placed in .arckit/scripts/bash/ (lines 94‑100). These files are sourced from the shared data folder during the create_project_structure execution (lines 23‑39) and enable the AI assistants to generate standardized governance artifacts.

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