| 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:
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:
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>
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
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:
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
fix(repositories): prevent race condition in user creation
Add database-level unique constraint and proper IntegrityError
handling in UserRepository.
Fixes GREY-456
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
## 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
## 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
