arckit-template-builder

---
name: arckit-template-builder
description: "Create new document templates by interviewing the user about their organization's requirements"
---

You are helping an enterprise architect create a brand-new document template tailored to their organization's specific needs. Unlike `$arckit-customize` (which copies existing templates for editing), this command creates entirely new templates from scratch through an interactive interview process.

## User Input

```text
$ARGUMENTS
```

## Overview

This command generates:

1. **A new document template** in `.arckit/templates-custom/{name}-template.md` with `Template Origin: Community` banner
2. **A usage guide** in `.arckit/guides-custom/{name}.md` with `Guide Origin: Community` banner
3. **Optionally**: A matching slash command in `.claude/commands/arckit.community.{name}.md`
4. **Optionally**: A shareable bundle in `.arckit/community/{name}/`

All community-generated content is clearly marked with origin banners to distinguish it from official ArcKit templates.

## Three-Tier Origin Model

ArcKit uses three origin tiers for all templates and guides:

- **Official** — Shipped with ArcKit (e.g., `Template Origin: Official`)
- **Custom** — User-modified copies of official templates via `$arckit-customize` (e.g., `Template Origin: Custom`)
- **Community** — Entirely new templates created via this command (e.g., `Template Origin: Community`)

## Instructions

### Step 1: Parse User Input

Extract the template type from `$ARGUMENTS`. If blank or vague, ask the user what kind of document template they want to create.

Check for the `--share` flag in arguments. If present, strip it from the template name and generate a shareable bundle in Step 8.

Slugify the template name: lowercase, replace spaces/special chars with hyphens, trim (e.g., "Security Assessment" -> "security-assessment").

### Step 2: Interview the User

Ask these questions BEFORE reading any templates. Call the **AskUserQuestion** tool exactly once with all 4 questions below in a single call. Do NOT proceed until the user has answered.

**Question 1** — header: `Category`, multiSelect: false
> "What category best describes this template?"

- **Governance (Recommended)**: Compliance assessments, audits, policy reviews
- **Technical**: Architecture patterns, design specs, technical evaluations
- **Procurement**: Vendor assessments, scoring matrices, contract templates
- **Strategy**: Roadmaps, capability assessments, transformation plans

**Question 2** — header: `Elements`, multiSelect: true
> "Which structural elements should the template include?"

- **Scoring/Rating Matrix**: Quantitative scoring with weighted criteria
- **Compliance Checklist**: Pass/fail items against a framework or standard
- **Approval Workflow**: Sign-off gates, review stages, escalation paths
- **Risk Assessment**: Risk identification, likelihood, impact, mitigations

**Question 3** — header: `Context`, multiSelect: false
> "What organizational context should the template support?"

- **UK Government (Recommended)**: GDS, TCoP, Orange/Green Book alignment
- **Enterprise/Corporate**: Standard corporate governance
- **Regulated Industry**: Financial services, healthcare, defence compliance
- **Technology Startup**: Lightweight, agile-friendly documentation

**Question 4** — header: `Outputs`, multiSelect: true
> "What additional outputs would you like?"

- **Slash Command**: Generate a matching `/arckit.community.{name}` command file
- **Minimal Template**: Skip optional sections, keep it lean

Apply the user's selections: the category determines the template's major sections. The structural elements determine which reusable components (matrices, checklists, workflows, risk tables) are included. The organizational context determines compliance sections and terminology. If "Slash Command" is selected, generate a command file in Step 6. If the user passed `--share`, generate a bundle in Step 7.

### Step 3: Read Reference Templates

Now that you have the user's preferences, read 2-3 existing official templates to understand the standard format. Use the Read tool only — do NOT use Bash, Glob, or Agent to search for templates.

**Always read**:

- `.arckit/templates/requirements-template.md` (canonical Document Control + structure)

**Read one more based on the user's category selection**:

- Governance: `.arckit/templates/conformance-assessment-template.md`
- Technical: `.arckit/templates/platform-design-template.md`
- Procurement: `.arckit/templates/evaluation-criteria-template.md`
- Strategy: `.arckit/templates/architecture-strategy-template.md`

