# null

# Linear Integration Guide for Agents

This guide explains how agents should interact with Linear using MCP tools to maintain extensive documentation and project status tracking.

***

## Prerequisites

Ensure Linear MCP server is configured in your MCP settings:

```json  theme={null}
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-linear"],
      "env": {
        "LINEAR_API_KEY": "your-api-key"
      }
    }
  }
}
```

***

## Available Linear MCP Tools

### 1. `mcp__linear__search_issues`

Search for Linear issues by query string.

**Parameters**:

* `query`: Search query (e.g., "LINEAR-123" or keywords)
* `limit`: Max number of results (default: 10)

**Example**:

```
mcp__linear__search_issues
  query: "LINEAR-123"
  limit: 1
```

### 2. `mcp__linear__get_issue`

Get detailed information about a specific issue.

**Parameters**:

* `issue_id`: The issue identifier (e.g., "LINEAR-123")

**Example**:

```
mcp__linear__get_issue
  issue_id: "LINEAR-123"
```

### 3. `mcp__linear__create_issue`

Create a new Linear issue.

**Parameters**:

* `title`: Issue title
* `description`: Detailed description (supports markdown)
* `team_id`: Team identifier
* `priority`: 0 (No priority), 1 (Urgent), 2 (High), 3 (Medium), 4 (Low)
* `state_id`: State identifier (Backlog, Todo, In Progress, Done, etc.)
* `assignee_id`: User ID to assign

**Example**:

```
mcp__linear__create_issue
  title: "Implement user authentication API"
  description: "## Overview

  Create RESTful API endpoints for user authentication.

  ## Requirements
  - POST /api/auth/register
  - POST /api/auth/login
  - GET /api/auth/me

  ## Acceptance Criteria
  - [ ] Registration endpoint validates email and password
  - [ ] Login returns JWT token
  - [ ] Me endpoint returns authenticated user info"
  team_id: "TEAM-123"
  priority: 2
```

### 4. `mcp__linear__update_issue`

Update an existing Linear issue.

**Parameters**:

* `issue_id`: Issue identifier
* `title`: New title (optional)
* `description`: New description (optional)
* `priority`: New priority (optional)
* `state_id`: New state (optional)
* `assignee_id`: New assignee (optional)

**Example**:

```
mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "in-progress"
  description: "## Implementation Plan

  ### Phase 1: API Setup
  - [x] Create route handlers
  - [x] Configure middleware
  - [ ] Add validation schemas

  ### Phase 2: Service Layer
  - [ ] Implement AuthService
  - [ ] Add business logic validation"
```

### 5. `mcp__linear__add_comment`

Add a comment to an issue.

**Parameters**:

* `issue_id`: Issue identifier
* `body`: Comment text (supports markdown)

**Example**:

```
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Progress Update - Phase 1 Complete

  Completed tasks:
  - ✅ Created route handlers in `src/routes/authRoutes.ts`
  - ✅ Configured middleware stack
  - ✅ Added Joi validation schemas

  Commits: abc123, def456, ghi789

  Starting Phase 2: Service Layer implementation"
```

### 6. `mcp__linear__list_teams`

List all teams in the Linear workspace.

**Example**:

```
mcp__linear__list_teams
```

### 7. `mcp__linear__get_team`

Get team details including states and workflows.

**Parameters**:

* `team_id`: Team identifier

**Example**:

```
mcp__linear__get_team
  team_id: "TEAM-123"
```

***

## Agent Workflow with Linear

### 1. **Start of Work - Read Ticket**

When starting a new task, agents should:

1. **Search for the ticket**:

```bash  theme={null}
# Use MCP tool to find the ticket
mcp__linear__search_issues
  query: "LINEAR-123"
  limit: 1
```

2. **Get full ticket details**:

```bash  theme={null}
mcp__linear__get_issue
  issue_id: "LINEAR-123"
```

3. **Read related documents** mentioned in the ticket description

### 2. **Update Status - Starting Work**

When beginning implementation:

```bash  theme={null}
mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "in-progress"
```

```bash  theme={null}
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Starting Implementation

**Agent**: @backend-developer
**Branch**: feature/LINEAR-123-user-auth
**Start Date**: 2025-01-10

### Implementation Plan Approved
[Link to detailed plan in docs]

### Next Steps
Starting Phase 1: API Setup"
```

### 3. **Document Implementation Plan**

After plan approval, update the ticket with comprehensive details:

