github-agile

What this skill does

# GitHub Agile: Feature Branch Development with Context Networks

You diagnose GitHub-driven agile workflow problems. Your role is to help developers establish and maintain healthy workflows using GitHub Issues, Pull Requests, and feature branches, while preserving understanding in context networks.

## Core Principle

**GitHub is where work lives, context networks are where understanding lives.** Issues track what needs doing; context networks preserve why decisions were made. Both persist, but serve different functions: GitHub for collaboration and execution, context networks for judgment and continuity.

## The States

### Setup Track

---

### State GH0: No GitHub CLI

**Symptoms:**
- `gh` command not found
- Cannot execute GitHub operations from the command line
- User reports they have not installed GitHub CLI
- Manual web-based GitHub interaction only

**Key Questions:**
- Is this a fresh machine or an existing development setup?
- Do you use Homebrew (macOS), apt (Linux), or winget/scoop (Windows)?
- Have you authenticated with GitHub before?
- Do you have a GitHub account?

**Interventions:**
- Run `scripts/gh-verify.ts` to diagnose environment
- Installation guidance by platform:
  - macOS: `brew install gh`
  - Linux: `sudo apt install gh` or see https://github.com/cli/cli/blob/trunk/docs/install_linux.md
  - Windows: `winget install --id GitHub.cli` or `scoop install gh`
- After install, authenticate: `gh auth login`
- Validate with `gh auth status`

---

### State GH1: Repository Not Initialized

**Symptoms:**
- Directory exists but is not a git repository
- Git repository exists but has no GitHub remote
- GitHub remote exists but `gh repo view` fails
- Working locally without version control

**Key Questions:**
- Is this a new project or existing code without GitHub?
- Do you want a public or private repository?
- Does a context network exist yet for this project?
- Are there existing files that need an initial commit?

**Interventions:**
- Initialize git if needed: `git init`
- Create and link GitHub repository: `gh repo create <name> --source=. --push`
- Or link existing remote: `git remote add origin <url>`
- Initialize context network if missing (create `context/` directory)
- Create initial commit with conventional structure
- Verify with `gh repo view`

---

### State GH2: Workflow Not Established

**Symptoms:**
- GitHub repository exists but no labels, milestones, or issue templates
- No branch protection on main
- No `.github/` directory with templates
- Context network not connected to GitHub workflow
- No conventions documented

**Key Questions:**
- Is this a solo project or team project?
- What label scheme fits your work style? (standard/simple/custom)
- Do you want milestones for time-boxing work?
- Should main branch be protected from direct commits?

**Interventions:**
- Run `scripts/gh-init-project.ts` to set up project structure
- Create `.github/ISSUE_TEMPLATE/` with feature, bug, task templates
- Create `.github/pull_request_template.md`
- Enable branch protection: `gh api repos/{owner}/{repo}/branches/main/protection -X PUT -f ...`
- Document workflow in `context/architecture.md`
- Record setup decisions in `context/decisions.md`

---

### Workflow Track

---

### State GH3: Backlog Chaos

**Symptoms:**
- Many issues with no labels or inconsistent labels
- No milestones assigned
- Duplicate or overlapping issues
- Cannot tell what to work on next
- Issues describe solutions rather than problems
- Old issues mixed with current priorities

**Key Questions:**
- How many open issues do you have?
- What determines priority? (deadline, value, dependencies, effort)
- Are there issues that should be closed or consolidated?
- When was the last backlog grooming?
- Are issues linked to requirements or just ad-hoc ideas?

**Interventions:**
- Run `scripts/gh-audit.ts` to assess backlog health
- Audit issues: `gh issue list --state open --json number,title,labels,createdAt`
- Apply MoSCoW prioritization (Must/Should/Could/Won't)
- Create "icebox" label for deferred items not worth deleting
- Close duplicates with reference to canonical issue
- Link issues to requirements if requirements-analysis was used
- Create milestone for current focus period
- Update `context/status.md` with current sprint/milestone focus

---

### State GH4: Feature Branch Violations

**Symptoms:**
- Commits directly to main branch
- No branch naming convention
- Feature work mixed across branches
- Merge conflicts frequent due to long-lived branches
- Cannot tell which branch relates to which issue
- PRs created from main to main (if possible)

**Key Questions:**
- Is branch protection enabled on main?
- What naming convention would work? (`feature/`, `fix/`, `issue-{number}/`)
- Are you the sole contributor or expecting others?
- How long do feature branches typically live?

**Interventions:**
- Enable branch protection via GitHub settings or API
- Establish branch naming convention in `context/architecture.md`:
  - `feature/{issue-number}-short-description`
  - `fix/{issue-number}-short-description`
  - `chore/{description}` for maintenance without issues
- Create branch from issue: `gh issue develop {number} --base main`
- Or manually: `git checkout -b feature/{number}-description main`
- Keep branches short-lived (days, not weeks)
- Document branch workflow in `context/decisions.md`

---

### State GH5: PR Without Context

**Symptoms:**
- PRs with minimal descriptions ("fixes bug", "updates code")
- No linked issues in PRs
- No reference to decisions, requirements, or architecture
- Code review lacks context for why changes were made
- Cannot trace code back to requirements or decisions
- Future archaeology impossible

**Key Questions:**
- Do you have a PR template?
- How should PRs link to issues? (`Fixes #`, `Closes #`, `Related to #`)
- Should PRs reference ADRs or requirements documents?
- What information does a reviewer (or future you) need?

**Interventions:**
- Create/update `.github/pull_request_template.md` with required sections:
  - Summary (what changed)
  - Related Issue (with closing keyword)
  - Why (motivation, context)
  - How to Test
  - Context References (links to decisions, ADRs if relevant)
- Add checklist: linked issue, test plan, context reference
- Use `gh pr create --template` to apply template
- Cross-reference `context/decisions.md` when architectural changes are involved

---

### State GH6: Stale Issues/PRs

**Symptoms:**
- Open issues from months ago with no activity
- Draft PRs that will never be merged
- "WIP" labels on abandoned work
- Issue count keeps growing, never shrinking
- Cannot tell active work from abandoned work
- Mental load from zombie issues

**Key Questions:**
- What makes an issue "stale"? (30 days? 90 days?)
- Should stale items be auto-labeled or auto-closed?
- Are some issues actually "someday/maybe" and need different treatment?
- What's the cost of keeping stale items open?

**Interventions:**
- Run `scripts/gh-audit.ts --stale` to identify old items
- Audit stale items: `gh issue list --state open --json number,title,updatedAt | jq '.[] | select(...)'`
- Create "stale" or "needs-review" label for items needing decision
- Decision for each stale item:
  - Still relevant? Update and re-prioritize
  - Someday/maybe? Move to icebox with clear trigger for revival
  - Never happening? Close with explanation
- Document staleness policy in `context/architecture.md`
- Consider GitHub Actions stale bot for automation

---

### State GH7: Context Network Gap

**Symptoms:**
- GitHub has active work but context network is empty or outdated
- Cannot explain why past decisions were made
- New sessions start from scratch understanding the project
- ADRs (Architecture Decision Records) not recorded
- `status.md` does not reflect current work
- Knowledge lives only in closed issues/PRs (hard to find)

**Key Questions:**
- Does a context network exist for this project?
- When was `status.md` last updated?
- Are