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.
- package/LICENSE +22 -0
- package/README.md +40 -0
- package/ace/references/continuation-format.md +249 -0
- package/ace/references/gates.md +1078 -0
- package/ace/references/git-integration.md +254 -0
- package/ace/references/horsepower-profiles.md +73 -0
- package/ace/references/planning-config.md +189 -0
- package/ace/references/questioning.md +141 -0
- package/ace/references/tdd.md +263 -0
- package/ace/references/ui-brand.md +160 -0
- package/ace/references/verification-patterns.md +612 -0
- package/ace/templates/architect-prompt.md +117 -0
- package/ace/templates/brief.md +184 -0
- package/ace/templates/codebase/architecture.md +264 -0
- package/ace/templates/codebase/concerns.md +310 -0
- package/ace/templates/codebase/conventions.md +307 -0
- package/ace/templates/codebase/integrations.md +280 -0
- package/ace/templates/codebase/stack.md +186 -0
- package/ace/templates/codebase/structure.md +295 -0
- package/ace/templates/codebase/testing.md +480 -0
- package/ace/templates/config.json +36 -0
- package/ace/templates/continue-here.md +78 -0
- package/ace/templates/debug.md +159 -0
- package/ace/templates/detective-prompt.md +91 -0
- package/ace/templates/intel.md +283 -0
- package/ace/templates/milestone-archive.md +123 -0
- package/ace/templates/milestone.md +115 -0
- package/ace/templates/proof.md +322 -0
- package/ace/templates/pulse.md +176 -0
- package/ace/templates/recap.md +246 -0
- package/ace/templates/research/architecture.md +204 -0
- package/ace/templates/research/features.md +147 -0
- package/ace/templates/research/pitfalls.md +200 -0
- package/ace/templates/research/recap.md +170 -0
- package/ace/templates/research/stack.md +120 -0
- package/ace/templates/research-lite.md +146 -0
- package/ace/templates/research.md +552 -0
- package/ace/templates/specs.md +231 -0
- package/ace/templates/stage-prompt.md +567 -0
- package/ace/templates/track.md +202 -0
- package/ace/templates/uat.md +247 -0
- package/ace/templates/user-setup.md +311 -0
- package/ace/workflows/audit-stage.md +628 -0
- package/ace/workflows/audit-work.md +596 -0
- package/ace/workflows/continue-project.md +305 -0
- package/ace/workflows/diagnose-issues.md +231 -0
- package/ace/workflows/list-assumptions.md +178 -0
- package/ace/workflows/map-codebase.md +322 -0
- package/ace/workflows/research-stage.md +289 -0
- package/ace/workflows/run-plan.md +1844 -0
- package/ace/workflows/run-stage.md +686 -0
- package/ace/workflows/scope-stage.md +433 -0
- package/ace/workflows/ship-milestone.md +833 -0
- package/ace/workflows/transition.md +556 -0
- package/agents/ace-architect.md +1415 -0
- package/agents/ace-auditor.md +778 -0
- package/agents/ace-codebase-mapper.md +738 -0
- package/agents/ace-detective.md +1203 -0
- package/agents/ace-integration-checker.md +423 -0
- package/agents/ace-navigator.md +605 -0
- package/agents/ace-plan-reviewer.md +812 -0
- package/agents/ace-project-scout.md +865 -0
- package/agents/ace-runner.md +784 -0
- package/agents/ace-stage-scout.md +669 -0
- package/agents/ace-synthesizer.md +256 -0
- package/bin/install.js +1432 -0
- package/commands/ace.add-stage.md +211 -0
- package/commands/ace.add-todo.md +194 -0
- package/commands/ace.audit-milestone.md +277 -0
- package/commands/ace.audit.md +219 -0
- package/commands/ace.check-todos.md +229 -0
- package/commands/ace.complete-milestone.md +134 -0
- package/commands/ace.continue.md +46 -0
- package/commands/ace.dash.md +308 -0
- package/commands/ace.debug.md +169 -0
- package/commands/ace.discuss-stage.md +86 -0
- package/commands/ace.help.md +465 -0
- package/commands/ace.insert-stage.md +231 -0
- package/commands/ace.list-stage-assumptions.md +49 -0
- package/commands/ace.map-codebase.md +71 -0
- package/commands/ace.new-milestone.md +710 -0
- package/commands/ace.pause.md +132 -0
- package/commands/ace.plan-milestone-gaps.md +295 -0
- package/commands/ace.plan-stage.md +568 -0
- package/commands/ace.remove-stage.md +353 -0
- package/commands/ace.research-stage.md +200 -0
- package/commands/ace.run-stage.md +343 -0
- package/commands/ace.set-profile.md +116 -0
- package/commands/ace.settings.md +151 -0
- package/commands/ace.start.md +1008 -0
- package/commands/ace.status.md +364 -0
- package/hooks/dist/ace-check-update.js +67 -0
- package/hooks/dist/ace-statusline.js +96 -0
- 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>
|