docuseal/docs/backlog/QUICKSTART_GITHUB_PROJECTS.md

Quick Start - GitHub Projects Populator

🚀 One-Command Setup (Recommended)

# From the project root
cd docs/backlog && ./populate_github_project.sh NeoSkosana floDoc-v3 6

📋 Prerequisites (5 minutes)

1. Install GitHub CLI

# macOS
brew install gh

# Ubuntu/Debian
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt install gh

2. Authenticate

gh auth login
# Follow the browser prompts

3. Install Extension

gh extension install mislav/gh-project

🎯 Run the Script

# Make executable (first time only)
chmod +x docs/backlog/populate_github_project.sh

# Run it
./docs/backlog/populate_github_project.sh NeoSkosana floDoc-v3 6

Parameters:

• NeoSkosana - Your GitHub username
• floDoc-v3 - Your repository name
• 6 - Your project number (from URL)

📊 What Happens

1. Parses all 42 stories from docs/prd/6-epic-details.md
2. Creates GitHub issues for each story
3. Adds labels (epic, priority, risk, portal type)
4. Adds issues to your project board
5. Generates summary file: docs/backlog/github_project_summary.md

🎨 Issue Format

Each issue contains:

[1.1] Database Schema Extension

## 📖 User Story
As a system architect, I want to create the database schema...

## 📋 Background
Based on the PRD analysis, we need three new tables...

## ✅ Acceptance Criteria
Functional:
1. ✅ All three tables created with correct schema
...

## 📊 Metadata
- Story Number: 1.1
- Epic: Phase 1 - Foundation
- Priority: Critical
- Estimated Effort: 2-3 days
- Risk Level: Low
- Status: Draft

🏷️ Labels Applied

• story:1.1 - Story identifier
• epic:phase-1-foundation - Epic/phase
• priority:critical - Priority level
• risk:low - Risk level
• status:draft - Current status
• portal:backend - Portal type

🔍 Troubleshooting

Problem: gh: command not found

Solution: Install GitHub CLI from https://cli.github.com/

Problem: Not authenticated

Solution: Run gh auth login

Problem: Cannot add to project

Solution: Add issues manually via GitHub UI (issues are still created)

Problem: Permission denied on script

Solution: chmod +x docs/backlog/populate_github_project.sh

📝 Manual Alternative (Python)

If you prefer Python or don't have GitHub CLI:

# Install dependencies
pip install requests

# Run with token
python docs/backlog/populate_github_project.py \
  --token YOUR_GITHUB_TOKEN \
  --owner NeoSkosana \
  --repo floDoc-v3 \
  --project 6

Get token from: GitHub → Settings → Developer settings → Personal access tokens

📂 Files Created

File	Description
github_project_summary.md	Complete story reference with links
GitHub Issues (42)	Individual story issues
Project Board Cards	Visual kanban cards

🎯 Next Steps

1. Review the summary file: cat docs/backlog/github_project_summary.md
2. Visit your project: https://github.com/users/NeoSkosana/projects/6
3. Organize issues into columns (Todo, In Progress, Done)
4. Start with Story 1.1 (Database Schema Extension)
5. Follow the BMad workflow in CLAUDE.md

📚 More Info

• Full Guide: docs/backlog/GITHUB_PROJECT_SETUP.md
• Story Index: docs/backlog/STORIES_INDEX.md
• Story Summary: docs/backlog/STORIES_SUMMARY.md
• Presentation: docs/backlog/stories-presentation.html

---

Need help? Check the full guide at docs/backlog/GITHUB_PROJECT_SETUP.md