Customizing Templates

How to customize ArcKit templates for your organization without losing updates

ArcKit uses document templates to generate consistent architecture artifacts. You can customize these templates without modifying the defaults, and your customizations will be preserved across updates.

How Template Customization Works

ArcKit uses a two-tier template system:

1. Default templates live in .arckit/templates/ (refreshed by arckit init)
2. Your customizations go in .arckit/templates-custom/ (preserved across updates)
3. Commands automatically check for custom templates first, falling back to defaults

This pattern ensures:

• Your customizations are preserved when upgrading ArcKit
• Default templates can be updated without losing your changes
• Easy to see what you’ve customized vs defaults

The /arckit.customize Command

Copy a Specific Template

/arckit.customize requirements

This copies the requirements template to .arckit/templates-custom/requirements-template.md for editing.

Copy All Templates

/arckit.customize all

Copies all 80+ templates to your customizations directory.

List Available Templates

/arckit.customize list

Shows all available templates with their corresponding commands.

Template Info

/arckit.customize info requirements

Shows what a template contains and common customization points.

Template Loading Logic

When you run an ArcKit command (e.g., /arckit.requirements):

1. Command checks: Does .arckit/templates-custom/requirements-template.md exist?
2. If YES → Uses YOUR customized template
3. If NO → Uses default from .arckit/templates/

Common Customizations

Remove UK Government Sections

For non-UK Gov projects:

<!-- Delete these sections -->
## UK Government Alignment
### Technology Code of Practice (TCoP)
### GDS Service Standard
### NCSC Cloud Security Principles

Change Document Control Fields

Add organization-specific fields:

| **Cost Centre** | [YOUR_COST_CENTRE] |
| **Programme** | [PROGRAMME_NAME] |
| **Budget Code** | [BUDGET_CODE] |

Modify Requirement Prefixes

Change from BR/FR/NFR to your organization’s taxonomy:

<!-- Before -->
**BR-001**: User Management
**FR-001**: User Registration
**NFR-001**: Response Time

<!-- After -->
**BUS-001**: User Management
**FUNC-001**: User Registration
**PERF-001**: Response Time

Update Priority Levels

Change MoSCoW to your framework:

<!-- Before -->
Priority: Must Have / Should Have / Could Have / Won't Have

<!-- After -->
Priority: P1 (Critical) / P2 (High) / P3 (Medium) / P4 (Low)

Add Organization Branding

<!-- Add to header -->
![Company Logo](../assets/logo.png)

---
**CONFIDENTIAL - [COMPANY NAME]**
---

Customize Classification Banners

<!-- UK Government -->
**Classification**: OFFICIAL-SENSITIVE

<!-- Corporate -->
**Classification**: Company Confidential

<!-- Healthcare -->
**Classification**: Protected Health Information (PHI)

Customizing the Pages Template

The pages-template.html generates a documentation website. Common customizations:

Change Styling

<!-- Replace GOV.UK Design System with neutral colors -->
<style>
  :root {
    --primary: #0066cc;      /* Your brand blue */
    --secondary: #00cc66;    /* Your brand green */
    --accent: #ff6600;       /* Your brand orange */
  }
</style>

Remove UK-Specific Sections

<!-- Delete this section -->
<div class="category">
  <h3>UK Government</h3>
  <ul>
    <li><a href="#...">TCoP Assessment</a></li>
    <li><a href="#...">Service Standard</a></li>
  </ul>
</div>

Add Organization Logo

<!-- Replace header -->
<header>
  <img src="/assets/logo.png" alt="Company Logo" />
  <h1>Architecture Documentation</h1>
</header>

Customize Footer

<footer>
  <p>&copy; 2025 [Your Organization]. All rights reserved.</p>
  <p><a href="/terms">Terms</a> | <a href="/privacy">Privacy</a></p>
</footer>

Keeping Templates Updated

When ArcKit releases new template features:

Compare Your Template with Default

1. Your custom template: .arckit/templates-custom/requirements-template.md
2. New default template: .arckit/templates/requirements-template.md
3. Use a diff tool to see what changed:

diff .arckit/templates/requirements-template.md \
     .arckit/templates-custom/requirements-template.md

Selective Adoption

You don’t have to adopt all changes. Cherry-pick what’s valuable:

