# GitHub Masterclass -- LLMHosts.com Repository Strategy

## META
- relevance: CORE -- GitHub is the single source of truth for all code, planning, tracking, and automation
- created: 2026-02-13
- standard: Everything described here is mandatory when the repo is initialized (SEC-011)

## PHILOSOPHY

GitHub is not just "where the code lives." It is the **single source of truth** for:
- All code and configuration (obvious)
- All work tracking (Issues = backlog items, Projects = kanban board)
- All quality gates (PRs, reviews, status checks)
- All automation (Actions = CI/CD, testing, Docker builds, security scanning)
- All deployment artifacts (GHCR = container registry)
- All security (secret scanning, push protection, Dependabot)

When done right, the GitHub repo IS the project. The docs/ folder documents intent; GitHub tracks execution.

---

## REPOSITORY STRUCTURE

### Naming & Access
- **Repo**: `LLMHosts/llmhost` (or `brendon-llmhost/llmhost-platform`)
- **Visibility**: Private (until open-source components are extracted)
- **Default branch**: `main` (production-ready at all times)
- **Development branch**: `develop` (integration branch for features)

### Branch Strategy (GitHub Flow + Develop)
```
main (production-ready, protected)
  ↑ PR with required checks
develop (integration, protected)
  ↑ PR with required checks
feature/CB-001-conductor-api (feature branches)
fix/CF-002-hardware-discovery-amd
docs/update-roadmap-phase1
chore/update-dependencies
```

### Branch Naming Convention
- `feature/<backlog-id>-<short-description>` -- new functionality
- `fix/<backlog-id>-<short-description>` -- bug fixes
- `docs/<description>` -- documentation only
- `chore/<description>` -- maintenance, dependencies, configs
- `hotfix/<description>` -- emergency production fixes (branch from main)

---

## GITHUB ISSUES -- BACKLOG AS SOURCE OF TRUTH

### Issue Templates (`.github/ISSUE_TEMPLATE/`)

#### Feature Request (`feature_request.yml`)
```yaml
name: Feature Request
description: New feature or enhancement
labels: ["feature"]
body:
  - type: input
    id: backlog-id
    attributes:
      label: Backlog ID
      description: "Reference to docs/backlog/ item (e.g., CB-001)"
  - type: dropdown
    id: epic
    attributes:
      label: Epic
      options:
        - Conductor Brain
        - Compute Fabric
        - Frontend / UX
        - Security
        - Caching Layer
        - Self-Evolution
        - Onboarding
        - Observability
        - Hive Mode
        - Email & Operations
  - type: dropdown
    id: priority
    attributes:
      label: Priority
      options: [P0, P1, P2]
  - type: dropdown
    id: phase
    attributes:
      label: Phase
      options: ["0: Foundation", "1: MVP", "2: Intelligence", "3: Growth", "4: Scale", "5: Autonomy"]
  - type: textarea
    id: description
    attributes:
      label: Description
  - type: textarea
    id: acceptance
    attributes:
      label: Acceptance Criteria
```

#### Bug Report (`bug_report.yml`)
```yaml
name: Bug Report
description: Something isn't working
labels: ["bug"]
body:
  - type: textarea
    id: description
    attributes:
      label: What happened?
  - type: textarea
    id: expected
    attributes:
      label: What should have happened?
  - type: textarea
    id: reproduction
    attributes:
      label: Steps to reproduce
  - type: input
    id: environment
    attributes:
      label: Environment (OS, GPU, Docker version)
```

### Labels System
```
# Priority
P0-critical       (red)
P1-important      (orange)
P2-nice-to-have   (yellow)

# Type
feature           (green)
bug               (red)
research          (purple)
docs              (blue)
chore             (gray)
security          (dark red)

# Epic
epic:conductor    (teal)
epic:compute      (teal)
epic:frontend     (teal)
epic:security     (teal)
epic:caching      (teal)
epic:evolution    (teal)
epic:onboarding   (teal)
epic:observability(teal)
epic:hive-mode    (teal)
epic:email-ops    (teal)

# Phase
phase:0           (light blue)
phase:1           (light blue)
phase:2           (light blue)
phase:3           (light blue)
phase:4           (light blue)

# Status
blocked           (black)
needs-review      (pink)
ready             (green)

# Source
gap:feasibility   (purple) -- items from feasibility report gaps
```

### Milestones
Map to roadmap phases:
- **Phase 0: Foundation** (due: Week 4)
- **Phase 1: MVP** (due: Week 12)
- **Phase 2: Intelligence** (due: Week 20)
- **Phase 3: Growth** (due: Week 28)
- **Phase 4: Scale** (due: Week 40)

---

## GITHUB PROJECTS V2 -- KANBAN BOARD

### Project Board: "LLMHosts Development"

#### Views
1. **Board View** (default): Kanban columns: Backlog → Ready → In Progress → Review → Done
2. **Table View**: All items sortable/filterable by epic, priority, phase, assignee
3. **Roadmap View**: Timeline view grouped by phase and milestone
4. **Sprint View**: Current 2-week sprint items only (filtered by iteration field)