```bash  theme={null}
mcp__linear__update_issue
  issue_id: "LINEAR-123"
  description: "## Overview
Create RESTful API endpoints for user authentication.

## Requirements
- POST /api/auth/register
- POST /api/auth/login
- GET /api/auth/me

## Implementation Plan

### Phase 1: API Setup ✅ [COMPLETE]
- [x] Task 1.1: Set up route handlers
  - File: `src/routes/authRoutes.ts`
  - Commit: abc123
- [x] Task 1.2: Configure middleware stack
  - File: `src/middleware/auth.ts`
  - Commit: def456
- [x] Task 1.3: Add validation schemas
  - File: `src/validators/authValidators.ts`
  - Commit: ghi789

### Phase 2: Service Layer 🔄 [IN PROGRESS]
- [ ] Task 2.1: Implement AuthService
- [ ] Task 2.2: Add business logic validation
- [ ] Task 2.3: Implement JWT token generation

### Phase 3: Database Integration ⏳ [TODO]
- [ ] Task 3.1: Create User repository
- [ ] Task 3.2: Implement password hashing
- [ ] Task 3.3: Add session management

### Phase 4: Testing ⏳ [TODO]
- [ ] Task 4.1: Unit tests for AuthService
- [ ] Task 4.2: Integration tests for endpoints
- [ ] Task 4.3: Security testing

## Technical Stack
- Framework: Express.js
- Database: PostgreSQL with Prisma
- Authentication: JWT with bcrypt
- Validation: Joi

## Security Considerations
- bcrypt password hashing (cost factor: 12)
- JWT expiration: 24 hours
- Rate limiting: 5 attempts per 15 minutes
- Input validation on all endpoints

## API Endpoints
\`\`\`
POST   /api/v1/auth/register  - User registration
POST   /api/v1/auth/login     - User login
GET    /api/v1/auth/me        - Get current user
POST   /api/v1/auth/logout    - User logout
POST   /api/v1/auth/refresh   - Refresh JWT token
\`\`\`

## Documentation Links
- [API Contract](docs/architecture/api-contracts/auth-api.yaml)
- [Database Schema](docs/database/schemas/users-schema.md)
- [Implementation Plan](docs/implementation/LINEAR-123-plan.md)

## Acceptance Criteria
- [x] Registration endpoint validates email and password
- [ ] Login returns JWT token
- [ ] Me endpoint returns authenticated user info
- [ ] All endpoints have proper error handling
- [ ] Test coverage > 80%"
```

### 4. **Progress Updates - After Each Phase**

After completing each phase:

```bash  theme={null}
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Phase 1 Complete ✅

### Completed Tasks
- ✅ Set up route handlers in `src/routes/authRoutes.ts`
- ✅ Configured middleware stack in `src/middleware/`
- ✅ Added Joi validation schemas in `src/validators/`

### Commits
- abc123: feat(api): add auth route handlers
- def456: feat(middleware): add JWT authentication middleware
- ghi789: feat(validation): add auth input validation schemas

### Files Changed
- `src/routes/authRoutes.ts` (+85 lines)
- `src/middleware/auth.ts` (+120 lines)
- `src/validators/authValidators.ts` (+65 lines)

### Progress: 25% Complete

### Next Phase
Starting Phase 2: Service Layer implementation"
```

### 5. **Technical Decisions**

Document all technical decisions in the ticket:

```bash  theme={null}
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Technical Decision: JWT Token Storage

### Decision
Store JWT tokens in HTTP-only cookies instead of localStorage

### Rationale
- Prevents XSS attacks from stealing tokens
- Automatically sent with requests
- Can set secure and SameSite flags

### Alternatives Considered
1. localStorage - Rejected due to XSS vulnerability
2. sessionStorage - Same security concerns as localStorage
3. Memory only - Rejected due to poor UX (login on every refresh)

### Implementation Impact
- Need to handle CSRF protection
- Requires cookie parsing middleware
- Must configure CORS to allow credentials

### References
- [OWASP Token Storage Best Practices](https://example.com)
- Architecture discussion: docs/architecture/decisions/jwt-storage.md"
```

### 6. **Blockers**

If encountering blockers:

```bash  theme={null}
mcp__linear__update_issue
  issue_id: "LINEAR-123"
  priority: 1
```

