<h1>Linear Integration Guide</h1><p>Spades provides seamless integration with Linear, enabling teams to estimate story points directly within their existing project management workflow. This guide covers all aspects of the Linear integration.</p><h2>Overview</h2><h3>What the Integration Provides:</h3><ul class="accent-bullets"><li><p><strong>Direct Issue Import</strong>: Automatically fetch unestimated issues from Linear</p></li><li><p><strong>Real-time Synchronization</strong>: Instant updates between Spades and Linear</p></li><li><p><strong>One-click Estimate Setting</strong>: Set story point estimates directly in Linear</p></li><li><p><strong>Complete Issue Context</strong>: View descriptions, comments, and metadata</p></li><li><p><strong>Flexible Filtering</strong>: Use Linear's teams, views, and projects for targeted estimation</p></li></ul><h3>Requirements:</h3><ul class="accent-bullets"><li><p>Active Linear workspace account</p></li><li><p>Permission to view and edit issues in your Linear teams</p></li><li><p>Spades account connected to Linear via OAuth</p></li></ul><hr><h2>Authentication &amp; Setup</h2><h3>Initial Connection</h3><h4><strong>Step 1: OAuth Authorization</strong></h4><ol class="steps-list"><li><p>Click "Get Started" or the play icon in the top right</p></li><li><p>Review permissions requested by Spades:</p><ul class="accent-bullets"><li><p>Read access to issues, teams, and projects</p></li><li><p>Write access to update issue estimates</p></li><li><p>Access to your workspace and user information</p></li></ul></li><li><p>Click "Authorize" to grant access</p></li></ol><h4><strong>Step 2: Token Management</strong></h4><ul class="accent-bullets"><li><p><strong>Secure Storage</strong>: Access tokens are encrypted and stored securely</p></li><li><p><strong>Automatic Renewal</strong>: Tokens are automatically refreshed as needed</p></li><li><p><strong>Scope Validation</strong>: Permissions are validated for each operation</p></li></ul><h4><strong>Step 3: Workspace Verification</strong></h4><ul class="accent-bullets"><li><p><strong>Team Access</strong>: Spades verifies access to your Linear teams</p></li><li><p><strong>Issue Permissions</strong>: Confirms ability to read and update issues</p></li><li><p><strong>Workspace Sync</strong>: Initial synchronization of team and project data</p></li></ul><h3>Re-authentication</h3><p>If you encounter authentication errors:</p><ol class="steps-list"><li><p><strong>Clear Session</strong>: Close browser and clear cache if needed</p></li><li><p><strong>Re-authorize</strong>: Login again with Linear to refresh permissions</p></li><li><p><strong>Verify Access</strong>: Confirm all teams and projects are accessible</p></li></ol><hr><h2>Issue Import &amp; Management</h2><h3>Automatic Issue Filtering</h3><p>Spades automatically filters for issues that need estimation:</p><h4><strong>Criteria for Import:</strong></h4><ul class="accent-bullets"><li><p><strong>No Existing Estimate</strong>: Issues without story point values</p></li><li><p><strong>Active State</strong>: Not archived or completed</p></li><li><p><strong>Team Access</strong>: Only issues from teams you have access to</p></li></ul><h4><strong>Excluded Issues:</strong></h4><ul class="accent-bullets"><li><p>Issues already estimated (have story point values)</p></li><li><p>Archived or completed issues</p></li><li><p>Issues in teams without estimation enabled</p></li><li><p>Private issues you don't have access to</p></li></ul><h3>Issue Data Synchronization</h3><h4><strong>What Gets Synced:</strong></h4><ul class="accent-bullets"><li><p><strong>Basic Metadata</strong>: Title, description</p></li><li><p><strong>Team Information</strong>: Assigned team, project association</p></li><li><p><strong>Comments</strong>: Linear comments with author and timestamp</p></li><li><p><strong>Assignees</strong>: Current assignee information</p></li></ul><h4><strong>Real-time Updates:</strong></h4><ul class="accent-bullets"><li><p><strong>Bidirectional Sync</strong>: Changes in Linear appear immediately in Spades</p></li><li><p><strong>Live Comments</strong>: New comments sync in real-time during estimation sessions</p></li></ul><hr><h2>Team, View, and Project Selection</h2><h3>Linear Teams Integration</h3><h4><strong>Saved Views Access:</strong></h4><ul class="accent-bullets"><li><p><strong>Personal Views</strong>: Your private saved Linear views</p></li><li><p><strong>Shared Views</strong>: Team and organization shared views</p></li><li><p><strong>Custom Filters</strong>: Complex filtering criteria from Linear</p></li><li><p><strong>Dynamic Results</strong>: Views update as underlying data changes</p></li></ul><h4><strong>View Types Supported:</strong></h4><ul class="accent-bullets"><li><p><strong>Project Views</strong>: Project-scoped issue views</p></li><li><p><strong>Team Views</strong>: Team-specific filtered views</p></li><li><p><strong>Custom Views</strong>: Views with custom field filters</p></li></ul><h4><strong>Advanced View Features:</strong></h4><ul class="accent-bullets"><li><p><strong>Filter Preservation</strong>: Maintains all Linear filter criteria</p></li><li><p><strong>Sorting Respect</strong>: Uses view's specified sorting</p></li><li><p><strong>Pagination Support</strong>: Handles large view results efficiently</p></li><li><p><strong>Real-time Updates</strong>: View results update as issues change</p></li></ul><h3>Linear Projects Integration</h3><h4><strong>Project-based Estimation:</strong></h4><ul class="accent-bullets"><li><p><strong>Project Scope</strong>: Estimate issues within specific projects</p></li><li><p><strong>Project Metadata</strong>: Access project descriptions and goals</p></li></ul><hr><h2>Estimate Setting Workflow</h2><h3>Fibonacci Compliance</h3><h4><strong>Automatic Rounding:</strong></h4><ul class="accent-bullets"><li><p><strong>Smart Rounding</strong>: Calculated results rounded to nearest Fibonacci value</p></li><li><p><strong>Standard Scale</strong>: Uses 1, 2, 3, 5, 8 sequence</p></li></ul><h4><strong>Supported Scales:</strong></h4><ul class="accent-bullets"><li><p><strong>Standard Fibonacci</strong>: 1, 2, 3, 5, 8</p></li></ul><hr><h2>Advanced Integration Features</h2><h3>Real-time Collaboration</h3><h4><strong>Multi-user Sessions:</strong></h4><ul class="accent-bullets"><li><p><strong>Shared State</strong>: All participants see the same issue data</p></li><li><p><strong>Live Navigation</strong>: Host's navigation synced to all participants</p></li><li><p><strong>Concurrent Voting</strong>: Multiple team members vote simultaneously</p></li><li><p><strong>Result Sharing</strong>: Calculated results visible to all participants</p></li></ul><h4><strong>Synchronization Features:</strong></h4><ul class="accent-bullets"><li><p><strong>Issue Updates</strong>: Live sync of issue changes from Linear</p></li><li><p><strong>Comment Streaming</strong>: New comments appear in real-time</p></li></ul><h3>Comment Integration</h3><h4><strong>Linear Comments in Spades:</strong></h4><ul class="accent-bullets"><li><p><strong>Complete History</strong>: All Linear comments displayed chronologically</p></li><li><p><strong>Rich Formatting</strong>: Markdown rendering for comment content</p></li><li><p><strong>Author Information</strong>: Comment author names and avatars</p></li></ul><h4><strong>Adding Comments from Spades:</strong></h4><ul class="accent-bullets"><li><p><strong>Estimation Context</strong>: Add comments about estimation decisions</p></li><li><p><strong>Technical Notes</strong>: Capture technical discussion points</p></li><li><p><strong>Assumption Documentation</strong>: Record assumptions made during estimation</p></li><li><p><strong>Decision Rationale</strong>: Explain reasoning behind final estimates</p></li></ul><hr><h2>Security &amp; Privacy</h2><h3>Data Protection</h3><h4><strong>Token Security:</strong></h4><ul class="accent-bullets"><li><p><strong>Encryption</strong>: All Linear tokens encrypted at rest</p></li><li><p><strong>Transmission</strong>: HTTPS for all API communications</p></li><li><p><strong>Scope Limitation</strong>: Minimum necessary permissions requested</p></li><li><p><strong>Regular Rotation</strong>: Automatic token refresh when possible</p></li></ul><h4><strong>Data Privacy:</strong></h4><ul class="accent-bullets"><li><p><strong>No Storage</strong>: Issue data not permanently stored in Spades</p></li><li><p><strong>Real-time Only</strong>: Issue content only held during active sessions</p></li><li><p><strong>Permission Respect</strong>: Only access issues you have Linear permissions for</p></li></ul><h3>Integration Monitoring</h3><h4><strong>Health Checks:</strong></h4><ul class="accent-bullets"><li><p><strong>API Status</strong>: Regular Linear API connectivity verification</p></li><li><p><strong>Permission Validation</strong>: Periodic access permission verification</p></li><li><p><strong>Token Status</strong>: OAuth token validity monitoring</p></li><li><p><strong>Error Rate Tracking</strong>: Integration error rate monitoring and alerting</p></li></ul><p></p>

User Guide

Linear Integration

Full Overview

Quick Start Guide

User Management

Troubleshooting

Next Steps

AI Integration

Voting and Estimation

Voting

Keyboard Shortcuts

Productivity

Summary

Voting Best Practices

Team Best Practices

Best Practices

Docs

Spades