Core Concepts

The Registry

A HoxCore registry is a standard Git repository containing only YAML entity definitions. There are no databases, no servers, no proprietary formats — just files you can read, edit, commit, branch, and merge like any other code.

This design gives you:

• Full version history of every entity change
• Branching to explore alternative structures
• Merging to consolidate registries
• Hosting on any Git provider (GitHub, GitLab, Gitea, local)
• Text-diffable, auditable changes via standard git log and git diff

Entity Types

HoxCore defines exactly four entity types. Each type captures a distinct mode of human endeavor, with clear semantic boundaries:

Program

Programs provide strategic grouping without containing specific deliverables themselves. A Program might be "Digital Transformation Initiative" or "Research & Development Portfolio."

type: program
uid: prog_a1b2c3d4e5f6
id: PROG-001
title: "Digital Transformation Initiative"
description: >
  Umbrella program for all digitization and automation efforts
  across the organization.

status: active
start_date: 2024-01-01

category: business.strategy/digital
tags: [strategy, digital, transformation]

# Programs contain other entities via relationships
children:
  - proj_x1y2z3  # "API Modernization"
  - proj_a9b8c7  # "Data Platform"
  - miss_m1n2o3  # "Q3 Product Launch"

Project

Projects are the workhorse entity. They carry the most metadata: deliverables, repositories, milestones, team members, integrations, AI models, and knowledge bases.

type: project
uid: proj_x1y2z3a4b5c6
id: P-001
title: "API Modernization"
description: >
  Migrate legacy REST endpoints to GraphQL with full
  backwards compatibility and automated test coverage.

status: active
start_date: 2024-01-15
due_date: 2024-09-30

category: software.dev/api.graphql
tags: [graphql, migration, api, backend]

parent: prog_a1b2c3d4e5f6

repositories:
  - name: github
    url: https://github.com/sdescobedo/api-modernization

milestones:
  - id: M1
    title: "Schema design complete"
    due_date: 2024-03-31
    status: completed
  - id: M2
    title: "Core resolvers implemented"
    due_date: 2024-06-30
    status: active

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

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

tools:
  - name: github-projects
    provider: github
    url: https://github.com/sdescobedo/api-modernization/projects/1

Mission

Missions represent event-driven efforts culminating in a specific outcome. The key distinction from a Project is the event orientation — a Mission "happens," a Project "produces."

type: mission
uid: miss_m1n2o3p4q5r6
id: M-001
title: "Q3 Product Launch"
description: >
  Public launch of v2.0 including press outreach,
  documentation release, and community announcement.

status: active
start_date: 2024-08-01
culmination_date: 2024-09-15

category: product.launch/major
tags: [launch, v2, public, marketing]

parent: prog_a1b2c3d4e5f6

tools:
  - name: notion-launch-board
    provider: notion
    url: https://notion.so/team/launch-board

Action

Actions model recurring or continuous activities. They don't complete — they continue until explicitly archived or suspended.

type: action
uid: actn_a1b2c3d4e5f6
id: A-001
title: "Weekly Engineering Sync"
description: >
  Weekly engineering team standup: progress updates,
  blockers, roadmap review.

status: active
start_date: 2024-01-08
recurrence: weekly

category: ops.meetings/team-sync
tags: [meeting, engineering, weekly]

tools:
  - name: google-meet
    provider: google
    url: https://meet.google.com/xyz-abc-def

Unique IDs (UIDs)

Every entity has two identifiers:

UIDs follow the pattern {prefix}_{12-char hex}:

• prog_ — Program UIDs
• proj_ — Project UIDs
• miss_ — Mission UIDs
• actn_ — Action UIDs

Categories

Categories provide a hierarchical classification system using dot and slash notation:

{domain}.{subdomain}/{type}.{variant}

Built-in domains

Statuses

Relationships

Entities relate to each other through three mechanisms:

Parent / Children

A hierarchical tree: Programs contain Projects, Missions, and Actions. Projects can contain sub-projects. References are always by UID.

# In the child entity:
parent: prog_a1b2c3d4e5f6

# In the parent entity (optional — derived automatically):
children:
  - proj_x1y2z3
  - miss_m1n2o3

Dependencies

Express blocking relationships between entities:

depends_on:
  - proj_infra_setup   # Must complete before this starts
blocks:
  - proj_frontend_launch  # This must complete before that starts

References

Non-hierarchical associations — "related to" without structural dependency:

related:
  - proj_api_v1       # Previous version
  - actn_weekly_sync  # Associated recurring meeting

YAML Schema

All entities share a common base schema with type-specific extensions:

Common fields (all entity types)

Extended fields

Design Principles

Declarative, not executable

HoxCore YAML files describe what exists — they don't run code. Templates are interpreted patterns, not scripts. This makes the registry safe to share, version, and hand to an LLM without security concerns.

References over duplication

HoxCore entities reference external tools (GitHub, Notion, Trello) rather than replicate their data. This keeps the registry lean and authoritative without becoming a shadow project manager.

UID immutability

UIDs never change. Names, IDs, categories, and status all can change freely — the UID anchors identity permanently. This is the same principle Git uses for commit hashes.

Human and machine readable

Every YAML file is designed to be readable by a human in any text editor and parseable by an LLM as a structured context block. No binary formats, no proprietary encoding.

Git as infrastructure

Rather than building a custom versioning layer, HoxCore delegates history, branching, and distribution to Git. Every change is a commit. Every registry is a repository you already know how to manage.