Core Concepts

Overview

HoxCore is a foundational, Git-inspired project registry and initialization system designed to manage any kind of human endeavor, not only software projects. Its core purpose is to provide a single, authoritative source of truth for projects and related activities, expressed through immutable, version-controlled metadata and declarative automation.

What Makes HoxCore Different?

• Universal Scope: Not limited to software—manage academic research, business initiatives, creative projects, and more
• Declarative First: No executable scripts, only pure YAML definitions
• Git-Native: Built on Git's proven model of immutability and version control
• LLM-Ready: Designed for AI integration from the ground up
• Integration-Focused: Connects with existing tools rather than replacing them

Entity Types

HoxCore manages four fundamental entity types, each representing a different kind of human endeavor:

Registry Model

The registry is the heart of HoxCore—a dedicated Git repository containing only metadata (YAML files).

Registry Structure

my-registry/
├── .git/                  # Git repository
├── config.yml             # Registry configuration
├── programs/              # Program definitions
│   ├── prog_abc123.yml
│   └── prog_def456.yml
├── projects/              # Project definitions
│   ├── proj_ghi789.yml
│   └── proj_jkl012.yml
├── missions/              # Mission definitions
│   └── miss_mno345.yml
├── actions/               # Action definitions
│   └── act_pqr678.yml
├── templates/             # Custom templates
│   └── my-template/
└── .hxc/                  # Internal HoxCore data
    └── index.db           # Entity index

Key Characteristics

• Git-Based: Every registry is a Git repository, providing version control, history, and collaboration
• Metadata Only: Contains only YAML definitions, no executable code or large binary files
• Indexed: Fast querying through an internal index database
• Scalable: Designed to handle thousands of entities efficiently
• Portable: Can be cloned, forked, and shared like any Git repository

Registry Configuration

The config.yml file defines registry-wide settings:

registry:
  name: my-registry
  version: 0.1.0
  created: 2024-01-01T00:00:00Z
  description: "My project registry"

settings:
  default_category: general
  auto_commit: true
  index_on_change: true
  uid_prefix: custom

integrations:
  github:
    enabled: true
    default_org: myorg
  azure_devops:
    enabled: false

Entity Definition

Every entity in HoxCore is defined by a YAML file with a standardized structure:

Complete Entity Schema

# --- Basic Metadata ---
type: project                # One of: program, project, mission, action
id: P-001                    # Optional: user-defined ID
uid: proj_abc123def456       # Auto-generated by HoxCore
title: "Example Project"     # Human-readable title
description: >               # Optional: purpose or summary
  This project builds an AI-integrated CLI for managing
  modular registries.

# --- Status & Lifecycle ---
status: active               # Options: active, completed, on-hold, canceled
start_date: 2024-01-01       # Optional
due_date: 2024-04-01         # Optional
completion_date: null        # Optional
duration_estimate: 90d       # e.g., 90d, 3w, 6m

# --- Classification & Hierarchy ---
category: software.dev/cli-tool.default
tags: [cli, ai, registry, tools]
parent: prog_xyz789          # Optional parent UID
children: []                 # Optional list of child UIDs
related: []                  # Optional list of related UIDs

# --- Git & Version Control Integrations ---
repositories:
  - name: github
    url: https://github.com/user/repo
  - name: overleaf
    url: https://www.overleaf.com/project/123abc
  - name: local-repo
    path: ./repos/example

# --- Storage Integrations ---
storage:
  - name: gdrive
    provider: google-drive
    url: https://drive.google.com/drive/folders/example
  - name: notion
    provider: notion
    url: https://notion.so/workspace/docs

# --- Database Integrations ---
databases:
  - name: local-sqlite
    type: sqlite
    path: ./data/example.db
  - name: remote-postgres
    type: postgres
    url: postgres://user:pass@host:5432/dbname

# --- Project Management Tools ---
tools:
  - name: azure-devops
    provider: azure
    url: https://dev.azure.com/org/project
  - name: github-projects
    provider: github
    url: https://github.com/user/repo/projects/1

# --- LLM Models & Knowledge Bases ---
models:
  - id: assistant
    provider: openwebui
    url: http://openwebui.local/?models=assistant

knowledge_bases:
  - id: kb-registry-specs
    url: http://openwebui.local/workspace/knowledge/5f0f9cc7...

# --- Template for Scaffolding ---
template: software.dev/cli-tool.default

Field Descriptions

Identification System

HoxCore uses a dual identification system to balance machine efficiency with human usability:

UID (Unique Identifier)

uid: proj_abc123def456  # Auto-generated, never changes

ID (Human-Defined Identifier)

id: P-001  # Optional, can be changed

Why Two Identifiers?

Classification & Categories

HoxCore uses a flexible classification system based on categories and tags:

Categories

Categories provide hierarchical, semantic classification:

# Basic category
category: software.dev/cli-tool

# Category with template variant
category: software.dev/cli-tool.python-advanced

# Academic category
category: academic/research-paper.ieee

# Business category
category: business/initiative.strategic

Category Structure

Tags

Tags provide flexible, subjective classification:

tags: [cli, ai, python, tools, automation]

Tags vs Categories

Relationships

Entities can be related to each other through three types of relationships:

Parent-Child Relationships

Hierarchical relationships representing containment or ownership:

# Parent entity (Program)
type: program
uid: prog_abc123
title: "Digital Transformation"
children:
  - proj_def456
  - proj_ghi789

