ace-experience 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +40 -0
  3. package/ace/references/continuation-format.md +249 -0
  4. package/ace/references/gates.md +1078 -0
  5. package/ace/references/git-integration.md +254 -0
  6. package/ace/references/horsepower-profiles.md +73 -0
  7. package/ace/references/planning-config.md +189 -0
  8. package/ace/references/questioning.md +141 -0
  9. package/ace/references/tdd.md +263 -0
  10. package/ace/references/ui-brand.md +160 -0
  11. package/ace/references/verification-patterns.md +612 -0
  12. package/ace/templates/architect-prompt.md +117 -0
  13. package/ace/templates/brief.md +184 -0
  14. package/ace/templates/codebase/architecture.md +264 -0
  15. package/ace/templates/codebase/concerns.md +310 -0
  16. package/ace/templates/codebase/conventions.md +307 -0
  17. package/ace/templates/codebase/integrations.md +280 -0
  18. package/ace/templates/codebase/stack.md +186 -0
  19. package/ace/templates/codebase/structure.md +295 -0
  20. package/ace/templates/codebase/testing.md +480 -0
  21. package/ace/templates/config.json +36 -0
  22. package/ace/templates/continue-here.md +78 -0
  23. package/ace/templates/debug.md +159 -0
  24. package/ace/templates/detective-prompt.md +91 -0
  25. package/ace/templates/intel.md +283 -0
  26. package/ace/templates/milestone-archive.md +123 -0
  27. package/ace/templates/milestone.md +115 -0
  28. package/ace/templates/proof.md +322 -0
  29. package/ace/templates/pulse.md +176 -0
  30. package/ace/templates/recap.md +246 -0
  31. package/ace/templates/research/architecture.md +204 -0
  32. package/ace/templates/research/features.md +147 -0
  33. package/ace/templates/research/pitfalls.md +200 -0
  34. package/ace/templates/research/recap.md +170 -0
  35. package/ace/templates/research/stack.md +120 -0
  36. package/ace/templates/research-lite.md +146 -0
  37. package/ace/templates/research.md +552 -0
  38. package/ace/templates/specs.md +231 -0
  39. package/ace/templates/stage-prompt.md +567 -0
  40. package/ace/templates/track.md +202 -0
  41. package/ace/templates/uat.md +247 -0
  42. package/ace/templates/user-setup.md +311 -0
  43. package/ace/workflows/audit-stage.md +628 -0
  44. package/ace/workflows/audit-work.md +596 -0
  45. package/ace/workflows/continue-project.md +305 -0
  46. package/ace/workflows/diagnose-issues.md +231 -0
  47. package/ace/workflows/list-assumptions.md +178 -0
  48. package/ace/workflows/map-codebase.md +322 -0
  49. package/ace/workflows/research-stage.md +289 -0
  50. package/ace/workflows/run-plan.md +1844 -0
  51. package/ace/workflows/run-stage.md +686 -0
  52. package/ace/workflows/scope-stage.md +433 -0
  53. package/ace/workflows/ship-milestone.md +833 -0
  54. package/ace/workflows/transition.md +556 -0
  55. package/agents/ace-architect.md +1415 -0
  56. package/agents/ace-auditor.md +778 -0
  57. package/agents/ace-codebase-mapper.md +738 -0
  58. package/agents/ace-detective.md +1203 -0
  59. package/agents/ace-integration-checker.md +423 -0
  60. package/agents/ace-navigator.md +605 -0
  61. package/agents/ace-plan-reviewer.md +812 -0
  62. package/agents/ace-project-scout.md +865 -0
  63. package/agents/ace-runner.md +784 -0
  64. package/agents/ace-stage-scout.md +669 -0
  65. package/agents/ace-synthesizer.md +256 -0
  66. package/bin/install.js +1432 -0
  67. package/commands/ace.add-stage.md +211 -0
  68. package/commands/ace.add-todo.md +194 -0
  69. package/commands/ace.audit-milestone.md +277 -0
  70. package/commands/ace.audit.md +219 -0
  71. package/commands/ace.check-todos.md +229 -0
  72. package/commands/ace.complete-milestone.md +134 -0
  73. package/commands/ace.continue.md +46 -0
  74. package/commands/ace.dash.md +308 -0
  75. package/commands/ace.debug.md +169 -0
  76. package/commands/ace.discuss-stage.md +86 -0
  77. package/commands/ace.help.md +465 -0
  78. package/commands/ace.insert-stage.md +231 -0
  79. package/commands/ace.list-stage-assumptions.md +49 -0
  80. package/commands/ace.map-codebase.md +71 -0
  81. package/commands/ace.new-milestone.md +710 -0
  82. package/commands/ace.pause.md +132 -0
  83. package/commands/ace.plan-milestone-gaps.md +295 -0
  84. package/commands/ace.plan-stage.md +568 -0
  85. package/commands/ace.remove-stage.md +353 -0
  86. package/commands/ace.research-stage.md +200 -0
  87. package/commands/ace.run-stage.md +343 -0
  88. package/commands/ace.set-profile.md +116 -0
  89. package/commands/ace.settings.md +151 -0
  90. package/commands/ace.start.md +1008 -0
  91. package/commands/ace.status.md +364 -0
  92. package/hooks/dist/ace-check-update.js +67 -0
  93. package/hooks/dist/ace-statusline.js +96 -0
  94. package/package.json +85 -0
