| 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
- Context first - Explain why this work matters
- List key files - Point to important entry points
- Clear completion criteria - Define what "done" means
- 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>"