#### Custom Fields
| Field | Type | Purpose |
|-------|------|---------|
| Status | Single select | Backlog, Ready, In Progress, Review, Done |
| Priority | Single select | P0, P1, P2 |
| Epic | Single select | Conductor, Compute, Frontend, etc. |
| Phase | Single select | 0 through 5 |
| Sprint | Iteration | 2-week iterations |
| Effort | Number | Story points (1, 2, 3, 5, 8, 13) |
| Backlog ID | Text | Maps to docs/backlog/ item (e.g., CB-001) |

#### Built-in Automations
- Issue opened → Status: Backlog
- PR linked to issue → Status: In Progress
- PR merged → Status: Done
- Issue closed → Archive after 2 weeks

---

## PULL REQUESTS -- QUALITY GATES

### PR Template (`.github/pull_request_template.md`)
```markdown
## Summary
<!-- What does this PR do? Link to issue(s). -->

Closes #

## Changes
- [ ] Change 1
- [ ] Change 2

## Backlog Item
<!-- Reference: CB-001, CF-005, etc. -->

## Type
- [ ] Feature
- [ ] Bug fix
- [ ] Docs
- [ ] Chore / Maintenance

## Testing
- [ ] Unit tests added/updated
- [ ] Integration test added/updated
- [ ] Manual testing completed
- [ ] Docker build succeeds

## Checklist
- [ ] Code follows coding standards (.cursor/rules/coding-standards.mdc)
- [ ] Docker-only (no native installs)
- [ ] No secrets in code
- [ ] Docs updated if needed
- [ ] Backlog item status updated
```

### Required Checks (Status Checks Before Merge)
1. `lint` -- ruff (Python) / ESLint (TypeScript) passes
2. `test` -- pytest / vitest passes
3. `build` -- Docker build succeeds
4. `security` -- No secrets detected, no critical vulnerabilities
5. `coverage` -- Code coverage does not decrease

---

## GITHUB ACTIONS -- CI/CD PIPELINES

### Workflow: CI on PR (`.github/workflows/ci.yml`)
Triggers on: PR to `develop` or `main`
```
Jobs:
  lint:
    - Python: ruff check + ruff format --check
    - TypeScript: eslint + prettier --check
  
  test:
    - Python: pytest with coverage
    - TypeScript: vitest with coverage
  
  build:
    - Docker build for each changed service (path filtering)
    - Multi-stage build, no push (build-only validation)
  
  security:
    - Secret scanning (trufflehog or gitleaks)
    - Dependency vulnerability check (pip-audit, npm audit)
```

### Workflow: Build & Push on Merge (`.github/workflows/build.yml`)
Triggers on: push to `main`
```
Jobs:
  build-and-push:
    - Login to GHCR (GitHub Container Registry)
    - Build Docker images (multi-stage, cached via GHA cache)
    - Tag: sha-<commit>, latest, v<semver>
    - Push to ghcr.io/llmhost/<service>
    - Attestation: sign images with Sigstore
  
  deploy:
    - Update docker-compose on staging
    - Run smoke tests
    - (Future) Deploy to production with approval gate
```

### Workflow: Dependabot Auto-merge (`.github/workflows/dependabot-automerge.yml`)
```
Triggers on: Dependabot PR
Jobs:
  auto-merge:
    - If patch version update + all checks pass → auto-approve + auto-merge
    - If minor version → auto-approve, manual merge
    - If major version → manual review required
```

### Workflow: Scheduled Security Scan (`.github/workflows/security-scan.yml`)
```
Triggers on: schedule (weekly)
Jobs:
  scan:
    - Trivy container scan on all Docker images
    - pip-audit + npm audit on dependencies
    - Report → create issue if vulnerabilities found
```

### Monorepo Path Filtering
Each workflow uses path filters to only run relevant jobs:
```yaml
on:
  push:
    paths:
      - 'services/conductor/**'
      - 'services/api/**'

jobs:
  build-conductor:
    if: contains(github.event.head_commit.modified, 'services/conductor')
```

### Caching Strategy
```yaml
# Docker layer caching via GitHub Actions cache
- uses: docker/build-push-action@v6
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

# Python dependency caching
- uses: actions/setup-python@v5
  with:
    cache: 'pip'

# Node dependency caching
- uses: actions/setup-node@v4
  with:
    cache: 'npm'
```

---

## GITHUB CONTAINER REGISTRY (GHCR)

### Image Naming
```
ghcr.io/llmhost/conductor:latest
ghcr.io/llmhost/conductor:v1.0.0
ghcr.io/llmhost/conductor:sha-abc1234
ghcr.io/llmhost/api:latest
ghcr.io/llmhost/agent:latest
ghcr.io/llmhost/frontend:latest
ghcr.io/llmhost/proxy:latest
```

### Tagging Strategy
- `latest` -- most recent main branch build
- `v{major}.{minor}.{patch}` -- semantic version releases
- `sha-{short-sha}` -- every commit for traceability
- `develop` -- latest develop branch build