@@ -0,0 +1,833 @@
1
+ <purpose>
2
+
3
+ Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in milestones.md, performs full brief.md evolution review, reorganizes track.md with milestone groupings, and tags the release in git.
4
+
5
+ This is the ritual that separates "development" from "shipped."
6
+
7
+ </purpose>
8
+
9
+ <required_reading>
10
+
11
+ **Read these files NOW:**
12
+
13
+ 1. templates/milestone.md
14
+ 2. templates/milestone-archive.md
15
+ 3. `.ace/track.md`
16
+ 4. `.ace/specs.md`
17
+ 5. `.ace/brief.md`
18
+
19
+ </required_reading>
20
+
21
+ <archival_behavior>
22
+
23
+ When a milestone completes, this workflow:
24
+
25
+ 1. Extracts full milestone details to `.ace/milestones/v[X.Y]-track.md`
26
+ 2. Archives specs to `.ace/milestones/v[X.Y]-specs.md`
27
+ 3. Updates track.md to replace milestone details with one-line summary
28
+ 4. Deletes specs.md (fresh one created for next milestone)
29
+ 5. Performs full brief.md evolution review
30
+ 6. Offers to create next milestone inline
31
+
32
+ **Context Efficiency:** Archives keep track.md constant-size and specs.md milestone-scoped.
33
+
34
+ **Archive Format:**
35
+
36
+ **TRACK archive** uses `templates/milestone-archive.md` template with:
37
+ - Milestone header (status, stages, date)
38
+ - Full stage details from track
39
+ - Milestone summary (decisions, issues, technical debt)
40
+
41
+ **SPECS archive** contains:
42
+ - All v1 specs marked complete with outcomes
43
+ - Traceability table with final status
44
+ - Notes on any specs that changed during milestone
45
+
46
+ </archival_behavior>
47
+
48
+ <process>
49
+
50
+ <step name="verify_readiness">
51
+
52
+ Check if milestone is truly complete:
53
+
54
+ ```bash
55
+ cat .ace/track.md
56
+ ls .ace/stages/*/recap.md 2>/dev/null | wc -l
57
+ ```
58
+
59
+ **Questions to ask:**
60
+
61
+ - Which stages belong to this milestone?
62
+ - Are all those stages complete (all runs have recaps)?
63
+ - Has the work been tested/validated?
64
+ - Is this ready to ship/tag?
65
+
66
+ Present:
67
+
68
+ ```
69
+ Milestone: [Name from user, e.g., "v1.0 MVP"]
70
+
71
+ Appears to include:
72
+ - Stage 1: Foundation (2/2 runs complete)
73
+ - Stage 2: Authentication (2/2 runs complete)
74
+ - Stage 3: Core Features (3/3 runs complete)
75
+ - Stage 4: Polish (1/1 run complete)
76
+
77
+ Total: 4 stages, 8 runs, all complete
78
+ ```
79
+
80
+ <config-check>
81
+
82
+ ```bash
83
+ cat .ace/config.json 2>/dev/null
84
+ ```
85
+
86
+ </config-check>
87
+
88
+ <if style="turbo">
89
+
90
+ ```
91
+ ⚡ Auto-approved: Milestone scope verification
92
+
93
+ [Show breakdown summary without prompting]
94
+
95
+ Proceeding to stats gathering...
96
+ ```
97
+
98
+ Proceed directly to gather_stats step.
99
+
100
+ </if>
101
+
102
+ <if style="guided" OR="custom with gates.confirm_milestone_scope true">
103
+
104
+ ```
105
+ Ready to mark this milestone as shipped?
106
+ (yes / wait / adjust scope)
107
+ ```
108
+
109
+ Wait for confirmation.
110
+
111
+ If "adjust scope": Ask which stages should be included.
112
+ If "wait": Stop, user will return when ready.
113
+
114
+ </if>
115
+
116
+ </step>
117
+
118
+ <step name="gather_stats">
119
+
120
+ Calculate milestone statistics:
121
+
122
+ ```bash
123
+ # Count stages and runs in milestone
124
+ # (user specified or detected from track)
125
+
126
+ # Find git range
127
+ git log --oneline --grep="feat(" | head -20
128
+
129
+ # Count files modified in range
130
+ git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
131
+
132
+ # Count LOC (adapt to language)
133
+ find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
134
+
135
+ # Calculate timeline
136
+ git log --format="%ai" FIRST_COMMIT | tail -1 # Start date
137
+ git log --format="%ai" LAST_COMMIT | head -1 # End date
138
+ ```
139
+
140
+ Present summary:
141
+
142
+ ```
143
+ Milestone Stats:
144
+ - Stages: [X-Y]
145
+ - Runs: [Z] total
146
+ - Tasks: [N] total (estimated from stage recaps)
147
+ - Files modified: [M]
148
+ - Lines of code: [LOC] [language]
149
+ - Timeline: [Days] days ([Start] → [End])
150
+ - Git range: feat(XX.XX) → feat(YY.YY)
151
+ ```
152
+
153
+ </step>
154
+
155
+ <step name="extract_accomplishments">
156
+
157
+ Read all stage recap.md files in milestone range:
158
+
159
+ ```bash
160
+ cat .ace/stages/01-*/01-*-recap.md
161
+ cat .ace/stages/02-*/02-*-recap.md
162
+ # ... for each stage in milestone
163
+ ```
164
+
165
+ From recaps, extract 4-6 key accomplishments.
166
+
167
+ Present:
168
+
169
+ ```
170
+ Key accomplishments for this milestone:
171
+ 1. [Achievement from stage 1]
172
+ 2. [Achievement from stage 2]
173
+ 3. [Achievement from stage 3]
174
+ 4. [Achievement from stage 4]
175
+ 5. [Achievement from stage 5]
176
+ ```
177
+
178
+ </step>
179
+
180
+ <step name="create_milestone_entry">
181
+
182
+ Create or update `.ace/milestones.md`.
183
+
184
+ If file doesn't exist:
185
+
186
+ ```markdown
187
+ # Project Milestones: [Project Name from brief.md]
188
+
189
+ [New entry]
190
+ ```
191
+
192
+ If exists, prepend new entry (reverse chronological order).
193
+
194
+ Use template from `templates/milestone.md`:
195
+
196
+ ```markdown
197
+ ## v[Version] [Name] (Shipped: YYYY-MM-DD)
198
+
199
+ **Delivered:** [One sentence from user]
200
+
201
+ **Stages completed:** [X-Y] ([Z] runs total)
202
+
203
+ **Key accomplishments:**
204
+
205
+ - [List from previous step]
206
+
207
+ **Stats:**
208
+
209
+ - [Files] files created/modified
210
+ - [LOC] lines of [language]
211
+ - [Stages] stages, [Runs] runs, [Tasks] tasks
212
+ - [Days] days from [start milestone or start project] to ship
213
+
214
+ **Git range:** `feat(XX.XX)` → `feat(YY.YY)`
215
+
216
+ **What's next:** [Ask user: what's the next goal?]
217
+
218
+ ---
219
+ ```
220
+
221
+ </step>
222
+
223
+ <step name="evolve_brief_full_review">
224
+
225
+ Perform full brief.md evolution review at milestone completion.
226
+
227
+ **Read all stage recaps in this milestone:**
228
+
229
+ ```bash
230
+ cat .ace/stages/*-*/*-recap.md
231
+ ```
232
+
233
+ **Full review checklist:**
234
+
235
+ 1. **"What This Is" accuracy:**
236
+ - Read current description
237
+ - Compare to what was actually built
238
+ - Update if the product has meaningfully changed
239
+
240
+ 2. **Core Value check:**
241
+ - Is the stated core value still the right priority?
242
+ - Did shipping reveal a different core value?
243
+ - Update if the ONE thing has shifted
244
+
245
+ 3. **Specs audit:**
246
+
247
+ **Validated section:**
248
+ - All Active specs shipped in this milestone → Move to Validated
249
+ - Format: `- ✓ [Spec] — v[X.Y]`
250
+
251
+ **Active section:**
252
+ - Remove specs that moved to Validated
253
+ - Add any new specs for next milestone
254
+ - Keep specs that weren't addressed yet
255
+
256
+ **Out of Scope audit:**
257
+ - Review each item — is the reasoning still valid?
258
+ - Remove items that are no longer relevant
259
+ - Add any specs invalidated during this milestone
260
+
261
+ 4. **Context update:**
262
+ - Current codebase state (LOC, tech stack)
263
+ - User feedback themes (if any)
264
+ - Known issues or technical debt to address
265
+
266
+ 5. **Key Decisions audit:**
267
+ - Extract all decisions from milestone stage recaps
268
+ - Add to Key Decisions table with outcomes where known
269
+ - Mark ✓ Good, ⚠️ Revisit, or — Pending for each
270
+
271
+ 6. **Constraints check:**
272
+ - Any constraints that changed during development?
273
+ - Update as needed
274
+
275
+ **Update brief.md:**
276
+
277
+ Make all edits inline. Update "Last updated" footer:
278
+
279
+ ```markdown
280
+ ---
281
+ *Last updated: [date] after v[X.Y] milestone*
282
+ ```
283
+
284
+ **Step complete when:**
285
+
286
+ - [ ] "What This Is" reviewed and updated if needed
287
+ - [ ] Core Value verified as still correct
288
+ - [ ] All shipped specs moved to Validated
289
+ - [ ] New specs added to Active for next milestone
290
+ - [ ] Out of Scope reasoning audited
291
+ - [ ] Context updated with current state
292
+ - [ ] All milestone decisions added to Key Decisions
293
+ - [ ] "Last updated" footer reflects milestone completion
294
+
295
+ </step>
296
+
297
+ <step name="reorganize_track">
298
+
299
+ Update `.ace/track.md` to group completed milestone stages.
300
+
301
+ Add milestone headers and collapse completed work:
302
+
303
+ ```markdown
304
+ # Track: [Project Name]
305
+
306
+ ## Milestones
307
+
308
+ - ✅ **v1.0 MVP** — Stages 1-4 (shipped YYYY-MM-DD)
309
+ - 🚧 **v1.1 Security** — Stages 5-6 (in progress)
310
+ - 📋 **v2.0 Redesign** — Stages 7-10 (planned)
311
+
312
+ ## Stages
313
+
314
+ <details>
315
+ <summary>✅ v1.0 MVP (Stages 1-4) — SHIPPED YYYY-MM-DD</summary>
316
+
317
+ - [x] Stage 1: Foundation (2/2 runs) — completed YYYY-MM-DD
318
+ - [x] Stage 2: Authentication (2/2 runs) — completed YYYY-MM-DD
319
+ - [x] Stage 3: Core Features (3/3 runs) — completed YYYY-MM-DD
320
+ - [x] Stage 4: Polish (1/1 run) — completed YYYY-MM-DD
321
+
322
+ </details>
323
+
324
+ ### 🚧 v[Next] [Name] (In Progress / Planned)
325
+
326
+ - [ ] Stage 5: [Name] ([N] runs)
327
+ - [ ] Stage 6: [Name] ([N] runs)
328
+
329
+ ## Progress
330
+
331
+ | Stage | Milestone | Runs Complete | Status | Completed |
332
+ | ----------------- | --------- | ------------- | ----------- | ---------- |
333
+ | 1. Foundation | v1.0 | 2/2 | Complete | YYYY-MM-DD |
334
+ | 2. Authentication | v1.0 | 2/2 | Complete | YYYY-MM-DD |
335
+ | 3. Core Features | v1.0 | 3/3 | Complete | YYYY-MM-DD |
336
+ | 4. Polish | v1.0 | 1/1 | Complete | YYYY-MM-DD |
337
+ | 5. Security Audit | v1.1 | 0/1 | Not started | - |
338
+ | 6. Hardening | v1.1 | 0/2 | Not started | - |
339
+ ```
340
+
341
+ </step>
342
+
343
+ <step name="archive_milestone">
344
+
345
+ Extract completed milestone details and create archive file.
346
+
347
+ **Process:**
348
+
349
+ 1. Create archive file path: `.ace/milestones/v[X.Y]-track.md`
350
+
351
+ 2. Read `~/.claude/ace/templates/milestone-archive.md` template
352
+
353
+ 3. Extract data from current track.md:
354
+ - All stages belonging to this milestone (by stage number range)
355
+ - Full stage details (goals, runs, dependencies, status)
356
+ - Stage run lists with completion checkmarks
357
+
358
+ 4. Extract data from brief.md:
359
+ - Key decisions made during this milestone
360
+ - Specs that were validated
361
+
362
+ 5. Fill template {{PLACEHOLDERS}}:
363
+ - {{VERSION}} — Milestone version (e.g., "1.0")
364
+ - {{MILESTONE_NAME}} — From track.md milestone header
365
+ - {{DATE}} — Today's date
366
+ - {{STAGE_START}} — First stage number in milestone
367
+ - {{STAGE_END}} — Last stage number in milestone
368
+ - {{TOTAL_RUNS}} — Count of all runs in milestone
369
+ - {{MILESTONE_DESCRIPTION}} — From track.md overview
370
+ - {{STAGES_SECTION}} — Full stage details extracted
371
+ - {{DECISIONS_FROM_BRIEF}} — Key decisions from brief.md
372
+ - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From recaps
373
+
374
+ 6. Write filled template to `.ace/milestones/v[X.Y]-track.md`
375
+
376
+ 7. Delete track.md (fresh one created for next milestone):
377
+ ```bash
378
+ rm .ace/track.md
379
+ ```
380
+
381
+ 8. Verify archive exists:
382
+ ```bash
383
+ ls .ace/milestones/v[X.Y]-track.md
384
+ ```
385
+
386
+ 9. Confirm track archive complete:
387
+
388
+ ```
389
+ ✅ v[X.Y] track archived to milestones/v[X.Y]-track.md
390
+ ✅ track.md deleted (fresh one for next milestone)
391
+ ```
392
+
393
+ **Note:** Stage directories (`.ace/stages/`) are NOT deleted. They accumulate across milestones as the raw execution history. Stage numbering continues (v1.0 stages 1-4, v1.1 stages 5-8, etc.).
394
+
395
+ </step>
396
+
397
+ <step name="archive_specs">
398
+
399
+ Archive specs and prepare for fresh specs in next milestone.
400
+
401
+ **Process:**
402
+
403
+ 1. Read current specs.md:
404
+ ```bash
405
+ cat .ace/specs.md
406
+ ```
407
+
408
+ 2. Create archive file: `.ace/milestones/v[X.Y]-specs.md`
409
+
410
+ 3. Transform specs for archive:
411
+ - Mark all v1 specs as `[x]` complete
412
+ - Add outcome notes where relevant (validated, adjusted, dropped)
413
+ - Update traceability table status to "Complete" for all shipped specs
414
+ - Add "Milestone Summary" section with:
415
+ - Total specs shipped
416
+ - Any specs that changed scope during milestone
417
+ - Any specs dropped and why
418
+
419
+ 4. Write archive file with header:
420
+ ```markdown
421
+ # Specs Archive: v[X.Y] [Milestone Name]
422
+
423
+ **Archived:** [DATE]
424
+ **Status:** ✅ SHIPPED
425
+
426
+ This is the archived specs for v[X.Y].
427
+ For current specs, see `.ace/specs.md` (created for next milestone).
428
+
429
+ ---
430
+
431
+ [Full specs.md content with checkboxes marked complete]
432
+
433
+ ---
434
+
435
+ ## Milestone Summary
436
+
437
+ **Shipped:** [X] of [Y] v1 specs
438
+ **Adjusted:** [list any specs that changed during implementation]
439
+ **Dropped:** [list any specs removed and why]
440
+
441
+ ---
442
+ *Archived: [DATE] as part of v[X.Y] milestone completion*
443
+ ```
444
+
445
+ 5. Delete original specs.md:
446
+ ```bash
447
+ rm .ace/specs.md
448
+ ```
449
+
450
+ 6. Confirm:
451
+ ```
452
+ ✅ Specs archived to milestones/v[X.Y]-specs.md
453
+ ✅ specs.md deleted (fresh one needed for next milestone)
454
+ ```
455
+
456
+ **Important:** The next milestone workflow starts with `/ace.new-milestone` which includes specs definition. brief.md's Validated section carries the cumulative record across milestones.
457
+
458
+ </step>
459
+
460
+ <step name="archive_audit">
461
+
462
+ Move the milestone audit file to the archive (if it exists):
463
+
464
+ ```bash
465
+ # Move audit to milestones folder (if exists)
466
+ [ -f .ace/v[X.Y]-MILESTONE-AUDIT.md ] && mv .ace/v[X.Y]-MILESTONE-AUDIT.md .ace/milestones/
467
+ ```
468
+
469
+ Confirm:
470
+ ```
471
+ ✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md
472
+ ```
473
+
474
+ (Skip silently if no audit file exists — audit is optional)
475
+
476
+ </step>
477
+
478
+ <step name="update_pulse">
479
+
480
+ Update pulse.md to reflect milestone completion.
481
+
482
+ **Project Reference:**
483
+
484
+ ```markdown
485
+ ## Project Reference
486
+
487
+ See: .ace/brief.md (updated [today])
488
+
489
+ **Core value:** [Current core value from brief.md]
490
+ **Current focus:** [Next milestone or "Planning next milestone"]
491
+ ```
492
+
493
+ **Current Position:**
494
+
495
+ ```markdown
496
+ Stage: [Next stage] of [Total] ([Stage name])
497
+ Run: Not started
498
+ Status: Ready to plan
499
+ Last activity: [today] — v[X.Y] milestone complete
500
+
501
+ Progress: [updated progress bar]
502
+ ```
503
+
504
+ **Accumulated Context:**
505
+
506
+ - Clear decisions summary (full log in brief.md)
507
+ - Clear resolved blockers
508
+ - Keep open blockers for next milestone
509
+
510
+ </step>
511
+
512
+ <step name="handle_branches">
513
+
514
+ Check if branching was used and offer merge options.
515
+
516
+ **Check branching strategy:**
517
+
518
+ ```bash
519
+ # Get branching strategy from config
520
+ BRANCHING_STRATEGY=$(cat .ace/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "none")
521
+ ```
522
+
523
+ **If strategy is "none":** Skip to git_tag step.
524
+
525
+ **For "stage" strategy — find stage branches:**
526
+
527
+ ```bash
528
+ STAGE_BRANCH_TEMPLATE=$(cat .ace/config.json 2>/dev/null | grep -o '"stage_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "ace/stage-{stage}-{slug}")
529
+
530
+ # Extract prefix from template (before first variable)
531
+ BRANCH_PREFIX=$(echo "$STAGE_BRANCH_TEMPLATE" | sed 's/{.*//')
532
+
533
+ # Find all stage branches for this milestone
534
+ STAGE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
535
+ ```
536
+
537
+ **For "milestone" strategy — find milestone branch:**
538
+
539
+ ```bash
540
+ MILESTONE_BRANCH_TEMPLATE=$(cat .ace/config.json 2>/dev/null | grep -o '"milestone_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "ace/{milestone}-{slug}")
541
+
542
+ # Extract prefix from template
543
+ BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
544
+
545
+ # Find milestone branch
546
+ MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
547
+ ```
548
+
549
+ **If no branches found:** Skip to git_tag step.
550
+
551
+ **If branches exist — present merge options:**
552
+
553
+ ```
554
+ ## Git Branches Detected
555
+
556
+ Branching strategy: {stage/milestone}
557
+
558
+ Branches found:
559
+ {list of branches}
560
+
561
+ Options:
562
+ 1. **Merge to main** — Merge branch(es) to main
563
+ 2. **Delete without merging** — Branches already merged or not needed
564
+ 3. **Keep branches** — Leave for manual handling
565
+ ```
566
+
567
+ Use AskUserQuestion:
568
+
569
+ ```
570
+ AskUserQuestion([
571
+ {
572
+ question: "How should branches be handled?",
573
+ header: "Branches",
574
+ multiSelect: false,
575
+ options: [
576
+ { label: "Squash merge (Recommended)", description: "Squash all commits into one clean commit on main" },
577
+ { label: "Merge with history", description: "Preserve all individual commits (--no-ff)" },
578
+ { label: "Delete without merging", description: "Branches already merged or not needed" },
579
+ { label: "Keep branches", description: "Leave branches for manual handling later" }
580
+ ]
581
+ }
582
+ ])
583
+ ```
584
+
585
+ **If "Squash merge":**
586
+
587
+ ```bash
588
+ CURRENT_BRANCH=$(git branch --show-current)
589
+ git checkout main
590
+
591
+ # For stage strategy - squash merge each stage branch
592
+ if [ "$BRANCHING_STRATEGY" = "stage" ]; then
593
+ for branch in $STAGE_BRANCHES; do
594
+ echo "Squash merging $branch..."
595
+ git merge --squash "$branch"
596
+ git commit -m "feat: $branch for v[X.Y]"
597
+ done
598
+ fi
599
+
600
+ # For milestone strategy - squash merge milestone branch
601
+ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
602
+ echo "Squash merging $MILESTONE_BRANCH..."
603
+ git merge --squash "$MILESTONE_BRANCH"
604
+ git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
605
+ fi
606
+
607
+ git checkout "$CURRENT_BRANCH"
608
+ ```
609
+
610
+ Report: "Squash merged branches to main"
611
+
612
+ **If "Merge with history":**
613
+
614
+ ```bash
615
+ CURRENT_BRANCH=$(git branch --show-current)
616
+ git checkout main
617
+
618
+ # For stage strategy - merge each stage branch
619
+ if [ "$BRANCHING_STRATEGY" = "stage" ]; then
620
+ for branch in $STAGE_BRANCHES; do
621
+ echo "Merging $branch..."
622
+ git merge --no-ff "$branch" -m "Merge branch '$branch' for v[X.Y]"
623
+ done
624
+ fi
625
+
626
+ # For milestone strategy - merge milestone branch
627
+ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
628
+ echo "Merging $MILESTONE_BRANCH..."
629
+ git merge --no-ff "$MILESTONE_BRANCH" -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
630
+ fi
631
+
632
+ git checkout "$CURRENT_BRANCH"
633
+ ```
634
+
635
+ Report: "Merged branches to main with full history"
636
+
637
+ **If "Delete without merging":**
638
+
639
+ ```bash
640
+ if [ "$BRANCHING_STRATEGY" = "stage" ]; then
641
+ for branch in $STAGE_BRANCHES; do
642
+ git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
643
+ done
644
+ fi
645
+
646
+ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
647
+ git branch -d "$MILESTONE_BRANCH" 2>/dev/null || git branch -D "$MILESTONE_BRANCH"
648
+ fi
649
+ ```
650
+
651
+ Report: "Deleted branches"
652
+
653
+ **If "Keep branches":**
654
+
655
+ Report: "Branches preserved for manual handling"
656
+
657
+ </step>
658
+
659
+ <step name="git_tag">
660
+
661
+ Create git tag for milestone:
662
+
663
+ ```bash
664
+ git tag -a v[X.Y] -m "$(cat <<'EOF'
665
+ v[X.Y] [Name]
666
+
667
+ Delivered: [One sentence]
668
+
669
+ Key accomplishments:
670
+ - [Item 1]
671
+ - [Item 2]
672
+ - [Item 3]
673
+
674
+ See .ace/milestones.md for full details.
675
+ EOF
676
+ )"
677
+ ```
678
+
679
+ Confirm: "Tagged: v[X.Y]"
680
+
681
+ Ask: "Push tag to remote? (y/n)"
682
+
683
+ If yes:
684
+
685
+ ```bash
686
+ git push origin v[X.Y]
687
+ ```
688
+
689
+ </step>
690
+
691
+ <step name="git_commit_milestone">
692
+
693
+ Commit milestone completion including archive files and deletions.
694
+
695
+ **Check config:**
696
+
697
+ ```bash
698
+ COMMIT_PLANNING_DOCS=$(cat .ace/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
699
+ git check-ignore -q .ace 2>/dev/null && COMMIT_PLANNING_DOCS=false
700
+ ```
701
+
702
+ **If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
703
+
704
+ **If `COMMIT_PLANNING_DOCS=true` (default):**
705
+
706
+ ```bash
707
+ # Stage archive files (new)
708
+ git add .ace/milestones/v[X.Y]-track.md
709
+ git add .ace/milestones/v[X.Y]-specs.md
710
+ git add .ace/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
711
+
712
+ # Stage updated files
713
+ git add .ace/milestones.md
714
+ git add .ace/brief.md
715
+ git add .ace/pulse.md
716
+
717
+ # Stage deletions
718
+ git add -u .ace/
719
+
720
+ # Commit with descriptive message
721
+ git commit -m "$(cat <<'EOF'
722
+ chore: complete v[X.Y] milestone
723
+
724
+ Archived:
725
+ - milestones/v[X.Y]-track.md
726
+ - milestones/v[X.Y]-specs.md
727
+ - milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
728
+
729
+ Deleted (fresh for next milestone):
730
+ - track.md
731
+ - specs.md
732
+
733
+ Updated:
734
+ - milestones.md (new entry)
735
+ - brief.md (specs → Validated)
736
+ - pulse.md (reset for next milestone)
737
+
738
+ Tagged: v[X.Y]
739
+ EOF
740
+ )"
741
+ ```
742
+
743
+ Confirm: "Committed: chore: complete v[X.Y] milestone"
744
+
745
+ </step>
746
+
747
+ <step name="offer_next">
748
+
749
+ ```
750
+ ✅ Milestone v[X.Y] [Name] complete
751
+
752
+ Shipped:
753
+ - [N] stages ([M] runs, [P] tasks)
754
+ - [One sentence of what shipped]
755
+
756
+ Archived:
757
+ - milestones/v[X.Y]-track.md
758
+ - milestones/v[X.Y]-specs.md
759
+
760
+ Summary: .ace/milestones.md
761
+ Tag: v[X.Y]
762
+
763
+ ---
764
+
765
+ ## ▶ Next Up
766
+
767
+ **Start Next Milestone** — questioning → research → specs → track
768
+
769
+ `/ace.new-milestone`
770
+
771
+ <sub>`/clear` first → fresh context window</sub>
772
+
773
+ ---
774
+ ```
775
+
776
+ </step>
777
+
778
+ </process>
779
+
780
+ <milestone_naming>
781
+
782
+ **Version conventions:**
783
+ - **v1.0** — Initial MVP
784
+ - **v1.1, v1.2, v1.3** — Minor updates, new features, fixes
785
+ - **v2.0, v3.0** — Major rewrites, breaking changes, significant new direction
786
+
787
+ **Name conventions:**
788
+ - v1.0 MVP
789
+ - v1.1 Security
790
+ - v1.2 Performance
791
+ - v2.0 Redesign
792
+ - v2.0 iOS Launch
793
+
794
+ Keep names short (1-2 words describing the focus).
795
+
796
+ </milestone_naming>
797
+
798
+ <what_qualifies>
799
+
800
+ **Create milestones for:**
801
+ - Initial release (v1.0)
802
+ - Public releases
803
+ - Major feature sets shipped
804
+ - Before archiving planning
805
+
806
+ **Don't create milestones for:**
807
+ - Every stage completion (too granular)
808
+ - Work in progress (wait until shipped)
809
+ - Internal dev iterations (unless truly shipped internally)
810
+
811
+ If uncertain, ask: "Is this deployed/usable/shipped in some form?"
812
+ If yes → milestone. If no → keep working.
813
+
814
+ </what_qualifies>
815
+
816
+ <success_criteria>
817
+
818
+ Milestone completion is successful when:
819
+
820
+ - [ ] milestones.md entry created with stats and accomplishments
821
+ - [ ] brief.md full evolution review completed
822
+ - [ ] All shipped specs moved to Validated in brief.md
823
+ - [ ] Key Decisions updated with outcomes
824
+ - [ ] track.md reorganized with milestone grouping
825
+ - [ ] Track archive created (milestones/v[X.Y]-track.md)
826
+ - [ ] Specs archive created (milestones/v[X.Y]-specs.md)
827
+ - [ ] specs.md deleted (fresh for next milestone)
828
+ - [ ] pulse.md updated with fresh project reference
829
+ - [ ] Git tag created (v[X.Y])
830
+ - [ ] Milestone commit made (includes archive files and deletion)
831
+ - [ ] User knows next step (/ace.new-milestone)
832
+
833
+ </success_criteria>