How to Customize Arc-Kit Templates for Architecture Governance

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

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:

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

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:

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

ArcKit reads 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:

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

/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	Default requirements template shipped with ArcKit.	View on GitHub
src/arckit_cli/__init__.py (lines 78-112)	CLI code that generates the templates-custom/README.md during arckit init.	View on GitHub
src/arckit_cli/__init__.py (lines 260-340)	Implementation of the /arckit.customize command that copies templates to the override directory.	View on GitHub
docs/guides/customize.md	Official user guide explaining the template customization workflow.	View on GitHub

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.

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