ScaledMinds
diff --git a/‎docs/guides/github-project-management.md‎
Lines changed: 349 additions & 0 deletions b/‎docs/guides/github-project-management.md‎
Lines changed: 349 additions & 0 deletions
@@ -0,0 +1,349 @@
+# GitHub Project Management for AgentCodeX
+
+## Overview
+
+AgentCodeX uses GitHub Issues + Projects for transparent backlog management.
+
+---
+
+## Quick Start
+
+### 1. Enable GitHub Projects
+
+```bash
+# View project boards
+gh project list --owner ScaledMinds
+
+# Or create new board
+gh project create --title "AgentCodeX v2.4.0" --owner ScaledMinds
+```
+
+### 2. Create Issues from Specs
+
+```bash
+# From your spec file, create issues
+gh issue create --title "Implement GPU Compute Service" \
+  --body "Priority #1 for v2.4.0
+
+See full spec: docs/roadmap/v2.4.0-SHARED-SERVICES-SPEC.md
+
+**Tasks:**
+- [ ] vLLM integration (LLaMA 3, Mixtral)
+- [ ] Failover logic to OpenAI, Anthropic, OpenRouter
+- [ ] Health monitoring & latency detection
+- [ ] Cost attribution & savings tracking
+
+**Success Criteria:**
+- P95 latency < 500ms on GPU
+- Failover triggers in < 5s
+- 70% cost reduction vs cloud-only
+" \
+  --label "enhancement,v2.4.0,priority:high"
+```
+
+### 3. Work on Feature
+
+```bash
+# Create branch from issue #125
+git checkout -b feature/125-gpu-compute-service
+
+# Make changes
+git add .
+git commit -m "feat: Add GPU compute service with vLLM
+
+Implements #125
+- vLLM server integration
+- Health check endpoints
+- Failover logic to cloud providers
+"
+
+# Push to GitHub
+git push -u origin feature/125-gpu-compute-service
+```
+
+### 4. Create Pull Request
+
+```bash
+# Create PR that closes the issue
+gh pr create \
+  --title "Add GPU Compute Service" \
+  --body "Closes #125
+
+## Summary
+Implements internal GPU compute with intelligent failover.
+
+## Changes
+- New service: `shared-services/gpu-compute/`
+- vLLM integration for LLaMA 3, Mixtral
+- Automatic failover to OpenAI, Anthropic, OpenRouter
+- Health monitoring with 5 failover triggers
+
+## Testing
+- [x] GPU latency < 500ms
+- [x] Failover triggers work
+- [x] Cost attribution accurate
+
+## Screenshots
+(Grafana dashboard showing 70% GPU usage, 30% cloud failover)
+" \
+  --label "enhancement,v2.4.0"
+```
+
+### 5. Code Review
+
+```bash
+# Request reviews
+gh pr edit 125 --add-reviewer @teammate1,@teammate2
+
+# View PR checks
+gh pr checks
+
+# View comments
+gh pr view 125 --comments
+```
+
+### 6. Merge
+
+```bash
+# Merge PR (auto-closes issue #125)
+gh pr merge 125 --squash --delete-branch
+```
+
+---
+
+## Project Board Setup
+
+### Columns
+
+Create these columns in your GitHub Project:
+
+1. **📋 Backlog** - Future features
+2. **🎯 Ready** - Prioritized, ready to start
+3. **🚧 In Progress** - Currently being worked on
+4. **👀 Review** - PR created, waiting for review
+5. **✅ Done** - Merged to main
+
+### Automation
+
+GitHub automatically moves issues:
+- Issue created → Backlog
+- PR created → In Progress
+- PR ready for review → Review
+- PR merged → Done
+
+---
+
+## Labels
+
+### Priority
+- `priority:critical` - Blocking, fix now
+- `priority:high` - Important, next sprint
+- `priority:medium` - Nice to have
+- `priority:low` - Future consideration
+
+### Type
+- `bug` - Something broken
+- `enhancement` - New feature
+- `documentation` - Docs update
+- `technical-debt` - Refactoring
+
+### Version
+- `v2.3.0` - Current release
+- `v2.4.0` - Shared services platform
+- `v2.5.0` - ORACLE implementation
+
+### Component
+- `cli` - CLI changes
+- `agents` - Agent updates
+- `infrastructure` - Docker, Traefik, etc.
+- `shared-services` - Platform services
+
+---
+
+## Example: v2.4.0 Shared Services Backlog
+
+### Create Issues
+
+```bash
+# Epic issue
+gh issue create --title "[EPIC] Shared Services Platform v2.4.0" \
+  --body "See docs/roadmap/v2.4.0-SHARED-SERVICES-SPEC.md" \
+  --label "epic,v2.4.0"
+
+# Task issues
+gh issue create --title "Implement GPU Compute Service" --label "enhancement,v2.4.0,priority:high"
+gh issue create --title "Create PLATFORM agent" --label "enhancement,v2.4.0,priority:high"
+gh issue create --title "Create SERVICE-FORGE agent" --label "enhancement,v2.4.0,priority:high"
+gh issue create --title "Add init-platform CLI command" --label "enhancement,v2.4.0,priority:medium"
+gh issue create --title "Add add-service CLI command" --label "enhancement,v2.4.0,priority:medium"
+gh issue create --title "Document GPU failover architecture" --label "documentation,v2.4.0"
+```
+
+### Link Issues to Epic
+
+In each task issue description, add:
+```
+Part of #123 (Epic: Shared Services Platform)
+```
+
+---
+
+## Best Practices
+
+### ✅ Do:
+- Create issue before starting work
+- Reference issue in commits (`Implements #123`)
+- Use PRs for all changes (even small ones)
+- Request reviews before merging
+- Keep PRs small (< 500 lines changed)
+- Update issue with progress notes
+
+### ❌ Don't:
+- Commit directly to main (except hotfixes)
+- Create PRs without linked issue
+- Merge your own PRs (get review first)
+- Leave stale branches (delete after merge)
+
+---
+
+## Workflow Comparison
+
+### Local-Only (Current)
+```
+1. Edit REVIEW-FINDINGS.md
+2. Fix code
+3. Commit to main
+4. Push to GitHub
+```
+**Pros:** Fast, simple
+**Cons:** No review, no tracking
+
+### GitHub Projects (Recommended)
+```
+1. Create issue (#125)
+2. Create branch (feature/125-gpu-service)
+3. Fix code
+4. Create PR (closes #125)
+5. Review + merge
+```
+**Pros:** Transparent, collaborative, tracked
+**Cons:** Slightly slower (worth it!)
+
+---
+
+## Migration for AgentCodeX
+
+### Step 1: Enable Projects
+
+1. Go to https://github.com/ScaledMinds/AgentCodeX/projects
+2. Click "New Project"
+3. Choose "Board" template
+4. Name: "AgentCodeX v2.4.0"
+
+### Step 2: Import Current Backlog
+
+Convert `REVIEW-FINDINGS.md` to issues:
+
+```bash
+# Critical issues from review
+gh issue create --title "Fix agentcodex init command" --label "bug,priority:critical" --body "See REVIEW-FINDINGS.md line 45"
+
+# Already fixed - close with note
+gh issue create --title "Update agent count 21→23" --label "bug,v2.3.0" --body "Fixed in commit 14669fc" --close
+```
+
+### Step 3: Future Work as Issues
+
+```bash
+# v2.4.0 features
+gh issue create --title "GPU Compute Service" --label "enhancement,v2.4.0"
+gh issue create --title "Shared Services Platform" --label "enhancement,v2.4.0"
+
+# v2.5.0 features
+gh issue create --title "Implement ORACLE agent" --label "enhancement,v2.5.0"
+gh issue create --title "Template variable system" --label "enhancement,v2.4.0"
+```
+
+### Step 4: Protect Main Branch
+
+```bash
+# Require PRs for main branch
+gh api repos/ScaledMinds/AgentCodeX \
+  --method PATCH \
+  --field default_branch=main
+
+# Require reviews
+# (Do this in GitHub UI: Settings → Branches → Add rule)
+```
+
+---
+
+## Sample PR Template
+
+Create `.github/pull_request_template.md`:
+
+```markdown
+## Description
+<!-- What does this PR do? -->
+
+Closes #(issue number)
+
+## Changes
+<!-- List main changes -->
+-
+-
+
+## Testing
+<!-- How did you test? -->
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual testing complete
+
+## Screenshots
+<!-- If UI changes -->
+
+## Checklist
+- [ ] Code follows project style
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented)
+- [ ] Tests added/updated
+```
+
+---
+
+## Useful Commands
+
+```bash
+# List open issues
+gh issue list --label v2.4.0
+
+# List PRs
+gh pr list
+
+# View issue
+gh issue view 125
+
+# Add comment to issue
+gh issue comment 125 --body "Starting work on this"
+
+# Close issue
+gh issue close 125 --comment "Fixed in PR #130"
+
+# Create draft PR
+gh pr create --draft --title "WIP: GPU Service"
+
+# Mark PR ready for review
+gh pr ready 130
+```
+
+---
+
+## Resources
+
+- [GitHub Issues Guide](https://docs.github.com/en/issues)
+- [GitHub Projects Guide](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
+- [GitHub CLI Manual](https://cli.github.com/manual/)
+
+---
+
+**Start using GitHub Projects for v2.4.0 and beyond!** ✅