Template Customization

ArcKit uses templates to ensure consistent, high-quality architecture documentation. You can customize these templates to match your organization’s standards without losing changes when you update ArcKit.

How Template Customization Works

ArcKit uses a two-tier template system:

Default Templates

Location: .arckit/templates/Refreshed when you run arckit init to update your project.Do not edit directly - changes will be lost on update.

Custom Templates

Location: .arckit/templates-custom/Preserved across arckit init updates.Commands check this directory first before falling back to defaults.

Creating Custom Templates

Use the /arckit.customize command to copy templates for editing:

Copy a Single Template

# Inside your AI assistant
/arckit.customize requirements

This copies requirements-template.md to .arckit/templates-custom/ where you can edit it.

Copy All Templates

/arckit.customize all

This copies all 54 templates to .arckit/templates-custom/ for bulk customization.

List Available Templates

/arckit.customize list

Shows all available templates with their current status (Default or Custom).

Template Naming Convention

Templates follow a consistent naming pattern:

{command-name}-template.md

Examples:

architecture-principles-template.md → /arckit.principles
requirements-template.md → /arckit.requirements
risk-register-template.md → /arckit.risk
data-model-template.md → /arckit.data-model
wardley-map-template.md → /arckit.wardley

Common Customizations

Organization Branding

Add your organization’s document control fields:

# Document Control

| Field | Value |
|-------|-------|
| Document Owner | [Auto-populated] |
| Department | Enterprise Architecture |
| Classification | OFFICIAL-SENSITIVE |
| Review Date | [Auto-calculated: +6 months] |
| Approval Authority | Architecture Review Board |
| Distribution List | EA Team, TDA, CTO Office |

Compliance Sections

Add mandatory compliance sections:

## ISO 27001 Compliance

| Control | Requirement | Status |
|---------|-------------|--------|
| A.8.2.1 | Classification of information | ✅ Compliant |
| A.8.2.2 | Labelling of information | ✅ Compliant |
| A.8.2.3 | Handling of assets | 🔄 In Progress |

## PCI-DSS Compliance

[If handling payment card data]

- [ ] Requirement 1: Install and maintain a firewall
- [ ] Requirement 2: Do not use vendor-supplied defaults
- [ ] Requirement 3: Protect stored cardholder data

Approval Workflows

Add department-specific approval workflows:

## Approval History

| Version | Date | Approver | Role | Status |
|---------|------|----------|------|--------|
| v1.0 | YYYY-MM-DD | [Name] | Lead Architect | ✅ Approved |
| v1.0 | YYYY-MM-DD | [Name] | Security Architect | ✅ Approved |
| v1.0 | YYYY-MM-DD | [Name] | TDA Chair | 🔄 Pending |
| v1.0 | YYYY-MM-DD | [Name] | CTO | ⏳ Awaiting |

## Approval Gates

- [ ] Technical Design Authority (TDA) Review
- [ ] Architecture Review Board (ARB) Approval
- [ ] Security Review Board Sign-off
- [ ] Data Governance Committee Approval

UK Government Classification

Add UK Government classification banners:

---
classification: OFFICIAL
handling: For UK Government Use Only
protective-marking: None
---

# [Document Title]

**OFFICIAL**

## Handling Instructions

This document is classified as **OFFICIAL** under the UK Government Security Classification Policy.

- **Distribution**: Authorized personnel only
- **Storage**: Approved UK Government IT systems
- **Disposal**: Secure disposal required
- **Sharing**: Authorized UK Government departments only

Custom Sections

Add organization-specific sections:

## Enterprise Architecture Alignment

| EA Domain | Alignment | Notes |
|-----------|-----------|-------|
| Business Architecture | ✅ Aligned | Supports Customer Journey Mapping initiative |
| Data Architecture | ✅ Aligned | Extends Enterprise Data Model v3.2 |
| Application Architecture | ⚠️ Partial | Migration from legacy CRM required |
| Technology Architecture | ✅ Aligned | Uses standard cloud platforms |

