tractorjuice/arckit-template-builder

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

$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 Codex skill in .agents/skills/arckit-community-{name}/SKILL.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. Present all 4 questions together, then wait for the user's answers before continuing.

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?"

• Codex Skill: Generate a matching $arckit-community-{name} skill 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 "Codex Skill" is selected, generate a skill 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. Read these files directly. Do not search broadly or delegate this step.

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.

Template Structure (mandatory elements):

# [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):

---

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

Guide Structure:

# {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

For official promotion: rename the generated skill if needed, change banner to Template Origin: Official, and open a PR.

### Step 6: Generate Optional Codex Skill

If the user selected "Codex Skill" in Round 2, create `.agents/skills/arckit-community-{name}/SKILL.md`. This location is auto-discovered by Codex as a project-level skill (available as `$arckit-community-{name}`).

**Skill Structure**:

```markdown
---
name: arckit-community-{name}
description: "{Brief description of what this skill generates}"
---

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 to projects/{project-dir}/ARC-{PROJECT_ID}-{TYPE_CODE}-v1.0.md

5. Show summary only (NOT the full document)

### 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 skill (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}/SKILL.md` -> `.agents/skills/` (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-custom/` and `arckit-claude/templates/`
3. Rename or relocate the community skill if promoting it to an official ArcKit command
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:

## 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` |
| Codex Skill | `.agents/skills/arckit-community-{name}/SKILL.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 skills use the arckit-community- prefix (e.g., .agents/skills/arckit-community-security-assessment/SKILL.md)
• Templates follow the same Document Control standard as official ArcKit templates
• Write generated artifacts to files instead of printing full content in the response
• 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)