Phase C: Discussions - Message Queue and Community Platform

Overview

Phase C implements GitHub Discussions as a Message Queue and community engagement platform for the Autonomous Operations system. This phase enables asynchronous communication, FAQ automation, idea collection, and automatic conversion of feature ideas into trackable GitHub Issues.

Status

• Status: Complete
• Priority: High
• Duration: 2 hours
• Agent: CodeGenAgent

GitHub as OS Mapping

GitHub Discussions → Message Queue / Forum System
- Discussion Categories → Message Topics/Channels
- Q&A → Support Ticketing System
- Ideas → Feature Request Queue
- Bot Responses → Auto-responder Service
- Idea→Issue Conversion → Task Creation Pipeline

Goals and Objectives

Primary Goals

1. Implement GitHub Discussions as asynchronous message queue
2. Create AI-powered discussion bot for automated responses
3. Enable FAQ auto-response system
4. Implement idea-to-issue conversion workflow
5. Establish community engagement automation

Success Metrics

• Discussion bot response time < 5 seconds
• FAQ match accuracy > 80%
• Idea conversion success rate > 95%
• Positive sentiment in bot interactions > 90%
• Zero missed discussion events

Implementation Details

1. Discussion Categories

Five primary categories for organized communication:

2. Discussion Bot

File: scripts/discussion-bot.ts

Core bot for automated discussion management.

Features

• Process new discussions
• Send welcome messages
• Provide FAQ responses
• Suggest category changes
• Convert ideas to issues
• Sentiment analysis
• Command parsing

Usage

# Process a specific discussion
npx tsx scripts/discussion-bot.ts process 42

# Search FAQ database
npx tsx scripts/discussion-bot.ts faq "how to setup"

# Run test scenario
npx tsx scripts/discussion-bot.ts test

Bot Implementation

class DiscussionBot {
  private anthropic: Anthropic;
  private github: Octokit;

  async processDiscussion(discussion: Discussion): Promise<void> {
    console.log('📬 Processing Discussion\n');
    console.log(`  Title: ${discussion.title}`);
    console.log(`  Author: @${discussion.author}`);
    console.log(`  Category: ${discussion.category}`);

    // AI analysis
    const analysis = await this.analyzeDiscussion(discussion);

    console.log('\n🧠 AI Analysis:\n');
    console.log(`  Suggested Category: ${analysis.category}`);
    console.log(`  Convert to Issue: ${analysis.shouldConvertToIssue ? 'Yes' : 'No'}`);
    console.log(`  Is Question: ${analysis.isQuestion ? 'Yes' : 'No'}`);
    console.log(`  Sentiment: ${analysis.sentiment}`);
    console.log(`  Reasoning: ${analysis.reasoning}`);

    // Send welcome message
    if (this.config.enableWelcomeMessage) {
      await this.sendWelcomeMessage(discussion);
      console.log('  ✓ Sent welcome message');
    }

    // Check FAQ
    if (this.config.enableFAQ && analysis.isQuestion) {
      const faqAnswer = this.searchFAQ(discussion.body);
      if (faqAnswer) {
        await this.sendFAQResponse(discussion, faqAnswer);
        console.log('  ✓ Sent FAQ response');
      }
    }

    // Suggest category
    if (this.config.enableCategorySuggestion &&
        analysis.category !== discussion.category) {
      await this.suggestCategory(discussion, analysis.category);
      console.log(`  ✓ Suggested category: ${analysis.category}`);
    }

    // Convert to issue if needed
    if (this.config.enableIdeaConversion &&
        analysis.shouldConvertToIssue) {
      await this.convertToIssue(discussion);
      console.log('  ✓ Converted to Issue');
    }

    console.log('\n✅ Discussion processing complete');
  }

  private async analyzeDiscussion(
    discussion: Discussion
  ): Promise<DiscussionAnalysis> {
    const prompt = `
Analyze this GitHub Discussion and provide:
1. Suggested category (Q&A, Ideas, Show & Tell, Announcements, General)
2. Should it be converted to a GitHub Issue?
3. Is it a question requiring FAQ response?
4. Sentiment (positive, neutral, negative)
5. Brief reasoning

Discussion:
Title: ${discussion.title}
Body: ${discussion.body}
Category: ${discussion.category}

Respond in JSON format.
    `;

    const response = await this.anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [{ role: 'user', content: prompt }],
    });

    return JSON.parse(response.content[0].text);
  }

  searchFAQ(query: string): string | null {
    const lowerQuery = query.toLowerCase();

    for (const faq of FAQ_DATABASE) {
      if (faq.keywords.some((keyword) => lowerQuery.includes(keyword))) {
        return faq.answer;
      }
    }

    return null;
  }
}