## Target Operating Model (TOM) Impact

- **People**: 3 new roles required (Data Analyst, ML Engineer, DevOps)
- **Process**: 2 new processes (Data Quality Assurance, Model Monitoring)
- **Technology**: 4 new platforms (Databricks, Snowflake, Datadog, GitHub)
- **Data**: 12 new data products (Customer 360, Product Catalog, Inventory)

Template Variables

ArcKit templates use variables that are auto-populated by commands:

Common Variables

Variable	Description	Example
`{PROJECT_ID}`	Project number	`001`
`{PROJECT_NAME}`	Project name	`payment-gateway`
`{DOCUMENT_TYPE}`	Document type code	`REQ`
`{VERSION}`	Document version	`v1.0`
`{DATE}`	Current date	`2026-03-04`
`{AUTHOR}`	Document author	Extracted from git or system
`{PHASE}`	GDS delivery phase	`Alpha`, `Beta`, `Live`

Template Example

---
id: ARC-{PROJECT_ID}-{DOCUMENT_TYPE}-{VERSION}
project: {PROJECT_NAME}
type: {DOCUMENT_TYPE}
version: {VERSION}
date: {DATE}
author: {AUTHOR}
phase: {PHASE}
---

# {PROJECT_NAME} - Requirements Specification

**Document ID**: ARC-{PROJECT_ID}-{DOCUMENT_TYPE}-{VERSION}
**Date**: {DATE}
**Author**: {AUTHOR}
**GDS Phase**: {PHASE}

...

When /arckit.requirements runs for project 001-payment-gateway, this becomes:

---
id: ARC-001-REQ-v1.0
project: payment-gateway
type: REQ
version: v1.0
date: 2026-03-04
author: Jane Smith
phase: Alpha
---

# payment-gateway - Requirements Specification

**Document ID**: ARC-001-REQ-v1.0
**Date**: 2026-03-04
**Author**: Jane Smith
**GDS Phase**: Alpha

...

Template Structure

ArcKit templates follow a consistent structure:

Frontmatter

YAML metadata at the top:

---
id: ARC-{PROJECT_ID}-{DOCUMENT_TYPE}-{VERSION}
project: {PROJECT_NAME}
type: {DOCUMENT_TYPE}
---

Document Header

Title and metadata table:

# {PROJECT_NAME} - Requirements Specification

| Field | Value |
|-------|-------|
| Document ID | ARC-{PROJECT_ID}-{DOCUMENT_TYPE}-{VERSION} |
| Date | {DATE} |
| Version | {VERSION} |

Content Sections

Structured content with headings:

## Executive Summary

[Summary content]

## Business Requirements

[BR-001] As a [user], I need [capability] so that [outcome]

## Functional Requirements

[FR-001] The system shall [requirement]

Traceability

Links to related artifacts:

## Linked Artifacts

- **Architecture Principles**: ARC-000-PRIN-v1.0
- **Stakeholder Analysis**: ARC-001-STKE-v1.0
- **Business Case**: ARC-001-SOBC-v1.0

Appendices

Supporting information:

## Appendix A: Glossary

| Term | Definition |
|------|------------|
| API | Application Programming Interface |

## Appendix B: References

- [1] UK Government Digital Service Manual
- [2] NCSC Cloud Security Principles

Best Practices

Start Small

Customize 1-2 key templates first (e.g., requirements, principles) before customizing all 54.

Document Changes

Add a “Customization Notes” section to track what you changed and why.

Version Your Templates

Commit custom templates to git so the team uses consistent formats.

Test Before Rolling Out

Test custom templates on a pilot project before using organization-wide.

Review Periodically

When ArcKit updates, review default templates for new sections you want to adopt.

Keep It Lean

Don’t add unnecessary sections - templates should guide, not burden.

