file-naming · diff

v4 to v5.0.0

3 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
- version: 4
+ version: "5.0.0"
scope: ["*"]
alwaysApply: true
description: File and directory naming conventions
+ lastUpdated: "2025-10-08"
+ dependencies: ["root-organization"]
---
# File Naming Conventions
## General Rules
**Use lowercase kebab-case** for all files and directories:
- ✅ `betting-analytics.ts`
- ✅ `mcp-integration.md`
- ✅ `test-helpers.ts`
- ❌ `BettingAnalytics.ts`
- ❌ `MCP_Integration.md`
- ❌ `testHelpers.ts`
**No spaces or mixed case in filenames.**
## TypeScript Files
### Source Files
```
src/
├── index.ts # Entry point
├── mcp/
│ ├── server.ts # Single word or kebab-case
│ ├── tool-registry.ts
│ └── handlers/
│ ├── steam-moves.ts
│ └── risk-concentration.ts
```
### Test Files
```
tests/
├── unit/
│ ├── clv.test.ts # Preferred: feature.test.ts
│ ├── sharp-score.test.ts
│ └── bet-ticker-sniffer.test.ts
├── integration/
│ ├── queue-integration.test.ts
│ └── trigger-implementation.test.ts
```
**Patterns:**
- `*.test.ts` (preferred)
- `*_test.ts` (alternative)
- `*.spec.ts` (alternative)
## Configuration Files
**Standard names (keep as-is):**
- ✅ `package.json`
- ✅ `tsconfig.json`
- ✅ `wrangler.toml`
- ✅ `bunfig.toml`
**Environment configs:**
- ✅ `wrangler.staging.toml`
- ✅ `wrangler.production.toml`
## Documentation Files
**Uppercase for major docs:**
- ✅ `README.md`
- ✅ `LICENSE`
- ✅ `CLAUDE.md`
- ✅ `CHANGELOG.md`
- ✅ `CONTRIBUTING.md`
**Uppercase for status/important docs:**
- ✅ `TESTING_STATUS.md`
- ✅ `MCP_INTEGRATION_STATUS.md`
- ✅ `AUTOMATION_GUIDE.md`
**Kebab-case for guides:**
- ✅ `quick-start.md`
- ✅ `debugging-guide.md`
- ✅ `api-reference.md`
## Script Files
```
scripts/
├── test-mcp.ts # Kebab-case
├── test-handlers-direct.ts
├── format.ts
├── lint.ts
└── automation/
└── build-and-test.ts
```
## HTML Files
```
tools/
├── extension-checker.html # Kebab-case
├── system-health-monitor.html
└── troubleshooting-guide.html
dashboards/
├── dashboard-enhanced.html # Kebab-case
├── dashboard-pro.html
└── dashboard-positions.html
```
## Directories
**Always lowercase, kebab-case:**
- ✅ `browser-extension/`
- ✅ `node_modules/`
- ✅ `test-results/`
- ❌ `BrowserExtension/`
- ❌ `Node_Modules/`
## Database Migrations
```
migrations/
├── 0001_initial_schema.sql # Number_description
├── 0002_add_ttl.sql
├── 0003_mcp_tables.sql
└── 0004_test_data.sql
```
**Pattern:** `NNNN_description.sql`
## Special Cases
### MCP Handlers
```
src/mcp/handlers/
├── steamMoves.ts # camelCase (matches tool names)
├── riskConcentration.ts
├── sharpActivity.ts
├── timeSeriesCLV.ts
└── enhancedSharpScore.ts
```
**Why camelCase?** These match the MCP tool names exactly (`getSteamMoves` → `steamMoves.ts`)
### Tool Files
```
src/tools/intelligence/
├── getBettingExposure.ts # camelCase (matches API endpoints)
├── getSharpScore.ts
├── getHoldPercentage.ts
└── getCLV.ts
```
## What NOT to Create
**Never create:**
- ❌ Backup files: `*.backup`, `*.old`, `*.bak`
- ❌ Temp files: `*.tmp`, `*.temp`
- ❌ System files: `.DS_Store` (gitignored)
- ❌ Tilde files: `~`, `~/`
## File Extensions
**Standardized extensions:**
- TypeScript: `.ts` (not `.tsx` unless React)
- Markdown: `.md` (not `.markdown`)
- HTML: `.html` (not `.htm`)
- SQL: `.sql`
- Config: `.json`, `.toml`, `.yaml`
**Cursor rules:**
- Rule files: `.mdc` (in `.cursor/rules/`)