菜单
将已发布版本（v1.0、v1.1、v2.0）标记为完成。在 MILESTONES.md 中创建历史记录，执行 PROJECT.md 演进审查，重组 ROADMAP.md，并在 git 中打标签。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| 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 对阶段的假设，使用户能够尽早纠正误解。纯对话式分析。