# GitHub SSOT Design — LLMHosts.com

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Make GitHub the single source of truth for LLMHosts.com — every backlog item, milestone, label, workflow, and community doc fully configured and synced.

**Architecture:** Offline-first staging. All artifacts (files, scripts) are created locally first. When tokens are available, a single push + two script runs deploy everything. The issue seeder reads backlog epics programmatically and creates issues with proper labels, milestones, and structured bodies.

**Tech Stack:** GitHub REST API via `gh` CLI, Python scripts for issue seeding/cleanup, YAML-based GitHub Actions workflows.

---

## Context

- **Account**: `LookNoHandsMom` (free plan, flagged — 60/hr REST, 0/hr GraphQL)
- **Repo**: `LookNoHandsMom/LLMHosts.com` (private)
- **Existing GitHub config**: ci.yml (6 jobs), release.yml, 3 issue templates, PR template, CODEOWNERS, FUNDING.yml
- **Backlog**: 167 items across 11 epics in `docs/backlog/`
- **Current issues**: 57 (29 unique + 28 duplicates), ~144 missing

## Deliverables

### Offline Artifacts (no API needed)

1. **`SECURITY.md`** — Vulnerability disclosure policy
2. **`CONTRIBUTING.md`** — Setup, branching, commits, PR process, TDD
3. **`CODE_OF_CONDUCT.md`** — Contributor Covenant v2.1
4. **`.github/dependabot.yml`** — Weekly pip + npm + Actions updates
5. **`tools/github-cleanup.py`** — Close duplicates, fix labels/milestones
6. **`tools/seed-github-issues.py`** — Full rewrite: reads all 11 epics, deduplicates, creates ~144 missing issues

### API Operations (need tokens)

1. Push all artifacts to GitHub
2. Run cleanup script (close ~28 duplicates)
3. Run seed script (create ~144 issues)
4. Sync develop branch

### Deferred (need Pro/$4mo or account unflag)

- Branch protection rulesets
- GitHub Projects v2 board with custom fields
- GitHub Discussions

## Issue Taxonomy

### Labels (36 exist + ~8 new)

| Category | Labels |
|----------|--------|
| `epic:*` | conductor, compute, frontend, security, caching, onboarding, observability, hive-mode, hive-ceo, email-ops, self-evolution |
| `phase:*` | phase-1, phase-2, phase-3, phase-4 |
| `priority:*` | critical, high, medium, low |
| `size:*` | xs, s, m, l, xl |
| `type:*` | feature, bug, chore, docs, test, security |
| `status:*` | needs-spec, ready, in-progress, blocked, done |

### Milestones (4 exist)

- Phase 1 (v0.1) — 73 items
- Phase 2 (v0.5) — 38 items
- Phase 3 (v1.0) — 36 items
- Phase 4 (v2.0) — 12 items

### Issue Body Format

```markdown
**Epic**: {epic} | **Backlog ID**: {id} | **Phase**: {phase} | **Size**: {size}

## Description
{description}

## Acceptance Criteria
{acceptance}

## Dependencies
{dependencies}

## Technical Notes
{notes}
```

## YAGNI — Not Doing

- GitHub Pages (Next.js on Vercel)
- GitHub Packages (PyPI distribution)
- GitHub Wiki (docs/ in repo)
- Sub-issues hierarchy (premature complexity)
- Stale bot (project actively developed)
- Complex Actions matrix (single Python/OS)
