Skip to main content

​
Overview

This quickstart guide will get you from zero to your first ArcKit command in under 5 minutes. You’ll:
  1. Install ArcKit CLI
  2. Initialize a project
  3. Run your first command
This guide uses OpenCode CLI as the example. For Claude Code or Gemini CLI, see the Installation guide.

​
Step 1: Install ArcKit CLI

Install ArcKit CLI using pip or uv: 
pip install git+https://github.com/tractorjuice/arc-kit.git
Prefer uv for faster installs and better dependency management. Install uv with:
curl -LsSf https://astral.sh/uv/install.sh | sh
Verify installation: 
arckit --help
You should see the ArcKit banner and help text.

​
Step 2: Initialize Your Project

Create a new architecture governance project: 
arckit init payment-modernization --ai opencode
This creates:
  • Project structure: projects/000-global/ for global principles
  • Templates: .arckit/templates/ for all document templates
  • Commands: .opencode/commands/ for all 54 ArcKit commands
  • Scripts: .arckit/scripts/bash/ for automation helpers
  • Documentation: docs/ with guides and references
payment-modernization/
├── .arckit/
│   ├── scripts/
│   │   └── bash/                          # Automation scripts
│   ├── templates/                         # Default templates
│   └── templates-custom/                  # Your customizations
├── projects/
│   └── 000-global/
│       └── .gitkeep                       # Global artifacts
├── .opencode/
│   ├── commands/                          # All 54 ArcKit commands
│   ├── agents/                            # Research agents
│   ├── skills/                            # Wardley Mapping, Mermaid
│   └── opencode.json                      # MCP server config
├── docs/
│   ├── guides/                            # Command guides
│   └── README.md                          # Documentation index
├── .envrc                                 # OPENCODE_HOME config
├── .gitignore                             # Git exclusions
├── CHANGELOG.md                           # Version history
├── DEPENDENCY-MATRIX.md                   # Artifact dependencies
├── VERSION                                # Current version
├── WORKFLOW-DIAGRAMS.md                   # Workflow visualizations
└── README.md                              # Project README
Navigate to your project: 
cd payment-modernization

​
Step 3: Set Up Environment

Set the OPENCODE_HOME environment variable so OpenCode can discover project-specific commands: 
# Install direnv if not already installed
# macOS: brew install direnv
# Linux: apt install direnv (or package manager)

# Allow .envrc in project directory
direnv allow
direnv automatically loads environment variables when you cd into the project directory. This is the recommended approach.Add this to your shell profile (.bashrc, .zshrc, etc.):
eval "$(direnv hook bash)"  # or zsh, fish, etc.

​
Step 4: Start OpenCode

Launch OpenCode CLI: 
opencode
OpenCode will load ArcKit commands from .opencode/commands/.

​
Step 5: Run Your First Command

Inside OpenCode, establish architecture principles for your organization: 
/arckit.principles Create principles for a financial services company modernizing payment systems. Focus on cloud-first, security, and regulatory compliance.
ArcKit will:
  1. Analyze your context (financial services, payments, compliance)
  2. Generate comprehensive architecture principles
  3. Save to projects/000-global/ARC-000-PRIN-v1.0.md
Example output: 
# ARC-000-PRIN-v1.0 — Enterprise Architecture Principles

## Document Control

| Metadata | Value |
|----------|-------|
| **Document ID** | ARC-000-PRIN-v1.0 |
| **Version** | 1.0 |
| **Status** | Draft |
| **Created** | 2026-03-04 |
| **Author** | Enterprise Architecture Team |

## 1. Cloud-First Architecture

**Statement**: All new systems must be designed for cloud deployment...

**Rationale**: Cloud platforms provide scalability, resilience...

**Implications**: 
- Development teams must adopt cloud-native patterns
- Legacy systems require migration roadmaps
- FinOps processes for cost governance
...
See the M365 GCC-H Migration principles from the ArcKit test repository for a complete example.

​
What’s Next?

Now that you’ve established principles, follow the ArcKit workflow:
1

Create Project Plan

Generate a project plan with timeline, phases, and gates:
/arckit.plan Create project plan for payment gateway modernization
2

Analyze Stakeholders

Identify stakeholders, drivers, goals, and outcomes:
/arckit.stakeholders Analyze stakeholders for payment modernization
3

Assess Risks

Create a comprehensive risk register (HM Treasury Orange Book):
/arckit.risk Create risk register for payment system migration
4

Build Business Case

Create Strategic Outline Business Case (Green Book 5-case model):
/arckit.sobc Create SOBC for payment gateway modernization
5

Define Requirements

Document comprehensive requirements:
/arckit.requirements Build requirements for real-time payment processing with PCI-DSS compliance and FCA regulatory requirements
6

Model Data

Create data model with ERD, GDPR compliance, and data governance:
/arckit.data-model Create data model for payment transactions
7

Research Technology

Research available solutions with build vs buy analysis:
/arckit.research Research payment gateway solutions
8

Strategic Planning

Create Wardley Maps for strategic positioning:
/arckit.wardley Create Wardley Map for payment architecture
9

Vendor Procurement (if needed)

Generate Statement of Work (RFP):
/arckit.sow Generate RFP for payment gateway vendor
For UK Government procurement:
/arckit.dos Generate DOS procurement for payment platform
/arckit.gcloud-search Search G-Cloud for payment services
10

Design Review

Review High-Level Design:
/arckit.hld-review Review payment gateway HLD

​
Example Projects

Explore complete ArcKit deliverables in public demonstration repositories:

​
Template Customization

Customize ArcKit templates without modifying defaults: 
/arckit.customize requirements   # Copy requirements template for editing
/arckit.customize all            # Copy all templates
/arckit.customize list           # See available templates
How it works:
  • Default templates live in .arckit/templates/ (refreshed by arckit init)
  • Your customizations go in .arckit/templates-custom/ (preserved across updates)
  • Commands automatically check for custom templates first, falling back to defaults

​
Getting Help

Inside your AI assistant, run: 
/arckit.start
This command provides:
  • Project status detection
  • Available commands exploration
  • Next step recommendations based on your current artifacts

​
Need More Help?

​
Summary

You’ve successfully: ✅ Installed ArcKit CLI
✅ Initialized a project
✅ Set up your environment
✅ Run your first command (architecture principles)
✅ Learned the ArcKit workflow Next, explore the Why ArcKit? page to understand the problems ArcKit solves.

Build docs developers (and LLMs) love

Get started for freeTalk to us