@howlil/ez-agents 2.0.0 → 3.0.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 (145) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +157 -110
  3. package/README.zh-CN.md +84 -84
  4. package/agents/ez-plan-checker.md +2 -2
  5. package/agents/ez-research-synthesizer.md +1 -1
  6. package/agents/ez-ui-auditor.md +0 -2
  7. package/agents/ez-ui-checker.md +2 -4
  8. package/agents/ez-ui-researcher.md +0 -2
  9. package/agents/ez-verifier.md +1 -1
  10. package/bin/install.js +211 -211
  11. package/commands/ez/debug.md +1 -1
  12. package/commands/ez/map-codebase.md +1 -1
  13. package/commands/ez/reapply-patches.md +3 -3
  14. package/commands/ez/research-phase.md +1 -1
  15. package/{get-shit-done → ez-agents}/bin/ez-tools.cjs +1 -1
  16. package/{get-shit-done → ez-agents}/bin/lib/assistant-adapter.cjs +205 -205
  17. package/{get-shit-done → ez-agents}/bin/lib/audit-exec.cjs +150 -150
  18. package/{get-shit-done → ez-agents}/bin/lib/auth.cjs +175 -175
  19. package/{get-shit-done → ez-agents}/bin/lib/circuit-breaker.cjs +118 -118
  20. package/{get-shit-done → ez-agents}/bin/lib/commands.cjs +666 -666
  21. package/{get-shit-done → ez-agents}/bin/lib/config.cjs +183 -183
  22. package/{get-shit-done → ez-agents}/bin/lib/core.cjs +495 -495
  23. package/{get-shit-done → ez-agents}/bin/lib/file-lock.cjs +236 -236
  24. package/{get-shit-done → ez-agents}/bin/lib/frontmatter.cjs +299 -299
  25. package/{get-shit-done → ez-agents}/bin/lib/fs-utils.cjs +153 -153
  26. package/{get-shit-done → ez-agents}/bin/lib/git-utils.cjs +203 -203
  27. package/{get-shit-done → ez-agents}/bin/lib/health-check.cjs +163 -163
  28. package/{get-shit-done → ez-agents}/bin/lib/index.cjs +113 -113
  29. package/{get-shit-done → ez-agents}/bin/lib/init.cjs +710 -710
  30. package/{get-shit-done → ez-agents}/bin/lib/logger.cjs +117 -117
  31. package/{get-shit-done → ez-agents}/bin/lib/milestone.cjs +241 -241
  32. package/{get-shit-done → ez-agents}/bin/lib/model-provider.cjs +146 -146
  33. package/{get-shit-done → ez-agents}/bin/lib/phase.cjs +908 -908
  34. package/{get-shit-done → ez-agents}/bin/lib/retry.cjs +119 -119
  35. package/{get-shit-done → ez-agents}/bin/lib/roadmap.cjs +305 -305
  36. package/{get-shit-done → ez-agents}/bin/lib/safe-exec.cjs +128 -128
  37. package/{get-shit-done → ez-agents}/bin/lib/safe-path.cjs +130 -130
  38. package/{get-shit-done → ez-agents}/bin/lib/state.cjs +721 -721
  39. package/{get-shit-done → ez-agents}/bin/lib/temp-file.cjs +239 -239
  40. package/{get-shit-done → ez-agents}/bin/lib/template.cjs +222 -222
  41. package/{get-shit-done → ez-agents}/bin/lib/test-file-lock.cjs +112 -112
  42. package/{get-shit-done → ez-agents}/bin/lib/test-graceful.cjs +93 -93
  43. package/{get-shit-done → ez-agents}/bin/lib/test-logger.cjs +60 -60
  44. package/{get-shit-done → ez-agents}/bin/lib/test-safe-exec.cjs +38 -38
  45. package/{get-shit-done → ez-agents}/bin/lib/test-safe-path.cjs +33 -33
  46. package/{get-shit-done → ez-agents}/bin/lib/test-temp-file.cjs +125 -125
  47. package/{get-shit-done → ez-agents}/bin/lib/timeout-exec.cjs +62 -62
  48. package/{get-shit-done → ez-agents}/bin/lib/verify.cjs +820 -820
  49. package/{get-shit-done → ez-agents}/references/checkpoints.md +776 -776
  50. package/{get-shit-done → ez-agents}/references/questioning.md +162 -162
  51. package/{get-shit-done → ez-agents}/references/tdd.md +263 -263
  52. package/{get-shit-done → ez-agents}/templates/codebase/concerns.md +310 -310
  53. package/{get-shit-done → ez-agents}/templates/codebase/conventions.md +307 -307
  54. package/{get-shit-done → ez-agents}/templates/codebase/integrations.md +280 -280
  55. package/{get-shit-done → ez-agents}/templates/codebase/stack.md +186 -186
  56. package/{get-shit-done → ez-agents}/templates/codebase/testing.md +480 -480
  57. package/{get-shit-done → ez-agents}/templates/config.json +37 -37
  58. package/{get-shit-done → ez-agents}/templates/continue-here.md +78 -78
  59. package/{get-shit-done → ez-agents}/templates/milestone-archive.md +123 -123
  60. package/{get-shit-done → ez-agents}/templates/milestone.md +115 -115
  61. package/{get-shit-done → ez-agents}/templates/requirements.md +231 -231
  62. package/{get-shit-done → ez-agents}/templates/research-project/ARCHITECTURE.md +204 -204
  63. package/{get-shit-done → ez-agents}/templates/research-project/FEATURES.md +147 -147
  64. package/{get-shit-done → ez-agents}/templates/research-project/PITFALLS.md +200 -200
  65. package/{get-shit-done → ez-agents}/templates/research-project/STACK.md +120 -120
  66. package/{get-shit-done → ez-agents}/templates/research-project/SUMMARY.md +170 -170
  67. package/{get-shit-done → ez-agents}/templates/retrospective.md +54 -54
  68. package/{get-shit-done → ez-agents}/templates/roadmap.md +202 -202
  69. package/{get-shit-done → ez-agents}/templates/summary-minimal.md +41 -41
  70. package/{get-shit-done → ez-agents}/templates/summary-standard.md +48 -48
  71. package/{get-shit-done → ez-agents}/templates/summary.md +248 -248
  72. package/{get-shit-done → ez-agents}/templates/user-setup.md +311 -311
  73. package/{get-shit-done → ez-agents}/templates/verification-report.md +322 -322
  74. package/{get-shit-done → ez-agents}/workflows/add-phase.md +112 -112
  75. package/{get-shit-done → ez-agents}/workflows/add-tests.md +351 -351
  76. package/{get-shit-done → ez-agents}/workflows/add-todo.md +158 -158
  77. package/{get-shit-done → ez-agents}/workflows/audit-milestone.md +332 -332
  78. package/{get-shit-done → ez-agents}/workflows/autonomous.md +743 -743
  79. package/{get-shit-done → ez-agents}/workflows/check-todos.md +177 -177
  80. package/{get-shit-done → ez-agents}/workflows/cleanup.md +152 -152
  81. package/{get-shit-done → ez-agents}/workflows/complete-milestone.md +766 -766
  82. package/ez-agents/workflows/debug.md +0 -0
  83. package/{get-shit-done → ez-agents}/workflows/diagnose-issues.md +219 -219
  84. package/{get-shit-done → ez-agents}/workflows/discovery-phase.md +289 -289
  85. package/{get-shit-done → ez-agents}/workflows/discuss-phase.md +762 -762
  86. package/{get-shit-done → ez-agents}/workflows/execute-phase.md +468 -468
  87. package/{get-shit-done → ez-agents}/workflows/execute-plan.md +483 -483
  88. package/{get-shit-done → ez-agents}/workflows/health.md +159 -159
  89. package/{get-shit-done → ez-agents}/workflows/help.md +492 -492
  90. package/{get-shit-done → ez-agents}/workflows/insert-phase.md +130 -130
  91. package/{get-shit-done → ez-agents}/workflows/list-phase-assumptions.md +178 -178
  92. package/{get-shit-done → ez-agents}/workflows/map-codebase.md +316 -316
  93. package/{get-shit-done → ez-agents}/workflows/new-milestone.md +384 -384
  94. package/{get-shit-done → ez-agents}/workflows/new-project.md +1111 -1111
  95. package/{get-shit-done → ez-agents}/workflows/node-repair.md +92 -92
  96. package/{get-shit-done → ez-agents}/workflows/pause-work.md +122 -122
  97. package/{get-shit-done → ez-agents}/workflows/plan-milestone-gaps.md +274 -274
  98. package/{get-shit-done → ez-agents}/workflows/plan-phase.md +651 -651
  99. package/{get-shit-done → ez-agents}/workflows/progress.md +382 -382
  100. package/{get-shit-done → ez-agents}/workflows/quick.md +610 -610
  101. package/{get-shit-done → ez-agents}/workflows/remove-phase.md +155 -155
  102. package/{get-shit-done → ez-agents}/workflows/research-phase.md +74 -74
  103. package/{get-shit-done → ez-agents}/workflows/resume-project.md +307 -307
  104. package/{get-shit-done → ez-agents}/workflows/set-profile.md +81 -81
  105. package/{get-shit-done → ez-agents}/workflows/settings.md +242 -242
  106. package/{get-shit-done → ez-agents}/workflows/stats.md +57 -57
  107. package/{get-shit-done → ez-agents}/workflows/transition.md +544 -544
  108. package/{get-shit-done → ez-agents}/workflows/ui-phase.md +290 -290
  109. package/{get-shit-done → ez-agents}/workflows/ui-review.md +157 -157
  110. package/{get-shit-done → ez-agents}/workflows/update.md +320 -320
  111. package/{get-shit-done → ez-agents}/workflows/validate-phase.md +167 -167
  112. package/{get-shit-done → ez-agents}/workflows/verify-phase.md +243 -243
  113. package/{get-shit-done → ez-agents}/workflows/verify-work.md +5 -5
  114. package/hooks/dist/ez-check-update.js +81 -0
  115. package/hooks/dist/ez-context-monitor.js +141 -0
  116. package/hooks/dist/ez-statusline.js +115 -0
  117. package/package.json +13 -3
  118. package/scripts/build-hooks.js +43 -43
  119. package/scripts/run-tests.cjs +29 -29
  120. /package/{get-shit-done → ez-agents}/references/continuation-format.md +0 -0
  121. /package/{get-shit-done → ez-agents}/references/decimal-phase-calculation.md +0 -0
  122. /package/{get-shit-done → ez-agents}/references/git-integration.md +0 -0
  123. /package/{get-shit-done → ez-agents}/references/git-planning-commit.md +0 -0
  124. /package/{get-shit-done → ez-agents}/references/model-profile-resolution.md +0 -0
  125. /package/{get-shit-done → ez-agents}/references/model-profiles.md +0 -0
  126. /package/{get-shit-done → ez-agents}/references/phase-argument-parsing.md +0 -0
  127. /package/{get-shit-done → ez-agents}/references/planning-config.md +0 -0
  128. /package/{get-shit-done → ez-agents}/references/ui-brand.md +0 -0
  129. /package/{get-shit-done → ez-agents}/references/verification-patterns.md +0 -0
  130. /package/{get-shit-done → ez-agents}/templates/DEBUG.md +0 -0
  131. /package/{get-shit-done → ez-agents}/templates/UAT.md +0 -0
  132. /package/{get-shit-done → ez-agents}/templates/UI-SPEC.md +0 -0
  133. /package/{get-shit-done → ez-agents}/templates/VALIDATION.md +0 -0
  134. /package/{get-shit-done → ez-agents}/templates/codebase/architecture.md +0 -0
  135. /package/{get-shit-done → ez-agents}/templates/codebase/structure.md +0 -0
  136. /package/{get-shit-done → ez-agents}/templates/context.md +0 -0
  137. /package/{get-shit-done → ez-agents}/templates/copilot-instructions.md +0 -0
  138. /package/{get-shit-done → ez-agents}/templates/debug-subagent-prompt.md +0 -0
  139. /package/{get-shit-done → ez-agents}/templates/discovery.md +0 -0
  140. /package/{get-shit-done → ez-agents}/templates/phase-prompt.md +0 -0
  141. /package/{get-shit-done → ez-agents}/templates/planner-subagent-prompt.md +0 -0
  142. /package/{get-shit-done → ez-agents}/templates/project.md +0 -0
  143. /package/{get-shit-done → ez-agents}/templates/research.md +0 -0
  144. /package/{get-shit-done → ez-agents}/templates/state.md +0 -0
  145. /package/{get-shit-done → ez-agents}/templates/summary-complex.md +0 -0
