Why Issue Relations Matter for AI Agents

When AI agents work on complex projects, understanding task dependencies is critical. An agent needs to know:

• Which issues are blocked by others (don't start work until blockers are resolved)
• Which issues are related (changes in one may affect the other)
• Which issues are duplicates (avoid redundant work)

Without visibility into these relationships, agents make suboptimal decisions—starting blocked work, missing related context, or duplicating effort. Linearis, being designed for LLM agents, should expose this relationship data to enable smarter task planning and execution.

Summary

This PR adds comprehensive issue relations support through a new issues relations subcommand group:

• List relations: linearis issues relations list ABC-123
• Add relations: linearis issues relations add ABC-123 --blocks DEF-456,DEF-789
• Remove relations: linearis issues relations remove <relation-uuid>

All four Linear relation types are supported:

• --blocks - This issue blocks the specified issues
• --related - General relationship between issues
• --duplicate - This issue is a duplicate of another
• --similar - Similar issues (note: typically AI-generated by Linear)

Relations are also now included in issues read output, giving agents complete context when examining an issue.

Example Usage

# List all relations for an issue
linearis issues relations list ABC-123

# Add blocking relations (multiple targets supported)
linearis issues relations add ABC-123 --blocks DEF-456,DEF-789

# Add related issues
linearis issues relations add ABC-123 --related GHI-101

# Remove a relation (use UUID from list output)
linearis issues relations remove 550e8400-e29b-12d3-a456-426614174000

# Relations now appear in issue read output
linearis issues read ABC-123

Output Format

{
  "issueId": "550e8400-e29b-12d3-a456-426614174000",
  "identifier": "ABC-123",
  "relations": [
    {
      "id": "660e8400-e29b-12d3-a456-426614174001",
      "type": "blocks",
      "issue": {"id": "...", "identifier": "ABC-123", "title": "Parent task"},
      "relatedIssue": {"id": "...", "identifier": "DEF-456", "title": "Blocked task"},
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Technical Implementation

• New ISSUE_RELATIONS_FRAGMENT in GraphQL queries fetching both relations and inverseRelations
• LinearIssueRelation TypeScript interface for type safety
• Human-friendly ID resolution (TEAM-123 → UUID) for all relation operations
• Proper validation:
  • Null/undefined checks for nested relation data
  • UUID validation for relation removal
  • Partial success reporting when batch creation fails
• Applied feedback from PR [FEAT] Add documents CLI commands #21 (_options: unknown with explanatory comments)

Test Plan

• Unit tests: 23 tests covering all relation methods and edge cases
• Integration tests: CLI validation tests (skipped tests document expected behavior without creating test data)
• All existing tests pass
• Manual testing with real Linear workspace

🤖 Generated with Claude Code