# How to Deploy a Project Built with Arc-Kit: A 3-Layer Production Guide

> Deploy your Arc-Kit project using this 3-layer production guide. Learn to scaffold, generate deployment artifacts, and execute IaC via CI/CD for seamless production deployment.

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

---

**Deploying a project built with arc-kit requires scaffolding the repository with `arckit init`, generating deployment artefacts via slash commands like `/arckit.diagram deployment` and `/arckit.devops`, and executing the generated Infrastructure as Code (IaC) through your preferred CI/CD pipeline.**

Arc-kit is a template-driven, AI-assisted toolkit maintained in the `tractorjuice/arc-kit` repository that generates complete architecture governance artefacts. When you deploy a project built with arc-kit, you follow a three-layer workflow that moves from initial scaffolding to production rollout while maintaining compliance and traceability.

## Step 1: Scaffold Your Arc-Kit Project

The first layer establishes the repository structure and document templates. The CLI entry point in [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py) parses the `init` command and invokes helper scripts in [`scripts/bash/create-project.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/bash/create-project.sh) to generate numbered project folders.

### Install the Arc-Kit CLI

Choose your installation method based on your AI assistant:

```bash

# For Claude Code (v2.1.112+) - adds slash commands

/plugin marketplace add tractorjuice/arc-kit

# For Codex, OpenCode, Gemini, or Copilot

pip install git+https://github.com/tractorjuice/arc-kit.git

```

### Initialize the Project Structure

Run the `arckit init` command to create the standard project skeleton:

```bash
arckit init payment-gateway --ai codex

```

This command creates:

- `.arckit/` – Contains default document templates ([`requirements-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/requirements-template.md), [`deployment-diagram-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/deployment-diagram-template.md)) and helper scripts ([`generate-document-id.sh`](https://github.com/tractorjuice/arc-kit/blob/main/generate-document-id.sh))
- `projects/` – Directory where generated artefacts land with standardized IDs like `ARC-001-REQ-v1.0`

You can upgrade an existing repository by running `arckit init --here --ai <assistant>` to preserve custom artefacts in `.arckit/templates-custom/` while updating the core scaffolding.

## Step 2: Generate Deployment-Centric Artefacts

The second layer produces the concrete deployment diagrams, CI/CD specifications, and operational runbooks. These commands are defined in `arckit-claude/commands/*.md` and leverage templates from `arckit-claude/templates/*.md`.

### Create Deployment Diagrams

Generate C4 deployment diagrams that visualize cloud regions, VPCs, and service communication:

```bash
/arckit.diagram deployment

```

This command creates a diagram file saved under `projects/<num>-<name>/` as [`ARC-XXX-DIAG-001-v1.0.md`](https://github.com/tractorjuice/arc-kit/blob/main/ARC-XXX-DIAG-001-v1.0.md), following the structure documented in [`docs/guides/diagram.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/diagram.md). The output includes compliance boundaries and external data sources.

### Define CI/CD Pipelines

Generate the DevOps strategy document with maturity-level pipeline definitions:

```bash
/arckit.devops

```

This creates [`devops-pipeline.md`](https://github.com/tractorjuice/arc-kit/blob/main/devops-pipeline.md) containing:

- Pipeline stages (build, test, security scan, deploy) with maturity levels (Level 1 – manual, Level 4 – continuous deployment)
- IaC recommendations (Terraform, Azure ARM, CloudFormation) with example snippets
- Rollback procedures and MTTR/MTBF targets based on the Secure-by-Design template in [`arckit-paperclip/templates/ukgov-secure-by-design-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-paperclip/templates/ukgov-secure-by-design-template.md)

Copy the generated snippets into a dedicated `infra/` folder for version control.

### Generate Operational Runbooks

Create operational procedures for scaling, restart, and incident response:

```bash
/arckit.operationalize

```

This command generates [`operationalize-runbook.md`](https://github.com/tractorjuice/arc-kit/blob/main/operationalize-runbook.md) based on [`arckit-paperclip/templates/operationalize-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-paperclip/templates/operationalize-template.md), including:

- Scaling commands (`kubectl scale deployment/...`)
- Rollout restarts (`kubectl rollout restart`)
- Undo procedures (`kubectl rollout undo`)
- Incident response playbooks and health check protocols

These runbooks integrate directly with ServiceNow, PagerDuty, or similar ticketing systems.

### Export Infrastructure as Code

For a fully-generated IaC bundle:

```bash
/arckit.export iac

```

This emits a `terraform/` directory containing minimal resources (VPC, subnets, IAM roles) matching the deployment diagram topology.

## Step 3: Execute Production Rollout

The third layer transforms generated artefacts into live infrastructure using your preferred toolchain.

### Choose Your IaC Engine

Select the engine that matches your cloud provider:

| Engine | Command | Documentation |
|--------|---------|---------------|
| **Terraform** | `terraform init && terraform apply` | Terraform docs |
| **Azure CLI** | `az deployment group create ...` | Azure CLI docs |
| **GitHub Actions** | Commit workflow to `.github/workflows/` | GitHub Actions docs |

The generated artefacts in [`devops-pipeline.md`](https://github.com/tractorjuice/arc-kit/blob/main/devops-pipeline.md) specify the appropriate engine based on your chosen cloud provider (AWS, Azure, GCP) as defined in the diagram evidence column.

### Configure Secrets and Credentials

Arc-kit stores sensitive configuration (e.g., `GOOGLE_API_KEY`, `DATA_COMMONS_API_KEY`) in the Claude plugin's `userConfig` section. For other assistants, these values are read from environment variables in the generated [`.mcp.json`](https://github.com/tractorjuice/arc-kit/blob/main/.mcp.json) file.

Create a CI secret store (GitHub Secrets, Azure Key Vault, or HashiCorp Vault) and expose these variables to your pipeline.

### Run the Deployment Pipeline

Execute the deployment through your CI/CD workflow:

```bash
git add .
git commit -m "feat: add deployment artefacts"
git push origin main

```

Your pipeline will:

1. Validate Terraform files against the diagram topology
2. Apply infrastructure (VPC, subnets, IAM)
3. Deploy container images referenced in the diagram
4. Notify the AI assistant via the built-in `Monitor` tool about rollout status

## Summary

Deploying a project built with arc-kit follows a structured three-layer workflow that bridges AI-assisted architecture and production infrastructure:

- **Scaffold** the repository using `arckit init` to create standardized project folders and document templates in `.arckit/` and `projects/`
- **Generate** deployment artefacts using slash commands like `/arckit.diagram deployment`, `/arckit.devops`, and `/arckit.operationalize` to produce C4 diagrams, CI/CD pipelines, and operational runbooks
- **Execute** production rollout by feeding generated IaC snippets into Terraform, Azure CLI, or GitHub Actions, managing secrets through environment variables or CI secret stores

## Frequently Asked Questions

### How do I upgrade an existing arc-kit project without losing custom templates?

Run `arckit init --here --ai <assistant>` inside your existing repository. This command preserves your custom artefacts in `.arckit/templates-custom/` while updating the core scaffolding and CLI scripts defined in [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py).

### Which cloud providers are supported by arc-kit deployment diagrams?

Arc-kit generates deployment diagrams for AWS, Azure, and GCP. The `/arckit.diagram deployment` command creates C4 diagrams that specify cloud regions, VPCs, subnets, and HA/DR zones specific to your chosen provider, as documented in [`docs/guides/diagram.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/diagram.md).

### Can I use arc-kit with CI/CD platforms other than GitHub Actions?

Yes. While the generated [`devops-pipeline.md`](https://github.com/tractorjuice/arc-kit/blob/main/devops-pipeline.md) includes GitHub Actions examples, the underlying IaC snippets (Terraform, Azure ARM, CloudFormation) and operational runbooks are platform-agnostic. You can execute the generated artefacts through Azure Pipelines, GitLab CI, Jenkins, or any platform supporting standard IaC tooling.

### What is the difference between `/arckit.devops` and `/arckit.operationalize`?

`/arckit.devops` generates the CI/CD pipeline strategy and Infrastructure as Code recommendations, covering build stages, maturity levels, and rollback procedures. `/arckit.operationalize` produces the post-deployment runbook containing specific operational commands like `kubectl scale` and incident response protocols. The devops artefact covers *how to build and deploy*, while the operationalize artefact covers *how to run and maintain*.