@@ -1,37 +1,37 @@
1
- {
2
- "mode": "interactive",
3
- "granularity": "standard",
4
- "workflow": {
5
- "research": true,
6
- "plan_check": true,
7
- "verifier": true,
8
- "auto_advance": false,
9
- "nyquist_validation": true
10
- },
11
- "planning": {
12
- "commit_docs": true,
13
- "search_gitignored": false
14
- },
15
- "parallelization": {
16
- "enabled": true,
17
- "plan_level": true,
18
- "task_level": false,
19
- "skip_checkpoints": true,
20
- "max_concurrent_agents": 3,
21
- "min_plans_for_parallel": 2
22
- },
23
- "gates": {
24
- "confirm_project": true,
25
- "confirm_phases": true,
26
- "confirm_roadmap": true,
27
- "confirm_breakdown": true,
28
- "confirm_plan": true,
29
- "execute_next_plan": true,
30
- "issues_review": true,
31
- "confirm_transition": true
32
- },
33
- "safety": {
34
- "always_confirm_destructive": true,
35
- "always_confirm_external_services": true
36
- }
37
- }
1
+ {
2
+ "mode": "interactive",
3
+ "granularity": "standard",
4
+ "workflow": {
5
+ "research": true,
6
+ "plan_check": true,
7
+ "verifier": true,
8
+ "auto_advance": false,
9
+ "nyquist_validation": true
10
+ },
11
+ "planning": {
12
+ "commit_docs": true,
13
+ "search_gitignored": false
14
+ },
15
+ "parallelization": {
16
+ "enabled": true,
17
+ "plan_level": true,
18
+ "task_level": false,
19
+ "skip_checkpoints": true,
20
+ "max_concurrent_agents": 3,
21
+ "min_plans_for_parallel": 2
22
+ },
23
+ "gates": {
24
+ "confirm_project": true,
25
+ "confirm_phases": true,
26
+ "confirm_roadmap": true,
27
+ "confirm_breakdown": true,
28
+ "confirm_plan": true,
29
+ "execute_next_plan": true,
30
+ "issues_review": true,
31
+ "confirm_transition": true
32
+ },
33
+ "safety": {
34
+ "always_confirm_destructive": true,
35
+ "always_confirm_external_services": true
36
+ }
37
+ }
@@ -1,78 +1,78 @@
1
- # Continue-Here Template
2
-
3
- Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
4
-
5
- ```yaml
6
- ---
7
- phase: XX-name
8
- task: 3
9
- total_tasks: 7
10
- status: in_progress
11
- last_updated: 2025-01-15T14:30:00Z
12
- ---
13
- ```
14
-
15
- ```markdown
16
- <current_state>
17
- [Where exactly are we? What's the immediate context?]
18
- </current_state>
19
-
20
- <completed_work>
21
- [What got done this session - be specific]
22
-
23
- - Task 1: [name] - Done
24
- - Task 2: [name] - Done
25
- - Task 3: [name] - In progress, [what's done on it]
26
- </completed_work>
27
-
28
- <remaining_work>
29
- [What's left in this phase]
30
-
31
- - Task 3: [name] - [what's left to do]
32
- - Task 4: [name] - Not started
33
- - Task 5: [name] - Not started
34
- </remaining_work>
35
-
36
- <decisions_made>
37
- [Key decisions and why - so next session doesn't re-debate]
38
-
39
- - Decided to use [X] because [reason]
40
- - Chose [approach] over [alternative] because [reason]
41
- </decisions_made>
42
-
43
- <blockers>
44
- [Anything stuck or waiting on external factors]
45
-
46
- - [Blocker 1]: [status/workaround]
47
- </blockers>
48
-
49
- <context>
50
- [Mental state, "vibe", anything that helps resume smoothly]
51
-
52
- [What were you thinking about? What was the plan?
53
- This is the "pick up exactly where you left off" context.]
54
- </context>
55
-
56
- <next_action>
57
- [The very first thing to do when resuming]
58
-
59
- Start with: [specific action]
60
- </next_action>
61
- ```
62
-
63
- <yaml_fields>
64
- Required YAML frontmatter:
65
-
66
- - `phase`: Directory name (e.g., `02-authentication`)
67
- - `task`: Current task number
68
- - `total_tasks`: How many tasks in phase
69
- - `status`: `in_progress`, `blocked`, `almost_done`
70
- - `last_updated`: ISO timestamp
71
- </yaml_fields>
72
-
73
- <guidelines>
74
- - Be specific enough that a fresh Claude instance understands immediately
75
- - Include WHY decisions were made, not just what
76
- - The `<next_action>` should be actionable without reading anything else
77
- - This file gets DELETED after resume - it's not permanent storage
78
- </guidelines>
1
+ # Continue-Here Template
2
+
3
+ Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
4
+
5
+ ```yaml
6
+ ---
7
+ phase: XX-name
8
+ task: 3
9
+ total_tasks: 7
10
+ status: in_progress
11
+ last_updated: 2025-01-15T14:30:00Z
12
+ ---
13
+ ```
14
+
15
+ ```markdown
16
+ <current_state>
17
+ [Where exactly are we? What's the immediate context?]
18
+ </current_state>
19
+
20
+ <completed_work>
21
+ [What got done this session - be specific]
22
+
23
+ - Task 1: [name] - Done
24
+ - Task 2: [name] - Done
25
+ - Task 3: [name] - In progress, [what's done on it]
26
+ </completed_work>
27
+
28
+ <remaining_work>
29
+ [What's left in this phase]
30
+
31
+ - Task 3: [name] - [what's left to do]
32
+ - Task 4: [name] - Not started
33
+ - Task 5: [name] - Not started
34
+ </remaining_work>
35
+
36
+ <decisions_made>
37
+ [Key decisions and why - so next session doesn't re-debate]
38
+
39
+ - Decided to use [X] because [reason]
40
+ - Chose [approach] over [alternative] because [reason]
41
+ </decisions_made>
42
+
43
+ <blockers>
44
+ [Anything stuck or waiting on external factors]
45
+
46
+ - [Blocker 1]: [status/workaround]
47
+ </blockers>
48
+
49
+ <context>
50
+ [Mental state, "vibe", anything that helps resume smoothly]
51
+
52
+ [What were you thinking about? What was the plan?
53
+ This is the "pick up exactly where you left off" context.]
54
+ </context>
55
+
56
+ <next_action>
57
+ [The very first thing to do when resuming]
58
+
59
+ Start with: [specific action]
60
+ </next_action>
61
+ ```
62
+
63
+ <yaml_fields>
64
+ Required YAML frontmatter:
65
+
66
+ - `phase`: Directory name (e.g., `02-authentication`)
67
+ - `task`: Current task number
68
+ - `total_tasks`: How many tasks in phase
69
+ - `status`: `in_progress`, `blocked`, `almost_done`
70
+ - `last_updated`: ISO timestamp
71
+ </yaml_fields>
72
+
73
+ <guidelines>
74
+ - Be specific enough that a fresh Claude instance understands immediately
75
+ - Include WHY decisions were made, not just what
76
+ - The `<next_action>` should be actionable without reading anything else
77
+ - This file gets DELETED after resume - it's not permanent storage
78
+ </guidelines>
@@ -1,123 +1,123 @@
1
- # Milestone Archive Template
2
-
3
- This template is used by the complete-milestone workflow to create archive files in `.planning/milestones/`.
4
-
5
- ---
6
-
7
- ## File Template
8
-
9
- # Milestone v{{VERSION}}: {{MILESTONE_NAME}}
10
-
11
- **Status:** ✅ SHIPPED {{DATE}}
12
- **Phases:** {{PHASE_START}}-{{PHASE_END}}
13
- **Total Plans:** {{TOTAL_PLANS}}
14
-
15
- ## Overview
16
-
17
- {{MILESTONE_DESCRIPTION}}
18
-
19
- ## Phases
20
-
21
- {{PHASES_SECTION}}
22
-
23
- [For each phase in this milestone, include:]
24
-
25
- ### Phase {{PHASE_NUM}}: {{PHASE_NAME}}
26
-
27
- **Goal**: {{PHASE_GOAL}}
28
- **Depends on**: {{DEPENDS_ON}}
29
- **Plans**: {{PLAN_COUNT}} plans
30
-
31
- Plans:
32
-
33
- - [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
34
- - [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
35
- [... all plans ...]
36
-
37
- **Details:**
38
- {{PHASE_DETAILS_FROM_ROADMAP}}
39
-
40
- **For decimal phases, include (INSERTED) marker:**
41
-
42
- ### Phase 2.1: Critical Security Patch (INSERTED)
43
-
44
- **Goal**: Fix authentication bypass vulnerability
45
- **Depends on**: Phase 2
46
- **Plans**: 1 plan
47
-
48
- Plans:
49
-
50
- - [x] 02.1-01: Patch auth vulnerability
51
-
52
- **Details:**
53
- {{PHASE_DETAILS_FROM_ROADMAP}}
54
-
55
- ---
56
-
57
- ## Milestone Summary
58
-
59
- **Decimal Phases:**
60
-
61
- - Phase 2.1: Critical Security Patch (inserted after Phase 2 for urgent fix)
62
- - Phase 5.1: Performance Hotfix (inserted after Phase 5 for production issue)
63
-
64
- **Key Decisions:**
65
- {{DECISIONS_FROM_PROJECT_STATE}}
66
- [Example:]
67
-
68
- - Decision: Use ROADMAP.md split (Rationale: Constant context cost)
69
- - Decision: Decimal phase numbering (Rationale: Clear insertion semantics)
70
-
71
- **Issues Resolved:**
72
- {{ISSUES_RESOLVED_DURING_MILESTONE}}
73
- [Example:]
74
-
75
- - Fixed context overflow at 100+ phases
76
- - Resolved phase insertion confusion
77
-
78
- **Issues Deferred:**
79
- {{ISSUES_DEFERRED_TO_LATER}}
80
- [Example:]
81
-
82
- - PROJECT-STATE.md tiering (deferred until decisions > 300)
83
-
84
- **Technical Debt Incurred:**
85
- {{SHORTCUTS_NEEDING_FUTURE_WORK}}
86
- [Example:]
87
-
88
- - Some workflows still have hardcoded paths (fix in Phase 5)
89
-
90
- ---
91
-
92
- _For current project status, see .planning/ROADMAP.md_
93
-
94
- ---
95
-
96
- ## Usage Guidelines
97
-
98
- <guidelines>
99
- **When to create milestone archives:**
100
- - After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
101
- - Triggered by complete-milestone workflow
102
- - Before planning next milestone work
103
-
104
- **How to fill template:**
105
-
106
- - Replace {{PLACEHOLDERS}} with actual values
107
- - Extract phase details from ROADMAP.md
108
- - Document decimal phases with (INSERTED) marker
109
- - Include key decisions from PROJECT-STATE.md or SUMMARY files
110
- - List issues resolved vs deferred
111
- - Capture technical debt for future reference
112
-
113
- **Archive location:**
114
-
115
- - Save to `.planning/milestones/v{VERSION}-{NAME}.md`
116
- - Example: `.planning/milestones/v1.0-mvp.md`
117
-
118
- **After archiving:**
119
-
120
- - Update ROADMAP.md to collapse completed milestone in `<details>` tag
121
- - Update PROJECT.md to brownfield format with Current State section
122
- - Continue phase numbering in next milestone (never restart at 01)
123
- </guidelines>
1
+ # Milestone Archive Template
2
+
3
+ This template is used by the complete-milestone workflow to create archive files in `.planning/milestones/`.
4
+
5
+ ---
6
+
7
+ ## File Template
8
+
9
+ # Milestone v{{VERSION}}: {{MILESTONE_NAME}}
10
+
11
+ **Status:** ✅ SHIPPED {{DATE}}
12
+ **Phases:** {{PHASE_START}}-{{PHASE_END}}
13
+ **Total Plans:** {{TOTAL_PLANS}}
14
+
15
+ ## Overview
16
+
17
+ {{MILESTONE_DESCRIPTION}}
18
+
19
+ ## Phases
20
+
21
+ {{PHASES_SECTION}}
22
+
23
+ [For each phase in this milestone, include:]
24
+
25
+ ### Phase {{PHASE_NUM}}: {{PHASE_NAME}}
26
+
27
+ **Goal**: {{PHASE_GOAL}}
28
+ **Depends on**: {{DEPENDS_ON}}
29
+ **Plans**: {{PLAN_COUNT}} plans
30
+
31
+ Plans:
32
+
33
+ - [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
34
+ - [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
35
+ [... all plans ...]
36
+
37
+ **Details:**
38
+ {{PHASE_DETAILS_FROM_ROADMAP}}
39
+
40
+ **For decimal phases, include (INSERTED) marker:**
41
+
42
+ ### Phase 2.1: Critical Security Patch (INSERTED)
43
+
44
+ **Goal**: Fix authentication bypass vulnerability
45
+ **Depends on**: Phase 2
46
+ **Plans**: 1 plan
47
+
48
+ Plans:
49
+
50
+ - [x] 02.1-01: Patch auth vulnerability
51
+
52
+ **Details:**
53
+ {{PHASE_DETAILS_FROM_ROADMAP}}
54
+
55
+ ---
56
+
57
+ ## Milestone Summary
58
+
59
+ **Decimal Phases:**
60
+
61
+ - Phase 2.1: Critical Security Patch (inserted after Phase 2 for urgent fix)
62
+ - Phase 5.1: Performance Hotfix (inserted after Phase 5 for production issue)
63
+
64
+ **Key Decisions:**
65
+ {{DECISIONS_FROM_PROJECT_STATE}}
66
+ [Example:]
67
+
68
+ - Decision: Use ROADMAP.md split (Rationale: Constant context cost)
69
+ - Decision: Decimal phase numbering (Rationale: Clear insertion semantics)
70
+
71
+ **Issues Resolved:**
72
+ {{ISSUES_RESOLVED_DURING_MILESTONE}}
73
+ [Example:]
74
+
75
+ - Fixed context overflow at 100+ phases
76
+ - Resolved phase insertion confusion
77
+
78
+ **Issues Deferred:**
79
+ {{ISSUES_DEFERRED_TO_LATER}}
80
+ [Example:]
81
+
82
+ - PROJECT-STATE.md tiering (deferred until decisions > 300)
83
+
84
+ **Technical Debt Incurred:**
85
+ {{SHORTCUTS_NEEDING_FUTURE_WORK}}
86
+ [Example:]
87
+
88
+ - Some workflows still have hardcoded paths (fix in Phase 5)
89
+
90
+ ---
91
+
92
+ _For current project status, see .planning/ROADMAP.md_
93
+
94
+ ---
95
+
96
+ ## Usage Guidelines
97
+
98
+ <guidelines>
99
+ **When to create milestone archives:**
100
+ - After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
101
+ - Triggered by complete-milestone workflow
102
+ - Before planning next milestone work
103
+
104
+ **How to fill template:**
105
+
106
+ - Replace {{PLACEHOLDERS}} with actual values
107
+ - Extract phase details from ROADMAP.md
108
+ - Document decimal phases with (INSERTED) marker
109
+ - Include key decisions from PROJECT-STATE.md or SUMMARY files
110
+ - List issues resolved vs deferred
111
+ - Capture technical debt for future reference
112
+
113
+ **Archive location:**
114
+
115
+ - Save to `.planning/milestones/v{VERSION}-{NAME}.md`
116
+ - Example: `.planning/milestones/v1.0-mvp.md`
117
+
118
+ **After archiving:**
119
+
120
+ - Update ROADMAP.md to collapse completed milestone in `<details>` tag
121
+ - Update PROJECT.md to brownfield format with Current State section
122
+ - Continue phase numbering in next milestone (never restart at 01)
123
+ </guidelines>