# GitHub Backlog Generator 🐷✨
<div align="center">
<img src="https://img.shields.io/badge/Flying%20Pig%20Labs-Python%20Edition-ff69b4?style=for-the-badge&logo=python&logoColor=white" alt="Flying Pig Labs Python">
**Enterprise-Grade AI-Powered GitHub Backlog Generation**
Transform any GitHub README into a comprehensive project backlog optimized for Claude Flow SPARC agents.
Part of the [Flying Pig Labs](https://www.flyingpig.ai) Innovation Stack
[](https://pypi.org/project/github-backlog-generator/)
[](https://pypi.org/project/github-backlog-generator/)
[](https://opensource.org/licenses/MIT)
</div>
## 🚀 Overview
A powerful Python CLI tool that takes a GitHub repository URL, analyzes its README with AI, and automatically creates a complete project backlog including milestones, epics, and detailed task issues - all formatted for autonomous AI agent execution.
## Features
- **GitHub URL Input**: Takes any GitHub repository URL as a CLI argument
- **Interactive Phase Selection**: Choose which phase (1-8) to generate
- **Single AI Call**: Efficiently generates phase, epic, and tasks in one LLM request
- **Complete Backlog Creation**: Automatically generates:
- GitHub Milestone for the phase (with due date)
- Epic issue (labeled "[Epic]") containing team composition and task checklist
- Individual task issues linked to the epic with role assignments
- **Smart Analysis**: Extracts project domain, complexity, tech stack from README
- **Retry Logic**: Automatically retries if AI response format is incorrect
- **Dry Run Mode**: Preview phase before creating GitHub content
- **JSON Export**: Save generated phase for later use
## Installation
```bash
# Clone the repository
git clone <your-repo-url>
cd github-backlog-generator
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
```
## Configuration
1. Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
2. Add your API keys:
```
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GITHUB_TOKEN=your_github_token_here
```
**Note**: GitHub token must have `repo` scope to create milestones.
## Usage
### Basic Usage
```bash
# Run the tool - it will prompt you to select a phase
python run.py https://github.com/owner/repo
# Or use shorthand format
python run.py owner/repo
```
The tool will:
1. Fetch and analyze the README
2. Show project information
3. List all 8 phases
4. Prompt you to enter a number (1-8) to select a phase
5. Generate the phase with AI
6. Create a milestone in GitHub
7. Generate an epic with 5-10 tasks
8. Create an epic issue with task checklist
9. Create individual task issues linked to the epic
### Command Options
```bash
python run.py [OPTIONS] REPO_URL
Arguments:
REPO_URL GitHub repository URL (e.g., https://github.com/owner/repo)
Options:
--api-key TEXT Anthropic API key (or use ANTHROPIC_API_KEY env var)
--github-token TEXT GitHub token (or use GITHUB_TOKEN env var)
--dry-run Generate phases without creating milestones
-o, --output PATH Save phases to JSON file
--help Show this message and exit
```
### Examples
```bash
# Dry run to preview phase without creating milestone
python run.py https://github.com/facebook/react --dry-run
# Then select phase number when prompted
# Create milestone and save phase to file
python run.py owner/repo --output phase.json
# Use different API keys
python run.py owner/repo --api-key sk-ant-... --github-token ghp_...
```
### Interactive Selection Example
```
Select a phase to generate:
1. Discovery & Requirements
2. Technical Planning & Architecture
3. UI/UX Design & Prototyping
4. Core Development
5. System Integration & Testing
6. Quality Assurance & Testing
7. Deployment & Distribution
8. Launch & Documentation
Enter phase number (1-8): 1
```
## Workflow
1. **Parse URL**: Extracts owner and repository name from GitHub URL
2. **Validate Access**: Checks that your token has write access to the repo
3. **Sparse Checkout**: Fetches only the README file from the repository
4. **Analyze README**: Extracts project information:
- Title and description
- Technology stack
- Project domain (web, mobile, AI, etc.)
- Complexity assessment
5. **Generate Phases**: AI creates 8 SDLC phases with:
- Unique IDs
- Descriptive titles
- Detailed descriptions
- Suggested roles
- Due dates (14 days apart)
6. **Interactive Selection**: User selects which phase to generate
7. **Create Milestone**: Pushes single milestone directly to GitHub
## Generated Phases
The tool creates 8 standard SDLC phases, customized for your project:
1. **Discovery & Requirements** - Initial analysis and planning
2. **Technical Planning & Architecture** - System design and tech selection
3. **UI/UX Design & Prototyping** - User interface and experience design
4. **Core Development** - Main feature implementation
5. **System Integration & Testing** - Integration and API testing
6. **Quality Assurance & Testing** - Comprehensive testing and fixes
7. **Deployment & Distribution** - Packaging and deployment setup
8. **Launch & Documentation** - Documentation and go-to-market
## Output Format
Milestones are created with:
- **Title**: "Phase N: Phase Title"
- **Description**: Detailed phase description
- **Due Date**: Calculated 14 days apart
- **State**: Open
JSON output includes:
```json
{
"repository": "owner/repo",
"project": {
"title": "Project Name",
"domain": "web",
"complexity": "moderate"
},
"phases": [
{
"id": "discovery",
"title": "Discovery & Requirements",
"description": "...",
"suggestedRoles": ["Product Owner", "UX Researcher"],
"dueDate": "2025-08-04"
}
]
}
```
## Requirements
- Python 3.8+
- Git (for sparse checkout)
- Anthropic API key
- GitHub personal access token with `repo` scope
## Error Handling
- Validates repository access before attempting to create milestones
- Handles various GitHub URL formats
- Checks for existing milestones to avoid duplicates
- Provides clear error messages for common issues
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/github-backlog-generator",
"name": "github-backlog-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "github, backlog, project-management, cli, developer-tools",
"author": "William Prior",
"author_email": "Flying Pig Labs <ford@flyingpig.ai>",
"download_url": "https://files.pythonhosted.org/packages/b4/72/d4e3df5f80624874be8fa5deea2a0e3f8d84f635f65524de820740c5539e/github_backlog_generator-1.0.0.tar.gz",
"platform": null,
"description": "# GitHub Backlog Generator \ud83d\udc37\u2728\n\n<div align=\"center\">\n\n<img src=\"https://img.shields.io/badge/Flying%20Pig%20Labs-Python%20Edition-ff69b4?style=for-the-badge&logo=python&logoColor=white\" alt=\"Flying Pig Labs Python\">\n\n**Enterprise-Grade AI-Powered GitHub Backlog Generation**\n\nTransform any GitHub README into a comprehensive project backlog optimized for Claude Flow SPARC agents.\n\nPart of the [Flying Pig Labs](https://www.flyingpig.ai) Innovation Stack\n\n[](https://pypi.org/project/github-backlog-generator/)\n[](https://pypi.org/project/github-backlog-generator/)\n[](https://opensource.org/licenses/MIT)\n\n</div>\n\n## \ud83d\ude80 Overview\n\nA powerful Python CLI tool that takes a GitHub repository URL, analyzes its README with AI, and automatically creates a complete project backlog including milestones, epics, and detailed task issues - all formatted for autonomous AI agent execution.\n\n## Features\n\n- **GitHub URL Input**: Takes any GitHub repository URL as a CLI argument\n- **Interactive Phase Selection**: Choose which phase (1-8) to generate\n- **Single AI Call**: Efficiently generates phase, epic, and tasks in one LLM request\n- **Complete Backlog Creation**: Automatically generates:\n - GitHub Milestone for the phase (with due date)\n - Epic issue (labeled \"[Epic]\") containing team composition and task checklist\n - Individual task issues linked to the epic with role assignments\n- **Smart Analysis**: Extracts project domain, complexity, tech stack from README\n- **Retry Logic**: Automatically retries if AI response format is incorrect\n- **Dry Run Mode**: Preview phase before creating GitHub content\n- **JSON Export**: Save generated phase for later use\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone <your-repo-url>\ncd github-backlog-generator\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n## Configuration\n\n1. Copy `.env.example` to `.env`:\n ```bash\n cp .env.example .env\n ```\n\n2. Add your API keys:\n ```\n ANTHROPIC_API_KEY=your_anthropic_api_key_here\n GITHUB_TOKEN=your_github_token_here\n ```\n\n **Note**: GitHub token must have `repo` scope to create milestones.\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Run the tool - it will prompt you to select a phase\npython run.py https://github.com/owner/repo\n\n# Or use shorthand format\npython run.py owner/repo\n```\n\nThe tool will:\n1. Fetch and analyze the README\n2. Show project information\n3. List all 8 phases\n4. Prompt you to enter a number (1-8) to select a phase\n5. Generate the phase with AI\n6. Create a milestone in GitHub\n7. Generate an epic with 5-10 tasks\n8. Create an epic issue with task checklist\n9. Create individual task issues linked to the epic\n\n### Command Options\n\n```bash\npython run.py [OPTIONS] REPO_URL\n\nArguments:\n REPO_URL GitHub repository URL (e.g., https://github.com/owner/repo)\n\nOptions:\n --api-key TEXT Anthropic API key (or use ANTHROPIC_API_KEY env var)\n --github-token TEXT GitHub token (or use GITHUB_TOKEN env var)\n --dry-run Generate phases without creating milestones\n -o, --output PATH Save phases to JSON file\n --help Show this message and exit\n```\n\n### Examples\n\n```bash\n# Dry run to preview phase without creating milestone\npython run.py https://github.com/facebook/react --dry-run\n# Then select phase number when prompted\n\n# Create milestone and save phase to file\npython run.py owner/repo --output phase.json\n\n# Use different API keys\npython run.py owner/repo --api-key sk-ant-... --github-token ghp_...\n```\n\n### Interactive Selection Example\n\n```\nSelect a phase to generate:\n\n 1. Discovery & Requirements\n 2. Technical Planning & Architecture\n 3. UI/UX Design & Prototyping\n 4. Core Development\n 5. System Integration & Testing\n 6. Quality Assurance & Testing\n 7. Deployment & Distribution\n 8. Launch & Documentation\n\nEnter phase number (1-8): 1\n```\n\n## Workflow\n\n1. **Parse URL**: Extracts owner and repository name from GitHub URL\n2. **Validate Access**: Checks that your token has write access to the repo\n3. **Sparse Checkout**: Fetches only the README file from the repository\n4. **Analyze README**: Extracts project information:\n - Title and description\n - Technology stack\n - Project domain (web, mobile, AI, etc.)\n - Complexity assessment\n5. **Generate Phases**: AI creates 8 SDLC phases with:\n - Unique IDs\n - Descriptive titles\n - Detailed descriptions\n - Suggested roles\n - Due dates (14 days apart)\n6. **Interactive Selection**: User selects which phase to generate\n7. **Create Milestone**: Pushes single milestone directly to GitHub\n\n## Generated Phases\n\nThe tool creates 8 standard SDLC phases, customized for your project:\n\n1. **Discovery & Requirements** - Initial analysis and planning\n2. **Technical Planning & Architecture** - System design and tech selection\n3. **UI/UX Design & Prototyping** - User interface and experience design\n4. **Core Development** - Main feature implementation\n5. **System Integration & Testing** - Integration and API testing\n6. **Quality Assurance & Testing** - Comprehensive testing and fixes\n7. **Deployment & Distribution** - Packaging and deployment setup\n8. **Launch & Documentation** - Documentation and go-to-market\n\n## Output Format\n\nMilestones are created with:\n- **Title**: \"Phase N: Phase Title\"\n- **Description**: Detailed phase description\n- **Due Date**: Calculated 14 days apart\n- **State**: Open\n\nJSON output includes:\n```json\n{\n \"repository\": \"owner/repo\",\n \"project\": {\n \"title\": \"Project Name\",\n \"domain\": \"web\",\n \"complexity\": \"moderate\"\n },\n \"phases\": [\n {\n \"id\": \"discovery\",\n \"title\": \"Discovery & Requirements\",\n \"description\": \"...\",\n \"suggestedRoles\": [\"Product Owner\", \"UX Researcher\"],\n \"dueDate\": \"2025-08-04\"\n }\n ]\n}\n```\n\n## Requirements\n\n- Python 3.8+\n- Git (for sparse checkout)\n- Anthropic API key\n- GitHub personal access token with `repo` scope\n\n## Error Handling\n\n- Validates repository access before attempting to create milestones\n- Handles various GitHub URL formats\n- Checks for existing milestones to avoid duplicates\n- Provides clear error messages for common issues\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enterprise-grade AI-powered tool to transform GitHub README files into comprehensive project backlogs optimized for Claude Flow SPARC agents",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/ford-at-home/agent-team-composer/issues",
"Company": "https://www.flyingpig.ai",
"Documentation": "https://github.com/ford-at-home/agent-team-composer#readme",
"Homepage": "https://www.flyingpig.ai",
"Repository": "https://github.com/ford-at-home/agent-team-composer"
},
"split_keywords": [
"github",
" backlog",
" project-management",
" cli",
" developer-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79d2730ec23ae563da4da3079766da52ad1d30ba714a5a54e3a11d1af14cef94",
"md5": "d8d09777375e684ba556ad21edd4d01e",
"sha256": "0c61199c95e1d36c3443b0aa4944feb06c96a4e7a53c2c1891a2f0f4acaddbfe"
},
"downloads": -1,
"filename": "github_backlog_generator-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8d09777375e684ba556ad21edd4d01e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 34540,
"upload_time": "2025-07-22T11:41:43",
"upload_time_iso_8601": "2025-07-22T11:41:43.835231Z",
"url": "https://files.pythonhosted.org/packages/79/d2/730ec23ae563da4da3079766da52ad1d30ba714a5a54e3a11d1af14cef94/github_backlog_generator-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b472d4e3df5f80624874be8fa5deea2a0e3f8d84f635f65524de820740c5539e",
"md5": "744ee304e8fcde213da7233f3c8962fa",
"sha256": "6deadb431e51bb66dda3512f96912b922b160fba4f087eb4eba82d84c01e74ca"
},
"downloads": -1,
"filename": "github_backlog_generator-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "744ee304e8fcde213da7233f3c8962fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27665,
"upload_time": "2025-07-22T11:41:44",
"upload_time_iso_8601": "2025-07-22T11:41:44.901471Z",
"url": "https://files.pythonhosted.org/packages/b4/72/d4e3df5f80624874be8fa5deea2a0e3f8d84f635f65524de820740c5539e/github_backlog_generator-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 11:41:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "github-backlog-generator",
"github_not_found": true,
"lcname": "github-backlog-generator"
}
JSON
