CODITECT File Naming Conventions

Purpose

This standard defines naming conventions for all files and directories within CODITECT projects, ensuring consistency, discoverability, and cross-platform compatibility.

Scope

Applies to all files and directories in:

• CODITECT repositories
• Customer projects using CODITECT framework
• Generated files and automation outputs

---

1. General Principles

1.1 Core Rules

Rule	Description	Example
Lowercase preferred	Use lowercase for most files	config.json, utils.py
UPPERCASE for standards	Use UPPERCASE for important docs	README.md, CLAUDE.md
Hyphens for multi-word	Separate words with hyphens	user-authentication.ts
No spaces	Never use spaces in names	my-file.md not my file.md
ASCII only	Avoid special characters	cafe.md not café.md
Descriptive names	Names should indicate purpose	generate-reports.py

1.2 Case Conventions

Convention	Use For	Example
UPPERCASE	Standards, important docs	README.md, LICENSE, CLAUDE.md
UPPER-KEBAB-CASE	Standard documents, ADRs	PROJECT-PLAN.md, ADR-001.md
kebab-case	Most files, folders	user-service.ts, api-handlers/
snake_case	Python modules	user_service.py, api_handlers/
camelCase	JavaScript/TypeScript variables	Internal code only
PascalCase	React components, classes	UserProfile.tsx, ApiService.ts

---

2. Directory Naming

2.1 Standard Directories

Directory	Convention	Examples
Top-level	kebab-case	docs/, scripts/, config/
Source code	kebab-case	src/, components/, services/
Python packages	snake_case	user_auth/, api_v1/
Test directories	kebab-case	tests/, unit/, integration/
Hidden directories	.name	.github/, .claude/, .coditect/

2.2 Directory Patterns

✅ CORRECT
docs/
scripts/
config/
src/
  components/
  services/
  utils/
tests/
  unit/
  integration/

❌ INCORRECT
Docs/              # No PascalCase for directories
my scripts/        # No spaces
src_code/          # Use src/ or source/
Tests/             # Lowercase preferred

2.3 Category Directories (Submodules)

Pattern: <category>/

submodules/
├── archives/      # Archived projects
├── cloud/         # Cloud infrastructure
├── compliance/    # Compliance & legal
├── core/          # Core framework
├── dev/           # Development tools
├── docs/          # Documentation
├── gtm/           # Go-to-market
└── ops/           # Operations

---

3. File Naming by Type

3.1 Documentation Files

Type	Convention	Examples
README	README.md	README.md (exactly)
Standards	UPPER-KEBAB-CASE.md	PROJECT-PLAN.md, TASKLIST.md
Guides	UPPER-KEBAB-CASE.md	QUICK-START.md, INSTALLATION.md
ADRs	ADR-NNN-title.md	ADR-001-database-choice.md
Checkpoints	CHECKPOINT-YYYY-MM-DD.md	CHECKPOINT-2026-01-02.md
AI Context	CLAUDE.md	CLAUDE.md (exactly)

3.2 Source Code Files

Language	Convention	Examples
TypeScript/JavaScript	kebab-case.ts	user-service.ts, api-handler.ts
React Components	PascalCase.tsx	UserProfile.tsx, Dashboard.tsx
Python	snake_case.py	user_service.py, api_handler.py
Rust	snake_case.rs	user_service.rs, api_handler.rs
Go	snake_case.go	user_service.go, api_handler.go
Shell	kebab-case.sh	deploy-app.sh, run-tests.sh

3.3 Configuration Files

Type	Convention	Examples
JSON config	kebab-case.json	component-counts.json
Environment-specific	name.environment.ext	settings.production.json
Local overrides	name.local.ext	settings.local.json
YAML	kebab-case.yaml	docker-compose.yaml
TOML	kebab-case.toml	pyproject.toml, Cargo.toml

3.4 Test Files

Type	Convention	Examples
Unit tests	name.test.ext or test_name.ext	user-service.test.ts, test_user_service.py
Integration	name.integration.test.ext	api.integration.test.ts
E2E	name.e2e.test.ext	login.e2e.test.ts
Spec files	name.spec.ext	user-service.spec.ts

3.5 CODITECT Components

Component	Convention	Examples
Agents	kebab-case.md	project-structure-analyzer.md
Skills	kebab-case/SKILL.md	project-organization/SKILL.md
Commands	kebab-case.md	organize.md, structure.md
Hooks	kebab-case.py or .sh	pre-commit-naming-check.py
Workflows	UPPER-KEBAB-CASE.md	PROJECT-REORGANIZATION-WORKFLOW.md
Prompts	kebab-case-prompt.md	analyze-structure-prompt.md

