GitHub Agile
Diagnose GitHub-driven agile workflow problems. Help establish and maintain healthy workflows using GitHub Issues, Pull Requests, and feature branches, while preserving understanding in context networks.
When to Use This Skill
Use this skill when:
Setting up a new project on GitHub Organizing a chaotic backlog Establishing branch and PR workflow Syncing GitHub state with context network Troubleshooting GitHub CLI issues
Do NOT use this skill when:
Working on code implementation Pure requirements or architecture work (use those skills first) Non-GitHub version control workflows 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.
Prerequisites GitHub CLI installed (brew install gh / apt install gh / winget install GitHub.cli) Authenticated (gh auth login then gh auth status) Repository linked (gh repo view succeeds)
Run scripts/gh-verify.ts to diagnose environment issues.
Diagnostic States Setup Track
GH0: No GitHub CLI - gh command not found
Install per platform, then gh auth login
GH1: Repository Not Initialized - No git repo or no GitHub remote
git init if needed
gh repo create
GH2: Workflow Not Established - No labels, templates, or branch protection
Run scripts/gh-init-project.ts --labels standard --templates --protection Workflow Track
GH3: Backlog Chaos - Many unlabeled issues, no priorities clear
Run scripts/gh-audit.ts to assess Apply MoSCoW prioritization Create "icebox" for deferred items Create milestone for current focus
GH4: Feature Branch Violations - Commits directly to main
Enable branch protection Establish naming: feature/{issue-number}-description Use gh issue develop {number} to create branch
GH5: PR Without Context - Minimal PR descriptions, no linked issues
Create .github/pull_request_template.md Require: Summary, Related Issue, Why, How to Test
GH6: Stale Issues/PRs - Old items with no activity
Audit: gh issue list --json number,updatedAt Close or icebox stale items
GH7: Context Network Gap - GitHub active but context network outdated
Run scripts/gh-sync-context.ts Update context/status.md with current state
GH8: Workflow Healthy - Issues labeled, PRs linked, context current
Key Workflows Feature Development
1. Create issue (if not exists)
gh issue create --title "Feature: X" --body "..."
2. Create branch from issue
gh issue develop {number} --base main
3. Make commits referencing issue
git commit -m "feat(scope): description (#123)"
4. Create PR
gh pr create --fill
5. Merge
gh pr merge --squash
Project Initialization
Verify CLI
deno run --allow-run scripts/gh-verify.ts
Create repo (if new)
gh repo create my-project --source=. --private --push
Initialize labels, templates, protection
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts \ --labels standard --templates --protection
Backlog Cleanup
Audit current state
deno run --allow-run scripts/gh-audit.ts --stale 30
List for triage
gh issue list --state open --json number,title,labels,updatedAt
Available Scripts Script Purpose Usage gh-verify.ts Check CLI installation and auth deno run --allow-run scripts/gh-verify.ts gh-init-project.ts Initialize labels, templates, protection deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts gh-audit.ts Audit backlog health deno run --allow-run scripts/gh-audit.ts gh-sync-context.ts Generate context updates from GitHub deno run --allow-run --allow-write scripts/gh-sync-context.ts Anti-Patterns The Issue Graveyard
Problem: Issues created and never closed, 200+ open issues. Fix: Regular grooming. If it won't be done in 90 days, icebox or close.
The Context-Free PR
Problem: PRs with no description or linked issue. Fix: PR template with required sections.
The Branch Protection Bypass
Problem: Committing directly to main "just this once." Fix: Branch protection exists for a reason. Enforce it.
The Disconnected Context
Problem: Context network not updated, becomes fiction. Fix: End-of-session ritual: update status.md.
GitHub ↔ Context Network Boundary
Lives in GitHub: Issues, PRs, Discussions, Actions, Labels, Milestones
Lives in Context Network: ADRs, decisions.md, status.md, architecture.md
Cross-Reference: Requirements linked from issues, ADRs referenced in PRs
Templates
Issue templates and PR template are in assets/:
issue-feature.md - Feature request template issue-bug.md - Bug report template issue-task.md - Task template pull-request.md - PR template labels-standard.json - Standard label definitions Related Skills requirements-analysis - Provides validated requirements to create issues from system-design - ADRs referenced in PRs, component map informs issue breakdown agile-workflow - Orchestrates the full development cycle