Menu
将已发布版本（v1.0、v1.1、v2.0）标记为完成。在 MILESTONES.md 中创建历史记录，执行 PROJECT.md 演进审查，重组 ROADMAP.md，并在 git 中打标签。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | complete-milestone |
| description | 将已发布版本（v1.0、v1.1、v2.0）标记为完成。在 MILESTONES.md 中创建历史记录，执行 PROJECT.md 演进审查，重组 ROADMAP.md，并在 git 中打标签。 |
<required_reading>
Read these files NOW:
.gsd/ROADMAP.md.gsd/REQUIREMENTS.md.gsd/PROJECT.md</required_reading>
<archival_behavior>
When a milestone completes, this workflow:
.gsd/milestones/v[X.Y]-ROADMAP.md.gsd/milestones/v[X.Y]-REQUIREMENTS.mdContext Efficiency: Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.
Archive Format:
ROADMAP archive uses templates/milestone-archive.md template with:
REQUIREMENTS archive contains:
</archival_behavior>
Check if milestone is truly complete:
cat .gsd/ROADMAP.md
ls .gsd/phases/*/SUMMARY.md 2>/dev/null | wc -l
Questions to ask:
Present:
Milestone: [Name from user, e.g., "v1.0 MVP"]
Appears to include:
- Phase 1: Foundation (2/2 plans complete)
- Phase 2: Authentication (2/2 plans complete)
- Phase 3: Core Features (3/3 plans complete)
- Phase 4: Polish (1/1 plan complete)
Total: 4 phases, 8 plans, all complete
cat .gsd/config.json 2>/dev/null
⚡ Auto-approved: Milestone scope verification
[Show breakdown summary without prompting]
Proceeding to stats gathering...
Proceed directly to gather_stats step.
Ready to mark this milestone as shipped?
(yes / wait / adjust scope)
Wait for confirmation.
If "adjust scope": Ask which phases should be included. If "wait": Stop, user will return when ready.
Calculate milestone statistics:
# Count phases and plans in milestone
# (user specified or detected from roadmap)
# Find git range
git log --oneline --grep="feat(" | head -20
# Count files modified in range
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
# Count LOC (adapt to language)
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
# Calculate timeline
git log --format="%ai" FIRST_COMMIT | tail -1 # Start date
git log --format="%ai" LAST_COMMIT | head -1 # End date
Present summary:
Milestone Stats:
- Phases: [X-Y]
- Plans: [Z] total
- Tasks: [N] total (estimated from phase summaries)
- Files modified: [M]
- Lines of code: [LOC] [language]
- Timeline: [Days] days ([Start] → [End])
- Git range: feat(XX-XX) → feat(YY-YY)
Read all phase SUMMARY.md files in milestone range:
cat .gsd/phases/01-*/01-*-SUMMARY.md
cat .gsd/phases/02-*/02-*-SUMMARY.md
# ... for each phase in milestone
From summaries, extract 4-6 key accomplishments.
Present:
Key accomplishments for this milestone:
1. [Achievement from phase 1]
2. [Achievement from phase 2]
3. [Achievement from phase 3]
4. [Achievement from phase 4]
5. [Achievement from phase 5]
Create or update .gsd/MILESTONES.md.
If file doesn't exist:
# Project Milestones: [Project Name from PROJECT.md]
[New entry]
If exists, prepend new entry (reverse chronological order).
Use template from templates/milestone.md:
## v[Version] [Name] (Shipped: YYYY-MM-DD)
**Delivered:** [One sentence from user]
**Phases completed:** [X-Y] ([Z] plans total)
**Key accomplishments:**
- [List from previous step]
**Stats:**
- [Files] files created/modified
- [LOC] lines of [language]
- [Phases] phases, [Plans] plans, [Tasks] tasks
- [Days] days from [start milestone or start project] to ship
**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
**What's next:** [Ask user: what's the next goal?]
---
Perform full PROJECT.md evolution review at milestone completion.
Read all phase summaries in this milestone:
cat .gsd/phases/*-*/*-SUMMARY.md
Full review checklist:
"What This Is" accuracy:
Core Value check:
Requirements audit:
Validated section:
- ✓ [Requirement] — v[X.Y]Active section:
Out of Scope audit:
Context update:
Key Decisions audit:
Constraints check:
Update PROJECT.md:
Make all edits inline. Update "Last updated" footer:
---
_Last updated: [date] after v[X.Y] milestone_
Example full evolution (v1.0 → v1.1 prep):
Before:
## What This Is
A real-time collaborative whiteboard for remote teams.
## Core Value
Real-time sync that feels instant.
## Requirements
### Validated
(None yet — ship to validate)
### Active
- [ ] Canvas drawing tools
- [ ] Real-time sync < 500ms
- [ ] User authentication
- [ ] Export to PNG
### Out of Scope
- Mobile app — web-first approach
- Video chat — use external tools
After v1.0:
## What This Is
A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
## Core Value
Real-time sync that feels instant.
## Requirements
### Validated
- ✓ Canvas drawing tools — v1.0
- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
- ✓ User authentication — v1.0
### Active
- [ ] Export to PNG
- [ ] Undo/redo history
- [ ] Shape tools (rectangles, circles)
### Out of Scope
- Mobile app — web-first approach, PWA works well
- Video chat — use external tools
- Offline mode — real-time is core value
## Context
Shipped v1.0 with 2,400 LOC TypeScript.
Tech stack: Next.js, Supabase, Canvas API.
Initial user testing showed demand for shape tools.
Step complete when:
Update .gsd/ROADMAP.md to group completed milestone phases.
Add milestone headers and collapse completed work:
# Roadmap: [Project Name]
## Milestones
- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
- 📋 **v2.0 Redesign** — Phases 7-10 (planned)
## Phases
<details>
<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
</details>
### 🚧 v[Next] [Name] (In Progress / Planned)
- [ ] Phase 5: [Name] ([N] plans)
- [ ] Phase 6: [Name] ([N] plans)
## Progress
| Phase | Milestone | Plans Complete | Status | Completed |
| ----------------- | --------- | -------------- | ----------- | ---------- |
| 1. Foundation | v1.0 | 2/2 | Complete | YYYY-MM-DD |
| 2. Authentication | v1.0 | 2/2 | Complete | YYYY-MM-DD |
| 3. Core Features | v1.0 | 3/3 | Complete | YYYY-MM-DD |
| 4. Polish | v1.0 | 1/1 | Complete | YYYY-MM-DD |
| 5. Security Audit | v1.1 | 0/1 | Not started | - |
| 6. Hardening | v1.1 | 0/2 | Not started | - |
Extract completed milestone details and create archive file.
Process:
Create archive file path: .gsd/milestones/v[X.Y]-ROADMAP.md
Read ~/.gsd/templates/milestone-archive.md template
Extract data from current ROADMAP.md:
Extract data from PROJECT.md:
Fill template {{PLACEHOLDERS}}:
Write filled template to .gsd/milestones/v[X.Y]-ROADMAP.md
Delete ROADMAP.md (fresh one created for next milestone):
rm .gsd/ROADMAP.md
Verify archive exists:
ls .gsd/milestones/v[X.Y]-ROADMAP.md
Confirm roadmap archive complete:
✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
✅ ROADMAP.md deleted (fresh one for next milestone)
Note: Phase directories (.gsd/phases/) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
Archive requirements and prepare for fresh requirements in next milestone.
Process:
Read current REQUIREMENTS.md:
cat .gsd/REQUIREMENTS.md
Create archive file: .gsd/milestones/v[X.Y]-REQUIREMENTS.md
Transform requirements for archive:
[x] completeWrite archive file with header:
# Requirements Archive: v[X.Y] [Milestone Name]
**Archived:** [DATE]
**Status:** ✅ SHIPPED
This is the archived requirements specification for v[X.Y].
For current requirements, see `.gsd/REQUIREMENTS.md` (created for next milestone).
---
[Full REQUIREMENTS.md content with checkboxes marked complete]
---
## Milestone Summary
**Shipped:** [X] of [Y] v1 requirements
**Adjusted:** [list any requirements that changed during implementation]
**Dropped:** [list any requirements removed and why]
---
_Archived: [DATE] as part of v[X.Y] milestone completion_
Delete original REQUIREMENTS.md:
rm .gsd/REQUIREMENTS.md
Confirm:
✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
Important: The next milestone workflow starts with /new-milestone.md which includes requirements definition. PROJECT.md's Validated section carries the cumulative record across milestones.
Move the milestone audit file to the archive (if it exists):
# Move audit to milestones folder (if exists)
[ -f .gsd/v[X.Y]-MILESTONE-AUDIT.md ] && mv .gsd/v[X.Y]-MILESTONE-AUDIT.md .gsd/milestones/
Confirm:
✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md
(Skip silently if no audit file exists — audit is optional)
Update STATE.md to reflect milestone completion.
Project Reference:
## Project Reference
See: .gsd/PROJECT.md (updated [today])
**Core value:** [Current core value from PROJECT.md]
**Current focus:** [Next milestone or "Planning next milestone"]
Current Position:
Phase: [Next phase] of [Total] ([Phase name])
Plan: Not started
Status: Ready to plan
Last activity: [today] — v[X.Y] milestone complete
Progress: [updated progress bar]
Accumulated Context:
Check if branching was used and offer merge options.
Check branching strategy:
# Get branching strategy from config
BRANCHING_STRATEGY=$(cat .gsd/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "none")
If strategy is "none": Skip to git_tag step.
For "phase" strategy — find phase branches:
PHASE_BRANCH_TEMPLATE=$(cat .gsd/config.json 2>/dev/null | grep -o '"phase_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/phase-{phase}-{slug}")
# Extract prefix from template (before first variable)
BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
# Find all phase branches for this milestone
PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
For "milestone" strategy — find milestone branch:
MILESTONE_BRANCH_TEMPLATE=$(cat .gsd/config.json 2>/dev/null | grep -o '"milestone_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/{milestone}-{slug}")
# Extract prefix from template
BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
# Find milestone branch
MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
If no branches found: Skip to git_tag step.
If branches exist — present merge options:
## Git Branches Detected
Branching strategy: {phase/milestone}
Branches found:
{list of branches}
Options:
1. **Merge to main** — Merge branch(es) to main
2. **Delete without merging** — Branches already merged or not needed
3. **Keep branches** — Leave for manual handling
Use HumanAgent MCP (HumanAgent_Chat):
HumanAgent MCP (HumanAgent_Chat)([
{
question: "How should branches be handled?",
header: "Branches",
multiSelect: false,
options: [
{ label: "Squash merge (Recommended)", description: "Squash all commits into one clean commit on main" },
{ label: "Merge with history", description: "Preserve all individual commits (--no-ff)" },
{ label: "Delete without merging", description: "Branches already merged or not needed" },
{ label: "Keep branches", description: "Leave branches for manual handling later" }
]
}
])
If "Squash merge":
CURRENT_BRANCH=$(git branch --show-current)
git checkout main
# For phase strategy - squash merge each phase branch
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
echo "Squash merging $branch..."
git merge --squash "$branch"
git commit -m "feat: $branch for v[X.Y]"
done
fi
# For milestone strategy - squash merge milestone branch
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
echo "Squash merging $MILESTONE_BRANCH..."
git merge --squash "$MILESTONE_BRANCH"
git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
fi
git checkout "$CURRENT_BRANCH"
Report: "Squash merged branches to main"
If "Merge with history":
CURRENT_BRANCH=$(git branch --show-current)
git checkout main
# For phase strategy - merge each phase branch
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
echo "Merging $branch..."
git merge --no-ff "$branch" -m "Merge branch '$branch' for v[X.Y]"
done
fi
# For milestone strategy - merge milestone branch
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
echo "Merging $MILESTONE_BRANCH..."
git merge --no-ff "$MILESTONE_BRANCH" -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
fi
git checkout "$CURRENT_BRANCH"
Report: "Merged branches to main with full history"
If "Delete without merging":
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
done
fi
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
git branch -d "$MILESTONE_BRANCH" 2>/dev/null || git branch -D "$MILESTONE_BRANCH"
fi
Report: "Deleted branches"
If "Keep branches":
Report: "Branches preserved for manual handling"
Create git tag for milestone:
git tag -a v[X.Y] -m "$(cat <<'EOF'
v[X.Y] [Name]
Delivered: [One sentence]
Key accomplishments:
- [Item 1]
- [Item 2]
- [Item 3]
See .gsd/MILESTONES.md for full details.
EOF
)"
Confirm: "Tagged: v[X.Y]"
Ask: "Push tag to remote? (y/n)"
If yes:
git push origin v[X.Y]
Commit milestone completion including archive files and deletions.
Check planning config:
COMMIT_PLANNING_DOCS=$(cat .gsd/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .gsd 2>/dev/null && COMMIT_PLANNING_DOCS=false
If COMMIT_PLANNING_DOCS=false: Skip git operations
If COMMIT_PLANNING_DOCS=true (default):
# Stage archive files (new)
git add .gsd/milestones/v[X.Y]-ROADMAP.md
git add .gsd/milestones/v[X.Y]-REQUIREMENTS.md
git add .gsd/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
# Stage updated files
git add .gsd/MILESTONES.md
git add .gsd/PROJECT.md
git add .gsd/STATE.md
# Stage deletions
git add -u .gsd/
# Commit with descriptive message
git commit -m "$(cat <<'EOF'
chore: complete v[X.Y] milestone
Archived:
- milestones/v[X.Y]-ROADMAP.md
- milestones/v[X.Y]-REQUIREMENTS.md
- milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
Deleted (fresh for next milestone):
- ROADMAP.md
- REQUIREMENTS.md
Updated:
- MILESTONES.md (new entry)
- PROJECT.md (requirements → Validated)
- STATE.md (reset for next milestone)
Tagged: v[X.Y]
EOF
)"
Confirm: "Committed: chore: complete v[X.Y] milestone"
✅ Milestone v[X.Y] [Name] complete
Shipped:
- [N] phases ([M] plans, [P] tasks)
- [One sentence of what shipped]
Archived:
- milestones/v[X.Y]-ROADMAP.md
- milestones/v[X.Y]-REQUIREMENTS.md
Summary: .gsd/MILESTONES.md
Tag: v[X.Y]
---
## ▶ Next Up
**Start Next Milestone** — questioning → research → requirements → roadmap
`/new-milestone.md`
<sub>`/clear` first → fresh context window</sub>
---
<milestone_naming>
Version conventions:
Name conventions:
Keep names short (1-2 words describing the focus).
</milestone_naming>
<what_qualifies>
Create milestones for:
Don't create milestones for:
If uncertain, ask: "Is this deployed/usable/shipped in some form?" If yes → milestone. If no → keep working.
</what_qualifies>
<success_criteria>
Milestone completion is successful when:
</success_criteria>
编排并行调试代理以调查 UAT 差距并查找根本原因。按差距生成调试代理，收集诊断结果，更新 UAT.md。
以适当的深度级别执行发现。生成 DISCOVERY.md 用于指导 PLAN.md 的创建。支持快速验证、标准和深度模式。
提取下游代理所需的实施决策。分析阶段以识别灰色地带，与用户讨论，并为研究和计划捕获决策。
使用波次并行执行阶段中的所有计划。编排器将计划执行委托给子代理，管理波次和检查点。
执行阶段提示（PLAN.md）并创建结果摘要（SUMMARY.md）。处理任务执行并集成 git。
在计划之前揭示 Copilot 对阶段的假设，使用户能够尽早纠正误解。纯对话式分析。