GitHub Agile

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 there decisions in GitHub discussions or issues that should be in decisions.md?
• Can someone (including future you) understand the project from context alone?

Interventions:

• Initialize context network if missing:

  context/
  ├── discovery.md      # Navigation and overview
  ├── status.md         # Current work, recent changes
  ├── decisions.md      # Key decisions with rationale
  ├── architecture.md   # System design, workflows
  └── glossary.md       # Project-specific terms

• Run scripts/gh-sync-context.ts to generate status update
• Update status.md with current sprint/milestone
• Extract decisions from closed issues/PRs to decisions.md
• Create architecture.md section documenting GitHub workflow
• Link GitHub milestones to context network phases

---

State GH8: Workflow Healthy

Symptoms:

• Issues are labeled, prioritized, and assigned to milestones
• All work happens on feature branches via PRs
• PRs link to issues and have meaningful descriptions
• Context network reflects current state and decisions
• Can answer "what am I working on?" and "why?"
• New sessions can resume without rediscovery

Indicators:

• gh issue list shows only relevant, current work
• gh pr status shows active work with clear purpose
• context/status.md matches GitHub reality
• Recent commits are on feature branches, not main
• No issues older than threshold without explanation

Maintenance:

• Weekly sync: GitHub state to context/status.md
• Sprint/milestone boundaries: retrospective insights to decisions.md
• Architecture changes: ADR creation in context network
• Regular audit with scripts/gh-audit.ts

---

GitHub ↔ Context Network Boundary

Lives in GitHub

Lives in Context Network

Bridge Artifacts (Cross-Reference)

---

Mode-Specific Workflows

Solo Developer Mode

Purpose: Self-discipline, history for future self, structured thinking

Adaptations:

• Branch protection still valuable (prevents accidents)
• Self-review PRs: use PR as thinking checkpoint, not just merge gate
• Issues as memory: write issues for future sessions
• Simplified labels: type:feature, type:bug, type:task, priority:high/low
• Context network especially important (no team to ask)

Workflow:

1. Start session: check context/status.md and gh issue list
2. Pick issue or create one for new work
3. Create feature branch: gh issue develop {number}
4. Work with regular commits (reference issue in messages)
5. Create PR: gh pr create --fill
6. Self-review: read diff as if someone else wrote it
7. Merge: gh pr merge --squash
8. Update context/status.md if significant

Team Mode (2-5 people)

Purpose: Collaboration, code review, shared understanding

Adaptations:

• Mandatory code review before merge
• Assignment conventions (who owns what)
• Sync ceremonies (standup, planning, retro)
• More structured labels including assignee-related
• Discussions for async decisions

Workflow:

1. Planning: create/refine issues, assign to milestone
2. Assignment: assign issues, communicate via comments
3. Development: feature branches, regular commits
4. PR creation: detailed description, request reviewers
5. Review: approve, request changes, or comment
6. Merge: after approval, squash merge
7. Sync: weekly context network update, milestone retros

Team Labels (additions):

• status:needs-review - waiting for code review
• status:changes-requested - reviewer requested changes
• needs:discussion - requires team input before proceeding

---

Key Workflows

1. Project Initialization Ceremony

Trigger: New project or first GitHub integration

Steps:

1. Verify GH CLI installed and authenticated (GH0): scripts/gh-verify.ts
2. Create or link repository (GH1): gh repo create or git remote add
3. Run initialization: scripts/gh-init-project.ts --labels standard --templates --protection
4. Initialize context network if missing
5. Document workflow in context/architecture.md
6. Record decisions in context/decisions.md
7. Create first milestone for initial work phase

2. Feature Development Workflow

Trigger: Starting new work item

Steps:

1. Ensure issue exists (create if not): gh issue create
2. Create feature branch from issue:

   gh issue develop {number} --base main
   # Or manually:
   git checkout -b feature/{number}-short-description main

3. Make commits with conventional messages:

   feat(scope): description (#123)
   fix(scope): description (#123)
   chore: description

4. Push regularly: git push -u origin HEAD
5. Create PR when ready:

   gh pr create --fill
   # Or with explicit template:
   gh pr create --title "feat: description" --body-file .github/pull_request_template.md

6. Ensure PR:
   • Links to issue (Closes #123)
   • Has meaningful description
   • References context if architectural
7. Review (self or team)
8. Merge via gh pr merge --squash (squash keeps history clean)
9. Issue auto-closes via PR keywords
10. Delete branch: git branch -d feature/{number}-description

3. Sprint/Milestone Sync

Trigger: Beginning or end of milestone

Beginning:

1. Create milestone: gh api repos/{owner}/{repo}/milestones -f title="Sprint X" -f due_on="YYYY-MM-DD"
2. Assign issues to milestone
3. Update context/status.md with milestone focus and goals
4. Communicate priorities (solo: write them down; team: planning meeting)

End:

1. Review milestone: gh issue list --milestone "Sprint X"
2. Close completed milestone
3. Move incomplete issues to next milestone or icebox
4. Record retrospective in context/decisions.md:
   • What worked well?
   • What didn't work?
   • What will we change?
5. Update context/status.md with summary

4. Context Sync Ceremony

Trigger: Weekly or after significant work

Steps:

1. Run audit: scripts/gh-audit.ts
2. Run sync: scripts/gh-sync-context.ts --dry-run (review first)
3. Update context/status.md:
   • Current milestone/sprint
   • Active issues/PRs
   • Recent completions
   • Blockers or decisions needed
4. Extract decisions from closed issues/PRs to decisions.md
5. Update architecture.md if workflow evolved
6. Verify: could someone resume work from context alone?

---

Anti-Patterns