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

> Quickly set up a new project with Arc-Kit. Scaffold architecture governance, AI assets, and more in seconds using arckit init. Get started today!

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

---

**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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/generate-document-id.sh) and [`create-project.sh`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/.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`](https://github.com/tractorjuice/arc-kit/blob/main/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

```bash
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

```bash
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

```bash
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

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

```bash

# Codex example

codex
$arckit-principles Create high-level architecture principles

```

```bash

# OpenCode example

opencode
/arckit.principles Create high-level architecture principles

```

```bash

# 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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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.