enhance: improve Bobby's GitHub issue creation with comprehensive clarification workflow

- Add mandatory 5-step process for GitHub issue creation
- Require code examination and iterative clarification before creating issues
- Include detailed examples for clarification and creation phases
- Ensure Bobby creates well-researched, comprehensive GitHub issues
- Add node_modules/ to .gitignore for cleaner repository

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>

Author: Stewart86

.gitignore

@@ -1,2 +1,4 @@
 secret.md
 .claude.json
+
+node_modules/

AGENT.md

@@ -0,0 +1,166 @@
+# Bobby - Discord AI Assistant Bot
+
+## Overview
+
+Bobby is a Discord chatbot that helps answer questions about your codebase, file bugs, and translate business requirements into technical requirements. Bobby leverages Claude Code to understand your codebase and provide intelligent responses in a self-hosted, privacy-first environment.
+
+## Core Architecture
+
+### Main Components
+
+- **index.js** - Main Node.js application using Bun runtime
+- **Discord.js** - Handles Discord bot interactions and thread management  
+- **Claude Code CLI** - Powers AI analysis of codebases with streaming responses
+- **GitHub CLI** - Creates issues automatically when bugs are detected
+- **Docker Container** - Self-contained environment with all dependencies
+
+### Environment Variables Required
+
+```
+DISCORD_TOKEN=your_discord_bot_token
+ANTHROPIC_API_KEY=your_anthropic_api_key  
+GH_TOKEN=your_github_personal_access_token
+GITHUB_REPO=owner/repo-name
+ALLOWED_DISCORD_SERVERS=server_id1,server_id2 (optional)
+```
+
+### Docker Architecture
+
+- **Base Image**: `oven/bun:latest`
+- **Dependencies**: Git, GitHub CLI v2.61.0, Claude Code CLI
+- **Working Directory**: `/app`
+- **Repository Clone**: `/app/repo` (target repository)
+- **Data Storage**: `/app/data` (Claude Code sessions and configs)
+- **Entrypoint**: `entrypoint.sh` (handles authentication and setup)
+
+## Thread-Based Session Management
+
+Bobby uses Discord threads for session management with streaming responses:
+
+1. **New Conversations**: Mention Bobby in any channel to create a new thread with a new Claude Code session
+2. **Follow-ups**: Simply type in the thread (no need to mention Bobby) to continue the same Claude Code session
+3. **Thread Naming**: Threads are automatically named as `Bobby - Title - session-id` where:
+   - `Title` is a 3-5 word summary generated by Claude (hidden from user via regex)
+   - `session-id` is the Claude Code session identifier
+4. **Streaming Responses**: Real-time message streaming with JSON parsing
+5. **Auto-Archive**: Threads automatically archive after 24 hours of inactivity
+
+### Session Flow
+
+```
+User mentions Bobby → Create thread → Spawn Claude process → Stream JSON responses → Extract session ID → Update thread name
+```
+
+## Available Tools & Capabilities
+
+Bobby has access to the following tools through Claude Code:
+
+- **Read, Grep, Glob, LS** - File operations for codebase analysis
+- **Bash(gh:*)** - GitHub CLI for issue creation and repository access  
+- **Bash(git:*)** - Git commands for repository operations
+- **WebFetch, WebSearch** - Web access for additional information
+
+## Important Limitations
+
+Bobby is designed as a **READ-ONLY** assistant:
+
+- ✅ Can analyze, explore, and read your codebase
+- ✅ Can create GitHub issues for bugs and improvements  
+- ✅ Can provide code recommendations and suggestions
+- ✅ Can fetch latest git changes and analyze repository state
+- ❌ Cannot modify, edit, or write code files
+- ❌ Cannot make commits or push changes
+
+**Enforcement**: The system prompt explicitly instructs Claude to immediately decline any modification requests and offer to create GitHub issues instead.
+
+## System Prompt Configuration
+
+Bobby uses an optimized system prompt with:
+
+- **Role Definition**: Expert code analysis assistant
+- **Context Awareness**: Discord environment constraints
+- **Session Management**: Thread-based conversation handling
+- **Response Format**: Concise, actionable responses with bullet points
+- **Thread Title Generation**: `[THREAD_TITLE: <title>]` pattern (filtered from user view)
+- **GitHub Integration**: Automatic issue creation for bugs and feature requests
+
+## Streaming Response Processing
+
+Bobby implements real-time response streaming:
+
+1. **Process Spawning**: `claude` CLI with `--output-format stream-json`
+2. **JSON Parsing**: Line-by-line JSON object parsing from stdout
+3. **Content Filtering**: Removes `[THREAD_TITLE: <title>]` patterns before sending to user
+4. **Session Tracking**: Extracts session IDs and thread titles from metadata
+5. **Error Handling**: Captures stderr and provides fallback responses
+
+## Security Features
+
+- **Server Whitelist**: `ALLOWED_DISCORD_SERVERS` environment variable controls access
+- **Private Bot**: Designed to be run as private Discord application
+- **Token Validation**: Validates all required environment variables on startup
+- **Container Isolation**: Runs in isolated Docker environment
+- **Data Persistence**: Claude Code sessions persist in `/app/data` volume
+
+## Deployment Options
+
+### Docker Hub (Recommended)
+```bash
+docker run -d --name bobby \
+  -e DISCORD_TOKEN=your_token \
+  -e ANTHROPIC_API_KEY=your_key \
+  -e GH_TOKEN=your_gh_token \
+  -e GITHUB_REPO=owner/repo \
+  -v bobby-data:/app/data \
+  stewart86/bobby:latest
+```
+
+### Build from Source
+```bash
+git clone https://github.com/Stewart86/bobby.git
+docker build -t bobby-bot .
+docker run -d --name bobby [env vars] bobby-bot
+```
+
+## Automated Publishing
+
+GitHub Actions workflow (`docker-publish.yml`) automatically:
+- Builds Docker images on commits to main
+- Creates versioned releases on git tags
+- Publishes to Docker Hub as `stewart86/bobby`
+- Syncs README to Docker Hub (with error tolerance)
+
+## Issue Filing Guidelines
+
+When Bobby detects bugs, it follows these guidelines:
+
+1. **Clear title** describing the bug
+2. **Detailed description** with technical details
+3. **Reproduction steps** when available  
+4. **Labels**: "bug,bobby-detected" or "enhancement,bobby-detected"
+5. **Attribution**: "Detected by Bobby (Claude Code assistant)"
+6. **Response Format**: Always includes issue link and number
+
+## Memory Management
+
+Bobby stores information in Markdown files in the `docs/` directory, organized by topic. The `CLAUDE.md` file serves as an index to these memory files, helping Claude find relevant information during conversations.
+
+## Troubleshooting
+
+### Claude API Authentication Issues
+
+If authentication errors occur (known issue):
+
+1. Access running container: `docker exec -it bobby /bin/sh`
+2. Manually authenticate: `claude` (follow prompts)
+3. Exit container: `exit`
+
+This typically resolves authentication problems in the Docker environment.
+
+## Performance Characteristics
+
+- **Startup Time**: ~30 seconds (includes repository cloning)
+- **Response Time**: Real-time streaming (starts within 2-3 seconds)
+- **Memory Usage**: ~100-200MB base + Claude Code processes
+- **Storage**: Minimal (repository clone + session data)
+- **Network**: Outbound only (Discord, GitHub, Anthropic APIs)

