# How to Customize Arc-Kit Templates for Architecture Governance

> Learn to customize Arc-Kit templates using the arckit customize command. Easily modify default templates in .arckit/templates-custom/ for your architecture governance needs. Keep customizations safe during upgrades.

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

---

**Use the `/arckit.customize` command to copy default templates from `.arckit/templates/` to `.arckit/templates-custom/` and edit them there; ArcKit automatically prefers custom versions while preserving your changes across upgrades.**

ArcKit generates architecture artifacts from Markdown templates stored in the tractorjuice/arc-kit repository. To align generated documents with your organization's branding, compliance requirements, or document control standards, you must customize arc-kit templates using the override system rather than editing shipped defaults directly.

## Understanding the Arc-Kit Template System

### Default vs. Custom Template Locations

ArcKit maintains two distinct template directories:

- **`.arckit/templates/`** — Shipped defaults that are version-controlled and refreshed every time you run `arckit init`. These files live in the repository root and include templates like [[`requirements-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/requirements-template.md)](https://github.com/tractorjuice/arc-kit/blob/main/.arckit/templates/requirements-template.md).

- **`.arckit/templates-custom/`** — Your organization's overrides. When you customize arc-kit templates, you place edited copies here. The CLI automatically creates a README in this directory during project initialization (see [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py) lines 78-112).

### Template Resolution Logic

When ArcKit renders a document, it checks `templates-custom/` first. If the requested template exists there, ArcKit uses it; otherwise, it falls back to the default in `templates/`. This resolution order ensures that your customizations persist across upgrades without blocking new default templates from being introduced.

## Step-by-Step: How to Customize Arc-Kit Templates

### 1. Initialize Your Project

If you haven't already created an ArcKit project, run:

```bash
arckit init my-project --ai copilot
cd my-project

```

The `arckit init` command writes the default templates into `.arckit/templates/` and creates the `.arckit/templates-custom/` directory with an explanatory README.

### 2. Copy Templates Using `/arckit.customize`

Use the built-in command to copy specific templates or all defaults at once:

```bash
/arckit.customize requirements      # Copy single template

/arckit.customize all               # Copy entire template library

```

*Implementation detail:* The `/arckit.customize` command is implemented in [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py) (lines 260-340). It performs a filesystem copy from `.arckit/templates/` to `.arckit/templates-custom/`, preserving the original filename.

### 3. Edit Custom Templates

Open the copied file in your editor:

```bash
code .arckit/templates-custom/requirements-template.md

```

Common customizations when you customize arc-kit templates include:

- **Document Control Fields** — Add placeholders like `[PROJECT_ID]`, `[PROJECT_NAME]`, and `[ORG]` in the header table.
- **Compliance Sections** — Insert mandatory ISO 27001, PCI-DSS, or MOD Secure-by-Design checklists.
- **Branding** — Replace logo URLs and update footer contact details to match corporate standards.

### 4. Verify Your Changes

Execute the relevant ArcKit command to ensure the custom template renders correctly:

```bash
/arckit.requirements "Create requirements for the new payment gateway"

```

ArcKit reads [`templates-custom/requirements-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/templates-custom/requirements-template.md) first, so the generated artifact reflects your edits.

## Automating Template Customization in CI/CD

For organizations managing multiple ArcKit projects, script the customization workflow to enforce standards:

```bash
#!/usr/bin/env bash

# automate-template-customisation.sh

PROJECT_ROOT="${1:-.}"
TEMPLATE_NAME="requirements"

cd "$PROJECT_ROOT"

# Ensure defaults exist

arckit init --here --ai copilot

# Copy template if not already customized

if [[ ! -f .arckit/templates-custom/${TEMPLATE_NAME}-template.md ]]; then
  /arckit.customize "$TEMPLATE_NAME"
fi

# Append organization-specific header

cat <<'EOF' >> .arckit/templates-custom/${TEMPLATE_NAME}-template.md

## Organisation Header

| Organisation | {{organisation_name}} |
|--------------|-----------------------|
EOF

# Commit changes

git add .arckit/templates-custom/${TEMPLATE_NAME}-template.md
git commit -m "custom: add organisation header to ${TEMPLATE_NAME} template"

```

Running this script ensures every project uses the customized arc-kit templates without manual copying.

## Creating New Templates from Scratch

Beyond customizing existing templates, you can create entirely new document types using the interactive builder:

```bash
/arckit:template-builder

```

This command interviews you for template name, required sections, and placeholder variables, then writes the new template directly into `.arckit/templates-custom/`. New templates created this way follow the same resolution rules as customized defaults.

## Key Files and Source Code References

| File | Description | Source Link |
|------|-------------|-------------|
| [`.arckit/templates/requirements-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/.arckit/templates/requirements-template.md) | Default requirements template shipped with ArcKit. | [View on GitHub](https://github.com/tractorjuice/arc-kit/blob/main/.arckit/templates/requirements-template.md) |
| [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py) (lines 78-112) | CLI code that generates the [`templates-custom/README.md`](https://github.com/tractorjuice/arc-kit/blob/main/templates-custom/README.md) during `arckit init`. | [View on GitHub](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py#L78-L112) |
| [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py) (lines 260-340) | Implementation of the `/arckit.customize` command that copies templates to the override directory. | [View on GitHub](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py#L260-L340) |
| [`docs/guides/customize.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/customize.md) | Official user guide explaining the template customization workflow. | [View on GitHub](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/customize.md) |

## Summary

- **Use `/arckit.customize`** to copy default templates from `.arckit/templates/` to `.arckit/templates-custom/` instead of editing originals.
- **ArcKit prefers custom templates** automatically, falling back to defaults only when custom versions are absent.
- **Preserve changes across upgrades** because `arckit init` refreshes only the default directory while leaving `templates-custom/` untouched.
- **Script the workflow** for CI/CD pipelines to enforce organization-wide document standards across multiple projects.

## Frequently Asked Questions

### Can I edit the default templates directly in `.arckit/templates/`?

No. The `.arckit/templates/` directory is overwritten every time you run `arckit init` or upgrade ArcKit. Always use `/arckit.customize` to copy files to `.arckit/templates-custom/` before editing. This override mechanism ensures your changes survive version updates.

### What happens if I customize a template and then ArcKit updates the default version?

Your custom template in `.arckit/templates-custom/` remains untouched. ArcKit always checks the custom directory first, so you continue using your version. If you want to incorporate changes from the new default, manually compare the files and merge updates into your custom copy using standard diff tools.

### Does the customization workflow work with all AI assistants supported by ArcKit?

Yes. Template resolution happens before the AI assistant receives the prompt, so Claude, GitHub Copilot, OpenCode, Gemini, and others all use the same custom templates stored in `.arckit/templates-custom/`. The assistant interface does not affect which template file ArcKit selects.

### How do I add entirely new document types that don't exist in the default templates?

Use the **`/arckit:template-builder`** command. This interactive tool interviews you for the template name, required sections, and variables, then writes the new template directly into `.arckit/templates-custom/`. New templates created this way follow the same override rules as customized defaults and persist across ArcKit upgrades.