commit 742559fa58134ed6bdb3f223dad1e615064958a5 Author: Zhongwei Li Date: Sat Nov 29 18:29:20 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..08eca05 --- /dev/null +++ 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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8118be3 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# linear + +Linear issue tracking integration with commands for debugging, testing, planning, and workflow management diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b2ee19b --- /dev/null +++ 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": [] + } +} \ No newline at end of file diff --git a/skills/commit-format/SKILL.md b/skills/commit-format/SKILL.md new file mode 100644 index 0000000..0ab8958 --- /dev/null +++ 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 + +``` +(): + +[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** diff --git a/skills/commit-format/checklists/commit-checklist.md b/skills/commit-format/checklists/commit-checklist.md new file mode 100644 index 0000000..ab48a5e --- /dev/null +++ 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 diff --git a/skills/commit-format/examples/INDEX.md b/skills/commit-format/examples/INDEX.md new file mode 100644 index 0000000..05cef4d --- /dev/null +++ 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` diff --git a/skills/commit-format/examples/frontend-examples.md b/skills/commit-format/examples/frontend-examples.md new file mode 100644 index 0000000..1606d1e --- /dev/null +++ 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 +``` diff --git a/skills/commit-format/templates/simple-commit.txt b/skills/commit-format/templates/simple-commit.txt new file mode 100644 index 0000000..4364fa7 --- /dev/null +++ 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 diff --git a/skills/commit-format/templates/with-body.txt b/skills/commit-format/templates/with-body.txt new file mode 100644 index 0000000..9405e87 --- /dev/null +++ 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 diff --git a/skills/linear-workflow/SKILL.md b/skills/linear-workflow/SKILL.md new file mode 100644 index 0000000..65f564d --- /dev/null +++ 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**: `--` + +```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 + +``` +(): + +[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: +``` +(): [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--` +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 diff --git a/skills/linear-workflow/checklists/issue-creation-checklist.md b/skills/linear-workflow/checklists/issue-creation-checklist.md new file mode 100644 index 0000000..aa4b8ea --- /dev/null +++ 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) diff --git a/skills/linear-workflow/checklists/pr-checklist.md b/skills/linear-workflow/checklists/pr-checklist.md new file mode 100644 index 0000000..59aa1b5 --- /dev/null +++ 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: `(): [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 diff --git a/skills/linear-workflow/examples/INDEX.md b/skills/linear-workflow/examples/INDEX.md new file mode 100644 index 0000000..32f721a --- /dev/null +++ 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) diff --git a/skills/linear-workflow/reference/INDEX.md b/skills/linear-workflow/reference/INDEX.md new file mode 100644 index 0000000..59ee844 --- /dev/null +++ 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)