Initial commit

2025-11-29 18:29:20 +08:00
commit 742559fa58
14 changed files with 1131 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "linear",
+  "description": "Linear issue tracking integration with commands for debugging, testing, planning, and workflow management",
+  "version": "1.0.0",
+  "author": {
+    "name": "Grey Haven Studio"
+  },
+  "skills": [
+    "./skills/linear-workflow",
+    "./skills/commit-format"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# linear
+
+Linear issue tracking integration with commands for debugging, testing, planning, and workflow management
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,85 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:greyhaven-ai/claude-code-config:grey-haven-plugins/linear",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "6ef49ddf0c6d0e559a563ab60e537c4bc3d44440",
+    "treeHash": "7b5f96d3404eb0ca6760e4c8dd6e729c4bae03ca985aea023347c4e2f4767b0a",
+    "generatedAt": "2025-11-28T10:17:05.888593Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "linear",
+    "description": "Linear issue tracking integration with commands for debugging, testing, planning, and workflow management",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "9267dee2ba391146f9086aeea53ec35bd49cc5a7d8b1ca0b181ac7dbf81ed7ba"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "d4ad1ebbbec0a0fb8347398994bf0fc64b698c3fe4d02010fce9b8c41fc543ad"
+      },
+      {
+        "path": "skills/commit-format/SKILL.md",
+        "sha256": "088ce061d7a0760cad4e53bb8d20fe10f960df853a416ee256e557876b499ee2"
+      },
+      {
+        "path": "skills/commit-format/checklists/commit-checklist.md",
+        "sha256": "f32a775a305e96228ad137d7b51a23b31c1fbf797490024d276f66bba6f8b702"
+      },
+      {
+        "path": "skills/commit-format/examples/frontend-examples.md",
+        "sha256": "79b561a5ab7099384139f359c6b2c7c81e936beed7ec1870624d73e1ede78235"
+      },
+      {
+        "path": "skills/commit-format/examples/INDEX.md",
+        "sha256": "3975e2af54ece0c24174c4a53f3eae74f30028d2b7bea7df7ee351dc340a5ea0"
+      },
+      {
+        "path": "skills/commit-format/templates/with-body.txt",
+        "sha256": "e5c03b3da707351c199f6291a47346a0ccafc2a288ebf4fa8c76137f10872e6c"
+      },
+      {
+        "path": "skills/commit-format/templates/simple-commit.txt",
+        "sha256": "da5f23ddb88a4a269acf4ee7acf3a63009e6fdd16c02210e8944fdd4b081c78d"
+      },
+      {
+        "path": "skills/linear-workflow/SKILL.md",
+        "sha256": "ef69c1984036e0c289a9e2bc532a82ae03d81e0ca202269573e8834f12ee8c3c"
+      },
+      {
+        "path": "skills/linear-workflow/checklists/issue-creation-checklist.md",
+        "sha256": "905121ba4510dec4d0e85d6f232a6eedeb5bd021fd68224ee574c0c91ab9293b"
+      },
+      {
+        "path": "skills/linear-workflow/checklists/pr-checklist.md",
+        "sha256": "0146375b1d54df84859e8414c7496359bf277d52ddf2dbf6c30cca211768711f"
+      },
+      {
+        "path": "skills/linear-workflow/examples/INDEX.md",
+        "sha256": "d846a47718f7b243257f94eddf39a5391ec6741b734c35d718639d610d39429a"
+      },
+      {
+        "path": "skills/linear-workflow/reference/INDEX.md",
+        "sha256": "c3b09fdee25fa8defca1078873d40eb627deec33e5000cd68322d13563fb9672"
+      }
+    ],
+    "dirSha256": "7b5f96d3404eb0ca6760e4c8dd6e729c4bae03ca985aea023347c4e2f4767b0a"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- 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
--- a/skills/linear-workflow/SKILL.md
+++ b/skills/linear-workflow/SKILL.md
@@ -0,0 +1,349 @@
+---
+name: grey-haven-linear-workflow
+description: Grey Haven's Linear issue workflow - creating well-documented issues, proper branch naming from issue IDs, commit message integration, PR linking, and status management. Use when creating issues, starting work, or managing project workflow.
+---
+
+# Grey Haven Linear Workflow
+
+Follow Grey Haven Studio's workflow for **Linear issue management**, **Git branching**, and **pull request integration**.
+
+## Linear Issue Management
+
+### Issue Creation Guidelines
+
+**Always create Linear issues BEFORE starting work** to track progress and context.
+
+**Issue Title Format**: Specific, actionable statements
+```
+[OK] Good titles:
+- Add magic link authentication
+- Fix race condition in user repository
+- Migrate organizations table to multi-tenant
+
+[X] Bad titles (too vague):
+- Auth improvements
+- Fix bug
+- Update dependencies
+```
+
+### Issue Templates
+
+**Feature Issue Structure**:
+```markdown
+Title: Add magic link authentication
+
+## Description
+[What you're building]
+
+## Motivation
+[Why this is needed - user pain points, business value]
+
+## Acceptance Criteria
+- [ ] Specific, testable criteria
+- [ ] Include multi-tenant isolation requirements
+- [ ] Target >80% test coverage
+
+## Technical Notes
+- Tech stack references (better-auth, TanStack, etc.)
+- Doppler environment variables needed
+- Database schema changes (snake_case fields)
+
+## Related Issues
+- Blocks: GREY-XXX
+- Related: GREY-YYY
+
+Labels: feature, [component], [priority]
+Estimate: X points
+```
+
+**Bug Issue Structure**:
+```markdown
+Title: Fix race condition in user repository
+
+## Description
+[What's broken]
+
+## Steps to Reproduce
+1. [Step-by-step]
+2. [With specific inputs]
+3. [Expected vs actual]
+
+## Impact
+- Frequency: X% of requests
+- User experience impact
+- Data corruption risk
+
+## Proposed Solution
+[How to fix it]
+
+## Environment
+- Backend: cvi-backend-template
+- Database: PostgreSQL with RLS
+- Doppler config: production
+
+Labels: bug, [component], [priority]
+Priority: [critical/high-priority/normal/low-priority]
+```
+
+### Labels
+
+**Type Labels**: `feature`, `bug`, `chore`, `docs`, `refactor`, `performance`
+
+**Component Labels**: `frontend`, `backend`, `database`, `auth`, `multi-tenant`, `testing`
+
+**Priority Labels**: `critical`, `high-priority`, `low-priority`
+
+### Story Point Estimates
+
+Use Fibonacci sequence:
+- **1 point**: < 1 hour (config change, simple fix)
+- **2 points**: 1-2 hours (small feature, simple bug)
+- **3 points**: Half day (moderate feature)
+- **5 points**: 1 day (complex feature, migration)
+- **8 points**: 2-3 days (large feature, major refactor)
+- **13 points**: 1 week (should be broken down into smaller issues)
+
+## Git Branching Strategy
+
+### Branch Naming Convention
+
+**Format**: `<issue-id>-<type>-<short-description>`
+
+```bash
+# Examples
+GREY-234-feat-magic-link-auth
+GREY-456-fix-user-race-condition
+GREY-890-migrate-add-tenant-id
+GREY-123-chore-update-dependencies
+GREY-789-docs-update-api-guide
+```
+
+### Creating Branches from Linear Issues
+
+```bash
+# Always branch from latest main!
+git checkout main
+git pull origin main
+git checkout -b GREY-234-feat-magic-link-auth
+```
+
+### Branch Protection Rules
+
+Main branch protection:
+- ✅ Require pull request before merging
+- ✅ Require 1 approval
+- ✅ Require status checks to pass
+- ✅ Require branches to be up to date
+- ✅ Require linear history (squash merges)
+- ❌ Do NOT allow force pushes
+- ❌ Do NOT allow deletions
+
+## Commit Message Integration
+
+### Format with Linear
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[Linear issue reference]
+```
+
+**Examples**:
+
+```bash
+# Feature commit
+feat(auth): add magic link authentication
+
+Implement magic link provider using better-auth with email
+verification via Resend.
+
+- Single-use tokens with 15 minute expiry
+- Tenant isolation via RLS policies
+- Server functions for sending/verifying links
+
+Closes GREY-234
+
+# Bug fix commit
+fix(repositories): prevent race condition in user creation
+
+Add database-level unique constraint and proper IntegrityError
+handling in UserRepository.
+
+Fixes GREY-456
+
+# Migration commit
+feat(db): add tenant_id to organizations table
+
+Add tenant_id column and RLS policies for multi-tenant isolation.
+Backfill from service_id column.
+
+Related to GREY-890
+```
+
+### Linear Keywords
+
+Use these keywords to automatically update Linear issues:
+
+- **Closes GREY-123**: Marks issue as Done when PR merges
+- **Fixes GREY-123**: Same as Closes (for bugs)
+- **Related to GREY-123**: Links issue without closing
+- **Blocks GREY-123**: Indicates dependency
+- **Blocked by GREY-123**: Indicates blocker
+
+## Pull Request Integration
+
+### PR Title Format
+
+Include Linear ID at the end:
+```
+<type>(<scope>): <description> [GREY-123]
+```
+
+**Examples**:
+```
+feat(auth): add magic link authentication [GREY-234]
+fix(repositories): prevent race condition in user creation [GREY-456]
+feat(db): add tenant_id to organizations table [GREY-890]
+```
+
+### PR Description Template
+
+```markdown
+## Summary
+[2-4 sentence description]. Closes GREY-XXX.
+
+## Linear Issue
+https://linear.app/grey-haven/issue/GREY-XXX/issue-title
+
+## Motivation
+[Why these changes are needed]
+
+## Implementation Details
+
+### Key Changes
+- **Component**: [what changed]
+- **Database**: [schema changes with snake_case]
+- **Tests**: [test coverage with markers]
+
+### Multi-Tenant Considerations
+- tenant_id added to [tables]
+- RLS policies created
+- Queries filter by tenant_id
+
+### Doppler Configuration
+- Added/updated: [environment variables]
+- Required in: [dev/test/staging/production]
+
+## Testing
+
+### Automated Tests
+- [OK] Unit tests: [coverage %]
+- [OK] Integration tests: [coverage %]
+- [OK] E2E tests: [coverage %]
+- [OK] Total coverage: >80%
+
+### Manual Testing
+Run with Doppler:
+```bash
+doppler run --config dev -- bun run dev
+doppler run --config test -- bun test
+```
+
+## Checklist
+- [ ] Code follows Grey Haven style (90 char TS, 130 char Python)
+- [ ] Tests added/updated (>80% coverage)
+- [ ] Multi-tenant isolation verified
+- [ ] Doppler env vars documented
+- [ ] Pre-commit hooks passing
+- [ ] Database migrations tested (if applicable)
+- [ ] Linear issue linked
+```
+
+## Linear Status Management
+
+### Issue Lifecycle
+
+```
+Backlog → Todo → In Progress → In Review → Done
+   ↓                                ↓
+Canceled                        Canceled
+```
+
+### Status Transitions
+
+**Todo → In Progress**:
+1. Create branch: `GREY-234-feat-magic-link-auth`
+2. Linear automatically moves to "In Progress"
+3. Start coding
+
+**In Progress → In Review**:
+1. Push commits to branch
+2. Create PR with "Closes GREY-234" in description
+3. Linear automatically moves to "In Review"
+4. Request review from team
+
+**In Review → Done**:
+1. Squash and merge PR to main
+2. Linear automatically closes issue (via "Closes GREY-234")
+3. Delete feature branch
+
+## Supporting Documentation
+
+All supporting files are under 500 lines per Anthropic best practices:
+
+- **[examples/](examples/)** - Complete workflow examples
+  - [feature-issue-template.md](examples/feature-issue-template.md) - Feature issue template
+  - [bug-issue-template.md](examples/bug-issue-template.md) - Bug issue template
+  - [migration-issue-template.md](examples/migration-issue-template.md) - Migration template
+  - [commit-message-examples.md](examples/commit-message-examples.md) - Commit message examples
+  - [pr-description-examples.md](examples/pr-description-examples.md) - PR description examples
+  - [INDEX.md](examples/INDEX.md) - Examples navigation
+
+- **[reference/](reference/)** - Workflow references
+  - [labels.md](reference/labels.md) - Label definitions and usage
+  - [status-transitions.md](reference/status-transitions.md) - Status lifecycle details
+  - [branch-protection.md](reference/branch-protection.md) - Branch protection rules
+  - [linear-keywords.md](reference/linear-keywords.md) - Automatic issue updates
+  - [INDEX.md](reference/INDEX.md) - Reference navigation
+
+- **[templates/](templates/)** - Copy-paste ready templates
+  - [feature-issue.md](templates/feature-issue.md) - Feature issue template
+  - [bug-issue.md](templates/bug-issue.md) - Bug issue template
+  - [pr-description.md](templates/pr-description.md) - PR description template
+
+- **[checklists/](checklists/)** - Workflow checklists
+  - [issue-creation-checklist.md](checklists/issue-creation-checklist.md) - Pre-issue checklist
+  - [pr-checklist.md](checklists/pr-checklist.md) - Pre-PR checklist
+
+## When to Apply This Skill
+
+Use this skill when:
+- Creating new Linear issues
+- Starting work on a feature or bug
+- Creating Git branches
+- Writing commit messages
+- Opening pull requests
+- Managing issue status transitions
+- Setting up Linear workflows for new team members
+
+## Template Reference
+
+These patterns are from Grey Haven's production workflows:
+- **Linear workspace**: grey-haven team configuration
+- **GitHub integration**: Automatic status updates
+- **Branch naming**: Issue ID prefixed branches
+
+## Critical Reminders
+
+1. **Create issues BEFORE work**: Track all work in Linear
+2. **Branch from main**: Always `git checkout main && git pull`
+3. **Branch naming**: `GREY-XXX-<type>-<description>`
+4. **Commit keywords**: Use "Closes", "Fixes", "Related to"
+5. **PR title format**: Include `[GREY-XXX]` at the end
+6. **Multi-tenant**: Document tenant isolation in PRs
+7. **Doppler**: Document env vars in issue/PR
+8. **Test coverage**: Maintain >80% coverage
+9. **Linear automation**: Keywords auto-update issue status
+10. **Squash merges**: Keep main branch history clean
--- a/skills/linear-workflow/checklists/issue-creation-checklist.md
+++ b/skills/linear-workflow/checklists/issue-creation-checklist.md
@@ -0,0 +1,82 @@
+# Issue Creation Checklist
+
+**Use before creating Linear issues.**
+
+## Issue Content
+
+### Title
+- [ ] Title is specific and actionable
+- [ ] Title starts with verb (Add, Fix, Update, etc.)
+- [ ] Title describes user-facing change or technical goal
+- [ ] Title is under 100 characters
+
+### Description
+- [ ] Description clearly explains what needs to be done
+- [ ] Description includes "why" (motivation/user pain point)
+- [ ] For bugs: steps to reproduce included
+- [ ] For features: user story or use case included
+- [ ] Technical implementation notes included (optional)
+
+### Acceptance Criteria
+- [ ] Acceptance criteria are specific and testable
+- [ ] Each criterion starts with "User can..." or "System..."
+- [ ] Multi-tenant isolation requirements specified
+- [ ] Test coverage target specified (>80%)
+- [ ] Performance requirements specified (if applicable)
+
+### Technical Details
+
+#### Multi-Tenant Considerations
+- [ ] tenant_id requirements documented
+- [ ] RLS policy requirements documented
+- [ ] Tenant isolation testing specified
+
+#### Database Changes (if applicable)
+- [ ] Schema changes use snake_case field names
+- [ ] Migration strategy documented
+- [ ] Rollback plan documented
+- [ ] Index requirements specified
+
+#### Doppler Configuration
+- [ ] Required environment variables listed
+- [ ] Doppler environments specified (dev/test/staging/production)
+- [ ] Secret rotation strategy noted (if applicable)
+
+### Labels
+- [ ] Type label assigned (feature/bug/chore/docs/refactor)
+- [ ] Component label assigned (frontend/backend/database/auth)
+- [ ] Priority label assigned (critical/high-priority/low-priority)
+- [ ] Additional relevant labels added
+
+### Estimate
+- [ ] Story points assigned using Fibonacci sequence
+- [ ] Estimate reflects complexity + uncertainty
+- [ ] Issues >8 points broken into smaller issues
+- [ ] Estimate discussed with team (if unclear)
+
+### Relationships
+- [ ] Related issues linked (Blocks/Blocked by)
+- [ ] Parent epic linked (if part of larger feature)
+- [ ] Dependencies documented
+
+## Before Submitting
+
+### Quality Check
+- [ ] Title and description are clear to someone unfamiliar with context
+- [ ] Technical jargon explained or avoided
+- [ ] Links to relevant documentation included
+- [ ] Screenshots/mockups attached (if applicable)
+
+### Team Alignment
+- [ ] Issue aligns with current sprint goals
+- [ ] Issue priority discussed with team lead (if high-priority)
+- [ ] Issue dependencies communicated to affected team members
+- [ ] Issue assigned to appropriate team member (or left unassigned for triage)
+
+## Post-Creation
+
+### Issue Management
+- [ ] Issue added to appropriate project/milestone
+- [ ] Issue added to current cycle (if starting immediately)
+- [ ] Issue status set correctly (Backlog/Todo)
+- [ ] Team notified of new issue (if urgent)
--- a/skills/linear-workflow/checklists/pr-checklist.md
+++ b/skills/linear-workflow/checklists/pr-checklist.md
@@ -0,0 +1,120 @@
+# Pull Request Checklist
+
+**Use before opening pull requests.**
+
+## Before Opening PR
+
+### Code Quality
+- [ ] Code follows Grey Haven style guide (90 char TS, 130 char Python)
+- [ ] No commented-out code
+- [ ] No console.log or print statements (use structured logging)
+- [ ] No TODO comments (create Linear issues instead)
+- [ ] All imports organized and unused imports removed
+- [ ] Pre-commit hooks passing
+
+### Testing
+- [ ] Unit tests added for new functions/components
+- [ ] Integration tests added for new features
+- [ ] E2E tests added for critical user flows
+- [ ] All tests passing locally with Doppler: `doppler run --config test -- bun test`
+- [ ] Test coverage >80% (verify with coverage report)
+- [ ] Tests use appropriate markers (@pytest.mark.unit, Vitest describe blocks)
+
+### Multi-Tenant Compliance
+- [ ] All new tables include tenant_id column (NOT NULL, indexed)
+- [ ] All queries filter by tenant_id
+- [ ] RLS policies created for new tables
+- [ ] Tenant isolation tested with different tenant contexts
+- [ ] No cross-tenant data leakage possible
+
+### Database Changes (if applicable)
+- [ ] Migration generated (Drizzle Kit or Alembic)
+- [ ] Migration tested up (apply)
+- [ ] Migration tested down (rollback)
+- [ ] Schema uses snake_case field names (NOT camelCase)
+- [ ] Indexes created for foreign keys and tenant_id
+- [ ] Migration reviewed by teammate
+
+### Doppler Configuration
+- [ ] New environment variables added to Doppler
+- [ ] Environment variables documented in PR description
+- [ ] Environment variables added to all environments (dev/test/staging/production)
+- [ ] No secrets committed to git
+- [ ] .env.example updated (if applicable)
+
+### Git & Linear
+- [ ] Branch follows naming convention: GREY-XXX-type-description
+- [ ] Commits follow conventional commits format
+- [ ] Linear issue ID in commits (Closes GREY-XXX / Fixes GREY-XXX)
+- [ ] Branch up to date with main: `git pull origin main`
+
+## PR Content
+
+### Title
+- [ ] PR title follows format: `<type>(<scope>): <description> [GREY-XXX]`
+- [ ] PR title matches issue title (or explains deviation)
+- [ ] PR title is under 100 characters
+
+### Description
+- [ ] Summary section explains changes (2-4 sentences)
+- [ ] "Closes GREY-XXX" keyword included
+- [ ] Linear issue URL included
+- [ ] Motivation section explains "why"
+- [ ] Implementation details section covers key changes
+
+### Implementation Details
+- [ ] Key changes documented by component
+- [ ] Database changes listed (if applicable)
+- [ ] Multi-tenant considerations documented
+- [ ] Doppler configuration changes documented
+- [ ] Breaking changes called out (if applicable)
+
+### Testing Section
+- [ ] Automated test results documented
+- [ ] Test coverage percentage included
+- [ ] Manual testing steps included (if applicable)
+- [ ] Doppler test command included
+- [ ] Screenshots/recordings attached (if UI changes)
+
+### Checklist
+- [ ] All PR description checklist items checked
+- [ ] Reviewers assigned
+- [ ] Labels synced from Linear issue
+
+## After Opening PR
+
+### CI/CD
+- [ ] GitHub Actions passing (tests, linting)
+- [ ] No merge conflicts with main
+- [ ] Branch protection checks passing
+- [ ] Deployment preview working (if applicable)
+
+### Review Process
+- [ ] At least 1 reviewer assigned
+- [ ] Responded to review comments within 24 hours
+- [ ] All requested changes addressed
+- [ ] Re-requested review after changes
+- [ ] Approved by required reviewers
+
+### Before Merging
+- [ ] All conversations resolved
+- [ ] CI/CD passing
+- [ ] Branch up to date with main
+- [ ] Squash merge selected (for clean history)
+- [ ] Linear issue will auto-close (verified "Closes GREY-XXX" in description)
+
+## After Merging
+
+### Post-Merge
+- [ ] Feature branch deleted
+- [ ] Linear issue automatically closed (verify)
+- [ ] Deployment to staging successful (if applicable)
+- [ ] Smoke tests passing in staging
+- [ ] Team notified of significant changes
+
+### Deployment
+- [ ] Production deployment successful
+- [ ] Smoke tests passing in production
+- [ ] Monitoring shows no errors (Sentry, Axiom)
+- [ ] Performance metrics acceptable
+- [ ] Linear issue updated with deployment notes
--- a/skills/linear-workflow/examples/INDEX.md
+++ b/skills/linear-workflow/examples/INDEX.md
@@ -0,0 +1,47 @@
+# Linear Workflow Examples
+
+Complete examples for Grey Haven's Linear workflow, Git branching, and PR integration.
+
+## Available Examples
+
+### [feature-issue-template.md](feature-issue-template.md)
+Complete feature issue template with examples.
+- Description and motivation
+- Acceptance criteria
+- Technical notes and Doppler setup
+- Multi-tenant considerations
+
+### [bug-issue-template.md](bug-issue-template.md)
+Complete bug issue template with examples.
+- Steps to reproduce
+- Impact assessment
+- Proposed solution
+- Environment details
+
+### [migration-issue-template.md](migration-issue-template.md)
+Database migration issue template.
+- Migration steps
+- Rollback plan
+- Testing strategy
+- Risk assessment
+
+### [commit-message-examples.md](commit-message-examples.md)
+Commit message examples with Linear integration.
+- Feature commits with "Closes"
+- Bug fix commits with "Fixes"
+- Migration commits with "Related to"
+- Multi-commit workflows
+
+### [pr-description-examples.md](pr-description-examples.md)
+Pull request description examples.
+- Feature PR with full testing details
+- Bug fix PR with reproduction steps
+- Migration PR with rollback plan
+- Doppler configuration documentation
+
+## Quick Reference
+
+**Need issue template?** → [feature-issue-template.md](feature-issue-template.md), [bug-issue-template.md](bug-issue-template.md)
+**Need commit examples?** → [commit-message-examples.md](commit-message-examples.md)
+**Need PR template?** → [pr-description-examples.md](pr-description-examples.md)
+**Need migration template?** → [migration-issue-template.md](migration-issue-template.md)
--- a/skills/linear-workflow/reference/INDEX.md
+++ b/skills/linear-workflow/reference/INDEX.md
@@ -0,0 +1,40 @@
+# Linear Workflow Reference
+
+Configuration and workflow references for Linear issue management and Git integration.
+
+## Available References
+
+### [labels.md](labels.md)
+Label definitions and usage guidelines.
+- Type labels (feature, bug, chore, etc.)
+- Component labels (frontend, backend, database, etc.)
+- Priority labels (critical, high-priority, low-priority)
+- Label combinations and best practices
+
+### [status-transitions.md](status-transitions.md)
+Linear issue status lifecycle details.
+- Status flow (Backlog → Todo → In Progress → In Review → Done)
+- Automatic transitions via GitHub integration
+- Manual status updates
+- Status change best practices
+
+### [branch-protection.md](branch-protection.md)
+GitHub branch protection rules.
+- Main branch protection settings
+- Required status checks
+- Review requirements
+- Merge strategies (squash merges)
+
+### [linear-keywords.md](linear-keywords.md)
+Keywords for automatic issue updates.
+- Closes/Fixes keywords
+- Related to keywords
+- Blocks/Blocked by keywords
+- Keyword placement in commits/PRs
+
+## Quick Reference
+
+**Need labels?** → [labels.md](labels.md)
+**Need status flow?** → [status-transitions.md](status-transitions.md)
+**Need branch rules?** → [branch-protection.md](branch-protection.md)
+**Need keywords?** → [linear-keywords.md](linear-keywords.md)