ADR-100: Unified Nomenclature Standard - Track-Integrated System

Status

ACCEPTED - January 21, 2026

Context

CODITECT lacked a unified, coded nomenclature system for content categorization across 74 submodules and 2,100+ components. The existing state included:

Track Nomenclature (ADR-054): Domain-based task IDs (A.9.1.3 format) for A-H tracks
Documentation Separation (ADR-099): Audience-based directories (docs-customer/, docs-contributor/)
Component Naming: Informal kebab-case (security-specialist.md)
No unified content coding system

Problems Identified

Inconsistent identification - No systematic way to identify content type/audience
Migration complexity - 74 submodules need coordinated updates
Scalability concerns - Current naming doesn't scale to enterprise deployment
Automation gaps - Hard to automate routing, access control, deployment by content type
Cognitive load - Users must learn multiple naming conventions

Requirements

Requirement	Priority	Description
Readability	P0	Humans must understand codes without lookup
Machine-Parseable	P0	Regex-extractable, automatable
Scalable	P0	Must work for 10,000+ components
Backward Compatible	P1	Migration path from current naming
Extensible	P1	New categories can be added
Consistent	P0	One system across all submodules
Track-Aligned	P0	Integrates with existing A-H track system

Decision

Adopt the Track-Integrated Nomenclature system that extends the existing A-H domain tracks with new content tracks (P, U, V, O, X, Z) to create a unified two-dimensional classification system.

Format Specification