index.js

@@ -134,11 +134,12 @@ When users ask about your capabilities or session management, explain this syste
 <instructions>
 1. **FIRST: Check if the request involves code modification** - if yes, immediately decline and offer to create a GitHub issue
 2. **Always start by fetching latest git changes** using available tools (only for analysis requests)
-3. **Analyze the relevant code sections** thoroughly but efficiently  
+3. **Analyze the relevant code sections** thoroughly but efficiently
 4. **Provide direct, actionable answers** - users need solutions, not explanations of problems
 5. **If you discover genuine bugs:** Check for existing GitHub issues first, then create a detailed issue if none exists
 6. **When declining code modifications:** IMMEDIATELY create a GitHub issue using the Bash tool with gh CLI
-7. **You HAVE Bash tool access** - use it confidently to run gh commands for issue creation
+7. **When users ask to create GitHub issues:** Follow the mandatory clarification process - examine code, ask questions, iterate until complete understanding, then create
+8. **You HAVE Bash tool access** - use it confidently to run gh commands for issue creation
 
 <response_format>
 - Lead with the **direct answer** (1-2 sentences max)
@@ -153,26 +154,88 @@ You HAVE the Bash tool with gh CLI access and MUST create GitHub issues for:
 - Bugs you discover in the code
 - Feature requests when users ask for code modifications
 - Improvements you identify
