agile-context-engineering 0.3.0 → 0.5.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 (147) hide show
  1. package/.claude-plugin/plugin.json +10 -0
  2. package/LICENSE +51 -51
  3. package/README.md +332 -324
  4. package/agents/ace-product-owner.md +1 -1
  5. package/agents/ace-research-synthesizer.md +228 -228
  6. package/agents/ace-wiki-mapper.md +449 -445
  7. package/bin/install.js +60 -64
  8. package/hooks/ace-check-update.js +70 -62
  9. package/hooks/ace-statusline.js +89 -89
  10. package/package.json +5 -4
  11. package/shared/lib/ace-core.js +308 -0
  12. package/shared/lib/ace-core.test.js +308 -0
  13. package/shared/lib/ace-github.js +753 -0
  14. package/shared/lib/ace-story.js +400 -0
  15. package/shared/lib/ace-story.test.js +250 -0
  16. package/{agile-context-engineering → shared}/utils/questioning.xml +110 -110
  17. package/{agile-context-engineering → shared}/utils/ui-formatting.md +299 -299
  18. package/skills/execute-story/SKILL.md +110 -0
  19. package/skills/execute-story/script.js +305 -0
  20. package/skills/execute-story/script.test.js +261 -0
  21. package/skills/execute-story/walkthrough-template.xml +255 -0
  22. package/{agile-context-engineering/workflows/execute-story.xml → skills/execute-story/workflow.xml} +1219 -1219
  23. package/skills/help/SKILL.md +69 -0
  24. package/skills/help/script.js +318 -0
  25. package/skills/help/script.test.js +183 -0
  26. package/{agile-context-engineering/workflows/help.xml → skills/help/workflow.xml} +540 -540
  27. package/skills/init-coding-standards/SKILL.md +72 -0
  28. package/skills/init-coding-standards/script.js +59 -0
  29. package/skills/init-coding-standards/script.test.js +70 -0
  30. package/{agile-context-engineering/workflows/init-coding-standards.xml → skills/init-coding-standards/workflow.xml} +381 -386
  31. package/skills/map-cross-cutting/SKILL.md +89 -0
  32. package/{agile-context-engineering/templates/wiki → skills/map-cross-cutting}/system-cross-cutting.xml +197 -197
  33. package/skills/map-cross-cutting/workflow.xml +330 -0
  34. package/skills/map-guide/SKILL.md +89 -0
  35. package/{agile-context-engineering/templates/wiki → skills/map-guide}/guide.xml +137 -137
  36. package/skills/map-guide/workflow.xml +320 -0
  37. package/skills/map-pattern/SKILL.md +89 -0
  38. package/{agile-context-engineering/templates/wiki → skills/map-pattern}/pattern.xml +159 -159
  39. package/skills/map-pattern/workflow.xml +331 -0
  40. package/skills/map-story/SKILL.md +127 -0
  41. package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/decizions.xml +115 -115
  42. package/skills/map-story/templates/guide.xml +137 -0
  43. package/skills/map-story/templates/pattern.xml +159 -0
  44. package/skills/map-story/templates/system-cross-cutting.xml +197 -0
  45. package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/system.xml +381 -381
  46. package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/walkthrough.xml +255 -255
  47. package/{agile-context-engineering/workflows/map-story.xml → skills/map-story/workflow.xml} +1046 -1046
  48. package/skills/map-subsystem/SKILL.md +111 -0
  49. package/skills/map-subsystem/script.js +60 -0
  50. package/skills/map-subsystem/script.test.js +68 -0
  51. package/skills/map-subsystem/templates/decizions.xml +115 -0
  52. package/skills/map-subsystem/templates/guide.xml +137 -0
  53. package/{agile-context-engineering/templates/wiki → skills/map-subsystem/templates}/module-discovery.xml +174 -174
  54. package/skills/map-subsystem/templates/pattern.xml +159 -0
  55. package/skills/map-subsystem/templates/system-cross-cutting.xml +197 -0
  56. package/skills/map-subsystem/templates/system.xml +381 -0
  57. package/skills/map-subsystem/templates/walkthrough.xml +255 -0
  58. package/{agile-context-engineering/workflows/map-subsystem.xml → skills/map-subsystem/workflow.xml} +15 -20
  59. package/skills/map-sys-doc/SKILL.md +90 -0
  60. package/skills/map-sys-doc/system.xml +381 -0
  61. package/skills/map-sys-doc/workflow.xml +336 -0
  62. package/skills/map-system/SKILL.md +85 -0
  63. package/skills/map-system/script.js +84 -0
  64. package/skills/map-system/script.test.js +73 -0
  65. package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/system-architecture.xml +254 -254
  66. package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/wiki-readme.xml +296 -296
  67. package/{agile-context-engineering/workflows/map-system.xml → skills/map-system/workflow.xml} +11 -16
  68. package/skills/map-walkthrough/SKILL.md +92 -0
  69. package/skills/map-walkthrough/walkthrough.xml +255 -0
  70. package/skills/plan-backlog/SKILL.md +75 -0
  71. package/{agile-context-engineering/templates/product/product-backlog.xml → skills/plan-backlog/product-backlog-template.xml} +231 -231
  72. package/skills/plan-backlog/script.js +136 -0
  73. package/skills/plan-backlog/script.test.js +83 -0
  74. package/{agile-context-engineering/workflows/plan-backlog.xml → skills/plan-backlog/workflow.xml} +13 -21
  75. package/skills/plan-feature/SKILL.md +76 -0
  76. package/skills/plan-feature/script.js +148 -0
  77. package/skills/plan-feature/script.test.js +80 -0
  78. package/{agile-context-engineering/workflows/plan-feature.xml → skills/plan-feature/workflow.xml} +1487 -1495
  79. package/skills/plan-product-vision/SKILL.md +75 -0
  80. package/skills/plan-product-vision/script.js +60 -0
  81. package/skills/plan-product-vision/script.test.js +69 -0
  82. package/{agile-context-engineering/workflows/plan-product-vision.xml → skills/plan-product-vision/workflow.xml} +4 -9
  83. package/skills/plan-story/SKILL.md +116 -0
  84. package/skills/plan-story/script.js +326 -0
  85. package/skills/plan-story/script.test.js +240 -0
  86. package/skills/plan-story/story-template.xml +451 -0
  87. package/{agile-context-engineering/workflows/plan-story.xml → skills/plan-story/workflow.xml} +1285 -944
  88. package/skills/research-external-solution/SKILL.md +107 -0
  89. package/skills/research-external-solution/script.js +238 -0
  90. package/skills/research-external-solution/script.test.js +134 -0
  91. package/{agile-context-engineering/workflows/research-external-solution.xml → skills/research-external-solution/workflow.xml} +4 -6
  92. package/skills/research-integration-solution/SKILL.md +98 -0
  93. package/skills/research-integration-solution/script.js +231 -0
  94. package/skills/research-integration-solution/script.test.js +134 -0
  95. package/{agile-context-engineering/workflows/research-integration-solution.xml → skills/research-integration-solution/workflow.xml} +3 -5
  96. package/skills/research-story-wiki/SKILL.md +92 -0
  97. package/skills/research-story-wiki/script.js +231 -0
  98. package/skills/research-story-wiki/script.test.js +138 -0
  99. package/{agile-context-engineering/workflows/research-story-wiki.xml → skills/research-story-wiki/workflow.xml} +3 -5
  100. package/skills/research-technical-solution/SKILL.md +103 -0
  101. package/skills/research-technical-solution/script.js +231 -0
  102. package/skills/research-technical-solution/script.test.js +134 -0
  103. package/{agile-context-engineering/workflows/research-technical-solution.xml → skills/research-technical-solution/workflow.xml} +3 -5
  104. package/skills/review-story/SKILL.md +100 -0
  105. package/skills/review-story/script.js +257 -0
  106. package/skills/review-story/script.test.js +169 -0
  107. package/skills/review-story/story-template.xml +451 -0
  108. package/{agile-context-engineering/workflows/review-story.xml → skills/review-story/workflow.xml} +279 -281
  109. package/skills/update/SKILL.md +53 -0
  110. package/{agile-context-engineering/workflows/update.xml → skills/update/workflow.xml} +12 -13
  111. package/agile-context-engineering/src/ace-tools.js +0 -2881
  112. package/agile-context-engineering/src/ace-tools.test.js +0 -1089
  113. package/agile-context-engineering/templates/_command.md +0 -54
  114. package/agile-context-engineering/templates/_workflow.xml +0 -17
  115. package/agile-context-engineering/templates/config.json +0 -0
  116. package/agile-context-engineering/templates/product/integration-solution.xml +0 -0
  117. package/commands/ace/execute-story.md +0 -138
  118. package/commands/ace/help.md +0 -93
  119. package/commands/ace/init-coding-standards.md +0 -83
  120. package/commands/ace/map-story.md +0 -165
  121. package/commands/ace/map-subsystem.md +0 -140
  122. package/commands/ace/map-system.md +0 -92
  123. package/commands/ace/map-walkthrough.md +0 -127
  124. package/commands/ace/plan-backlog.md +0 -83
  125. package/commands/ace/plan-feature.md +0 -89
  126. package/commands/ace/plan-product-vision.md +0 -81
  127. package/commands/ace/plan-story.md +0 -159
  128. package/commands/ace/research-external-solution.md +0 -138
  129. package/commands/ace/research-integration-solution.md +0 -135
  130. package/commands/ace/research-story-wiki.md +0 -116
  131. package/commands/ace/research-technical-solution.md +0 -147
  132. package/commands/ace/review-story.md +0 -109
  133. package/commands/ace/update.md +0 -56
  134. /package/{agile-context-engineering/templates/product/story.xml → skills/execute-story/story-template.xml} +0 -0
  135. /package/{agile-context-engineering/templates/wiki/coding-standards.xml → skills/init-coding-standards/coding-standards-template.xml} +0 -0
  136. /package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/tech-debt-index.xml +0 -0
  137. /package/{agile-context-engineering/templates/wiki → skills/map-subsystem/templates}/subsystem-architecture.xml +0 -0
  138. /package/{agile-context-engineering/templates/wiki → skills/map-subsystem/templates}/subsystem-structure.xml +0 -0
  139. /package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/system-structure.xml +0 -0
  140. /package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/testing-framework.xml +0 -0
  141. /package/{agile-context-engineering/workflows/map-walkthrough.xml → skills/map-walkthrough/workflow.xml} +0 -0
  142. /package/{agile-context-engineering/templates/product/feature.xml → skills/plan-feature/feature-template.xml} +0 -0
  143. /package/{agile-context-engineering/templates/product/product-vision.xml → skills/plan-product-vision/product-vision-template.xml} +0 -0
  144. /package/{agile-context-engineering/templates/product/external-solution.xml → skills/research-external-solution/external-solution-template.xml} +0 -0
  145. /package/{agile-context-engineering/templates/product/story-integration-solution.xml → skills/research-integration-solution/integration-solution-template.xml} +0 -0
  146. /package/{agile-context-engineering/templates/product/story-wiki.xml → skills/research-story-wiki/story-wiki-template.xml} +0 -0
  147. /package/{agile-context-engineering/templates/product/story-technical-solution.xml → skills/research-technical-solution/technical-solution-template.xml} +0 -0
