Naming Convention Audit — 2026-02-19
Executive Summary
| Category | Count | Safe to Rename | Must Keep |
|---|---|---|---|
| UPPERCASE skill companions | 1 | 1 | 0 |
| snake_case hooks | 16 | 15 | 1 (hook_logger.py) |
| snake_case scripts | 286 | 235 | 51 (imported) |
| Total | 303 | 251 | 52 |
Convention exceptions (correct as-is):
LICENSE.md— 6 files, standard convention (keep uppercase)SKILL.md,README.md,CHANGELOG.md— standard conventions (keep uppercase)- Python modules imported by other files — MUST stay snake_case per PEP 8
Decision
Snake_case Python files that are imported as modules CANNOT be renamed to kebab-case.
Python does not allow hyphens in import statements (from hook-logger import ... is a syntax error). These 52 files are correctly named per Python conventions and must stay as-is.
The remaining 251 files CAN be renamed but the value is low compared to the risk:
- 235 standalone scripts would need all external references updated (shell scripts, commands, SKILL.md files)
- 15 hooks would need hook registration config updates
- 1 skill template file is a trivial rename
Recommendation: Do NOT rename existing snake_case Python files. Instead:
- Enforce kebab-case for NEW standalone scripts and hooks (non-imported)
- Document that snake_case is acceptable for Python modules that may be imported
- Rename the 1 UPPERCASE skill template file
Category Details
1. UPPERCASE Skill Companion Files (1 file)
Only one non-standard-exception file remains uppercase:
| File | Proposed Name | Risk |
|---|---|---|
skills/submodule-setup/templates/PROJECT-PLAN.template.md | project-plan.template.md | Low |
2. snake_case Hooks (16 files)
| File | Imported By | Decision |
|---|---|---|
hooks/hook_logger.py | 15 files | KEEP (critical shared module) |
hooks/classify_document.py | hook_logger | Can rename |
hooks/dependency_management.py | none | Can rename |
hooks/enhance_prompt.py | none | Can rename |
hooks/error_recovery_resilience.py | none | Can rename |
hooks/monitoring_observability.py | none | Can rename |
hooks/multi_tool_orchestration.py | none | Can rename |
hooks/performance_optimization.py | none | Can rename |
hooks/performance_profiling.py | none | Can rename |
hooks/pre_commit_quality.py | none | Can rename |
hooks/quality_gate_enforcement.py | none | Can rename |
hooks/session_start_governance.py | hook_logger | Can rename |
hooks/standards_compliance.py | none | Can rename |
hooks/sync_documentation.py | none | Can rename |
hooks/trajectory_logger_hook.py | hook_logger, trajectory_logging | Can rename |
hooks/validate_component.py | none | Can rename |
3. snake_case Scripts — Imported Modules (51 files, MUST KEEP)
These 51 modules are imported by other files and cannot be renamed:
| Module | Imported By (count) | Key Importers |
|---|---|---|
hook_logger | 15 | Nearly all hooks |
qa_common | 8 | All grade-*.py QA scripts |
unified_logger | 8 | Checkpoint, dashboard, LLM executors |
message_bus | 5 | Agent delegation, message bus health, session bus |
session_message_bus | 3 | session-register-bus, file-conflict-bus, task-id-validator |
conversation_deduplicator | 3 | Checkpoint, export POCs |
privacy_manager | 3 | Privacy integration, memory context |
component_activator | 3 | Activate-all, agent dispatcher, framework bridge |
task_queue_manager | 3 | Agent delegation tests, priority router |
backup_compress | 2 | backup_databases, db_backup |
backup_crypto | 2 | backup_databases, db_backup |
backup_databases | 2 | Self, db_backup |
backup_gcs | 2 | db_backup, self |
nested_learning | 2 | Self, memory_context_integration |
priority_router | 2 | Test, self |
privacy_integration | 2 | Checkpoint, self |
session_export | 2 | Checkpoint, memory_context_integration |
token_resolver | 2 | a2ui_transformer, self |
| Plus 33 more with 1 importer each |
4. snake_case Scripts — Standalone (235 files, CAN rename but low value)
These scripts are executed directly (python3 scripts/foo_bar.py) and not imported.
Renaming is technically possible but affects:
- Shell scripts or commands that reference them by filename
- Documentation links
- User muscle memory
Convention Standard
Based on this audit, the naming convention for coditect-core is:
| File Type | Convention | Rationale |
|---|---|---|
| Standalone scripts | kebab-case (new), snake_case (existing OK) | CLI convention |
| Python modules (imported) | snake_case (required) | PEP 8 / Python import syntax |
| Hooks (standalone) | kebab-case (preferred) | CLI convention |
| Hooks (imported) | snake_case (required) | PEP import syntax |
| Skill companion files | lowercase kebab-case | Match directory naming |
| Standard files | UPPERCASE (README.md, LICENSE.md, CHANGELOG.md, SKILL.md) | Universal convention |
| Markdown docs | kebab-case | URL-friendly |
| Directories | kebab-case | URL-friendly, match repo naming |
Machine-Readable Manifest
Full JSON manifest with all file paths and import dependencies: /tmp/naming-audit.json
Related
- fix-skill-resources.py updated to generate lowercase filenames (RESOURCE_NAMES + slugify())
- MoE classifier
template_expert.pyuses filename case for confidence scoring (line 46) - ADR-213: Documentation externalization (separate concern)