• New compliance sections: Copy if relevant to your industry
• New requirement types: Adopt if your projects need them
• Updated formatting: Adopt if it improves clarity
• UK Gov specifics: Skip if not applicable

Reverting to Default

To stop using a custom template:

rm .arckit/templates-custom/requirements-template.md

The command will now use the default template again.

Real-World Examples

Financial Services

Customization: Add PCI-DSS compliance section

## PCI-DSS Compliance

### Requirement 1: Install and Maintain Network Security Controls
- Firewall rules documented: [YES/NO]
- Network segmentation enforced: [YES/NO]

### Requirement 3: Protect Stored Account Data
- Cardholder data encrypted: [YES/NO]
- Encryption standard: AES-256

Healthcare (US)

Customization: Add HIPAA compliance

## HIPAA Compliance

### Administrative Safeguards
- Risk assessment completed: [YES/NO]
- Security officer assigned: [NAME]

### Physical Safeguards
- Facility access controls: [DESCRIBE]
- Workstation security: [DESCRIBE]

### Technical Safeguards
- Access controls: [DESCRIBE]
- Audit controls: [DESCRIBE]
- Encryption: AES-256 in transit and at rest

Manufacturing (Automotive)

Customization: Add ISO 26262 (functional safety)

## ISO 26262 Functional Safety

### ASIL Rating
- Safety Goal: [DESCRIBE]
- ASIL Level: [A/B/C/D]

### Safety Requirements
- Fault detection: [DESCRIBE]
- Fault handling: [DESCRIBE]
- Redundancy: [DESCRIBE]

Defense/Government

Customization: Add clearance and classification

## Security Classification

**Classification**: SECRET // REL TO USA, GBR, CAN, AUS, NZL
**Clearance Required**: SECRET with SC eligibility
**Handling Caveats**: NOFORN, ORCON

## MOD JSP 440 Compliance
- Security Operating Procedures (SyOPs): [REFERENCE]
- IAMM Level: [1/2/3/4/5]

Template Versioning

Custom templates inherit version numbers from the defaults:

> **Template Origin**: Custom | **Based On**: `/arckit.requirements` | **ArcKit Version**: 3.0.9

This helps track:

• Which default version your customization is based on
• When to review for updates
• Whether breaking changes have occurred

Best Practices

1. Start Small

Don’t customize everything at once. Start with your most-used templates:

• Requirements (requirements-template.md)
• Risk Register (risk-register-template.md)
• Architecture Principles (architecture-principles-template.md)

2. Document Your Changes

Add a note at the top of custom templates:

<!--
CUSTOMIZATIONS:
- Added ISO 27001 compliance section
- Removed UK Government alignment
- Changed requirement prefixes (BR → BUS, FR → FUNC)
- Updated with v3.0.9 defaults on 2025-01-15
-->

3. Version Control

Commit custom templates to git:

git add .arckit/templates-custom/
git commit -m "Customize requirements template for ISO 27001"

4. Review Quarterly

Set a calendar reminder to check for template updates:

1. Check ArcKit release notes
2. Compare your custom templates with new defaults
3. Adopt useful changes selectively

5. Share Across Projects

If you have multiple ArcKit projects:

# Copy customizations to new project
cp -r old-project/.arckit/templates-custom/* \
       new-project/.arckit/templates-custom/

Troubleshooting

Command Not Using My Custom Template

Symptom: Command generates document from default template

Causes:

1. Filename mismatch (check spelling and hyphens)
2. Template in wrong directory (must be .arckit/templates-custom/)
3. Template has wrong extension (must be .md for markdown, .html for HTML)

Fix:

# Check filename
ls .arckit/templates-custom/requirements-template.md

# Should match exactly (case-sensitive)

Template Validation Errors

Symptom: Command fails with “Template validation failed”

Causes:

1. Missing required placeholders (e.g., [PROJECT_ID], [VERSION])
2. Invalid markdown syntax
3. Broken document control section

Fix: Compare with default template to ensure all required fields present.

Custom Template Out of Date

Symptom: Generated documents missing new features

Fix:

1. Check CHANGELOG.md for template changes
2. Diff your custom template against new default
3. Manually merge new sections you want to keep

Further Reading

• Sprint Planning Guide - Customize backlog templates
• Traceability Guide - Customize traceability matrix
• Upgrading Guide - Preserve customizations during upgrades