feat: GitHub Context Subagent (Issue #10)

[prosdev]

🚀 GitHub Context Subagent

Implements a new subagent to index and search GitHub issues, PRs, and discussions, providing rich context to AI coding assistants.

📋 Closes

• Closes Implement GitHub Context Subagent #10

✨ Features

Core Functionality

• ✅ GitHubIndexer: Fetch and store GitHub documents (issues/PRs)
• ✅ Semantic Search: Query GitHub data with relevance scoring
• ✅ Context Provision: Get complete context for specific issues/PRs
• ✅ Relationship Extraction: Auto-detect issue refs, file paths, mentions, URLs
• ✅ Code Linking: Connect GitHub items to relevant code files via RepositoryIndexer

CLI Commands

dev gh index              # Index GitHub data
dev gh search <query>     # Search GitHub context
dev gh context <number>   # Get full context for issue/PR

Agent Integration

• ✅ GitHubAgent: Coordinator-compatible agent wrapper
• ✅ Message Routing: 4 actions (index, search, context, related)
• ✅ Error Handling: Structured error responses

🏗️ Architecture

github/
├── agent.ts          # Agent wrapper (162 lines)
├── indexer.ts        # Document indexer (290 lines)
├── types.ts          # Type definitions
├── utils/
│   ├── fetcher.ts    # GitHub CLI integration
│   └── parser.ts     # Content parsing (100% test coverage)
└── README.md         # Comprehensive docs (540 lines)

🧪 Testing

• ✅ Parser utilities: 47 tests, 100% coverage
• ✅ Coordinator integration: 14 tests, 100% coverage
• ✅ All tests passing: 61/61 ✅
• ✅ Zero linting errors

📊 Commits (8 focused commits)

1. feat(github): add fetcher and parser utilities - Foundation
2. feat(github): add GitHubIndexer for document storage and search - Core indexing
3. feat(github): add CLI commands for GitHub context - User interface
4. test(github): add comprehensive parser utility tests - 47 tests
5. fix(github): achieve 100% test coverage for parser utilities - Bug fixes from tests
6. feat(github): add GitHub Context Agent - Coordinator integration
7. test(github): add coordinator integration tests - 14 integration tests
8. docs(github): add comprehensive GitHub agent documentation - Complete README

🔍 Implementation Highlights

1. Modular Utility Architecture

Following the testability gold standard:

• Pure functions in domain-specific modules (fetcher.ts, parser.ts)
• 100% unit test coverage
• Clear separation of concerns

2. Relationship Extraction

Automatically parses GitHub content for:

• Issue references: #123, GH-456, owner/repo#789
• File paths: src/auth/login.ts, packages/core/index.ts
• Mentions: @username
• GitHub URLs: Full issue/PR URLs

3. Code Linking

Links GitHub documents to code files:

const context = await githubIndexer.getContext(42, 'issue');
// Returns: { document, relatedIssues, relatedCode }

4. Coordinator Integration

Seamless message routing:

const response = await coordinator.sendMessage({
  type: 'request',
  recipient: 'github',
  payload: { action: 'search', query: 'authentication bug' }
});

📝 Files Changed

• New files: 10
• Lines added: ~1,500 (including tests + docs)
• Test coverage: 100% for utilities, 100% for integration
• Documentation: Complete 540-line README with examples

🎯 Merge Strategy

Recommended: Rebase and Merge

• 8 clean, atomic commits
• All focused on GitHub agent feature
• Follows conventional commit format
• Linear history for easy bisecting

✅ Ready to Merge

• All tests passing (61/61)
• Zero linting errors
• 100% test coverage for utilities
• Comprehensive documentation
• Follows testability guidelines
• CLI commands working
• Agent integration tested

🚀 Usage Example

import { GitHubAgent, SubagentCoordinator } from '@lytics/dev-agent-subagents';
import { RepositoryIndexer } from '@lytics/dev-agent-core';

// Setup
const codeIndexer = new RepositoryIndexer({ repositoryPath: '.' });
await codeIndexer.initialize();

const coordinator = new SubagentCoordinator();
await coordinator.registerAgent(new GitHubAgent({ 
  repositoryPath: '.', 
  codeIndexer 
}));

// Use it
const response = await coordinator.sendMessage({
  type: 'request',
  recipient: 'github',
  payload: { action: 'search', query: 'rate limiting' }
});