3. FAQ Database

Built-in FAQ database with automatic keyword matching:

const FAQ_DATABASE = [
  {
    question: 'How do I set up the project?',
    answer: 'Run `npm install` to install dependencies, then `npm run setup:token` to configure your GitHub token.',
    keywords: ['setup', 'install', 'start', 'begin', 'configure'],
  },
  {
    question: 'How do I run the agents?',
    answer: 'Use `npm run agents:parallel:exec -- --issue <number>` to execute agents on a specific issue.',
    keywords: ['run', 'execute', 'agent', 'start agent'],
  },
  {
    question: 'What agents are available?',
    answer: 'Available agents: CoordinatorAgent, CodeGenAgent, ReviewAgent, IssueAgent, PRAgent, DeploymentAgent.',
    keywords: ['agents', 'which agent', 'available agent', 'agent list'],
  },
  {
    question: 'How do I create a new agent?',
    answer: 'Extend the BaseAgent class and implement the `execute()` method. See `docs/AGENTS.md` for details.',
    keywords: ['create agent', 'new agent', 'custom agent', 'implement agent'],
  },
  {
    question: 'Where are the logs?',
    answer: 'Agent logs are stored in `.agentic/logs/` directory. Use `npm run agents:status` to view recent activity.',
    keywords: ['logs', 'logging', 'debug', 'trace', 'log file'],
  },
];

4. Idea to Issue Converter

File: scripts/convert-idea-to-issue.ts

Converts feature ideas from Discussions to GitHub Issues using Claude AI.

Conversion Process

class IdeaToIssueConverter {
  async convert(discussionNumber: number): Promise<void> {
    console.log('🔄 Converting Discussion to Issue\n');

    // Step 1: Fetch discussion
    const discussion = await this.fetchDiscussion(discussionNumber);
    console.log(`✓ Fetched Discussion #${discussionNumber}\n`);

    // Step 2: AI analysis
    console.log('🧠 AI Analysis:\n');
    const template = await this.analyzeAndGenerateIssue(discussion);

    console.log(`  Issue Title: ${template.title}`);
    console.log(`  Priority: ${template.priority}`);
    console.log(`  Estimated Effort: ${template.estimatedEffort}`);
    console.log(`  Labels: ${template.labels.join(', ')}`);
    console.log(`\n  Reasoning: ${template.reasoning}\n`);

    // Step 3: Create issue
    const issueNumber = await this.createIssue(discussion, template);
    console.log(`✓ Created Issue #${issueNumber}\n`);

    // Step 4: Link back to discussion
    await this.postConversionComment(discussion, issueNumber);

    console.log('✅ Conversion complete!\n');
    console.log(`📋 Issue URL: ${this.getIssueURL(issueNumber)}`);
  }

  private async analyzeAndGenerateIssue(
    discussion: Discussion
  ): Promise<IssueTemplate> {
    const prompt = `
Convert this feature idea from GitHub Discussion into a structured GitHub Issue.

Discussion:
Title: ${discussion.title}
Body: ${discussion.body}
Author: ${discussion.author}

Generate:
1. Clear issue title
2. Detailed description with problem statement
3. Proposed solution
4. Acceptance criteria (checklist)
5. Technical considerations
6. Estimated effort (XS/S/M/L/XL)
7. Appropriate labels (type, priority, phase, agent)

Respond in JSON format.
    `;

    const response = await this.anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 2048,
      messages: [{ role: 'user', content: prompt }],
    });

    return JSON.parse(response.content[0].text);
  }

  private async createIssue(
    discussion: Discussion,
    template: IssueTemplate
  ): Promise<number> {
    const body = `
## Original Discussion

**Discussion:** #${discussion.number} - ${discussion.title}
**Author:** @${discussion.author}
**Category:** ${discussion.category}
**Created:** ${discussion.createdAt}

---

${template.body}

---

## Metadata

**Estimated Effort:** ${template.estimatedEffort}
**Priority:** ${template.priority}

## Links

- 💬 [Original Discussion](${discussion.url})
- 📚 [Documentation](/docs)
- 🤖 [Agent Documentation](/docs/AGENTS.md)
    `;

    const response = await this.github.rest.issues.create({
      owner: this.config.owner,
      repo: this.config.repo,
      title: template.title,
      body: body,
      labels: template.labels,
    });

    return response.data.number;
  }

  private async postConversionComment(
    discussion: Discussion,
    issueNumber: number
  ): Promise<void> {
    const comment = `
## ✅ Converted to Issue

This idea has been converted to Issue #${issueNumber} for tracking and implementation.

**Issue URL:** ${this.getIssueURL(issueNumber)}

The development team will review this and prioritize accordingly.

Thank you for your contribution! 🎉
    `;

    await this.github.rest.discussions.createComment({
      discussion_id: discussion.id,
      body: comment,
    });
  }
}