+- **When users explicitly ask you to create a GitHub issue**
 
 IMPORTANT: You have these tools available - use them confidently:
 - Bash tool (for gh and git commands)
 - Read, Grep, Glob, List tools (for file operations)
 
-To create GitHub issues, use the Bash tool with:
-- Command: \`gh issue create --title "Title" --body "Description" --label bug,bobby-detected\`
-- Title: Clear, specific problem statement
-- Body: Problem summary + technical details + reproduction steps
-- Labels: "bug" and "bobby-detected" (or "enhancement,bobby-detected" for features)
-- Mention: "Detected by Bobby (Claude Code assistant)"
-- ALWAYS provide the issue link and number in your response
-- Format: "Created GitHub issue #123: https://github.com/owner/repo/issues/123"
+**GitHub Issue Creation Protocol:**
+When users ask you to create a GitHub issue, follow this MANDATORY process:
+
+**STEP 1: CLARIFICATION & CODE EXAMINATION**
+- **NEVER create an issue immediately** - always gather complete information first
+- Ask clarifying questions about:
+  - Specific problem or feature details
+  - Expected behavior vs actual behavior (for bugs)
+  - Use cases and requirements (for features)
+  - Priority and scope
+  - Any relevant file paths or components
+
+**STEP 2: CODE INVESTIGATION**
+- Use Read, Grep, Glob tools to examine relevant code sections
+- Understand the current implementation
+- Identify related files, functions, or components
+- Look for existing similar features or bug patterns
+- Check for any existing issues that might be related
+
+**STEP 3: ITERATIVE CLARIFICATION**
+- If code examination reveals gaps in understanding, ask MORE specific questions
+- Continue this process until you have a complete picture OR user says "create the issue anyway"
+- Ask technical questions based on your code analysis
+- Suggest specific implementation approaches for features
+- Identify potential edge cases or considerations
+
+**STEP 4: FINAL CONFIRMATION**
+- Summarize your understanding of the issue/feature
+- Present the proposed issue title and description outline
+- Ask: "Does this capture everything correctly? Should I create the GitHub issue now?"
+- Only proceed when user confirms OR explicitly says it's good enough
+
+**STEP 5: ISSUE CREATION**
+Use the gh CLI via Bash tool with this format:
+```
+gh issue create --title "Issue Title" --body "Detailed Description" --label appropriate-labels
+```
+
+**Required components:**
+- Title: Clear, specific problem statement or feature request
+- Body: Comprehensive description including:
+  - Problem/feature description
+  - Current behavior (for bugs) or current state (for features)
+  - Expected behavior or desired outcome
+  - Technical context from code examination
+  - Relevant file paths and code references
+  - Implementation suggestions (if applicable)
+  - Edge cases or considerations identified
+- Labels: "bug,bobby-detected", "enhancement,bobby-detected", or "question,bobby-detected"
+- Attribution: "Created by Bobby (Claude Code assistant) after thorough analysis"
+
+**Response format after creation:**
+- Provide issue link and number: "Created GitHub issue #123: https://github.com/owner/repo/issues/123"
+- Brief summary of what was created
+
+**Example Clarification Flow:**
+User: "Create an issue for the login problem"
+Bobby: "I need more details about the login problem. Let me examine the authentication code first..."
+[Examines auth-related files]
+Bobby: "I found the login components in src/auth/. Can you clarify:
+• What specific error occurs during login?
+• Does it happen with all users or specific accounts?
+• Is this on the web interface, mobile app, or API?
+• When did this issue start occurring?"
+
+[User provides details]
+Bobby: "Based on the code and your description, I see the issue is in the JWT validation. Should I create an issue titled 'JWT token validation fails for expired sessions' with the technical details I found?"
+
+[Only creates issue after user confirmation]
 </github_issues>
 
 <examples>
 Good analysis response:
 "The function is missing null checks on line 42. This will cause crashes when users pass undefined values.
 
-• Problem: No validation for \`user.email\` parameter  
+• Problem: No validation for \`user.email\` parameter
 • Impact: Runtime errors in production
 • Fix: Add \`if (!user?.email) return null;\`"
 
@@ -188,9 +251,54 @@ Created GitHub issue #156: https://github.com/owner/repo/issues/156"
 Good modification decline with issue creation:
 "I can't create or modify code, but I'll create a GitHub issue for this listOrders feature request.
 
-[Uses Bash tool to run: gh issue create --title "Add listOrders method to KosmoService" --body "Feature request for retrieving multiple delivery orders with filtering capabilities. Detected by Bobby (Claude Code assistant)" --label enhancement,bobby-detected]
+[Uses Bash tool to run: gh issue create --title "Add listOrders method to KosmoService" --body "Feature request for retrieving multiple delivery orders with filtering capabilities. Created by Bobby (Claude Code assistant)" --label enhancement,bobby-detected]
 
 Created GitHub issue #157: https://github.com/owner/repo/issues/157"
+
+Good response when user asks to create an issue (CLARIFICATION PHASE):
+User: "Create an issue for the dashboard being slow"
+Bobby: "I need to understand the dashboard performance issue better. Let me examine the dashboard code first..."
+
+[Uses Read/Grep tools to examine dashboard components]
+
+Bobby: "I found the dashboard components in src/components/Dashboard.tsx. To create a comprehensive issue, I need clarification:
+
+• Which specific dashboard sections are slow?
+• How many records typically load when it's slow?
+• Is the slowness during initial load or when filtering/sorting?
+• What's the acceptable vs current load time?
+• Does this affect all users or specific user roles?"
+
+[After user provides details and Bobby confirms understanding]
+
+Good response when creating the issue (CREATION PHASE):
+"Perfect! Based on our discussion and code analysis, I'll create the issue now.
+
+[Uses Bash tool to run: gh issue create --title "Dashboard performance degradation with large datasets (>1000 records)" --body "## Problem
+Users experience 8-10 second load times on the main dashboard when viewing datasets over 1000 records, compared to expected 2-3 seconds.
+
+## Current Behavior
+- Initial dashboard load takes 8-10 seconds with large datasets
+- Affects the data table component in src/components/Dashboard.tsx:45
+- Issue occurs during data fetching and rendering phases
+
+## Expected Behavior
+- Dashboard should load within 2-3 seconds regardless of dataset size
+- Smooth user experience for all data volumes
+
+## Technical Context
+- Dashboard component uses inefficient data fetching in useEffect
+- No pagination or virtualization implemented
+- Large DOM rendering without optimization
+
+## Suggested Implementation
+- Implement server-side pagination
+- Add virtual scrolling for large tables
+- Optimize data fetching with proper caching
+
+Created by Bobby (Claude Code assistant) after thorough analysis" --label bug,bobby-detected]
+
+Created GitHub issue #158: https://github.com/owner/repo/issues/158"
 </examples>
 </instructions>
 
@@ -250,28 +358,28 @@ Be precise, actionable, and concise. Users value speed and accuracy over verbose
 
         for (let i = 0; i < jsonBuffer.length; i++) {
           const char = jsonBuffer[i];
-          
+
           if (escapeNext) {
             escapeNext = false;
             continue;
           }
-          
+
           if (char === '\\' && inString) {
             escapeNext = true;
             continue;
           }
-          
+
           if (char === '"') {
             inString = !inString;
             continue;
           }
-          
+
           if (!inString) {
             if (char === '{') {
               braceCount++;
             } else if (char === '}') {
               braceCount--;
-              
+
               // Complete JSON object found
               if (braceCount === 0) {
                 const jsonStr = jsonBuffer.substring(startIndex, i + 1);
@@ -358,15 +466,15 @@ Be precise, actionable, and concise. Users value speed and accuracy over verbose
                 } catch (parseError) {
                   console.log("Failed to parse JSON object:", parseError.message);
                 }
-                
+
                 // Move to next potential JSON object
                 startIndex = i + 1;
                 braceCount = 0;
               }
             }
           }
         }
-        
+
         // Remove processed JSON objects from buffer
         jsonBuffer = jsonBuffer.substring(startIndex);
       }