docuseal/docs/backlog/GITHUB_PROJECTS_SUMMARY.md

GitHub Projects Integration - Summary

✅ What Was Created

I've created a complete GitHub Projects integration system that will populate your project board with all 42 FloDoc user stories.

📁 Files Created

1. populate_github_project.sh (Shell Script - RECOMMENDED)

• Location: docs/backlog/populate_github_project.sh
• Size: 7.6KB
• Purpose: Uses GitHub CLI to create issues and add to project board
• Best for: Quick setup, easy to use

2. populate_github_project.py (Python Script)

• Location: docs/backlog/populate_github_project.py
• Size: 13KB
• Purpose: Uses GitHub API directly to create issues
• Best for: Advanced users, custom modifications

3. GITHUB_PROJECT_SETUP.md (Complete Guide)

• Location: docs/backlog/GITHUB_PROJECT_SETUP.md
• Size: 8KB
• Contents:
  • Prerequisites for both scripts
  • Step-by-step setup instructions
  • Troubleshooting guide
  • Customization options
  • Example workflow

4. QUICKSTART_GITHUB_PROJECTS.md (Quick Reference)

• Location: docs/backlog/QUICKSTART_GITHUB_PROJECTS.md
• Size: 3.8KB
• Contents:
  • One-command setup
  • 5-minute prerequisites
  • Troubleshooting
  • Quick reference

5. Updated README.md

• Location: docs/backlog/README.md
• Changes:
  • Added GitHub Projects Integration section
  • Added quick start guide
  • Added output description
  • Added contact section for GitHub help

🎯 How to Use (30-Second Guide)

# 1. Install GitHub CLI (if needed)
#    https://cli.github.com/

# 2. Authenticate
gh auth login

# 3. Install extension
gh extension install mislav/gh-project

# 4. Run the script
cd docs/backlog
./populate_github_project.sh NeoSkosana floDoc-v3 6

📊 What You'll Get

GitHub Issues (42 total)

Each issue includes:

• Title: [1.1] Database Schema Extension
• User Story: Full "As a... I want... So that..." format
• Background: Context and rationale
• Acceptance Criteria: All requirements
• Metadata: Story number, epic, priority, effort, risk, status
• Labels: For filtering and organization

Labels Applied

• story:X.X - Story identifier
• epic:phase-X-name - Epic/phase
• priority:critical/high/medium/low - Priority
• risk:low/medium/high - Risk level
• status:draft/in-progress/etc - Current status
• portal:admin/student/sponsor/backend/qa/infrastructure - Portal type

Generated Files

• github_project_summary.md - Complete reference with all stories and links

🎨 Example Output

Issue Title

[1.1] Database Schema Extension

Issue Body

## 📖 User Story

**As a** system architect,
**I want** to create the database schema for FloDoc's new models,
**So that** the application has the foundation to support cohort management.

## 📋 Background

Based on the PRD analysis, we need three new tables:
- institutions
- cohorts
- cohort_enrollments

## ✅ Acceptance Criteria

**Functional:**
1. ✅ All three tables created with correct schema
2. ✅ Foreign key relationships established
...

## 📊 Metadata

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

🏗️ Project Board Setup

Your project board should have these columns:

1. Todo - Stories not started
2. In Progress - Active work
3. In Review - Awaiting review
4. Done - Completed

After running the script, drag issues from "Todo" to other columns as work progresses.

🔍 Troubleshooting

Problem	Solution
gh: command not found	Install from https://cli.github.com/
Not authenticated	Run gh auth login
Permission denied	chmod +x populate_github_project.sh
Can't add to project	Issues still created; add manually via UI
Rate limit hit	Wait 60 minutes or use Python script with token

📚 Reference Files

File	Purpose
STORIES_INDEX.md	All 42 stories by phase
STORIES_SUMMARY.md	Quick story reference
stories-presentation.html	Interactive presentation
6-epic-details.md	Full story details (source)

🎯 Next Steps After Running Script

1. Review the summary file

   cat docs/backlog/github_project_summary.md
   

2. Visit your project board

   https://github.com/users/NeoSkosana/projects/6
   

3. Organize issues into columns

4. Start with Story 1.1 (Database Schema Extension)

5. Follow the BMad workflow from CLAUDE.md

📞 Need Help?

• Full Guide: docs/backlog/GITHUB_PROJECT_SETUP.md
• Quick Start: docs/backlog/QUICKSTART_GITHUB_PROJECTS.md
• Story Details: docs/backlog/STORIES_INDEX.md

---

Ready to go? Just run:

./populate_github_project.sh NeoSkosana floDoc-v3 6