5. GitHub Actions Workflow

File: .github/workflows/discussion-bot.yml

Automated workflow for discussion processing.

name: Discussion Bot

on:
  discussion:
    types: [created]
  discussion_comment:
    types: [created]

jobs:
  process-discussion:
    if: github.event_name == 'discussion' && github.event.action == 'created'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install

      - name: Process discussion
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx tsx scripts/discussion-bot.ts process ${{ github.event.discussion.number }}

  convert-idea-to-issue:
    if: |
      github.event_name == 'discussion_comment' &&
      github.event.action == 'created' &&
      contains(github.event.comment.body, '/convert-to-issue') &&
      github.event.discussion.category.name == 'Ideas'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install

      - name: Convert to Issue
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx tsx scripts/convert-idea-to-issue.ts ${{ github.event.discussion.number }}

Completion Criteria and KPIs

Acceptance Criteria

Key Performance Indicators

Implementation Steps and Code Examples

Step 1: Enable GitHub Discussions

# Via GitHub UI
# Repository → Settings → Features → Enable Discussions

Step 2: Create Discussion Categories

Categories are auto-created by GitHub:

• Q&A
• Ideas
• Show & Tell
• Announcements
• General

Step 3: Configure Environment Variables

# Add to repository secrets
# Settings → Secrets and variables → Actions

GITHUB_TOKEN           # Auto-provided
ANTHROPIC_API_KEY      # Your Claude API key

Step 4: Test Discussion Bot

# Local testing
npx tsx scripts/discussion-bot.ts test

# Test FAQ search
npx tsx scripts/discussion-bot.ts faq "how to setup"

# Process specific discussion
npx tsx scripts/discussion-bot.ts process 1

Testing Methodology

Unit Tests

Test FAQ matching:

describe('FAQ Search', () => {
  const bot = new DiscussionBot();

  it('matches setup question', () => {
    const result = bot.searchFAQ('How do I setup the project?');
    expect(result).toContain('npm install');
  });

  it('returns null for no match', () => {
    const result = bot.searchFAQ('Unrelated question');
    expect(result).toBeNull();
  });
});

Integration Tests

Test idea conversion:

# 1. Create test discussion in Ideas category
# 2. Comment: /convert-to-issue
# 3. Verify Issue created with proper structure
# 4. Verify labels applied correctly
# 5. Verify link back to discussion

Troubleshooting Guide

Issue: Bot Not Responding

Symptom: New discussions created but no bot response

Solutions:

1. Check workflow enabled: .github/workflows/discussion-bot.yml
2. Verify ANTHROPIC_API_KEY in repository secrets
3. Check GitHub Actions logs
4. Ensure Discussions feature enabled

Issue: GraphQL API Errors

Symptom: "Failed to fetch discussion" errors

Solutions:

1. Verify GITHUB_TOKEN has discussions:read permission
2. Check discussion number is valid
3. Ensure repository has Discussions enabled
4. Test with GitHub GraphQL Explorer

Issue: FAQ Not Matching

Symptom: Questions don't trigger FAQ responses

Solutions:

1. Check FAQ keywords in FAQ_DATABASE
2. Add more keywords to existing FAQs
3. Verify question text contains keywords
4. Test: npx tsx scripts/discussion-bot.ts faq "your query"

Issue: Idea Conversion Failing

Symptom: /convert-to-issue command doesn't work

Solutions:

1. Ensure discussion in Ideas category
2. Check ANTHROPIC_API_KEY is valid
3. Verify user has permission to create issues
4. Review GitHub Actions logs

Next Phase Transition

Integration with Phase A (Projects V2)

Converted issues automatically added to Projects:

// After issue creation
import { GitHubProjectsClient } from '@agentic-os/github-projects';

const client = new GitHubProjectsClient({ token, project });
await client.addIssueToProject(issueNumber);

Integration with Phase B (Webhooks)

Discussion events trigger webhook routing:

// Webhook handler for discussion events
on:
  discussion:
    types: [created]

References and Resources

Official Documentation

• GitHub Discussions Guide
• Claude API Documentation

Internal Documentation

• Phase A: Projects V2
• Phase B: Webhooks

Credits

Implemented by: CodeGenAgent Issue: #5 Phase C Model: Claude Sonnet 4 Date: 2025-10-08 Duration: 2 hours

Status: ✅ Complete Next Phase: Phase D - Packages