```bash  theme={null}
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## ⚠️ BLOCKER ENCOUNTERED

### Blocker Description
Cannot proceed with Phase 3 (Database Integration) because user schema is not yet created in database.

### Impact
- Phase 3 delayed by estimated 2 days
- Overall ticket completion delayed
- Blocking LINEAR-124 (User Profile API)

### Dependency
Waiting on: LINEAR-100 (Database Schema Implementation)
Assigned to: @dba

### Temporary Solution
- Continuing with mock data for testing
- Writing integration tests that will work once schema is ready
- Documenting exact schema requirements

### Required to Unblock
User table must have:
- id (UUID, primary key)
- email (VARCHAR, unique, not null)
- password_hash (VARCHAR, not null)
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)

### Next Steps
- [ ] Notify @dba of dependency
- [ ] Continue with testable work
- [ ] Resume Phase 3 once LINEAR-100 is complete"
```

### 7. **Implementation Complete**

When implementation is finished:

```bash  theme={null}
mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "ready-for-review"
```

```bash  theme={null}
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Implementation Complete ✅

### Summary
All API endpoints for user authentication have been implemented, tested, and documented.

### Completed Deliverables
- ✅ All API endpoints implemented per specification
- ✅ AuthService with complete business logic
- ✅ User repository with password hashing
- ✅ JWT token generation and validation
- ✅ Input validation on all endpoints
- ✅ Comprehensive error handling
- ✅ Rate limiting configured (5 attempts / 15 min)
- ✅ Test coverage: 87%
- ✅ All acceptance criteria met

### Git Information
- **Branch**: feature/LINEAR-123-user-auth
- **Total Commits**: 15 commits
- **Files Changed**: 12 files
- **Lines Added**: +1,247
- **Lines Removed**: -53

### Key Commits
- abc123: feat(api): implement user registration endpoint
- def456: feat(api): implement user login endpoint
- ghi789: feat(auth): add JWT token generation
- jkl012: test(auth): add comprehensive auth tests

### API Endpoints Implemented
- ✅ POST   /api/v1/auth/register - User registration
- ✅ POST   /api/v1/auth/login - User login
- ✅ GET    /api/v1/auth/me - Get current user
- ✅ POST   /api/v1/auth/logout - User logout
- ✅ POST   /api/v1/auth/refresh - Refresh token

### How to Test
\`\`\`bash
# 1. Checkout branch
git checkout feature/LINEAR-123-user-auth

# 2. Install dependencies
npm install

# 3. Set up environment
cp .env.example .env
# Add required vars: DATABASE_URL, JWT_SECRET

# 4. Run migrations
npm run migrate

# 5. Start server
npm run dev

# 6. Test registration
curl -X POST http://localhost:3000/api/v1/auth/register \\
  -H \"Content-Type: application/json\" \\
  -d '{\"email\":\"test@example.com\",\"password\":\"Test123!@#\"}'

# 7. Test login
curl -X POST http://localhost:3000/api/v1/auth/login \\
  -H \"Content-Type: application/json\" \\
  -d '{\"email\":\"test@example.com\",\"password\":\"Test123!@#\"}'
\`\`\`

### Test Results
- Unit tests: 45 tests, 45 passing ✅
- Integration tests: 12 tests, 12 passing ✅
- Coverage: 87% (target: 80%) ✅

### Security Checklist
- [x] Input validation on all endpoints
- [x] Password hashing with bcrypt (cost: 12)
- [x] JWT tokens with expiration
- [x] Rate limiting implemented
- [x] CORS configured properly
- [x] Error messages don't leak sensitive data
- [x] No SQL injection vulnerabilities
- [x] XSS prevention in place

### Documentation
- [x] API documentation updated
- [x] README updated with auth endpoints
- [x] Postman collection created
- [x] Inline code comments added

### Performance
- Registration: ~180ms avg response time
- Login: ~150ms avg response time
- Token validation: ~5ms avg response time

### Next Steps
**Ready for handoff to:**
- @app-security-engineer for security scan
- @senior-qa-engineer for QA testing

**Handoff Instructions:**
1. Review implementation in `src/routes/authRoutes.ts`
2. Run security scan: `bash .claude/skills/secure-push/scripts/pre-push-scan.sh`
3. Execute test plan: `docs/testing/auth-test-plan.md`

### Related Issues
- Blocks: LINEAR-124 (User Profile API)
- Blocks: LINEAR-125 (Password Reset Flow)
- Related: LINEAR-100 (Database Schema) - Used this schema"
```

### 8. **After Review/QA Feedback**

When receiving feedback:

