github-milestone

name	github-milestone
description	Create well-structured GitHub milestones. Use when planning new phases of work that group related issues together.

Milestones group related issues into a phase of work. A well-structured milestone provides context and clear completion criteria.

Milestone Description Format

## Summary
[1-2 sentences providing context for the agent. What does this milestone accomplish?]

## Key Files
- `path/to/relevant/file.php`
- `path/to/another/file.tsx`

## Done When
- [ ] High-level acceptance criterion 1
- [ ] High-level acceptance criterion 2

Required Sections

Section	Required	Description
Summary	Yes	Brief context for the agent about the milestone's purpose
Key Files	No	Paths to important files the agent should examine
Done When	Yes	High-level criteria that determine milestone completion

Example

## Summary
Add Stripe billing to the app so users can subscribe to plans. Covers checkout, webhook handling, and the billing portal page.

## Key Files
- `app/Http/Controllers/BillingController.php`
- `app/Services/Stripe/`
- `config/services.php`
- `resources/js/Pages/Billing/`

## Done When
- [ ] Users can start a checkout for each plan
- [ ] Subscription state is synced via webhooks
- [ ] Billing portal page shows current plan + invoices
- [ ] Feature tests cover checkout + cancellation

Best Practices

1. Context first - Explain why this work matters
2. List key files - Point to important entry points
3. Clear completion criteria - Define what "done" means
4. Keep milestones focused - 3-7 issues per milestone is ideal

Creating Milestones

Preferred: gh CLI

gh api repos/{owner}/{repo}/milestones \
  --method POST \
  -f title="Milestone title" \
  -f description="$(cat <<'EOF'
## Summary
Brief context about the milestone.

## Done When
- [ ] Criterion 1
- [ ] Criterion 2
EOF
)"

Fallback: GitHub MCP

If gh CLI is unavailable:

Tool: mcp__github__create_milestone
Parameters:
  owner: "<repo-owner>"
  repo: "<repo-name>"
  title: "Milestone title"
  description: "<markdown description following the format above>"