---

## SECURITY FEATURES

### Free Tier (Available Day 1)
1. **Dependabot Alerts**: Auto-detect vulnerable dependencies
2. **Dependabot Security Updates**: Auto-PR to fix vulnerabilities
3. **Dependabot Version Updates**: Auto-PR to keep deps current
4. **Secret Scanning**: Detect leaked API keys, tokens, passwords
5. **Push Protection**: Block pushes containing secrets before they land
6. **.gitignore**: docs/secure/, .env, *.key, *.pem (already configured)

### Configuration (`.github/dependabot.yml`)
```yaml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/services/conductor"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
  
  - package-ecosystem: "pip"
    directory: "/services/api"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
  
  - package-ecosystem: "npm"
    directory: "/frontend"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
  
  - package-ecosystem: "docker"
    directory: "/services/conductor"
    schedule:
      interval: "weekly"
  
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
```

### Pre-commit Hooks (Local)
```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks
  
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0
    hooks:
      - id: ruff
      - id: ruff-format
```

---

## BRANCH PROTECTION / RULESETS

### Ruleset: `main` Branch
- Require PR before merging (no direct push)
- Require 1 approval (when team grows, increase to 2)
- Require status checks: lint, test, build, security
- Require linear history (squash merge)
- Require signed commits (when GPG keys configured)
- Block force pushes
- Block branch deletion

### Ruleset: `develop` Branch
- Require PR before merging
- Require status checks: lint, test, build
- Allow merge commits (for feature integration)
- Block force pushes

---

## RELEASES & CHANGELOG

### Semantic Versioning
- `v0.1.0` -- Phase 0 complete (foundation)
- `v0.2.0` -- Phase 1 complete (MVP)
- `v0.3.0` -- Phase 2 complete (Intelligence)
- `v1.0.0` -- Phase 3 complete (public launch)

### GitHub Releases
- Create Release for each milestone version
- Auto-generate changelog from PR titles (conventional commits)
- Attach Docker image digests to release
- Tag release commit

### Conventional Commits → Auto-Changelog
PR titles follow conventional commits format:
- `feat(conductor): add rule-based routing` → Features section
- `fix(agent): resolve GPU detection on AMD` → Bug Fixes section
- `docs: update roadmap Phase 1` → Documentation section
- `chore: update vLLM to v0.8.0` → Maintenance section

---

## GITHUB ACTIONS WORKFLOW FILES TO CREATE

| File | Trigger | Purpose |
|------|---------|---------|
| `.github/workflows/ci.yml` | PR to develop/main | Lint, test, build validation |
| `.github/workflows/build.yml` | Push to main | Build + push Docker images to GHCR |
| `.github/workflows/dependabot-automerge.yml` | Dependabot PR | Auto-merge safe dependency updates |
| `.github/workflows/security-scan.yml` | Weekly schedule | Container + dependency vulnerability scan |
| `.github/workflows/release.yml` | Tag v*.*.* | Create GitHub Release with changelog |
| `.github/dependabot.yml` | -- | Dependabot configuration |
| `.github/ISSUE_TEMPLATE/feature_request.yml` | -- | Feature request template |
| `.github/ISSUE_TEMPLATE/bug_report.yml` | -- | Bug report template |
| `.github/pull_request_template.md` | -- | PR template |
| `.pre-commit-config.yaml` | -- | Local pre-commit hooks |

---

## MIGRATION: docs/backlog/ → GitHub Issues

When repo is initialized, systematically create GitHub Issues from docs/backlog/ items:
1. Each backlog item (CB-001, CF-001, etc.) becomes a GitHub Issue
2. Apply labels: priority, epic, phase, type
3. Assign to milestone (phase)
4. Add to GitHub Project board
5. Cross-reference: Issue body links to docs/backlog/ item for full context
6. docs/backlog/ remains the authoritative design document; Issues track execution status

This is a one-time migration followed by ongoing sync.

---

## IMPLEMENTATION CHECKLIST (SEC-011 + SEC-012)

When initializing the repo, execute in order:
1. [ ] `git init` + initial commit with all current docs
2. [ ] Create private repo on GitHub, push
3. [ ] Create labels (all listed above)
4. [ ] Create milestones (Phase 0 through Phase 4)
5. [ ] Configure rulesets (main + develop branches)
6. [ ] Enable Dependabot alerts + security updates + version updates
7. [ ] Enable secret scanning + push protection
8. [ ] Create `.github/` templates (issues, PRs)
9. [ ] Create `.github/workflows/` CI/CD pipelines
10. [ ] Create `.pre-commit-config.yaml`
11. [ ] Create `.github/dependabot.yml`
12. [ ] Create GitHub Project "LLMHosts Development"
13. [ ] Configure Project views (Board, Table, Roadmap, Sprint)
14. [ ] Migrate backlog items → GitHub Issues
15. [ ] Verify: PR to main requires all checks to pass
