github-agile

name	github-agile
description	Diagnose GitHub-driven agile workflow problems and guide feature branch development
license	MIT
metadata	{"author":"jwynia","version":"1.0","domain":"agile-software","cluster":"software","type":"diagnostic","mode":"assistive"}

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

Artifact	Why GitHub
Issues	Collaboration, state tracking, notifications, linking
Pull Requests	Code review, CI integration, merge tracking
Discussions	Team/community conversation, Q&A, RFCs
Actions/Workflows	CI/CD, automation, enforcement
Labels/Milestones	Organization, filtering, progress tracking
Project Boards	Visual workflow (optional)

Lives in Context Network

Artifact	Why Context Network
ADRs (Architecture Decision Records)	Structured reasoning, searchable, framework integration
decisions.md	Cross-cutting decisions, policy, rationale
status.md	Current focus, recent changes, session continuity
architecture.md	System design, workflow documentation
discovery.md	Project understanding, navigation
glossary.md	Vocabulary, shared understanding
Retrospective insights	Learnings that improve future work

Bridge Artifacts (Cross-Reference)

Artifact	Primary Location	Cross-Reference
Requirements document	context/ or docs/	Linked from issues
System design	context/architecture.md	Referenced in PRs
Sprint/milestone goals	status.md	Matched to GitHub milestone
Key decisions	decisions.md	Referenced in issue/PR comments

---

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

The GitHub-as-Wiki

Problem: Using GitHub issues for long-form documentation, decisions, and context that should live in the context network. Important information gets buried in comments, impossible to find later. Symptoms: Massive issue descriptions, architecture debates in comments, decisions scattered across closed issues. Fix: GitHub tracks work items; context network tracks understanding. If it needs to survive beyond the issue lifecycle, move it to context/.

The Issue Graveyard

Problem: Issues created and never closed, making the backlog meaningless. New issues pile on top of old ones. Symptoms: 200+ open issues, most untouched for months, "I'll get to it" mentality, paralysis choosing what to work on. Fix: Regular grooming. If it won't be done in 90 days, icebox or close it. A small, current backlog beats a large, stale one. Delete aggressively.

The Context-Free PR

Problem: PRs that describe what changed but not why, making future archaeology impossible. Symptoms: "Fixed the bug", "Updated styles", "Refactored code" with no context. Six months later, no one knows why. Fix: PR template with required sections: What, Why, How to test, Related issues. If it's architectural, reference the ADR.

The Duplicate Issue Machine

Problem: Creating new issues without checking if one exists, leading to fragmented discussion and wasted effort. Symptoms: Multiple issues about the same thing, effort split across duplicates, conflicting resolutions. Fix: Search before creating: gh issue list --search "keyword". Close duplicates with reference to canonical issue.

The Eternal Draft PR

Problem: PRs opened as drafts and never completed, blocking mental progress and cluttering the PR list. Symptoms: Draft PRs older than 30 days, WIP labels that become permanent, scope creep making PRs unmergeable. Fix: Time-box drafts. If not ready in 2 weeks, close and re-scope. Small PRs that can merge beat large PRs that cannot.

The Branch Protection Bypass

Problem: Disabling branch protection "just this once" and committing directly to main. Creates precedent for future bypasses. Symptoms: Commits to main without PRs, broken builds on main, "I'll fix it in the next commit". Fix: Branch protection exists for a reason. Even solo developers benefit from the PR workflow for history, review checkpoint, and rollback capability.

The Disconnected Context

Problem: Context network exists but is not updated, becoming fiction rather than documentation. Worse than no context because it's misleading. Symptoms: status.md shows work completed months ago, decisions.md missing recent architectural changes, new sessions can't trust context. Fix: Make context sync part of the workflow, not an afterthought. End-of-session ritual: does status.md reflect reality?

---

Available Tools

gh-verify.ts

Verifies GitHub CLI installation and authentication status.

deno run --allow-run scripts/gh-verify.ts
deno run --allow-run scripts/gh-verify.ts --json

Output:

• CLI installation status and version
• Authentication status and current user
• Default repository (if in a repo directory)
• Recommendations if anything is missing

Exit codes: 0 (all good), 1 (gh missing), 2 (not logged in), 3 (no repo context)

gh-init-project.ts

Initializes GitHub project with labels, templates, and branch protection.

deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --labels standard --templates --protection
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --mode team --labels standard

Options:

• --labels [standard|simple|minimal] - Label scheme to create
• --templates - Create issue and PR templates
• --protection - Enable branch protection on main
• --mode [solo|team] - Adjust defaults for working style
• --dry-run - Show what would be created without creating

Creates:

• Labels via gh label create
• .github/ISSUE_TEMPLATE/ with feature, bug, task templates
• .github/pull_request_template.md
• Branch protection rules (if --protection)

gh-audit.ts

Audits current GitHub state against healthy workflow indicators.

deno run --allow-run scripts/gh-audit.ts
deno run --allow-run scripts/gh-audit.ts --json
deno run --allow-run scripts/gh-audit.ts --stale 30

Options:

• --json - Output as JSON for scripting
• --stale [days] - Flag items with no activity for N days (default: 30)
• --verbose - Show detailed item-by-item analysis

Checks:

• Open issue count and label coverage
• Open PR status (draft, linked issues, age)
• Recent commits (which branch, direct to main?)
• Milestone usage and progress
• Stale item identification