### Step 4: Generate the Template

Create the template file at `.arckit/templates-custom/{name}-template.md` using the Write tool.

**Template Structure** (mandatory elements):

```markdown
# [DOCUMENT_TYPE]: [PROJECT_NAME]

> **Template Origin**: Community | **Generated By**: `/arckit.template-builder` | **ArcKit Version**: [VERSION]

## Document Control

| Field | Value |
|-------|-------|
| **Document ID** | ARC-[PROJECT_ID]-[TYPE_CODE]-v[VERSION] |
| **Document Type** | [DOCUMENT_TYPE_NAME] |
| **Project** | [PROJECT_NAME] (Project [PROJECT_ID]) |
| **Classification** | [PUBLIC / OFFICIAL / OFFICIAL-SENSITIVE / SECRET] |
| **Status** | [DRAFT / IN_REVIEW / APPROVED / PUBLISHED / SUPERSEDED / ARCHIVED] |
| **Version** | [VERSION] |
| **Created Date** | [YYYY-MM-DD] |
| **Last Modified** | [YYYY-MM-DD] |
| **Review Cycle** | [Monthly / Quarterly / Annual / On-Demand] |
| **Next Review Date** | [YYYY-MM-DD] |
| **Owner** | [OWNER_NAME_AND_ROLE] |
| **Reviewed By** | [REVIEWER_NAME] on [DATE] or [PENDING] |
| **Approved By** | [APPROVER_NAME] on [DATE] or [PENDING] |
| **Distribution** | [DISTRIBUTION_LIST] |

## Revision History

| Version | Date | Author | Changes | Approved By | Approval Date |
|---------|------|--------|---------|-------------|---------------|
| [VERSION] | [DATE] | ArcKit AI | Initial creation from `/arckit.[COMMAND]` command | [PENDING] | [PENDING] |
```

**Body sections** — Generate based on interview answers:

- **Purpose & Scope** section (always included)
- Category-specific sections based on Round 1 answers
- Structural elements based on user selections (scoring matrix, compliance checklist, etc.)
- Organizational context sections based on Round 2 answers
- **Appendices** section (always included)

**Standard footer** (always included):

```markdown
---

**Generated by**: ArcKit `/arckit.template-builder` command
**Generated on**: [DATE]
**ArcKit Version**: [VERSION]
**Project**: [PROJECT_NAME]
**Model**: [AI_MODEL]
```

**TYPE_CODE**: Generate a short 3-5 character uppercase code for the document type (e.g., "SECAS" for Security Assessment, "VSCR" for Vendor Scorecard). Ensure it does not conflict with existing ArcKit type codes (REQ, RISK, SOBC, STKE, ADR, DIAG, etc.).

### Step 5: Generate the Usage Guide

Create a usage guide at `.arckit/guides-custom/{name}.md` using the Write tool.

**Guide Structure**:

```markdown
# {Template Name} Guide

> **Guide Origin**: Community | **Generated By**: `/arckit.template-builder` | **ArcKit Version**: [VERSION]

`/arckit.community.{name}` generates a {brief description of what the template produces}.

---

## Preparation

| Artefact | Why it matters |
|----------|----------------|
| {prerequisite 1} | {why it's needed} |
| {prerequisite 2} | {why it's needed} |

---

## Usage

```text
$arckit-community.{name} {example arguments}
```

Output: `.arckit/templates-custom/{name}-template.md`

---

## Template Sections

{Describe each major section of the template and what it covers}

---

## Customization

This is a community template. You can:

- Edit `.arckit/templates-custom/{name}-template.md` directly
- Submit it to ArcKit for official inclusion (see Sharing section below)

---

## Sharing

To share this template:

1. Copy the bundle from `.arckit/community/{name}/` (if generated)
2. Share via Git or submit a PR to [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)

For official promotion: rename command (drop `community.` prefix), change banner to `Template Origin: Official`, and open a PR.

```text

### Step 6: Generate Optional Slash Command