---

4. Special Files

4.1 Required Exact Names

These files MUST use exact names (case-sensitive):

File	Exact Name	Location
Readme	README.md	Every directory
License	LICENSE or LICENSE.md	Root
AI Context	CLAUDE.md	Root, key directories
Git Ignore	.gitignore	Root
Git Modules	.gitmodules	Root (if using submodules)
Changelog	CHANGELOG.md	Root
Contributing	CONTRIBUTING.md	Root
Code of Conduct	CODE_OF_CONDUCT.md	Root

4.2 Package Manifests

Language	Exact Name
Node.js	package.json
Python	pyproject.toml or setup.py
Rust	Cargo.toml
Go	go.mod
Ruby	Gemfile

---

5. Naming Patterns

5.1 Versioned Files

Pattern: name-vN.N.N.ext or name.vN.ext

✅ CORRECT
api-v1/
api-v2/
schema-v2.0.0.json

❌ INCORRECT
api_version_1/
apiV1/
schema-version-2.json

5.2 Date-Stamped Files

Pattern: NAME-YYYY-MM-DD.ext

✅ CORRECT
CHECKPOINT-2026-01-02.md
backup-2026-01-02.sql
report-2026-01-02.pdf

❌ INCORRECT
CHECKPOINT-01-02-2026.md    # Wrong date format
backup_20260102.sql         # No separators
report-Jan-02-2026.pdf      # Text month

5.3 Numbered Files

Pattern: NNN-name.ext (3-digit prefix)

✅ CORRECT
001-introduction.md
002-getting-started.md
010-advanced-topics.md

❌ INCORRECT
1-introduction.md           # Single digit
01-introduction.md          # Two digits
introduction-1.md           # Number at end

---

6. Prohibited Patterns

6.1 Never Use

Pattern	Problem	Alternative
Spaces	Cross-platform issues	Use hyphens
Special chars !@#$%^&*()	Shell escaping issues	Use alphanumeric
Leading dots (except hidden)	Confusion with hidden files	Remove dot
Trailing dots	Windows issues	Remove dot
Mixed case directories	Cross-platform issues	Lowercase
Very long names (>50 chars)	Display issues	Abbreviate
Underscores in docs	Inconsistency	Use hyphens

6.2 Platform-Specific Issues

Issue	Problem	Solution
CON, PRN, AUX, NUL	Windows reserved names	Avoid completely
Case-only differences	macOS/Windows conflicts	Don't rely on case
Colons :	Windows path issues	Never use
Backslashes \	Path issues	Never use

---

7. Enforcement

7.1 Automated Checking

# Check naming conventions
/naming-check

# Check and auto-fix where possible
/naming-check --fix

# Check specific directory
/naming-check --path docs/

7.2 Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: naming-check
        name: Check file naming conventions
        entry: python scripts/enforce-naming-conventions.py
        language: python
        types: [file]

7.3 CI/CD Integration

# .github/workflows/naming-check.yml
name: Naming Convention Check
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python scripts/enforce-naming-conventions.py --check

---

8. Migration Guide

8.1 Renaming Files

Always use git mv to preserve history:

# Single file
git mv "Old Name.md" "new-name.md"

# Batch rename (example: uppercase to kebab-case)
for f in docs/*.md; do
  new=$(echo "$f" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
  git mv "$f" "$new"
done

8.2 Common Migrations

From	To	Command
My Document.md	my-document.md	git mv "My Document.md" my-document.md
userService.ts	user-service.ts	git mv userService.ts user-service.ts
API_Handler.py	api_handler.py	git mv API_Handler.py api_handler.py

---

9. Quick Reference Card

DIRECTORIES:
  Standard:        kebab-case/       (docs/, scripts/, config/)
  Python packages: snake_case/       (user_auth/, api_v1/)
  Hidden:          .name/            (.github/, .claude/)

FILES:
  Standards:       UPPER-KEBAB.md    (README.md, CLAUDE.md)
  Documents:       UPPER-KEBAB.md    (PROJECT-PLAN.md)
  Source (TS/JS):  kebab-case.ts     (user-service.ts)
  Source (Python): snake_case.py     (user_service.py)
  React:           PascalCase.tsx    (UserProfile.tsx)
  Config:          kebab-case.json   (app-config.json)
  Tests:           name.test.ext     (user.test.ts)

PATTERNS:
  Versioned:       name-v1.0.0.ext
  Dated:           NAME-YYYY-MM-DD.ext
  Numbered:        NNN-name.ext

---

Version: 1.0.0 Status: Active Owner: CODITECT Core Team Last Updated: 2026-01-02