Output: Health score (0-100) with specific recommendations

gh-sync-context.ts

Generates context network updates from GitHub state.

deno run --allow-run --allow-write scripts/gh-sync-context.ts
deno run --allow-run scripts/gh-sync-context.ts --dry-run
deno run --allow-run --allow-write scripts/gh-sync-context.ts --status --decisions

Options:

• --dry-run - Output what would be written without writing
• --status - Generate status.md update section
• --decisions - Extract decisions from closed issues with "decision" label
• --output [dir] - Directory to write to (default: context/)

Generates:

• Status update content for status.md
• Decision candidates from closed issues
• Milestone summary

---

Example Interactions

Solo Developer: Starting Fresh

Developer: "I have a local project I want to put on GitHub and start using proper workflow."

Diagnosis: State GH1 (Repository Not Initialized)

Approach:

1. Run scripts/gh-verify.ts - confirm CLI ready
2. Ask: "Public or private repository?"
3. Create repo: gh repo create my-project --source=. --private --push
4. Run scripts/gh-init-project.ts --mode solo --labels simple --templates
5. Initialize context network: create context/ with status.md, decisions.md
6. Document in context/architecture.md: "Using GitHub Issues for tracking, feature branches for all changes, PRs for merge and history."
7. Create first issue for current work
8. Demonstrate branch workflow: gh issue develop 1

Team: Backlog Cleanup

Developer: "We have 150 open issues and no one knows what's important."

Diagnosis: State GH3 (Backlog Chaos)

Approach:

1. Run scripts/gh-audit.ts --stale 60 - identify scope
2. Ask: "What's the current priority? What must ship soon?"
3. Create milestone for immediate focus
4. Triage issues:
   • Critical for milestone → assign to milestone, add priority label
   • Valid but not now → icebox label
   • Stale with no path forward → close with explanation
   • Duplicates → close with reference to canonical
5. Update context/status.md with focus
6. Establish grooming cadence: weekly 15-minute review

Solo Developer: Context Decay

Developer: "I came back to this project after a month and have no idea what I was doing."

Diagnosis: State GH7 (Context Network Gap)

Approach:

1. Check GitHub state: gh issue list, gh pr status
2. Run scripts/gh-sync-context.ts --dry-run to see current state
3. Initialize or update context network:
   • status.md: What's the current milestone? Active issues?
   • decisions.md: Any architectural decisions in closed PRs?
4. Review closed issues/PRs from last session for context
5. Update status.md with "Last session" summary
6. Establish habit: end each session by updating status.md

---

Output Persistence

Output Discovery

Before doing any other work:

1. Check for context/output-config.md in the project
2. If found, look for this skill's entry
3. If not found, ask: "Where should I save GitHub workflow output?"
   • Suggest: context/ for context network files, .github/ for GitHub configuration
4. Store preference in context/output-config.md

Primary Output

Output	Location
Issue templates	.github/ISSUE_TEMPLATE/
PR template	.github/pull_request_template.md
Workflow documentation	context/architecture.md (GitHub workflow section)
Setup decisions	context/decisions.md
Status updates	context/status.md
Audit reports	context/github-audit-{date}.md (if persisted)

Conversation vs. File

Goes to File	Stays in Conversation
Templates (.github/)	Diagnosis discussion
Workflow documentation	Label scheme exploration
Context network updates	Triage decisions
Audit reports (if requested)	Quick status checks

---

What You Do NOT Do

• You do not create issues without user confirmation
• You do not merge PRs automatically
• You do not delete issues, PRs, or branches without explicit request
• You do not change branch protection without explicit request
• You do not skip verification of gh availability (always check GH0 first)
• You do not assume GitHub access without gh auth status check
• You do not replace the context network with GitHub-only storage
• You do not create commits on main branch (enforce feature branch workflow)
• You do not push to remote without user awareness
• You diagnose, recommend, and execute with confirmation - the developer decides

---

Integration with Other Skills

From requirements-analysis

requirements-analysis Output	github-agile Input
Problem Statement	Creates initial issue(s) describing the problem
Need Hierarchy	Maps to issue priority labels
Constraint Inventory	Documents in context/, references in issues
Validated Requirements	Creates feature issues, links to requirements doc

From system-design

system-design Output	github-agile Input
ADRs	Stored in context/adr/ or docs/adr/, referenced in PRs
Component Map	Informs issue breakdown by component
Walking Skeleton	First milestone with linked issues
Integration Points	Documented in context/architecture.md

To requirements-analysis

When GitHub state reveals requirements problems:

github-agile State	Trigger	requirements-analysis State
GH3 (Backlog Chaos)	Issues describe solutions not problems	RA0-RA1
GH3 (Backlog Chaos)	Cannot prioritize (everything important)	RA4

To system-design

When GitHub state reveals design problems:

github-agile State	Trigger	system-design State
GH5 (PR Without Context)	PR involves undocumented architecture decisions	SD4
GH4 (Branch Violations)	Frequent merge conflicts	SD3 (Missing Integration Points)

---

References

This skill operationalizes:

• GitHub CLI documentation: https://cli.github.com/manual/
• Context Networks framework: references/context-networks/
• Feature branch workflow best practices
• Conventional Commits: https://www.conventionalcommits.org/