Templates

What Are Templates?

Templates are reusable YAML scaffolds that pre-fill fields when creating new entities. They enforce consistency, reduce repetitive typing, and encode team conventions directly into the registry.

Key properties of HoxCore templates:

• Declarative — pure YAML, no code, no scripts
• Variable substitution — placeholders replaced at apply-time
• Versioned — stored in the registry, committed with Git like everything else
• Composable — templates can extend other templates

Template Schema

Templates live in the templates/ directory of your registry as .yaml files.

# templates/software-project.yaml
template:
  name: software-project
  description: "Standard template for software development projects"
  entity_type: project
  version: "1.0"

variables:
  - name: repo_url
    description: "GitHub repository URL"
    required: true
  - name: team
    description: "Team or owner name"
    required: false
    default: "engineering"

defaults:
  status: active
  category: software.dev
  tags: [software, engineering]

scaffold:
  type: project
  title: "{{title}}"
  description: "{{description}}"
  status: "{{status}}"
  category: "{{category}}"
  tags: "{{tags}}"

  repositories:
    - name: github
      url: "{{repo_url}}"

  milestones:
    - id: M1
      title: "Design complete"
      status: planned
    - id: M2
      title: "Implementation complete"
      status: planned
    - id: M3
      title: "Testing and review"
      status: planned
    - id: M4
      title: "Release"
      status: planned

  models:
    - id: assistant
      provider: ollama
      model: llama3

  knowledge_bases:
    - id: kb-project
      path: ./docs/

Variables

Templates use {{variable_name}} syntax for substitution. Variables are declared in the variables block:

Built-in variables

These variables are always available in templates:

Creating Templates

Method 1: From scratch

Create a YAML file in your registry's templates/ directory:

$EDITOR templates/my-template.yaml

Method 2: From an existing entity

Export an entity's raw YAML with hxc show, then manually edit it into a template by replacing concrete values with {{variable}} placeholders:

# Export the raw YAML of an existing entity
hxc show P-001 --raw > templates/my-project-template.yaml

# Open and edit: replace concrete values with {{variable}} placeholders
$EDITOR templates/my-project-template.yaml

Method 3: Copy and modify a built-in

Inspect a built-in template's YAML with hxc show (they are stored as regular YAML files in templates/), then adapt it:

# Show the raw YAML of a built-in template file
hxc show software-project --raw > templates/my-variant.yaml
$EDITOR templates/my-variant.yaml

Applying Templates

Templates are applied at entity-creation time via the --template flag on hxc create. The template name corresponds to the template.name field in the template YAML file.

Basic usage

# Create an entity using a named template
hxc create project "New API Service" --template software-project

# Specify additional fields alongside the template
hxc create project "GraphQL Migration" \
  --template software-project \
  --description "Migrate legacy REST API to GraphQL" \
  --tags graphql migration backend \
  --due-date 2025-12-31

From a values file

For templates with many custom variables, you can provide a YAML values file and pass it at creation time. The file maps variable names to values:

# values.yaml
title: "New API Service"
repo_url: "https://github.com/sdescobedo/new-api"
team: backend
tags: [api, python, backend]

hxc create project "New API Service" \
  --template software-project \
  --registry /path/to/registry

Built-in Templates

HoxCore ships with a set of default templates covering common patterns. They live in the templates/ directory of a freshly initialized registry and can be inspected with hxc show <name> --raw:

List all template files in the registry and inspect one:

# List template YAML files directly
ls templates/

# Inspect a built-in template
hxc show research-project --raw

Template Examples

Research project template

template:
  name: research-project
  description: "Academic research project"
  entity_type: project

variables:
  - name: institution
    description: "University or organization"
    required: false
    default: ""
  - name: paper_url
    description: "Paper or preprint URL"
    required: false

defaults:
  category: research/academic
  tags: [research, academic]
  status: active

scaffold:
  type: project
  title: "{{title}}"
  description: "{{description}}"
  category: "{{category}}"
  tags: "{{tags}}"

  tools:
    - name: overleaf
      provider: overleaf
      url: "{{overleaf_url}}"
    - name: notion
      provider: notion
      url: "{{notion_url}}"

  knowledge_bases:
    - id: kb-papers
      path: ./papers/
    - id: kb-data
      path: ./data/

  milestones:
    - id: M1
      title: "Literature review"
      status: planned
    - id: M2
      title: "Methodology defined"
      status: planned
    - id: M3
      title: "Data collection"
      status: planned
    - id: M4
      title: "Analysis complete"
      status: planned
    - id: M5
      title: "Paper submitted"
      status: planned

Product launch mission template

template:
  name: product-launch
  description: "Product launch mission"
  entity_type: mission

variables:
  - name: version
    description: "Version being launched (e.g. v2.0)"
    required: true
  - name: launch_date
    description: "Target launch date (YYYY-MM-DD)"
    required: true

defaults:
  category: product.launch/major
  tags: [launch, product]
  status: active

scaffold:
  type: mission
  title: "{{title}} Launch"
  description: "Public launch of {{version}}."
  culmination_date: "{{launch_date}}"

  milestones:
    - id: M1
      title: "Feature freeze"
      status: planned
    - id: M2
      title: "Documentation ready"
      status: planned
    - id: M3
      title: "Press outreach"
      status: planned
    - id: M4
      title: "Launch day"
      due_date: "{{launch_date}}"
      status: planned
    - id: M5
      title: "Post-launch review"
      status: planned

Sharing Templates

Templates are plain YAML files in the templates/ directory — they're committed to Git and shared naturally through the repository.

Team templates

Commit your templates to a shared registry repository. Every team member who clones the registry gets the templates automatically.

Template-only repositories

You can maintain a dedicated registry that contains only templates. Use it as a reference library and apply its templates by pointing hxc create at that registry:

# Apply a template stored in a separate template library
hxc create project "My New Project" \
  --template research-project \
  --registry /path/to/template-library