@@ -1,231 +1,231 @@
1
- <template>
2
-
3
- <purpose>
4
- Template for `.ace/artifacts/product/product-backlog.md` — the single ordered backlog
5
- of Epics and Features that define what the product will deliver. Epics are broad
6
- capability categories; Features are concrete deliverables within an Epic.
7
- </purpose>
8
-
9
- <output-format>
10
-
11
- <section name="header">
12
- ## Product Backlog
13
-
14
- Brief paragraph describing the product's current direction and what this backlog
15
- is ordered toward. Keep it to 2-3 sentences — enough context for anyone reading
16
- the backlog to understand the "why" behind the ordering.
17
- </section>
18
-
19
- <section name="epic-index">
20
- ### Epic Index
21
-
22
- &lt;!-- Ordered by strategic priority. This is the master list of all Epics. --&gt;
23
-
24
- | ID | Title | Description | Status | Priority | Size | Sprint | Milestone | Link |
25
- |----|-------|-------------|--------|----------|------|--------|-----------|------|
26
- | #45 | [Exact GitHub title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | — | [Milestone] | [#45](url) |
27
- | E1 | [New epic title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | — | [Milestone] | — |
28
- </section>
29
-
30
- <section name="epic-details" repeat="once per Epic">
31
- ### #45: [Exact GitHub Epic Title] &lt;!-- or ### E[N]: [Title] for local epics --&gt;
32
-
33
- &lt;!-- Features ordered by delivery sequence within this Epic. --&gt;
34
-
35
- | ID | Title | Description | Status | Priority | Size | Sprint | Milestone | Link |
36
- |----|-------|-------------|--------|----------|------|--------|-----------|------|
37
- | #78 | [Exact GitHub title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | [Sprint] | [Milestone] | [#78](url) |
38
- | F1 | [New feature title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | [Sprint] | [Milestone] | — |
39
- </section>
40
-
41
- </output-format>
42
-
43
- <column-definitions>
44
-
45
- <column name="ID">
46
- <format>
47
- <github-linked>#[issue_number] — when the item has a corresponding GitHub issue (e.g. #45, #78)</github-linked>
48
- <local-epic>E[number] — sequential, for epics without a GitHub issue (e.g. E1, E2)</local-epic>
49
- <local-feature>F[number] — sequential across the entire backlog, for features without a GitHub issue (e.g. F1, F2)</local-feature>
50
- </format>
51
- <rules>
52
- <rule>GitHub-linked items ALWAYS use #[issue_number] as their ID — this is the source of truth</rule>
53
- <rule>Only items without a GitHub issue use E[N] or F[N] local IDs</rule>
54
- <rule>IDs are stable — never renumber after assignment</rule>
55
- <rule>Gaps in E[N]/F[N] sequences are fine (deleted items leave gaps)</rule>
56
- <rule>When an item gets a GitHub issue later (via sync), its ID changes from E[N]/F[N] to #[issue_number]</rule>
57
- </rules>
58
- </column>
59
-
60
- <column name="Title">
61
- <rules>
62
- <rule>GitHub-linked items: use the EXACT GitHub issue title — do NOT rephrase, shorten, or "improve" it</rule>
63
- <rule>New items (no GitHub issue): short, descriptive name (5-10 words max)</rule>
64
- <rule>Epics: broad capability area (e.g., "User Authentication", "Data Export Pipeline")</rule>
65
- <rule>Features: specific deliverable (e.g., "OAuth2 Login Flow", "CSV Bulk Export")</rule>
66
- </rules>
67
- </column>
68
-
69
- <column name="Description">
70
- <rules>
71
- <rule>1-2 sentences max — what this item delivers and why it matters</rule>
72
- <rule>Epics: describe the broad capability and its user impact</rule>
73
- <rule>Features: describe the specific deliverable and what it enables</rule>
74
- <rule>Write for someone unfamiliar with the project — no jargon without context</rule>
75
- </rules>
76
- </column>
77
-
78
- <column name="Status">
79
- <allowed-values>
80
- <value name="Todo">Not yet started or refined</value>
81
- <value name="Refined">Requirements clear, ready to be planned into stories</value>
82
- <value name="In Progress">Currently being implemented (has active stories)</value>
83
- <value name="Done">All stories complete, acceptance criteria met</value>
84
- </allowed-values>
85
- <rules>
86
- <rule>An Epic's status reflects its aggregate — "In Progress" if any child Feature is in progress</rule>
87
- <rule>An Epic is "Done" only when ALL child Features are Done</rule>
88
- </rules>
89
- </column>
90
-
91
- <column name="Size">
92
- <allowed-values>
93
- <value name="10">Trivial — a single story, minimal complexity</value>
94
- <value name="20">Small — a few stories, low complexity</value>
95
- <value name="30">Medium — moderate scope, some unknowns</value>
96
- <value name="50">Large — significant scope, multiple components</value>
97
- <value name="80">Very Large — cross-cutting, high complexity</value>
98
- <value name="130">Massive — cross-cutting, high complexity, should be split</value>
99
- </allowed-values>
100
- <rules>
101
- <rule>Fibonacci×10 relative sizing — compared to other items in this backlog</rule>
102
- <rule>130-point items should be reviewed for splitting opportunities</rule>
103
- <rule>Epic size reflects total scope of all child Features</rule>
104
- </rules>
105
- </column>
106
-
107
- <column name="Priority">
108
- <allowed-values>
109
- <value name="Critical">Blocks other work or has external deadline</value>
110
- <value name="High">Core functionality, high user impact</value>
111
- <value name="Medium">Important but not blocking</value>
112
- <value name="Low">Nice to have, can be deferred</value>
113
- </allowed-values>
114
- <rules>
115
- <rule>Priority reflects business importance, not technical difficulty</rule>
116
- <rule>Epic priority drives its position in the Epic Index ordering</rule>
117
- <rule>When synced from GitHub Project, use the project's Priority field value</rule>
118
- </rules>
119
- </column>
120
-
121
- <column name="Sprint">
122
- <format>
123
- Sprint name or iteration identifier from the GitHub Project board.
124
- Examples: Sprint 1, Sprint 2, 2026-W10, —
125
- </format>
126
- <rules>
127
- <rule>Use "—" when no sprint is assigned</rule>
128
- <rule>Epics typically don't have sprints (use "—") — only features are sprint-planned</rule>
129
- <rule>When synced from GitHub Project, use the project's Iteration field value</rule>
130
- <rule>Sprint assignment happens during feature/story planning, not backlog creation</rule>
131
- </rules>
132
- </column>
133
-
134
- <column name="Milestone">
135
- <format>
136
- Semver-style release target or named milestone.
137
- Examples: mvp, v0.1.0, v0.2.0, v1.0.0
138
- </format>
139
- <rules>
140
- <rule>Milestones are delivery targets, not deadlines</rule>
141
- <rule>Features inherit their Epic's milestone unless explicitly overridden</rule>
142
- <rule>Use "mvp" for the minimum viable product milestone</rule>
143
- </rules>
144
- </column>
145
-
146
- <column name="Link">
147
- <format>
148
- GitHub issue link in markdown format: [#number](url)
149
- Example: [#76](https://github.com/owner/repo/issues/76)
150
- </format>
151
- <rules>
152
- <rule>"—" when the item has no corresponding GitHub issue (ID will be E[N] or F[N])</rule>
153
- <rule>When ID is #[N], Link MUST also be populated: [#N](url)</rule>
154
- <rule>Populated automatically when issues are created via GitHub sync</rule>
155
- <rule>Links are stable — issue numbers never change</rule>
156
- </rules>
157
- </column>
158
-
159
- </column-definitions>
160
-
161
- <ordering-rules>
162
- <rule>Epic Index is ordered by strategic priority (highest value first)</rule>
163
- <rule>Each Epic's feature table is ordered by delivery sequence</rule>
164
- <rule>Epic detail sections appear in the same order as the Epic Index</rule>
165
- <rule>Cross-Epic dependencies may force reordering — note these in a comment</rule>
166
- </ordering-rules>
167
-
168
- <guidelines>
169
-
170
- <guideline name="epic-structure">
171
- Epics are broad capability categories, not phases or sprints.
172
- A good Epic groups related Features that together deliver a coherent
173
- user-facing capability. Epics should be decomposable into 3-10 Features.
174
- If an Epic has only 1-2 Features, it may be too narrow — consider merging.
175
- If an Epic has 10+ Features, it may be too broad — consider splitting.
176
- </guideline>
177
-
178
- <guideline name="feature-scope">
179
- A Feature is a concrete deliverable that can be broken down into stories
180
- during planning. Features at 80 points or above (~6 sprints) should be
181
- reviewed for splitting. Features describe WHAT will be delivered, not
182
- HOW it will be implemented.
183
- </guideline>
184
-
185
- <guideline name="status-transitions">
186
- Items move forward through statuses: Todo -> Refined -> In Progress -> Done.
187
- Moving backward (e.g., In Progress -> Todo) is valid when scope changes
188
- or blockers are discovered. Document the reason in a commit message.
189
- </guideline>
190
-
191
- <guideline name="milestone-assignment">
192
- Assign milestones based on delivery priority and dependencies.
193
- Not every item needs a milestone — unassigned items are future/exploratory.
194
- Milestones should have a clear theme (e.g., "mvp" = core user flows).
195
- </guideline>
196
-
197
- <guideline name="backlog-hygiene">
198
- Prune regularly — delete items that have been Todo for too long.
199
- Review ordering after each milestone completion.
200
- Keep the backlog as short as practical — fewer items, more focus.
201
- </guideline>
202
-
203
- <guideline name="table-formatting">
204
- Tables MUST be column-aligned for readability. Pad every cell with spaces so
205
- that column separators (`|`) line up vertically across all rows. Use consistent
206
- minimum widths per column:
207
-
208
- - **ID**: 6 chars (e.g. `| #45 |` or `| E1 |`)
209
- - **Title**: pad to the longest title in the table
210
- - **Description**: pad to the longest description in the table
211
- - **Status**: 14 chars (longest value: "In Progress")
212
- - **Priority**: 10 chars (longest value: "Critical")
213
- - **Size**: 6 chars (longest value: "130")
214
- - **Sprint**: 10 chars
215
- - **Milestone**: 10 chars
216
- - **Link**: pad to the longest link in the table
217
-
218
- The separator row (`|------|---...`) must match column widths using dashes.
219
-
220
- Example of properly aligned table:
221
- ```
222
- | ID | Title | Description | Status | Priority | Size | Sprint | Milestone | Link |
223
- |------|--------------------------------|-------------------------------------------------|-------------|----------|------|----------|-----------|---------------------------------------------------------|
224
- | #45 | Indicator &amp; Chart Engine | Core charting capability with indicators | In Progress | Critical | 130 | — | mvp | [#45](https://github.com/owner/repo/issues/45) |
225
- | E1 | AI Agent Swarm | Agentic order execution and analysis | Todo | High | 80 | — | v0.2.0 | — |
226
- ```
227
- </guideline>
228
-
229
- </guidelines>
230
-
231
- </template>
1
+ <template>
2
+
3
+ <purpose>
4
+ Template for `.ace/artifacts/product/product-backlog.md` — the single ordered backlog
5
+ of Epics and Features that define what the product will deliver. Epics are broad
6
+ capability categories; Features are concrete deliverables within an Epic.
7
+ </purpose>
8
+
9
+ <output-format>
10
+
11
+ <section name="header">
12
+ ## Product Backlog
13
+
14
+ Brief paragraph describing the product's current direction and what this backlog
15
+ is ordered toward. Keep it to 2-3 sentences — enough context for anyone reading
16
+ the backlog to understand the "why" behind the ordering.
17
+ </section>
18
+
19
+ <section name="epic-index">
20
+ ### Epic Index
21
+
22
+ &lt;!-- Ordered by strategic priority. This is the master list of all Epics. --&gt;
23
+
24
+ | ID | Title | Description | Status | Priority | Size | Sprint | Milestone | Link |
25
+ |----|-------|-------------|--------|----------|------|--------|-----------|------|
26
+ | #45 | [Exact GitHub title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | — | [Milestone] | [#45](url) |
27
+ | E1 | [New epic title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | — | [Milestone] | — |
28
+ </section>
29
+
30
+ <section name="epic-details" repeat="once per Epic">
31
+ ### #45: [Exact GitHub Epic Title] &lt;!-- or ### E[N]: [Title] for local epics --&gt;
32
+
33
+ &lt;!-- Features ordered by delivery sequence within this Epic. --&gt;
34
+
35
+ | ID | Title | Description | Status | Priority | Size | Sprint | Milestone | Link |
36
+ |----|-------|-------------|--------|----------|------|--------|-----------|------|
37
+ | #78 | [Exact GitHub title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | [Sprint] | [Milestone] | [#78](url) |
38
+ | F1 | [New feature title] | [1-2 sentence summary] | [Status] | [Priority] | [10-130] | [Sprint] | [Milestone] | — |
39
+ </section>
40
+
41
+ </output-format>
42
+
43
+ <column-definitions>
44
+
45
+ <column name="ID">
46
+ <format>
47
+ <github-linked>#[issue_number] — when the item has a corresponding GitHub issue (e.g. #45, #78)</github-linked>
48
+ <local-epic>E[number] — sequential, for epics without a GitHub issue (e.g. E1, E2)</local-epic>
49
+ <local-feature>F[number] — sequential across the entire backlog, for features without a GitHub issue (e.g. F1, F2)</local-feature>
50
+ </format>
51
+ <rules>
52
+ <rule>GitHub-linked items ALWAYS use #[issue_number] as their ID — this is the source of truth</rule>
53
+ <rule>Only items without a GitHub issue use E[N] or F[N] local IDs</rule>
54
+ <rule>IDs are stable — never renumber after assignment</rule>
55
+ <rule>Gaps in E[N]/F[N] sequences are fine (deleted items leave gaps)</rule>
56
+ <rule>When an item gets a GitHub issue later (via sync), its ID changes from E[N]/F[N] to #[issue_number]</rule>
57
+ </rules>
58
+ </column>
59
+
60
+ <column name="Title">
61
+ <rules>
62
+ <rule>GitHub-linked items: use the EXACT GitHub issue title — do NOT rephrase, shorten, or "improve" it</rule>
63
+ <rule>New items (no GitHub issue): short, descriptive name (5-10 words max)</rule>
64
+ <rule>Epics: broad capability area (e.g., "User Authentication", "Data Export Pipeline")</rule>
65
+ <rule>Features: specific deliverable (e.g., "OAuth2 Login Flow", "CSV Bulk Export")</rule>
66
+ </rules>
67
+ </column>
68
+
69
+ <column name="Description">
70
+ <rules>
71
+ <rule>1-2 sentences max — what this item delivers and why it matters</rule>
72
+ <rule>Epics: describe the broad capability and its user impact</rule>
73
+ <rule>Features: describe the specific deliverable and what it enables</rule>
74
+ <rule>Write for someone unfamiliar with the project — no jargon without context</rule>
75
+ </rules>
76
+ </column>
77
+
78
+ <column name="Status">
79
+ <allowed-values>
80
+ <value name="Todo">Not yet started or refined</value>
81
+ <value name="Refined">Requirements clear, ready to be planned into stories</value>
82
+ <value name="In Progress">Currently being implemented (has active stories)</value>
83
+ <value name="Done">All stories complete, acceptance criteria met</value>
84
+ </allowed-values>
85
+ <rules>
86
+ <rule>An Epic's status reflects its aggregate — "In Progress" if any child Feature is in progress</rule>
87
+ <rule>An Epic is "Done" only when ALL child Features are Done</rule>
88
+ </rules>
89
+ </column>
90
+
91
+ <column name="Size">
92
+ <allowed-values>
93
+ <value name="10">Trivial — a single story, minimal complexity</value>
94
+ <value name="20">Small — a few stories, low complexity</value>
95
+ <value name="30">Medium — moderate scope, some unknowns</value>
96
+ <value name="50">Large — significant scope, multiple components</value>
97
+ <value name="80">Very Large — cross-cutting, high complexity</value>
98
+ <value name="130">Massive — cross-cutting, high complexity, should be split</value>
99
+ </allowed-values>
100
+ <rules>
101
+ <rule>Fibonacci×10 relative sizing — compared to other items in this backlog</rule>
102
+ <rule>130-point items should be reviewed for splitting opportunities</rule>
103
+ <rule>Epic size reflects total scope of all child Features</rule>
104
+ </rules>
105
+ </column>
106
+
107
+ <column name="Priority">
108
+ <allowed-values>
109
+ <value name="Critical">Blocks other work or has external deadline</value>
110
+ <value name="High">Core functionality, high user impact</value>
111
+ <value name="Medium">Important but not blocking</value>
112
+ <value name="Low">Nice to have, can be deferred</value>
113
+ </allowed-values>
114
+ <rules>
115
+ <rule>Priority reflects business importance, not technical difficulty</rule>
116
+ <rule>Epic priority drives its position in the Epic Index ordering</rule>
117
+ <rule>When synced from GitHub Project, use the project's Priority field value</rule>
118
+ </rules>
119
+ </column>
120
+
121
+ <column name="Sprint">
122
+ <format>
123
+ Sprint name or iteration identifier from the GitHub Project board.
124
+ Examples: Sprint 1, Sprint 2, 2026-W10, —
125
+ </format>
126
+ <rules>
127
+ <rule>Use "—" when no sprint is assigned</rule>
128
+ <rule>Epics typically don't have sprints (use "—") — only features are sprint-planned</rule>
129
+ <rule>When synced from GitHub Project, use the project's Iteration field value</rule>
130
+ <rule>Sprint assignment happens during feature/story planning, not backlog creation</rule>
131
+ </rules>
132
+ </column>
133
+
134
+ <column name="Milestone">
135
+ <format>
136
+ Semver-style release target or named milestone.
137
+ Examples: mvp, v0.1.0, v0.2.0, v1.0.0
138
+ </format>
139
+ <rules>
140
+ <rule>Milestones are delivery targets, not deadlines</rule>
141
+ <rule>Features inherit their Epic's milestone unless explicitly overridden</rule>
142
+ <rule>Use "mvp" for the minimum viable product milestone</rule>
143
+ </rules>
144
+ </column>
145
+
146
+ <column name="Link">
147
+ <format>
148
+ GitHub issue link in markdown format: [#number](url)
149
+ Example: [#76](https://github.com/owner/repo/issues/76)
150
+ </format>
151
+ <rules>
152
+ <rule>"—" when the item has no corresponding GitHub issue (ID will be E[N] or F[N])</rule>
153
+ <rule>When ID is #[N], Link MUST also be populated: [#N](url)</rule>
154
+ <rule>Populated automatically when issues are created via GitHub sync</rule>
155
+ <rule>Links are stable — issue numbers never change</rule>
156
+ </rules>
157
+ </column>
158
+
159
+ </column-definitions>
160
+
161
+ <ordering-rules>
162
+ <rule>Epic Index is ordered by strategic priority (highest value first)</rule>
163
+ <rule>Each Epic's feature table is ordered by delivery sequence</rule>
164
+ <rule>Epic detail sections appear in the same order as the Epic Index</rule>
165
+ <rule>Cross-Epic dependencies may force reordering — note these in a comment</rule>
166
+ </ordering-rules>
167
+
168
+ <guidelines>
169
+
170
+ <guideline name="epic-structure">
171
+ Epics are broad capability categories, not phases or sprints.
172
+ A good Epic groups related Features that together deliver a coherent
173
+ user-facing capability. Epics should be decomposable into 3-10 Features.
174
+ If an Epic has only 1-2 Features, it may be too narrow — consider merging.
175
+ If an Epic has 10+ Features, it may be too broad — consider splitting.
176
+ </guideline>
177
+
178
+ <guideline name="feature-scope">
179
+ A Feature is a concrete deliverable that can be broken down into stories
180
+ during planning. Features at 80 points or above (~6 sprints) should be
181
+ reviewed for splitting. Features describe WHAT will be delivered, not
182
+ HOW it will be implemented.
183
+ </guideline>
184
+
185
+ <guideline name="status-transitions">
186
+ Items move forward through statuses: Todo -> Refined -> In Progress -> Done.
187
+ Moving backward (e.g., In Progress -> Todo) is valid when scope changes
188
+ or blockers are discovered. Document the reason in a commit message.
189
+ </guideline>
190
+
191
+ <guideline name="milestone-assignment">
192
+ Assign milestones based on delivery priority and dependencies.
193
+ Not every item needs a milestone — unassigned items are future/exploratory.
194
+ Milestones should have a clear theme (e.g., "mvp" = core user flows).
195
+ </guideline>
196
+
197
+ <guideline name="backlog-hygiene">
198
+ Prune regularly — delete items that have been Todo for too long.
199
+ Review ordering after each milestone completion.
200
+ Keep the backlog as short as practical — fewer items, more focus.
201
+ </guideline>
202
+
203
+ <guideline name="table-formatting">
204
+ Tables MUST be column-aligned for readability. Pad every cell with spaces so
205
+ that column separators (`|`) line up vertically across all rows. Use consistent
206
+ minimum widths per column:
207
+
208
+ - **ID**: 6 chars (e.g. `| #45 |` or `| E1 |`)
209
+ - **Title**: pad to the longest title in the table
210
+ - **Description**: pad to the longest description in the table
211
+ - **Status**: 14 chars (longest value: "In Progress")
212
+ - **Priority**: 10 chars (longest value: "Critical")
213
+ - **Size**: 6 chars (longest value: "130")
214
+ - **Sprint**: 10 chars
215
+ - **Milestone**: 10 chars
216
+ - **Link**: pad to the longest link in the table
217
+
218
+ The separator row (`|------|---...`) must match column widths using dashes.
219
+
220
+ Example of properly aligned table:
221
+ ```
222
+ | ID | Title | Description | Status | Priority | Size | Sprint | Milestone | Link |
223
+ |------|--------------------------------|-------------------------------------------------|-------------|----------|------|----------|-----------|---------------------------------------------------------|
224
+ | #45 | Indicator &amp; Chart Engine | Core charting capability with indicators | In Progress | Critical | 130 | — | mvp | [#45](https://github.com/owner/repo/issues/45) |
225
+ | E1 | AI Agent Swarm | Agentic order execution and analysis | Todo | High | 80 | — | v0.2.0 | — |
226
+ ```
227
+ </guideline>
228
+
229
+ </guidelines>
230
+
231
+ </template>
@@ -0,0 +1,136 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * plan-backlog skill script — Entry point for ace-tools operations
5
+ * needed by the plan-backlog skill.
6
+ *
7
+ * Subcommands:
8
+ * init [args] Environment detection for plan-backlog workflow
9
+ * resolve-fields [args] Resolve GitHub Project field IDs
10
+ * create-issue [args] Create a GitHub issue in a project
11
+ * fetch-issues [args] Fetch all epics/features from a GitHub project
12
+ *
13
+ * Usage: node script.js <subcommand> [args] [--raw]
14
+ */
15
+
16
+ const fs = require('fs');
17
+ const path = require('path');
18
+
19
+ const {
20
+ loadConfig, pathExists, resolveModel,
21
+ detectBrownfieldStatus, loadSettings, output, error,
22
+ } = require('../../shared/lib/ace-core');
23
+
24
+ const {
25
+ resolveFields, createIssue, fetchIssues,
26
+ } = require('../../shared/lib/ace-github');
27
+
28
+ // ─── CLI Dispatch ────────────────────────────────────────────────────────────
29
+
30
+ const cwd = process.cwd();
31
+ const args = process.argv.slice(2);
32
+ const raw = args.includes('--raw');
33
+ const cmd = args[0];
34
+
35
+ switch (cmd) {
36
+ case 'init':
37
+ cmdInit(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
38
+ break;
39
+ case 'resolve-fields':
40
+ resolveFields(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
41
+ break;
42
+ case 'create-issue':
43
+ createIssue(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
44
+ break;
45
+ case 'fetch-issues':
46
+ fetchIssues(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
47
+ break;
48
+ default:
49
+ error(`Unknown command: ${cmd}\nAvailable: init, resolve-fields, create-issue, fetch-issues`);
50
+ }
51
+
52
+ // ─── Init: Plan Backlog ─────────────────────────────────────────────────────
53
+
54
+ function cmdInit(cwd, raw) {
55
+ const config = loadConfig(cwd);
56
+ const brownfield = detectBrownfieldStatus(cwd);
57
+
58
+ // Wiki detection — system-wide
59
+ const wikiSystemDir = '.docs/wiki/system-wide';
60
+ const has_wiki_system_wide = pathExists(cwd, wikiSystemDir);
61
+ const has_system_architecture = pathExists(cwd, path.join(wikiSystemDir, 'system-architecture.md'));
62
+ const has_system_structure = pathExists(cwd, path.join(wikiSystemDir, 'system-structure.md'));
63
+ const has_testing_framework = pathExists(cwd, path.join(wikiSystemDir, 'testing-framework.md'));
64
+
65
+ // Wiki detection — subsystems
66
+ const wikiSubsystemsDir = '.docs/wiki/subsystems';
67
+ const has_wiki_subsystems = pathExists(cwd, wikiSubsystemsDir);
68
+
69
+ let wiki_subsystem_names = [];
70
+ if (has_wiki_subsystems) {
71
+ try {
72
+ const entries = fs.readdirSync(path.join(cwd, wikiSubsystemsDir), { withFileTypes: true });
73
+ wiki_subsystem_names = entries
74
+ .filter(e => e.isDirectory())
75
+ .map(e => e.name);
76
+ } catch {}
77
+ }
78
+
79
+ const has_wiki = has_wiki_system_wide || has_wiki_subsystems;
80
+
81
+ const result = {
82
+ // Models
83
+ product_owner_model: resolveModel(cwd, 'ace-product-owner'),
84
+ researcher_model: resolveModel(cwd, 'ace-project-researcher'),
85
+
86
+ // Config
87
+ commit_docs: config.commit_docs,
88
+
89
+ // Product artifacts
90
+ has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
91
+ has_product_backlog: pathExists(cwd, '.ace/artifacts/product/product-backlog.md'),
92
+
93
+ // Research artifacts (from previous runs)
94
+ has_features_research: pathExists(cwd, '.ace/research/FEATURES.md'),
95
+ has_architecture_research: pathExists(cwd, '.ace/research/ARCHITECTURE.md'),
96
+
97
+ // Wiki analysis cache (from previous runs)
98
+ has_wiki_analysis: pathExists(cwd, '.ace/artifacts/wiki/wiki-analysis.md'),
99
+
100
+ // Brownfield detection
101
+ ...brownfield,
102
+
103
+ // Wiki state — system-wide
104
+ has_wiki,
105
+ has_wiki_system_wide,
106
+ has_system_architecture,
107
+ has_system_structure,
108
+ has_testing_framework,
109
+
110
+ // Wiki state — subsystems
111
+ has_wiki_subsystems,
112
+ wiki_subsystem_names,
113
+
114
+ // Git state
115
+ has_git: pathExists(cwd, '.git'),
116
+
117
+ // GitHub CLI
118
+ has_gh_cli: (() => {
119
+ try {
120
+ const { execSync } = require('child_process');
121
+ execSync('gh --version', { stdio: 'pipe' });
122
+ return true;
123
+ } catch {
124
+ return false;
125
+ }
126
+ })(),
127
+
128
+ // GitHub Project settings (from settings.json)
129
+ github_project: (() => {
130
+ const settings = loadSettings(cwd);
131
+ return settings.github_project;
132
+ })(),
133
+ };
134
+
135
+ output(result, raw);
136
+ }