If the user selected "Slash Command" in Round 2, create `.claude/commands/arckit.community.{name}.md` using the Write tool. This location is auto-discovered by Claude Code as a project-level slash command (available as `/arckit.community.{name}`).

**Command Structure**:

```markdown
---
description: {Brief description of what this command generates}
argument-hint: "<project ID or name>"
---

You are generating a {template type} document using a community template.

## User Input

```text
$ARGUMENTS
```

## Instructions

1. **Identify the target project**:
   - Use the **ArcKit Project Context** (above) to find the project matching the user's input
   - If no match, create a new project directory

2. **Read the template**:
   - Read `.arckit/templates-custom/{name}-template.md`

3. **Generate the document** following the template structure

4. **Write the output** using the Write tool to `projects/{project-dir}/ARC-{PROJECT_ID}-{TYPE_CODE}-v1.0.md`

5. **Show summary only** (NOT the full document)

```text

### Step 7: Generate Optional Shareable Bundle

If the user passed `--share` in their arguments, create the bundle directory:

- `.arckit/community/{name}/README.md` — Usage instructions, author info, description, and "Submit to ArcKit" section
- `.arckit/community/{name}/{name}-template.md` — Copy of the template
- `.arckit/community/{name}/{name}.md` — Copy of the usage guide
- `.arckit/community/{name}/arckit.community.{name}.md` — Copy of the command (if generated)

**README.md for the bundle**:

```markdown
# Community Template: {Template Name}

> **Origin**: Community | **Created with**: ArcKit `/arckit.template-builder`

## Description

{What this template is for and when to use it}

## Installation

Copy the files to your ArcKit project:

- `{name}-template.md` -> `.arckit/templates-custom/`
- `{name}.md` -> `.arckit/guides-custom/`
- `arckit.community.{name}.md` -> `.claude/commands/` (optional)

## Submit to ArcKit

To propose this template for official inclusion:

1. Fork [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
2. Copy template to `.arckit/templates/` and `arckit-claude/templates/`
3. Rename command file: drop `community.` prefix
4. Change `Template Origin: Community` to `Template Origin: Official`
5. Change `Guide Origin: Community` to `Guide Origin: Official`
6. Add guide to the category map in `arckit-claude/hooks/sync-guides.mjs`
7. Open a PR with description of the template's purpose
```

### Step 8: Show Summary

After writing all files, show ONLY this summary:

```markdown
## Template Builder Complete

**Template**: {Template Name}
**Category**: {Category from Round 1}
**Type Code**: {TYPE_CODE}

### Files Created

| File | Location |
|------|----------|
| Template | `.arckit/templates-custom/{name}-template.md` |
| Usage Guide | `.arckit/guides-custom/{name}.md` |
| Slash Command | `.claude/commands/arckit.community.{name}.md` (if selected) |
| Shareable Bundle | `.arckit/community/{name}/` (if selected) |

### Template Sections

- {List of major sections in the generated template}

### How to Use

1. Run `/arckit.community.{name} <project>` to generate a document from this template
2. Or use `$arckit-customize` to copy any official template for lighter customization

### How to Share

- Share the `.arckit/community/{name}/` bundle via Git
- Submit a PR to [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit) for official promotion

### Origin Model

| Tier | Description |
|------|-------------|
| **Official** | Shipped with ArcKit — 50+ templates |
| **Custom** | Your modifications of official templates (`$arckit-customize`) |
| **Community** | New templates you create (`$arckit-template-builder`) |
```

## Important Notes

- All community templates MUST have `Template Origin: Community` banner
- All community guides MUST have `Guide Origin: Community` banner
- Community commands use the `community.` prefix (e.g., `.claude/commands/arckit.community.security-assessment.md`)
- Templates follow the same Document Control standard as official ArcKit templates
- The Write tool MUST be used for all file creation (avoids token limit issues)
- Never output the full template content in the response — show summary only

## Suggested Next Steps

After completing this command, consider running:

- `$arckit-customize` -- Copy and modify existing official templates instead of creating new ones *(when User wants to customize an existing template rather than build a new one)*