From 4cf97d2da068842d2464ebe15dd52438e3843abd Mon Sep 17 00:00:00 2001
From: Roo Code <roomote@roocode.com>
Date: Thu, 22 Jan 2026 02:15:20 +0000
Subject: [PATCH] docs: add Linear integration documentation and demo video
 plan

- Add comprehensive Linear integration documentation with corrected information
- Create demo video plan based on Slack integration example
- Add Linear integration to sidebar navigation
- Correct mention format (@Roo Code or @roocode, not @roo-code)
- Clarify that settings are in Organization Settings (not configurable triggers)
- Document account linking requirement for first-time users

Fixes ROO-573
---
 .../linear-integration-demo-plan.md           | 259 ++++++++++++++++++
 docs/roo-code-cloud/linear-integration.mdx    | 164 +++++++++++
 sidebars.ts                                   |   1 +
 3 files changed, 424 insertions(+)
 create mode 100644 docs/roo-code-cloud/linear-integration-demo-plan.md
 create mode 100644 docs/roo-code-cloud/linear-integration.mdx

diff --git a/docs/roo-code-cloud/linear-integration-demo-plan.md b/docs/roo-code-cloud/linear-integration-demo-plan.md
new file mode 100644
index 00000000..d30ba020
--- /dev/null
+++ b/docs/roo-code-cloud/linear-integration-demo-plan.md
@@ -0,0 +1,259 @@
+# Linear Integration Demo Video Plan
+
+## Overview
+Create a demonstration video showing how Roo Code Cloud integrates with Linear for seamless issue-to-code workflow automation.
+
+**Target Duration:** 3-5 minutes  
+**Audience:** Development teams using Linear for issue tracking  
+**Goal:** Show how teams can delegate development work directly from Linear issues to Roo Code agents
+
+---
+
+## Key Corrections from Original Instructions
+
+Based on code review, the following corrections have been made to the documentation:
+
+1. **Settings Location:** Integration is configured in **Organization Settings**, not project settings or configurable triggers
+2. **Mention Format:** The agent is mentioned as `@Roo Code` or `@roocode` (not `@roo-code`)
+3. **Trigger Configuration:** Triggers are **not configurable** - the integration works via:
+   - Assigning issues to the "Roo Code" user
+   - Mentioning `@Roo Code` in issue comments
+4. **Account Linking:** First-time users must link their Linear account to their Roo Code account (one-time authentication flow)
+
+---
+
+## Demo Outline
+
+### 1. Introduction (30 seconds)
+**Script:**
+> "Integrate your Linear workflow with Roo Code Cloud to automate development tasks directly from your issue tracker. Let's see how it works."
+
+**Show:**
+- Quick visual of Linear + Roo Code logos
+- Text overlay: "Turn Linear Issues into Pull Requests Automatically"
+
+---
+
+### 2. Setup & Configuration (45 seconds)
+
+**Script:**
+> "Setting up is simple. Navigate to Organization Settings in Roo Code Cloud, go to Integrations, and click Connect next to Linear. You'll authorize via OAuth - no API keys needed."
+
+**Show:**
+1. Roo Code Cloud dashboard
+2. Click user menu → Organization Settings
+3. Navigate to Integrations tab
+4. Click "Connect" button next to Linear
+5. OAuth authorization screen
+6. Success message
+
+**Key Points:**
+- Organization-level integration
+- OAuth authentication (secure, no manual keys)
+- Requires Team plan
+
+---
+
+### 3. First-Time Account Linking (30 seconds)
+
+**Script:**
+> "The first time you interact with the Roo Code agent in Linear, you'll link your accounts. This one-time step ensures your work is properly tracked."
+
+**Show:**
+1. Create a Linear issue
+2. Assign to "Roo Code" user
+3. Authentication prompt appears in Linear
+4. Click authentication link
+5. Quick login/confirmation flow
+6. Success message in Linear
+
+---
+
+### 4. Assigning Work to Roo Code (60 seconds)
+
+**Script:**
+> "Now let's delegate some work. I'll create an issue for adding a dark mode toggle, with clear acceptance criteria. Then I'll assign it to Roo Code just like any other team member."
+
+**Show:**
+1. **Create Linear Issue:**
+   - Title: "Add dark mode toggle to settings page"
+   - Description with acceptance criteria:
+     ```
+     Add a dark mode toggle to the user settings page.
+     
+     Requirements:
+     - Toggle should persist user preference
+     - Theme should apply across the entire app
+     - Include support for system theme detection
+     ```
+   - Assign to "Roo Code"
+
+2. **Agent Response:**
+   - "Getting started..." comment appears
+   - "Analyzing codebase..." update
+   - "Creating implementation plan..." with checklist
+   - "Opening PR..." with link
+
+**Key Points:**
+- Clear issue descriptions get better results
+- Real-time progress updates
+- Agent acts like a team member
+
+---
+
+### 5. Mentioning the Agent (45 seconds)
+
+**Script:**
+> "You can also interact with Roo Code by mentioning it in comments. Let's add a requirement."
+
+**Show:**
+1. Add comment to the issue:
+   ```
+   @Roo Code Please also add a keyboard shortcut (Cmd+Shift+D) to toggle dark mode
+   ```
+2. Agent acknowledges: "I'll add keyboard shortcut support..."
+3. Updated PR link appears
+
+**Key Points:**
+- Use `@Roo Code` or `@roocode` for mentions
+- Agent maintains context from previous work
+- Can provide feedback at any stage
+
+---
+
+### 6. Reviewing the Pull Request (30 seconds)
+
+**Script:**
+> "The agent creates a PR and automatically links it to the Linear issue using the issue identifier in the branch name. Now you can review, test, and merge through your normal GitHub workflow."
+
+**Show:**
+1. Click PR link from Linear issue
+2. Show GitHub PR with:
+   - Branch name includes issue ID (e.g., `ROO-123/add-dark-mode-toggle`)
+   - Code changes
+   - Tests included
+   - Linked back to Linear issue
+3. Show Linear issue updates automatically when PR is merged
+
+---
+
+### 7. Getting Recommendations (30 seconds)
+
+**Script:**
+> "Not ready to implement yet? Ask for consultation first."
+
+**Show:**
+1. Create new issue: "Improve authentication middleware performance"
+2. Add comment:
+   ```
+   @Roo Code What's the best approach to improve our auth middleware performance? Consider our current architecture.
+   ```
+3. Agent responds with analysis and recommendations (no code changes)
+
+**Key Points:**
+- Use agent as a consultant before committing to implementation
+- Agent analyzes your codebase for context-aware recommendations
+
+---
+
+### 8. Stopping Work (15 seconds)
+
+**Script:**
+> "Need to halt work? Use the stop signal from Linear's agent session UI."
+
+**Show:**
+1. Active agent session in Linear
+2. Click stop button
+3. Agent confirms: "Work has been stopped as requested."
+
+---
+
+### 9. Key Benefits Summary (30 seconds)
+
+**Script:**
+> "With the Linear integration, you get native issue-to-code automation, full visibility into agent work, automatic PR linking, and seamless team collaboration - all without leaving Linear."
+
+**Show:**
+- Split screen showing Linear and GitHub
+- Text overlays with key benefits:
+  - ✓ Work where you plan
+  - ✓ Full progress visibility
+  - ✓ Automatic PR linking
+  - ✓ Team collaboration built-in
+  - ✓ Requires Team plan
+
+**End Screen:**
+- "Try Roo Code Cloud with Linear"
+- Link: app.roocode.com
+- Call to action: "Start with Team Plan"
+
+---
+
+## Recording Notes
+
+### Environment Setup
+- Clean Linear workspace with sample project
+- Connected GitHub repository with simple codebase
+- Roo Code Cloud account with Team plan
+- Prepare issues in advance but show creation process
+
+### Technical Requirements
+- Screen recording software (Loom, OBS, or similar)
+- Clear audio (voiceover or narration)
+- 1920x1080 or higher resolution
+- Smooth cursor movements
+- Fast-forward waiting periods (agent processing, PR creation)
+
+### Production Tips
+1. **Pre-create the Linear project** with appropriate naming
+2. **Use a demo repository** with realistic but simple code
+3. **Speed up waiting periods** (2-4x) during agent processing
+4. **Add text overlays** for key points and corrections
+5. **Include captions** for accessibility
+6. **Keep branding consistent** with existing Roo Code materials
+
+---
+
+## Post-Production Checklist
+
+- [ ] Add intro/outro with Roo Code branding
+- [ ] Include captions/subtitles
+- [ ] Add background music (subtle, non-distracting)
+- [ ] Ensure all sensitive data is removed (tokens, API keys)
+- [ ] Export in multiple resolutions (1080p, 720p)
+- [ ] Create thumbnail with clear value proposition
+- [ ] Prepare description with:
+  - Documentation link
+  - Setup instructions
+  - Team plan information
+  - Support/contact information
+
+---
+
+## Distribution Channels
+
+1. **YouTube** - Main hosting platform
+2. **Docs site** - Embed in Linear integration documentation
+3. **Social media** - Twitter/X, LinkedIn clips
+4. **Email newsletter** - Announcement to existing users
+5. **Landing page** - Feature on Linear integration page
+
+---
+
+## Follow-Up Content Ideas
+
+- **Written tutorial** mirroring the video
+- **GIF demos** for specific workflows (assigning, mentioning)
+- **Troubleshooting guide** for common issues
+- **Comparison matrix** vs manual development workflow
+- **Customer testimonials** from teams using the integration
+
+---
+
+## Metrics to Track
+
+- Video views and watch time
+- Documentation page visits
+- Linear integration connections (conversion)
+- Team plan upgrades after viewing
+- Support tickets related to Linear integration
diff --git a/docs/roo-code-cloud/linear-integration.mdx b/docs/roo-code-cloud/linear-integration.mdx
new file mode 100644
index 00000000..1cb61c07
--- /dev/null
+++ b/docs/roo-code-cloud/linear-integration.mdx
@@ -0,0 +1,164 @@
+---
+description: Use Roo Code Cloud agents directly from Linear to implement features, fix bugs, and collaborate on development tasks.
+keywords:
+  - Linear Integration
+  - Issue Tracking
+  - "@Roo Code"
+  - Linear bot
+  - AI coding
+  - collaborative development
+  - issue automation
+  - agent delegation
+---
+
+# Linear Integration
+
+The Roo Code Linear integration brings your Cloud Agent team directly into your issue tracking workflow. You can delegate issues to agents, get implementation plans, or execute coding tasks without leaving Linear, streamlining your development process.
+
+Using agents from Linear is an effective way to automate routine development tasks and maintain context between planning and implementation.
+
+---
+
+## Prerequisites
+
+- **Roo Code Cloud Team plan** — Linear integration is only available on the Team plan
+- **GitHub repository** — The repository must be connected to your Roo Code Cloud workspace
+- **Organization Settings access** — You'll need admin access to configure integrations
+
+---
+
+## Setting Up
+
+1. Navigate to **Organization Settings** in Roo Code Cloud (top right user menu)
+2. Go to **Integrations** → **Linear**
+3. Click **Connect** and authorize the OAuth connection (no API keys required)
+4. The Roo Code agent will be added to your Linear workspace
+
+**Note:** The integration uses OAuth authentication and requires no manual API key configuration.
+
+---
+
+## Linking Your Account
+
+The first time you interact with the Roo Code agent in Linear, you'll need to link your Linear account to your Roo Code account:
+
+1. When you first assign an issue or mention the agent, you'll receive an authentication prompt
+2. Click the authentication link to connect your accounts
+3. Once linked, your requests will be processed automatically
+
+This one-time linking ensures that agent work is properly attributed and tracked within your Roo Code organization.
+
+---
+
+## How to Use
+
+### Assigning Work to Roo Code
+
+Delegate issues to the agent just like assigning to a team member:
+
+1. Create a Linear issue with a clear description and acceptance criteria
+2. Assign the issue to **Roo Code** (the agent appears as a user in your workspace)
+3. The agent will acknowledge the assignment and begin working
+
+**Example:**
+> **Issue:** Add dark mode toggle to settings page
+>
+> **Description:** Implement a dark mode toggle in the user settings. The toggle should persist the user's preference and apply the theme across the entire application.
+
+### Mentioning the Agent
+
+You can also interact with the agent by mentioning it in issue comments:
+
+```
+@Roo Code Please implement this feature with support for system theme detection
+```
+
+```
+@Roo Code What's the best approach to implement this? Consider our existing auth middleware.
+```
+
+**Note:** The exact mention format is `@Roo Code` or `@roocode` depending on how the agent user was created in your workspace.
+
+### Monitor Progress
+
+The agent provides real-time updates as comments on the Linear issue:
+
+- "Getting started..."
+- "Analyzing codebase..."
+- "Creating implementation plan..."
+- "Opening PR..."
+
+All progress is visible directly in Linear, maintaining full context with your issue tracking.
+
+### Provide Feedback
+
+Continue the conversation by commenting on the issue:
+
+```
+@Roo Code Please also add a "system" option that follows OS preference
+```
+
+The agent will acknowledge your feedback and adapt its approach accordingly.
+
+### Review the PR
+
+When work is complete:
+- A GitHub pull request link appears in the Linear issue
+- The PR is automatically linked to the Linear issue (using issue identifier in branch name)
+- Review and merge through your normal GitHub workflow
+- Linear automatically updates when the PR is merged
+
+---
+
+## What Roo Code Can Do from Linear
+
+- **Implement features** — Turn requirements into working code with pull requests
+- **Fix bugs** — Analyze and resolve issues with automated fixes
+- **Provide consultation** — Analyze codebase and provide recommendations without making changes
+- **Review code** — If a PR already exists, the agent can review and suggest improvements
+- **Update documentation** — Keep docs in sync with code changes
+
+---
+
+## Stopping Work
+
+If you need to halt agent work on an issue:
+
+1. Send a stop signal from Linear (available in the agent session UI)
+2. The agent will immediately cancel any active work
+3. A confirmation message will be posted to the issue
+
+---
+
+## Key Benefits
+
+- **Work where you plan** — No context switching between Linear and your IDE
+- **Assign to agents like team members** — Familiar workflow for delegation
+- **Full visibility** — Progress updates appear directly in Linear issues
+- **Automatic PR linking** — PRs are automatically linked to Linear issues
+- **Team collaboration** — Everyone on the team can see agent work and provide feedback
+
+---
+
+## Limitations
+
+- **Organization Settings only** — Integration is configured at the organization level (not per-project)
+- **Team plan required** — Available only on Roo Code Cloud Team plan
+- **Active subscription** — Requires funded Cloud credits
+- **Account linking required** — Each Linear user must link their Roo Code account once
+
+---
+
+## Troubleshooting
+
+### "Please link your Roo Code account"
+
+This message appears if you haven't linked your Linear account to Roo Code yet. Click the authentication link in the prompt to complete the one-time linking process.
+
+### "No Coder agent is configured"
+
+This means your Roo Code organization doesn't have a Cloud Agent configured. Set up a Coder agent in your Roo Code Cloud settings before using the Linear integration.
+
+### "Linear authentication has expired"
+
+The OAuth connection needs to be refreshed. An organization admin should disconnect and reconnect the Linear integration in Organization Settings.
diff --git a/sidebars.ts b/sidebars.ts
index 69663d7d..6aa97c92 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -133,6 +133,7 @@ const sidebars: SidebarsConfig = {
         'roo-code-cloud/analytics',
         'roo-code-cloud/github-integration',
         'roo-code-cloud/slack-integration',
+        'roo-code-cloud/linear-integration',
         'roo-code-cloud/team-plan',
       ],
     },