# Child entity (Project)
type: project
uid: proj_def456
title: "Build CLI Tool"
parent: prog_abc123

Characteristics:

• One parent per entity (optional)
• Multiple children per entity
• Bidirectional references (parent knows children, children know parent)
• Typically: Programs contain Projects, Projects contain Missions/Actions

Related Entities

Non-hierarchical relationships representing dependencies or associations:

type: project
uid: proj_abc123
title: "Frontend Development"
related:
  - proj_def456  # Backend API project
  - proj_ghi789  # Design system project

Characteristics:

• Multiple related entities per entity
• Non-hierarchical (peers)
• Can be unidirectional or bidirectional
• Represents dependencies, collaborations, or associations

Relationship Visualization

Program: Digital Transformation (prog_abc123)
├── Project: Build CLI Tool (proj_def456)
│   ├── Mission: Launch v1.0 (miss_jkl012)
│   └── Action: Weekly Standup (act_mno345)
└── Project: API Development (proj_ghi789)
    └── Related to: proj_def456 (Frontend)

Lifecycle Management

Entities progress through a defined lifecycle with status tracking and date management:

Status Values

Date Fields

start_date: 2024-01-01        # When work began
due_date: 2024-04-01          # Expected completion
completion_date: 2024-03-28   # Actual completion
duration_estimate: 90d        # Estimated duration

Duration Format

Duration estimates support multiple formats:

• 90d - 90 days
• 3w - 3 weeks
• 6m - 6 months
• 1y - 1 year

Lifecycle Transitions

┌─────────┐
│ Created │
└────┬────┘
     │
     v
┌────────┐     ┌──────────┐
│ active │────>│ on-hold  │
└───┬────┘     └────┬─────┘
    │               │
    │<──────────────┘
    │
    v
┌───────────┐
│ completed │
└───────────┘
    │
    v
┌──────────┐
│ canceled │
└──────────┘

Git Integration

Every HoxCore registry is a Git repository, providing powerful version control capabilities:

Automatic Git Operations

• Initialization: hxc init creates a Git repository
• Commits: Entity changes can be auto-committed (configurable)
• History: Full audit trail of all changes
• Branching: Experiment with changes in branches

Git Workflow

# Initialize registry (creates Git repo)
hxc init my-registry

# Create entity (auto-commits if enabled)
hxc create project --title "New Project"

# View Git history
cd my-registry
git log

# Create branch for experiments
git checkout -b experiment

# Make changes
hxc update P-001 --status completed

# Merge back to main
git checkout main
git merge experiment

Benefits of Git Integration

Templates

Templates in HoxCore are purely declarative and secure—no executable code, only YAML definitions:

Template Purpose

• Define folder and file scaffolding
• Specify file copying and text injection
• Configure Git repository initialization
• Set up project structure consistently

Template Structure

# template.yml
name: cli-tool-python
description: "Python CLI tool template"
category: software.dev/cli-tool

scaffolding:
  directories:
    - src/
    - tests/
    - docs/
  
  files:
    - path: README.md
      content: |
        # {{title}}
        {{description}}
    
    - path: src/main.py
      source: templates/cli-tool-python/main.py.template
    
    - path: pyproject.toml
      source: templates/cli-tool-python/pyproject.toml.template

git:
  initialize: true
  initial_commit: true
  gitignore:
    - __pycache__/
    - *.pyc
    - .venv/

Template Variables

Templates support variable substitution using {{variable}} syntax:

• {{title}} - Entity title
• {{description}} - Entity description
• {{uid}} - Entity UID
• {{id}} - Entity ID (if set)
• {{category}} - Entity category

Security Model

For more details, see the Templates documentation.

Integrations

HoxCore integrates with external tools rather than replacing them:

Integration Categories

Integration Definition

# In entity definition
repositories:
  - name: github
    url: https://github.com/user/repo

storage:
  - name: gdrive
    provider: google-drive
    url: https://drive.google.com/drive/folders/example

tools:
  - name: azure-devops
    provider: azure
    url: https://dev.azure.com/org/project

databases:
  - name: local-sqlite
    type: sqlite
    path: ./data/example.db

For detailed integration guides, see the Integrations documentation.

AI Integration

HoxCore is designed to be LLM-native from the ground up:

LLM Model References

Projects can reference one or multiple LLM models:

models:
  - id: assistant
    provider: openwebui
    url: http://openwebui.local/?models=assistant
  
  - id: code-helper
    provider: ollama
    model: codellama
  
  - id: gpt4
    provider: openai
    model: gpt-4-turbo

Knowledge Base Integration

Link knowledge bases for context-aware AI assistance:

knowledge_bases:
  - id: kb-registry-specs
    url: http://openwebui.local/workspace/knowledge/5f0f9cc7...
  
  - id: kb-project-docs
    path: ./docs/knowledge-base/

AI Capabilities

• Registry Indexing: The entire registry can be indexed as an LLM-accessible knowledge base
• Global Assistant: AI can reason over all projects, relationships, and metadata
• Context-Aware Help: AI understands project context and provides relevant assistance
• Natural Language Queries: Query the registry using natural language

For more details, see the AI Features documentation.

Design Principles

HoxCore is built on a foundation of clear, consistent design principles:

Next Steps

Now that you understand the core concepts, explore specific features: