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

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 parses the init command and invokes helper scripts in scripts/bash/create-project.sh to generate numbered project folders.

Install the Arc-Kit CLI

Choose your installation method based on your AI assistant:

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

arckit init payment-gateway --ai codex

This command creates:

• .arckit/ – Contains default document templates (requirements-template.md, deployment-diagram-template.md) and helper scripts (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:

/arckit.diagram deployment

This command creates a diagram file saved under projects/<num>-<name>/ as ARC-XXX-DIAG-001-v1.0.md, following the structure documented in 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:

/arckit.devops

This creates 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

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

Generate Operational Runbooks

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

/arckit.operationalize

This command generates operationalize-runbook.md based on 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:

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

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.

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.

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

Yes. While the generated 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.

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