141 lines
3.5 KiB
Markdown
141 lines
3.5 KiB
Markdown
# Naming Conventions
|
|
|
|
Comprehensive naming rules for all file types. See SKILL.md Rule 2 for overview.
|
|
|
|
## Slug Generation
|
|
|
|
### Rules
|
|
|
|
- Convert title/topic to lowercase
|
|
- Replace spaces and special chars with hyphens
|
|
- Keep numbers
|
|
- Max 50 characters (truncate at word boundary)
|
|
- No leading/trailing hyphens
|
|
- No consecutive hyphens
|
|
|
|
### Examples
|
|
|
|
| Title | Slug |
|
|
|-------|------|
|
|
| "User Authentication Flow" | `user-authentication-flow` |
|
|
| "Fix: API Rate Limiting Bug #42" | `fix-api-rate-limiting-bug-42` |
|
|
| "10 Tips for Better CI/CD" | `10-tips-for-better-ci-cd` |
|
|
| "AI & Automation: A Guide" | `ai-automation-a-guide` |
|
|
|
|
## Date Formats
|
|
|
|
Use `$CK_PLAN_DATE_FORMAT` env var if set, otherwise default to `YYMMDD-HHmm`.
|
|
|
|
| Format | Example | Use case |
|
|
|--------|---------|----------|
|
|
| `YYMMDD-HHmm` | `260304-1530` | Default for time-sensitive files |
|
|
| `YYMMDD` | `260304` | Date-only (ADRs, daily reports) |
|
|
| No date | `{slug}` | Evergreen content |
|
|
|
|
### When to timestamp
|
|
|
|
- Plans, reports, journals, sessions, brainstorms
|
|
- Generated/AI content
|
|
- Campaign-specific assets
|
|
- Any content that becomes stale over time
|
|
|
|
### When NOT to timestamp
|
|
|
|
- Docs (architecture, standards, guides)
|
|
- Config files
|
|
- Source code
|
|
- Templates
|
|
- Brand assets (logos, styles)
|
|
|
|
## Code File Naming
|
|
|
|
Defer to `descriptive-name` hook for language-specific conventions:
|
|
|
|
| Language | Convention | Example |
|
|
|----------|-----------|---------|
|
|
| JS/TS/Python/Shell | kebab-case | `user-auth-service.ts` |
|
|
| C#/Java/Kotlin/Swift | PascalCase | `UserAuthService.cs` |
|
|
| Go/Rust | snake_case | `user_auth_service.go` |
|
|
| CSS/SCSS | kebab-case | `auth-form-styles.scss` |
|
|
|
|
**Priority:** Self-documenting > short. A long descriptive name is better than a cryptic abbreviation.
|
|
|
|
## File Extensions
|
|
|
|
| Type | Extensions |
|
|
|------|-----------|
|
|
| Images | `.png`, `.jpg`, `.webp`, `.svg`, `.gif` |
|
|
| Videos | `.mp4`, `.mov`, `.webm` |
|
|
| Audio | `.mp3`, `.wav`, `.m4a` |
|
|
| Documents | `.md`, `.txt`, `.pdf` |
|
|
| Data | `.json`, `.yaml`, `.yml`, `.csv`, `.xml` |
|
|
| Config | `.json`, `.yaml`, `.toml`, `.ini`, `.env` |
|
|
|
|
## Variant Naming
|
|
|
|
### Size variants
|
|
|
|
Pattern: `{name}-{width}x{height}.{ext}`
|
|
|
|
- `hero-1920x1080.png`
|
|
- `thumbnail-300x200.jpg`
|
|
- `banner-mobile-640x100.png`
|
|
|
|
### Platform variants
|
|
|
|
Pattern: `{name}-{platform}.{ext}`
|
|
|
|
- `cover-youtube.png`
|
|
- `post-instagram.png`
|
|
- `ad-linkedin.jpg`
|
|
|
|
### Theme/style variants
|
|
|
|
Pattern: `{name}-{variant}.{ext}`
|
|
|
|
- `logo-dark.svg`
|
|
- `logo-light.svg`
|
|
- `banner-alt.png`
|
|
|
|
### Version variants
|
|
|
|
Pattern: `{name}-v{N}.{ext}`
|
|
|
|
- `mockup-v2.png`
|
|
- `proposal-v3.pdf`
|
|
|
|
## Directory Naming
|
|
|
|
- Always kebab-case
|
|
- Plural for collections: `tests/`, `scripts/`, `assets/`
|
|
- Singular for specific items: `src/auth/`, `docs/`
|
|
- No abbreviations: `configurations/` not `configs/` (exception: well-known like `docs/`, `src/`)
|
|
|
|
## Report File Naming
|
|
|
|
Pattern: `{agent-type}-{YYMMDD-HHmm}-{slug}.md`
|
|
|
|
Examples:
|
|
- `scout-260304-1530-auth-module-analysis.md`
|
|
- `researcher-260304-1545-oauth2-comparison.md`
|
|
- `brainstorm-260304-1600-caching-strategy.md`
|
|
- `code-reviewer-260304-1700-api-endpoints.md`
|
|
|
|
## Plan Folder Naming
|
|
|
|
Pattern: `{YYMMDD-HHmm}-{slug}/`
|
|
|
|
Examples:
|
|
- `260304-1530-implement-user-authentication/`
|
|
- `260305-0900-migrate-database-to-postgres/`
|
|
- `260306-1400-redesign-dashboard-layout/`
|
|
|
|
## Scene/Sequence Naming
|
|
|
|
Pattern: `scene-{NN}-{position}.{ext}` or `step-{NN}-{name}.{ext}`
|
|
|
|
- `scene-01-start.png`, `scene-01-end.png`
|
|
- `step-01-install.md`, `step-02-configure.md`
|
|
|
|
Zero-padded numbers for correct sorting.
|