tractorjuice/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)

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

If user wants to see available templates, use Glob to find .arckit/templates/*-template.md and .arckit/templates/*-template.html, then extract the template name from each filename (strip the -template.md/.html suffix).

Display as a table:

| Template | Command | Description | |----------|---------|-------------| | adr | $arckit-adr | Architecture Decision Records (MADR v4.0) | | analysis-report | $arckit-analyze | Governance quality analysis report | | architecture-diagram | $arckit-diagram | Mermaid architecture diagrams | | architecture-principles | $arckit-principles | Enterprise architecture principles | | architecture-strategy | $arckit-strategy | Executive-level strategy document | | aws-research | $arckit-aws-research | AWS service research findings | | azure-research | $arckit-azure-research | Azure service research findings | | backlog | $arckit-backlog | Product backlog with user stories | | data-mesh-contract | $arckit-data-mesh-contract | Data product contracts | | data-model | $arckit-data-model | Data model with GDPR compliance | | datascout | $arckit-datascout | External data source discovery | | devops | $arckit-devops | DevOps strategy and CI/CD | | dld-review | $arckit-dld-review | Detailed design review | | dos-requirements | $arckit-dos | Digital Outcomes & Specialists | | dpia | $arckit-dpia | Data Protection Impact Assessment | | evaluation-criteria | $arckit-evaluate | Vendor evaluation framework | | finops | $arckit-finops | FinOps cloud cost management | | gcloud-clarify | $arckit-gcloud-clarify | G-Cloud clarification questions | | gcloud-requirements | $arckit-gcloud-search | G-Cloud service requirements | | hld-review | $arckit-hld-review | High-level design review | | jsp-936 | $arckit-jsp-936 | MOD AI assurance (JSP 936) | | mlops | $arckit-mlops | MLOps strategy | | mod-secure-by-design | $arckit-mod-secure | MOD Secure by Design | | operationalize | $arckit-operationalize | Operational readiness pack | | platform-design | $arckit-platform-design | Platform Design Toolkit | | principles-compliance-assessment | $arckit-principles-compliance | Principles compliance scorecard | | project-plan | $arckit-plan | Project plan with timeline | | requirements | $arckit-requirements | Business & technical requirements | | research-findings | $arckit-research | Technology research findings | | risk-register | $arckit-risk | Risk register (Orange Book) | | roadmap | $arckit-roadmap | Architecture roadmap | | service-assessment-prep | $arckit-service-assessment | GDS Service Standard prep | | servicenow-design | $arckit-servicenow | ServiceNow service design | | sobc | $arckit-sobc | Strategic Outline Business Case | | sow | $arckit-sow | Statement of Work / RFP | | stakeholder-drivers | $arckit-stakeholders | Stakeholder analysis | | story | $arckit-story | Project story with timeline | | tcop-review | $arckit-tcop | Technology Code of Practice | | traceability-matrix | $arckit-traceability | Requirements traceability | | uk-gov-ai-playbook | $arckit-ai-playbook | AI Playbook compliance | | uk-gov-atrs | $arckit-atrs | Algorithmic Transparency Record | | uk-gov-tcop | $arckit-tcop | TCoP review template | | ukgov-secure-by-design | $arckit-secure | UK Gov Secure by Design | | vendor-scoring | $arckit-evaluate | Vendor scoring matrix | | wardley-map | $arckit-wardley | Wardley Map documentation | | pages | $arckit-pages | GitHub Pages site (HTML/CSS/JS) |

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, inform the user and suggest running $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/

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)]

**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