Custom templates can be shared across projects:

Option 1: Git Submodule (Recommended)

# Create a shared templates repository
mkdir arckit-templates-org
cd arckit-templates-org
git init
cp /path/to/project/.arckit/templates-custom/* .
git add .
git commit -m "Initial custom templates"
git remote add origin https://github.com/yourorg/arckit-templates.git
git push -u origin main

# Use in new projects
cd new-project
arckit init --ai codex
rm -rf .arckit/templates-custom
git submodule add https://github.com/yourorg/arckit-templates.git .arckit/templates-custom

Option 2: Copy from Shared Location

# Initialize project
arckit init payment-gateway --ai codex
cd payment-gateway

# Copy organization's custom templates
cp -r /shared/arckit-templates-custom/* .arckit/templates-custom/

Option 3: Wrapper Script

Create an organization-specific arckit-org wrapper:

#!/bin/bash
# arckit-org - Organization-specific ArcKit initialization

set -e

PROJECT_NAME="$1"
AI_ASSISTANT="${2:-codex}"

# Run standard arckit init
arckit init "$PROJECT_NAME" --ai "$AI_ASSISTANT"

cd "$PROJECT_NAME"

# Copy organization custom templates
cp -r /opt/arckit-templates-org/* .arckit/templates-custom/

# Copy organization policies
cp -r /opt/arckit-policies-org/* projects/000-global/external/

echo "✅ Organization-specific ArcKit project initialized"

Reverting to Default Templates

To revert a custom template back to the default:

# Remove the custom template
rm .arckit/templates-custom/requirements-template.md

# Commands will now use the default from .arckit/templates/

To revert all custom templates:

rm -rf .arckit/templates-custom/*

Next Steps

Workflow

Understand the 16-phase ArcKit workflow

Project Structure

Learn about ArcKit’s directory structure

AI Assistants

Choose your AI assistant platform

Get Started

Initialize your first ArcKit project

Get Started

Core Concepts

Governance Workflow

Vendor Procurement

Design & Review

UK Government Compliance

Guides

Templates

Template Customization

How Template Customization Works

Default Templates

Custom Templates

Creating Custom Templates

Copy a Single Template

Copy All Templates

List Available Templates

Template Naming Convention

Common Customizations

Template Variables

Common Variables

Template Example

Template Structure

Best Practices

Start Small

Document Changes

Version Your Templates

Test Before Rolling Out

Review Periodically

Keep It Lean

Option 1: Git Submodule (Recommended)

Option 2: Copy from Shared Location

Option 3: Wrapper Script

Reverting to Default Templates

Next Steps

Workflow

Project Structure

AI Assistants

Get Started

Get Started

Core Concepts

Governance Workflow

Vendor Procurement

Design & Review

UK Government Compliance

Guides

Documentation Index

​Template Customization

​How Template Customization Works

Default Templates

Custom Templates

​Creating Custom Templates

​Copy a Single Template

​Copy All Templates

​List Available Templates

​Template Naming Convention

​Common Customizations

​Template Variables

​Common Variables

​Template Example

​Template Structure

​Best Practices

Start Small

Document Changes

Version Your Templates

Test Before Rolling Out

Review Periodically

Keep It Lean

​Sharing Custom Templates

​Option 1: Git Submodule (Recommended)

​Option 2: Copy from Shared Location

​Option 3: Wrapper Script

​Reverting to Default Templates

​Next Steps

Workflow

Project Structure

AI Assistants

Get Started

Template Customization

How Template Customization Works

Creating Custom Templates

Copy a Single Template

Copy All Templates

List Available Templates

Template Naming Convention

Common Customizations

Template Variables

Common Variables

Template Example

Template Structure

Best Practices

Sharing Custom Templates

Option 1: Git Submodule (Recommended)

Option 2: Copy from Shared Location

Option 3: Wrapper Script

Reverting to Default Templates

Next Steps