```bash  theme={null}
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## QA Feedback Received

### Issues Found
1. ⚠️ **Rate limiting not working on /register endpoint**
   - Severity: High
   - Can spam registration attempts
   - Fix: Apply rate limiter middleware to route

2. ⚠️ **Password validation too weak**
   - Severity: Medium
   - Only checks length, not complexity
   - Fix: Add complexity requirements (upper, lower, number, special char)

3. ℹ️ **Missing password strength indicator**
   - Severity: Low
   - Enhancement suggestion
   - Future improvement

### Fixes Applied
- [x] Applied rate limiter to registration endpoint (commit: xyz789)
- [x] Enhanced password validation rules (commit: uvw456)
- [ ] Password strength indicator (deferred to LINEAR-126)

### Re-test Results
- All QA test cases passing ✅
- Security scan clean ✅
- Ready for deployment"
```

### 9. **Merge to Main**

After merge:

```bash  theme={null}
mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "done"
```

```bash  theme={null}
mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Merged to Main ✅

### Merge Details
- **PR**: #42
- **Merged By**: [User]
- **Merge Date**: 2025-01-10
- **Merge Commit**: abc123def456

### Deployment Status
- ✅ Merged to main
- ✅ Deployed to staging (v1.2.0-rc1)
- ⏳ Awaiting production deployment

### Production Deployment
- **Scheduled**: 2025-01-12 10:00 AM UTC
- **Deployer**: @devops-engineer
- **Deployment Ticket**: LINEAR-130

### Metrics
- Total development time: 5 days
- Commits: 15
- Files changed: 12
- Test coverage: 87%

### Follow-up Items
- [ ] Monitor error rates in production
- [ ] Create LINEAR-126 for password strength indicator
- [ ] Update user documentation"
```

***

## Documentation Standards

### Ticket Description Structure

Every Linear ticket should have:

1. **Overview** - Brief summary of the task
2. **Requirements** - What needs to be built/fixed
3. **Implementation Plan** - Phased approach with tasks
4. **Technical Stack** - Technologies used
5. **Security Considerations** - Security measures
6. **API/Database Details** - Specific technical details
7. **Documentation Links** - Links to related docs
8. **Acceptance Criteria** - Clear success criteria

### Comment Standards

Every comment should:

1. **Use clear headers** with ## markdown
2. **Include status indicators** (✅ ✓ ⏳ 🔄 ⚠️)
3. **Reference commits** when discussing code changes
4. **Link to files** when discussing implementation
5. **Provide context** - explain the "why" not just "what"
6. **Be actionable** - clear next steps

### Update Frequency

Agents should update Linear:

1. **At start of work** - Status change + initial comment
2. **After each phase** - Progress update
3. **When making decisions** - Document the decision
4. **When blocked** - Immediate blocker notification
5. **At completion** - Comprehensive summary
6. **After feedback** - Document changes made
7. **After merge** - Final status update

***

## Best Practices

### DO ✅

* **Be comprehensive** - Include all relevant details
* **Use markdown** - Format for readability
* **Link extensively** - Connect to files, commits, docs
* **Update frequently** - Keep stakeholders informed
* **Document decisions** - Explain technical choices
* **Include examples** - Show how to test/use
* **Reference blockers** - Call out dependencies
* **Provide metrics** - Performance, coverage, time

### DON'T ❌

* **Be vague** - Avoid "Fixed stuff" or "Updated code"
* **Skip updates** - Don't go silent for days
* **Hide blockers** - Surface issues immediately
* **Forget links** - Always link to related work
* **Omit context** - Explain why, not just what
* **Ignore feedback** - Acknowledge and address all feedback
* **Rush documentation** - Take time to be thorough

***

## Example: Complete Ticket Lifecycle

See [LINEAR-123-EXAMPLE.md](./examples/LINEAR-123-EXAMPLE.md) for a complete example of a ticket from creation through deployment with all updates and comments.

***

## Troubleshooting

### Linear MCP Not Working

1. Check MCP server configuration
2. Verify LINEAR\_API\_KEY is set
3. Restart Claude Code
4. Test with simple search query

### Cannot Find Issue

1. Verify issue ID format (LINEAR-XXX)
2. Check you have access to the team
3. Try searching by title/keywords instead

### Cannot Update Issue

1. Verify you have write permissions
2. Check state\_id is valid for your team
3. Ensure assignee\_id exists

***

## Additional Resources

* [Linear API Documentation](https://developers.linear.app/docs)
* [Linear MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/linear)
* [Project Overview Document](./PROJECT_OVERVIEW.md)
* [Agent Handoff Protocol](./AGENT_HANDOFF_PROTOCOL.md)


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.agentsoflearning.com/llms.txt