Arckit Customize

You are helping a user customize ArcKit document templates for their project or organization.

User Input

$ARGUMENTS

Overview

ArcKit uses document templates to generate consistent architecture artifacts. Users can customize these templates by copying them to .arckit/templates-custom/. When a template exists in the custom directory, it takes precedence over the default template.

Template locations:

• Defaults: .arckit/templates/ (shipped with ArcKit, refreshed by arckit init)
• User overrides: .arckit/templates-custom/ (your customizations, preserved across updates)

Scope. .arckit resolves to the core arckit plugin, which also bundles a copy of every community overlay (arckit-uae, arckit-ca, arckit-uk-nhs, arckit-repo and the rest) under .arckit/plugins/. Both halves are therefore reachable, and the overlays are the larger half of the catalogue:

• list covers core and overlays
• Copying by name covers core and overlays
• all covers core only, deliberately, because a UK project has no use for twelve UAE templates

Whichever scope an action has, say which one you used. Never present a core-only result as the complete inventory.

Instructions

1. Parse User Request

The user may request:

• List templates: Show all available templates (no arguments or "list")
• Copy specific template: Copy one template (e.g., "requirements", "risk", "adr")
• Copy all templates: Copy all templates ("all")
• Show template info: Explain what a template contains ("info requirements")

2. List Available Templates

Glob both template trees, then strip the -template.md/.html suffix from each filename to get the short name:

1. Core: .arckit/templates/*-template.md and .arckit/templates/*-template.html
2. Overlays: .arckit/plugins/**/templates/*-template.md and .arckit/plugins/**/templates/*-template.html

For an overlay hit, derive the owning plugin from the path segments between plugins/ and templates/: join them with - and prefix arckit-. So plugins/uae/templates/ is arckit-uae and plugins/uk/finance/templates/ is arckit-uk-finance. Overlay directories nest one or two levels deep, which is why the glob needs **.

State the totals first, in these words or close to them:

NN templates available: NN in the core arckit plugin, NN across NN community overlay plugins.

Then display the core templates as a table:

Then list the overlay templates, grouped by owning plugin, ordered by descending count. Render these from the glob results, not from a hardcoded list, so a newly added overlay appears without this file changing:

Close with the line that makes the two halves actionable:

Copy any of these by name, for example $arckit-customize uae-ai-charter. $arckit-customize all copies the core set only.

If the user asked to list a single plugin's templates (e.g. "list arckit-repo"), show only that group.

3. Copy Template(s)

Copy specific template:

1. Map the user's short name to the full filename (e.g., "requirements" → requirements-template.md, "pages" → pages-template.html)
2. Use the Read tool to read the source template from .arckit/templates/{name}-template.{ext}
3. Update the origin banner: Before writing, change the Template Origin line from Official to Custom and add a Based On reference:
   • Find: > **Template Origin**: Official | **ArcKit Version**: [VERSION] | **Command**: `$arckit-{command}`
   • Replace with: > **Template Origin**: Custom | **Based On**: `$arckit-{command}` | **ArcKit Version**: [VERSION]
4. Use the Write tool to save it to .arckit/templates-custom/{name}-template.{ext} (the directory will be created automatically)
5. If the source template does not exist, do not stop at "not found". Glob .arckit/plugins/**/templates/{name}-template.* before answering: if it matches, the template ships in an overlay plugin, so follow "Copy an overlay template" below. Only if both globs come back empty, tell the user it does not exist and suggest $arckit-customize list.

Copy all templates:

1. Use Glob to find all .arckit/templates/*-template.md and .arckit/templates/*-template.html files

2. For each template found, use Read to load it, update the origin banner (change Template Origin: Official to Template Origin: Custom | Based On: $arckit-{command}), and Write to save it to .arckit/templates-custom/

3. Report the scope, not just the count. "all" here means all core templates. Say so explicitly, and say that overlay templates were not included:

   Copied NN core arckit templates. Community overlay plugins ship their own templates, which all does not cover.

   Reporting "copied all templates" after a core-only pass is a wrong answer, not a terse one.

Copy an overlay template:

Templates belonging to a community overlay plugin are not in the core templates/ glob, but the core plugin bundles a copy of every overlay under its own root, so copy one exactly as you would a core template:

1. Glob .arckit/plugins/**/templates/{name}-template.* to locate the file (overlay directories nest one or two levels deep, e.g. plugins/uae/, plugins/uk/finance/)
2. Read it, update the origin banner as under "Copy specific template" above, and Write it to .arckit/templates-custom/{name}-template.{ext}
3. Tell the user which overlay it came from, and that the copy is the version bundled with the installed core plugin, which can lag a separately installed overlay

4. Show Template Info

If user asks about a specific template (e.g., "info requirements"), read and summarize:

• What document it generates
• Key sections included
• UK Government frameworks referenced
• Common customization points

5. Provide Customization Guidance

After copying, explain:

## Template Customization Guide

Your template has been copied to `.arckit/templates-custom/`. You can now customize it.

### How It Works

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 "UK Government Alignment" sections
- Remove TCoP, GDS Service Standard references
- Change classification from "OFFICIAL-SENSITIVE" to your scheme

**Change Document Control fields**:
- Add organization-specific fields (Cost Centre, Programme, etc.)
- Remove fields not relevant to your organization
- Change review cycle defaults

**Modify requirement prefixes**:
- Change BR/FR/NFR to your organization's taxonomy
- Update priority levels (MUST/SHOULD/MAY → P1/P2/P3)

**Add organization branding**:
- Add logo placeholder
- Include standard headers/footers
- Add disclaimer text

**Customize the Pages template** (`pages-template.html`):
- Replace GOV.UK Design System CSS with neutral or organization-specific styling
- Change the color palette (header, sidebar, accent colors)
- Remove or rename UK-specific guide categories (e.g., "UK Government" section)
- Adjust the governance dashboard checklist items to match your framework
- Add organization logo or branding to the header
- Modify the footer text and links

### Keeping Templates Updated

When ArcKit CLI updates with new template features:
- Default templates in `.arckit/templates/` are refreshed by `arckit init`
- Your customizations in `.arckit/templates-custom/` are **preserved**
- Compare your templates with defaults periodically to adopt new features

To see the current default template, use the Read tool on `.arckit/templates/{name}-template.md`.

To compare your customization with the default, read both files and compare the content.

### Reverting to Default

To stop using a custom template and revert to default, delete `.arckit/templates-custom/{name}-template.md`.

Output Summary

After completing the request, show:

## Template Customization Complete ✅

**Action**: [Listed templates / Copied X template(s)]

**Scope**: [Core + overlays ([N] templates) for `list` and copy-by-name / Core `arckit` plugin only ([N] templates) for `all`]

**Location**: `.arckit/templates-custom/`

**Files**:
- [List of files copied or available]

**Next Steps**:
1. Edit the template(s) in `.arckit/templates-custom/`
2. Run the corresponding `$arckit-*` command
3. Your customized template will be used automatically

**Tip**: Read both the default and your custom template to compare differences.

Example Usage

List all templates:

$arckit-customize list

Copy requirements template:

$arckit-customize requirements

Copy multiple templates:

$arckit-customize requirements risk adr

Copy all templates:

$arckit-customize all

Get info about a template:

$arckit-customize info requirements