Initial commit

2025-11-29 18:29:20 +08:00
commit 742559fa58
14 changed files with 1131 additions and 0 deletions
--- a/skills/commit-format/SKILL.md
+++ b/skills/commit-format/SKILL.md
@@ -0,0 +1,213 @@
+---
+name: grey-haven-commit-format
+description: Format commit messages according to Grey Haven Studio's actual commitlint configuration (100 char header, lowercase subject, conventional commits). Use when creating git commits or reviewing commit messages.
+---
+
+# Grey Haven Commit Message Format
+
+Follow Grey Haven Studio's **actual** commit message standards, enforced by commitlint configuration from production templates.
+
+## Format Structure
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+## CRITICAL Rules (Commitlint Enforced)
+
+**These rules are automatically enforced by commitlint:**
+
+1. **Header max length: 100 characters** (NOT 72 or 50!)
+2. **Type: REQUIRED** and must be lowercase
+3. **Subject: REQUIRED** and lowercase (NO sentence-case, start-case, pascal-case, or upper-case)
+4. **Body: blank line before** (if included)
+5. **Footer: blank line before** (if included)
+
+## Commit Types
+
+Use **exactly** these types from Grey Haven's commitlint configuration:
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| **feat** | New feature for the user | `feat(auth): add magic link authentication` |
+| **fix** | Bug fix for the user | `fix(api): resolve race condition in order processing` |
+| **docs** | Documentation changes only | `docs(readme): update TanStack Start setup guide` |
+| **style** | Code style changes (formatting) - no logic changes | `style: apply Prettier to all TypeScript files` |
+| **refactor** | Code refactoring - neither fixes a bug nor adds a feature | `refactor(repositories): simplify user query logic` |
+| **test** | Adding or updating tests | `test(auth): add integration tests for OAuth flow` |
+| **chore** | Maintenance tasks, dependency updates | `chore(deps): upgrade React to v19.1.0` |
+| **perf** | Performance improvements | `perf(db): add composite index on user_id and created_at` |
+| **ci** | CI/CD configuration changes | `ci: add Vitest coverage threshold check` |
+| **build** | Build system or dependency changes | `build: configure bun for monorepo` |
+| **revert** | Revert a previous commit | `revert: feat(auth): add OAuth authentication` |
+
+**Any other type will be REJECTED by commitlint.**
+
+## Subject Line Rules
+
+### Requirements
+- **Max length: 100 characters** (header includes type + scope + subject)
+- **Case: lowercase ONLY** - NO capitals anywhere
+- **Format: imperative mood** - "add" not "added" or "adds"
+- **No period** at the end
+- **Be specific** about what changed
+
+### Calculating Header Length
+```
+feat(auth): add OAuth provider for Google authentication
+^---------^ = 9 chars (type + scope)
+            ^----------------------------------------^ = 45 chars (subject)
+Total: 54 characters (within 100 limit ✅)
+```
+
+### Good Examples
+```
+feat(auth): add password reset with email verification
+fix(api): prevent duplicate user email registrations
+docs: update API authentication guide with examples
+refactor(utils): simplify date formatting helper functions
+perf(db): add composite index on user_id and created_at
+```
+
+### Bad Examples (Fail Commitlint)
+```
+❌ feat(auth): Add OAuth provider     # Uppercase 'A' (violates subject-case)
+❌ Fix bug in API                      # Uppercase 'F' (violates subject-case)
+❌ feat: add new feature.              # Period at end
+❌ WIP                                 # Not a valid type
+❌ added new endpoint                  # Missing type
+❌ feat(api): Added endpoint and updated schema and added validation and wrote tests and updated docs
+   # Exceeds 100 characters
+```
+
+## Scope Guidelines
+
+The scope should indicate which part of the codebase is affected:
+
+### Frontend Scopes (TanStack Start/React)
+- `auth`, `ui`, `forms`, `layout`, `routes`, `queries`, `db`, `server`
+
+### Backend Scopes (FastAPI/Python)
+- `api`, `models`, `repositories`, `services`, `schemas`, `db`, `utils`, `config`
+
+### Infrastructure Scopes
+- `deps`, `docker`, `deploy`, `scripts`, `ci`, `hooks`
+
+**Scope is optional** - omit if change affects multiple areas or is global.
+
+## Body (Optional)
+
+Use the body to provide additional context when needed.
+
+### When to Include a Body
+- Explaining **why** the change was made (motivation)
+- Describing **implementation approach** that isn't obvious
+- Noting **breaking changes** or important considerations
+- Referencing **related Linear issues** or GitHub issues
+- Listing **multiple changes** in a larger commit
+
+### Body Format
+- **Blank line REQUIRED** between subject and body
+- Wrap at **90 characters per line**
+- Use **bullet points** for lists (markdown format)
+- Write in **present tense**, imperative mood
+
+## Footer (Optional)
+
+### Breaking Changes (CRITICAL)
+Start with `BREAKING CHANGE:` followed by description:
+
+```
+feat(api): migrate user IDs to UUID format
+
+Change user ID format from sequential integers to UUIDs for better
+scalability and security in multi-tenant architecture.
+
+BREAKING CHANGE: User IDs are now UUIDs instead of sequential integers.
+All API clients must update to handle UUID format. Database migration
+required before deploying this change.
+```
+
+### Linear Issue References
+```
+Fixes GREY-456
+Related to GREY-123
+```
+
+### GitHub Issue References
+```
+Fixes #234
+Closes #456
+Related to #789
+```
+
+## Supporting Documentation
+
+All supporting files are under 500 lines per Anthropic best practices:
+
+- **[examples/](examples/)** - Complete commit message examples
+  - [frontend-examples.md](examples/frontend-examples.md) - TypeScript/TanStack examples
+  - [backend-examples.md](examples/backend-examples.md) - Python/FastAPI examples
+  - [multi-tenant-examples.md](examples/multi-tenant-examples.md) - Multi-tenant patterns
+  - [breaking-change-examples.md](examples/breaking-change-examples.md) - Breaking changes
+  - [INDEX.md](examples/INDEX.md) - Examples navigation
+
+- **[reference/](reference/)** - Configuration and rules
+  - [commitlint-config.md](reference/commitlint-config.md) - Commitlint configuration
+  - [scope-reference.md](reference/scope-reference.md) - Detailed scope guidelines
+  - [validation.md](reference/validation.md) - Pre-commit validation
+  - [INDEX.md](reference/INDEX.md) - Reference navigation
+
+- **[templates/](templates/)** - Copy-paste ready templates
+  - [simple-commit.txt](templates/simple-commit.txt) - Simple commit template
+  - [with-body.txt](templates/with-body.txt) - Commit with body template
+  - [breaking-change.txt](templates/breaking-change.txt) - Breaking change template
+
+- **[checklists/](checklists/)** - Pre-commit validation
+  - [commit-checklist.md](checklists/commit-checklist.md) - Pre-commit checklist
+
+## Quick Checklist
+
+Before committing, verify:
+
+- [ ] Type is one of: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
+- [ ] Type is lowercase
+- [ ] Subject is lowercase (NO capitals anywhere)
+- [ ] Subject uses imperative mood ("add" not "added")
+- [ ] Full header is under 100 characters
+- [ ] Subject doesn't end with a period
+- [ ] Body has blank line after subject (if included)
+- [ ] Breaking changes start with "BREAKING CHANGE:"
+
+## When to Apply This Skill
+
+Use this skill when:
+- Creating git commits in Grey Haven projects
+- Reviewing pull requests and commit messages
+- Setting up commit message templates
+- Configuring commitlint for new projects
+- Writing release notes from commit history
+- Squashing commits before merging
+
+## Template Reference
+
+These standards come from Grey Haven's actual templates:
+- **cvi-template**: TanStack Start + React 19 (commitlint.config.cjs)
+- **cvi-backend-template**: FastAPI + SQLModel (same commitlint config)
+
+## Critical Reminders
+
+1. **Header max: 100 characters** (NOT 72 or 50!)
+2. **Subject: lowercase ONLY** (NO capitals anywhere)
+3. **Types: exact match required** (feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert)
+4. **Body/footer: blank line before** (enforced by commitlint)
+5. **Breaking changes: use BREAKING CHANGE:** prefix
+6. **Linear issues: reference as GREY-123**
+7. **Multi-tenant: mention tenant_id when relevant**
+8. **Python projects: activate .venv before committing**
+9. **Pre-commit hooks: will validate format automatically**
+10. **Squash merges: preferred for main branch**
--- a/skills/commit-format/checklists/commit-checklist.md
+++ b/skills/commit-format/checklists/commit-checklist.md
@@ -0,0 +1,46 @@
+# Commit Message Checklist
+
+**Use before creating any git commit.**
+
+## Format Validation
+
+- [ ] Type is one of: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
+- [ ] Type is lowercase
+- [ ] Scope is meaningful and lowercase (if included)
+- [ ] Subject uses imperative mood ("add" not "added")
+- [ ] Subject is lowercase (NO capitals anywhere)
+- [ ] Full header (type + scope + subject) is under 100 characters
+- [ ] Subject doesn't end with a period
+
+## Body (if included)
+
+- [ ] Blank line after subject
+- [ ] Explains **why** the change was made
+- [ ] Wraps at 90 characters per line
+- [ ] Uses bullet points for lists
+- [ ] Written in present tense
+
+## Footer (if included)
+
+- [ ] Blank line before footer
+- [ ] Breaking changes start with "BREAKING CHANGE:"
+- [ ] Linear issues referenced as GREY-123
+- [ ] GitHub issues referenced as #123
+
+## Content Quality
+
+- [ ] Commit message is descriptive and specific
+- [ ] Change is atomic (single logical change)
+- [ ] No sensitive information (passwords, keys, tokens)
+- [ ] Multi-tenant changes mention tenant_id (if applicable)
+
+## Python Projects
+
+- [ ] Virtual environment activated (source .venv/bin/activate)
+- [ ] Pre-commit hooks will run (Ruff, mypy, pytest)
+
+## Before Pushing
+
+- [ ] Commits follow squash-merge strategy (if merging to main)
+- [ ] Breaking changes are clearly documented
+- [ ] Linear issues are referenced
--- a/skills/commit-format/examples/INDEX.md
+++ b/skills/commit-format/examples/INDEX.md
@@ -0,0 +1,22 @@
+# Commit Format Examples
+
+Complete commit message examples for Grey Haven projects.
+
+## Available Examples
+
+### [frontend-examples.md](frontend-examples.md)
+TypeScript/TanStack Start commit examples.
+- Simple features
+- Bug fixes with context
+- TanStack Query hooks
+- Server functions
+- Drizzle schema changes
+- Dependency updates
+- Refactoring
+
+## Quick Reference
+
+**Simple feature:** `feat(scope): add feature name`
+**Bug fix:** `fix(scope): resolve issue description`
+**Documentation:** `docs: update documentation title`
+**Dependency:** `chore(deps): upgrade package to version`
--- a/skills/commit-format/examples/frontend-examples.md
+++ b/skills/commit-format/examples/frontend-examples.md
@@ -0,0 +1,90 @@
+# Frontend Commit Examples
+
+Complete examples for TypeScript/TanStack Start commits.
+
+## Simple Feature
+```
+feat(ui): add loading skeleton for user profile card
+```
+
+## Bug Fix with Context
+```
+fix(routes): prevent navigation flicker on auth check
+
+Route loader was running auth check on every navigation causing
+visible UI flicker. Moved auth check to layout's beforeLoad.
+
+- Auth check in /_authenticated/_layout beforeLoad
+- Prevents unnecessary auth calls on navigation
+- Fixes flicker on protected routes
+
+Fixes GREY-234
+```
+
+## TanStack Query Hook
+```
+feat(queries): add useUser custom hook for user profile
+
+Create reusable custom hook wrapping TanStack Query for user profile
+data fetching with automatic cache management.
+
+- useUser hook with userId parameter
+- Automatic stale time: 60 seconds
+- Optimistic updates with onSuccess
+- Type-safe return values
+
+Related to GREY-456
+```
+
+## TanStack Start Server Function
+```
+feat(server): add createUser server function with validation
+
+Create TanStack Start server function with Zod validation and
+tenant isolation for user creation.
+
+- POST server function with Zod schema
+- Tenant ID from session context
+- Returns User object or throws ValidationError
+- Integration with UserRepository
+
+Fixes GREY-567
+```
+
+## Drizzle Schema Change
+```
+feat(db): add users table with tenant isolation
+
+Create users table following Grey Haven conventions with snake_case
+fields and tenant_id for multi-tenant isolation.
+
+- UUID primary key
+- created_at, updated_at timestamps
+- tenant_id with foreign key
+- email_address unique constraint
+- Index on tenant_id
+
+Related to GREY-890
+```
+
+## Dependency Update
+```
+chore(deps): upgrade TanStack Query to v5.62.0
+
+- Fixes type inference issues with useQuery
+- Improves DevTools performance
+- No breaking changes in our usage
+```
+
+## Refactoring
+```
+refactor(queries): extract query keys to constants
+
+Move all TanStack Query keys to centralized queryKeys object for
+consistency and type safety.
+
+- queryKeys.ts with all key factories
+- Type-safe key generation
+- Easier cache invalidation
+- Reduces typo errors
+```
--- a/skills/commit-format/templates/simple-commit.txt
+++ b/skills/commit-format/templates/simple-commit.txt
@@ -0,0 +1,10 @@
+# Simple Commit Template
+# Copy and customize for simple commits
+
+type(scope): subject line here
+
+# Examples:
+# feat(auth): add password reset flow
+# fix(api): resolve duplicate email validation
+# docs: update installation guide
+# chore(deps): upgrade React to v19.1.0
--- a/skills/commit-format/templates/with-body.txt
+++ b/skills/commit-format/templates/with-body.txt
@@ -0,0 +1,12 @@
+# Commit with Body Template
+# Copy and customize for commits needing explanation
+
+type(scope): subject line here
+
+Explain why this change was made and any important context.
+
+- Key point 1
+- Key point 2
+- Key point 3
+
+Fixes GREY-123