[DOMAIN].[CONTENT].[###]-[DESCRIPTIVE-NAME]

Components:
- DOMAIN:      Single letter (A-H) from existing Track system, or omitted
- CONTENT:     Single letter (P, U, V, O, X, Z) for audience/purpose
- ###:         3-digit sequential number (001-999)
- NAME:        SCREAMING-KEBAB-CASE descriptive name

Domain Tracks (Existing - Immutable)

Track	Domain	Description
A	Backend API	Server-side logic, APIs, databases
B	Frontend UI	Client-side interfaces, components
C	DevOps/Infrastructure	CI/CD, deployment, cloud
D	Security	Authentication, authorization, auditing
E	Testing/QA	Test frameworks, quality assurance
F	Documentation	Written content, guides, references
G	DMS	Document Management System (deferred)
H	Innovation/Research	New features, experiments, AI H.P.001-AGENTS

Content Tracks (New)

Track	Audience	Description	Portal
P	Product	Ships to customers as core product	Customer install
U	User	Customer support, training, onboarding	docs.coditect.ai
V	deVeloper	Contributor documentation, internal	internal.coditect.ai
O	Operations	Deployment, infrastructure, runbooks	Internal
X	eXternal	Marketing, GTM, sales materials	Public
Z	Generated	Auto-built, read-only, API refs	Auto-deployed

Cross-Reference Matrix

Content	A (Backend)	B (Frontend)	C (DevOps)	D (Security)	E (Testing)	F (Docs)	H (Innovation)
P (Product)	A.P.###	B.P.###	C.P.###	D.P.###	E.P.###	-	H.P.###
U (User)	-	B.U.###	-	-	-	F.U.###	-
V (Developer)	A.V.###	B.V.###	C.V.###	D.V.###	E.V.###	F.V.###	H.V.###
O (Operations)	-	-	C.O.###	D.O.###	-	-	-
X (Marketing)	-	-	-	-	-	-	-
Z (Generated)	A.Z.###	B.Z.###	-	-	E.Z.###	F.Z.###	H.Z.###

Note: X (Marketing) and standalone content omit the domain track: X.001-MARKET-POSITIONING

Examples

# Innovation (H) as Product (P)
H.P.001-AGENTS-SPECIALIST-LIBRARY
H.P.002-COMMANDS-SLASH-WORKFLOWS
H.P.003-SKILLS-REUSABLE-PATTERNS
H.P.004-SCRIPTS-AUTOMATION-TOOLS
H.P.005-HOOKS-EVENT-HANDLERS

# Documentation (F) for Users (U)
F.U.001-QUICK-START-GUIDE
F.U.002-MEMORY-MANAGEMENT-GUIDE
F.U.003-TROUBLESHOOTING-FAQ
F.U.004-USER-TRAINING-PATHWAY

# Documentation (F) for Developers (V)
F.V.001-ADR-ARCHITECTURE-DECISIONS
F.V.002-STANDARDS-FRAMEWORK-RULES
F.V.003-RESEARCH-MOE-VERIFICATION
F.V.004-CONTRIBUTION-GUIDE

# DevOps (C) for Operations (O)
C.O.001-KUBERNETES-DEPLOYMENT
C.O.002-DOCKER-CONTAINER-CONFIG
C.O.003-RUNBOOK-INCIDENT-RESPONSE

# Backend (A) as Product (P)
A.P.001-API-MODELS-LICENSE
A.P.002-API-ENDPOINTS-CONTEXT
A.P.003-API-SERIALIZERS-USER

# Marketing (standalone)
X.001-MARKET-POSITIONING-BRIEF
X.002-CASE-STUDY-ENTERPRISE
X.003-COMPETITIVE-ANALYSIS

Directory Structure

coditect-core/
├── H.P-innovation-product/
│   ├── H.P.001-H.P.001-AGENTS/
│   │   ├── H.P.001.001-security-specialist.md
│   │   ├── H.P.001.002-devops-engineer.md
│   │   └── ...
│   ├── H.P.002-H.P.002-COMMANDS/
│   ├── H.P.003-H.P.003-SKILLS/
│   ├── H.P.004-H.P.004-SCRIPTS/
│   └── H.P.005-H.P.005-HOOKS/
├── F.U-docs-user/
│   ├── F.U.001-getting-started/
│   ├── F.U.002-guides/
│   ├── F.U.003-tutorials/
│   └── F.U.004-troubleshooting/
├── F.V-docs-developer/
│   ├── F.V.001-adrs/
│   ├── F.V.002-standards/
│   ├── F.V.003-research/
│   └── F.V.004-development/
├── C.O-devops-operations/
│   ├── C.O.001-kubernetes/
│   └── C.O.002-docker/
└── X-marketing/
    ├── X.001-positioning/
    └── X.002-case-studies/

Validation Rules

Regex Pattern:

^([A-H]\.)?[POUVXZ]\.\d{3}-[A-Z][A-Z0-9-]+$

Validation Script:

import re

PATTERN = r'^([A-H]\.)?[POUVXZ]\.\d{3}-[A-Z][A-Z0-9-]+$'

def validate_nomenclature(name: str) -> bool:
    return bool(re.match(PATTERN, name))

# Valid examples
assert validate_nomenclature("H.P.001-AGENTS-LIBRARY")
assert validate_nomenclature("F.U.002-QUICK-START")
assert validate_nomenclature("X.001-POSITIONING")

# Invalid examples
assert not validate_nomenclature("CORE-0001-AGENTS")  # Wrong format
assert not validate_nomenclature("H.P.1-AGENTS")       # Need 3 digits
assert not validate_nomenclature("H.Q.001-AGENTS")     # Q not valid content

Consequences

Positive

Single unified system - One nomenclature for all content types
Native Track integration - Extends familiar A-H system developers already know
Two-dimensional clarity - Domain × Content provides precise classification
Infinite scalability - Add new tracks without breaking existing system
Machine-parseable - Simple regex validation and extraction
CI/CD compatible - Works with existing Track-based pipelines
Reduced cognitive load - Learn one system, not multiple parallel systems

Negative

Initial learning curve - Single-letter codes require reference
Migration effort - 2,100+ components need renaming
Unique to CODITECT - Not an industry standard (though logical)
Some edge cases - Not all Domain × Content combinations make sense

Neutral

Documentation updates - Extensive but manageable
Tooling updates - CI/CD needs Content track recognition

Implementation

Symlink Compatibility Layer (CRITICAL)

Operational directories MUST maintain backward-compatible symlinks to prevent breaking the framework runtime. The Track-Integrated names are the canonical directories; legacy names are symlinks.

coditect-core/
├── H.P.001-AGENTS/           # Canonical (new name)
├── agents -> H.P.001-AGENTS  # Symlink (legacy compatibility)
├── H.P.002-COMMANDS/
├── commands -> H.P.002-COMMANDS
├── H.P.003-SKILLS/
├── skills -> H.P.003-SKILLS
├── H.P.004-SCRIPTS/
├── scripts -> H.P.004-SCRIPTS
├── H.P.005-HOOKS/
├── hooks -> H.P.005-HOOKS
├── H.P.006-WORKFLOWS/
├── workflows -> H.P.006-WORKFLOWS
├── H.P.007-PROMPTS/
├── prompts -> H.P.007-PROMPTS
├── H.P.008-TEMPLATES/
├── templates -> H.P.008-TEMPLATES
├── H.P.009-CONFIG/
├── config -> H.P.009-CONFIG
└── internal/
    └── project -> ../H.V.001-PROJECT-MANAGEMENT

Rationale:

Claude Code hooks reference ~/.coditect/hooks/
Framework scripts reference ~/.coditect/scripts/
Agent discovery uses ~/.coditect/agents/
Config loading expects ~/.coditect/config/

Breaking these paths breaks the entire framework. Symlinks provide:

New naming visible - Directory listings show Track-Integrated names
Legacy compatibility - Existing references continue to work
Zero migration risk - No need to update 7,755+ file references
Gradual adoption - New code can use new paths; old code still works

Cross-Platform Compatibility

Platform	Symlink Method	Requirements
macOS	Native symlinks	None
Linux	Native symlinks	None
Windows	Directory junctions	None (junctions don't need admin)
Windows (alt)	Symlinks	Developer Mode or Admin

Windows Implementation:

Primary: Directory junctions via mklink /J (no elevation required)
Fallback: Symlinks via mklink /D (requires Developer Mode)
Git: Must set git config --global core.symlinks true

Git Configuration (.gitattributes):

# Preserve symlinks - don't convert to text files
agents symlink
commands symlink
skills symlink
scripts symlink
hooks symlink
workflows symlink
prompts symlink
templates symlink
config symlink

Setup Script (CODITECT-CORE-INITIAL-SETUP.py v2.5.0+):

Cross-platform create_symlink() function handles all platforms
Automatically creates junctions on Windows, symlinks on Unix
create_operational_symlinks() creates all ADR-100 compatibility links

Migration Plan

Phase	Scope	Duration	Priority
1	Create automation scripts	Day 1-2	P0
2	Rename directories + create symlinks	Day 3-4	P0
3	Update CI/CD pipelines	Day 4-5	P0
4	Migrate submodules	Day 5-7	P1
5	Update documentation	Day 6-7	P1

Migration Script Requirements

# migration_nomenclature.py

CURRENT_TO_NEW = {
    # Agents
    'H.P.001-AGENTS/': 'H.P.001-H.P.001-AGENTS/',
    'H.P.001-AGENTS/security-specialist.md': 'H.P.001-H.P.001-AGENTS/H.P.001.001-security-specialist.md',

    # Commands
    'H.P.002-COMMANDS/': 'H.P.002-H.P.002-COMMANDS/',

    # Skills
    'H.P.003-SKILLS/': 'H.P.003-H.P.003-SKILLS/',

    # Scripts
    'H.P.004-SCRIPTS/': 'H.P.004-H.P.004-SCRIPTS/',

    # Hooks
    'H.P.005-HOOKS/': 'H.P.005-H.P.005-HOOKS/',

    # Customer docs
    'F.U.001-GETTING-STARTED/': 'F.U.001-getting-started/',
    'F.U.002-GUIDES/': 'F.U.002-guides/',
    'F.U.003-TUTORIALS/': 'F.U.003-tutorials/',
    'F.U.005-TROUBLESHOOTING/': 'F.U.004-troubleshooting/',

    # Contributor docs
    'F.V.001-ADRS/': 'F.V.001-adrs/',
    'F.V.003-STANDARDS/': 'F.V.002-standards/',
    'F.V.004-RESEARCH/': 'F.V.003-research/',
    'F.V.005-DEVELOPMENT/': 'F.V.004-development/',

    # Operations
    'ops/kubernetes/': 'C.O.001-kubernetes/',
    'ops/docker/': 'C.O.002-docker/',
}

Success Criteria

All 2,100+ components renamed to new nomenclature
All internal references updated (imports, links, H.P.009-CONFIGs)
CI/CD pipelines recognize new Content tracks
All tests passing
Documentation updated with new naming convention
Zero regressions in production

Rollback Plan

If critical issues discovered:

Revert git history to pre-migration commit
Restore symlinks if needed
Re-run CI/CD with original naming
Document issues for next attempt

MoE Evaluation Summary

This decision was made using the MoE Decision Framework with 5 judge personas:

Metric	Value
Decision ID	NOM-2026-001
Solutions Evaluated	5
Judges	5
Winner Score	85.4 (B+)
Consensus	5/5
Threshold	Passed (≥80)

Evaluated Solutions

Solution	Score	Grade
D: Track-Integrated	85.4	B+ (WINNER)
E: Hybrid Badge	84.2	B
C: Hierarchical Triple	83.6	B
A: ADR-Style Extended	82.8	B
B: Dot-Notation Compact	77.6	C+ (Rejected)

Key Decision Factors

Track Integration (D6) - Only solution with full native integration (95.6 avg)
Systematization (D2) - Extends proven system (90.0 avg)
Scalability (D3) - Two-dimensional matrix scales infinitely (91.0 avg)
Migration Effort (D4) - Leverages existing knowledge (82.0 avg)

Changelog

Date	Change
2026-01-22	Added Cross-Platform Compatibility section (Windows support)
2026-01-22	Added Symlink Compatibility Layer section (CRITICAL)
2026-01-21	Initial decision - Accepted

Decision Authority: Hal Casteel, CEO/CTO, AZ1.AI INC Version: 1.0.0 Created: January 21, 2026

Status​

Context​

Problems Identified​

Requirements​

Decision​

Format Specification​

Domain Tracks (Existing - Immutable)​

Content Tracks (New)​

Cross-Reference Matrix​

Examples​

Directory Structure​

Validation Rules​

Consequences​

Positive​

Negative​

Neutral​

Implementation​

Symlink Compatibility Layer (CRITICAL)​

Cross-Platform Compatibility​

Migration Plan​

Migration Script Requirements​

Success Criteria​

Rollback Plan​

MoE Evaluation Summary​

Evaluated Solutions​

Key Decision Factors​

Related Documents​

Changelog​