agile-context-engineering 0.3.0 → 0.5.1

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 (139) hide show
  1. package/.claude-plugin/marketplace.json +18 -0
  2. package/.claude-plugin/plugin.json +10 -0
  3. package/CHANGELOG.md +7 -1
  4. package/LICENSE +51 -51
  5. package/README.md +330 -318
  6. package/agents/ace-code-discovery-analyst.md +245 -245
  7. package/agents/ace-code-integration-analyst.md +248 -248
  8. package/agents/ace-code-reviewer.md +375 -375
  9. package/agents/ace-product-owner.md +365 -361
  10. package/agents/ace-project-researcher.md +606 -606
  11. package/agents/ace-research-synthesizer.md +228 -228
  12. package/agents/ace-technical-application-architect.md +315 -315
  13. package/agents/ace-wiki-mapper.md +449 -445
  14. package/bin/install.js +605 -195
  15. package/hooks/ace-check-update.js +71 -62
  16. package/hooks/ace-statusline.js +107 -89
  17. package/hooks/hooks.json +14 -0
  18. package/package.json +7 -5
  19. package/shared/lib/ace-core.js +361 -0
  20. package/shared/lib/ace-core.test.js +308 -0
  21. package/shared/lib/ace-github.js +753 -0
  22. package/shared/lib/ace-story.js +400 -0
  23. package/shared/lib/ace-story.test.js +250 -0
  24. package/{agile-context-engineering → shared}/utils/questioning.xml +110 -110
  25. package/{agile-context-engineering → shared}/utils/ui-formatting.md +299 -299
  26. package/{commands/ace/execute-story.md → skills/execute-story/SKILL.md} +116 -138
  27. package/skills/execute-story/script.js +291 -0
  28. package/skills/execute-story/script.test.js +261 -0
  29. package/{agile-context-engineering/templates/product/story.xml → skills/execute-story/story-template.xml} +451 -451
  30. package/skills/execute-story/walkthrough-template.xml +255 -0
  31. package/{agile-context-engineering/workflows/execute-story.xml → skills/execute-story/workflow.xml} +1221 -1219
  32. package/skills/help/SKILL.md +71 -0
  33. package/skills/help/script.js +315 -0
  34. package/skills/help/script.test.js +183 -0
  35. package/{agile-context-engineering/workflows/help.xml → skills/help/workflow.xml} +544 -533
  36. package/{commands/ace/init-coding-standards.md → skills/init-coding-standards/SKILL.md} +91 -83
  37. package/{agile-context-engineering/templates/wiki/coding-standards.xml → skills/init-coding-standards/coding-standards-template.xml} +531 -531
  38. package/skills/init-coding-standards/script.js +50 -0
  39. package/skills/init-coding-standards/script.test.js +70 -0
  40. package/{agile-context-engineering/workflows/init-coding-standards.xml → skills/init-coding-standards/workflow.xml} +381 -386
  41. package/skills/map-cross-cutting/SKILL.md +126 -0
  42. package/{agile-context-engineering/templates/wiki → skills/map-cross-cutting}/system-cross-cutting.xml +197 -197
  43. package/skills/map-cross-cutting/workflow.xml +330 -0
  44. package/skills/map-guide/SKILL.md +126 -0
  45. package/{agile-context-engineering/templates/wiki → skills/map-guide}/guide.xml +137 -137
  46. package/skills/map-guide/workflow.xml +320 -0
  47. package/skills/map-pattern/SKILL.md +125 -0
  48. package/{agile-context-engineering/templates/wiki → skills/map-pattern}/pattern.xml +159 -159
  49. package/skills/map-pattern/workflow.xml +331 -0
  50. package/{commands/ace/map-story.md → skills/map-story/SKILL.md} +180 -165
  51. package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/decizions.xml +115 -115
  52. package/skills/map-story/templates/guide.xml +137 -0
  53. package/skills/map-story/templates/pattern.xml +159 -0
  54. package/skills/map-story/templates/system-cross-cutting.xml +197 -0
  55. package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/system.xml +381 -381
  56. package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/tech-debt-index.xml +125 -125
  57. package/{agile-context-engineering/templates/wiki → skills/map-story/templates}/walkthrough.xml +255 -255
  58. package/{agile-context-engineering/workflows/map-story.xml → skills/map-story/workflow.xml} +1046 -1046
  59. package/{commands/ace/map-subsystem.md → skills/map-subsystem/SKILL.md} +155 -140
  60. package/skills/map-subsystem/script.js +51 -0
  61. package/skills/map-subsystem/script.test.js +68 -0
  62. package/skills/map-subsystem/templates/decizions.xml +115 -0
  63. package/skills/map-subsystem/templates/guide.xml +137 -0
  64. package/{agile-context-engineering/templates/wiki → skills/map-subsystem/templates}/module-discovery.xml +174 -174
  65. package/skills/map-subsystem/templates/pattern.xml +159 -0
  66. package/{agile-context-engineering/templates/wiki → skills/map-subsystem/templates}/subsystem-architecture.xml +343 -343
  67. package/{agile-context-engineering/templates/wiki → skills/map-subsystem/templates}/subsystem-structure.xml +234 -234
  68. package/skills/map-subsystem/templates/system-cross-cutting.xml +197 -0
  69. package/skills/map-subsystem/templates/system.xml +381 -0
  70. package/skills/map-subsystem/templates/walkthrough.xml +255 -0
  71. package/{agile-context-engineering/workflows/map-subsystem.xml → skills/map-subsystem/workflow.xml} +1173 -1178
  72. package/skills/map-sys-doc/SKILL.md +125 -0
  73. package/skills/map-sys-doc/system.xml +381 -0
  74. package/skills/map-sys-doc/workflow.xml +336 -0
  75. package/{commands/ace/map-system.md → skills/map-system/SKILL.md} +103 -92
  76. package/skills/map-system/script.js +75 -0
  77. package/skills/map-system/script.test.js +73 -0
  78. package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/system-architecture.xml +254 -254
  79. package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/system-structure.xml +177 -177
  80. package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/testing-framework.xml +283 -283
  81. package/{agile-context-engineering/templates/wiki → skills/map-system/templates}/wiki-readme.xml +296 -296
  82. package/{agile-context-engineering/workflows/map-system.xml → skills/map-system/workflow.xml} +667 -672
  83. package/{commands/ace/map-walkthrough.md → skills/map-walkthrough/SKILL.md} +140 -127
  84. package/skills/map-walkthrough/walkthrough.xml +255 -0
  85. package/{agile-context-engineering/workflows/map-walkthrough.xml → skills/map-walkthrough/workflow.xml} +457 -457
  86. package/{commands/ace/plan-backlog.md → skills/plan-backlog/SKILL.md} +93 -83
  87. package/{agile-context-engineering/templates/product/product-backlog.xml → skills/plan-backlog/product-backlog-template.xml} +231 -231
  88. package/skills/plan-backlog/script.js +121 -0
  89. package/skills/plan-backlog/script.test.js +83 -0
  90. package/{agile-context-engineering/workflows/plan-backlog.xml → skills/plan-backlog/workflow.xml} +1348 -1356
  91. package/{commands/ace/plan-feature.md → skills/plan-feature/SKILL.md} +99 -89
  92. package/{agile-context-engineering/templates/product/feature.xml → skills/plan-feature/feature-template.xml} +361 -361
  93. package/skills/plan-feature/script.js +131 -0
  94. package/skills/plan-feature/script.test.js +80 -0
  95. package/{agile-context-engineering/workflows/plan-feature.xml → skills/plan-feature/workflow.xml} +1487 -1495
  96. package/{commands/ace/plan-product-vision.md → skills/plan-product-vision/SKILL.md} +91 -81
  97. package/{agile-context-engineering/templates/product/product-vision.xml → skills/plan-product-vision/product-vision-template.xml} +227 -227
  98. package/skills/plan-product-vision/script.js +51 -0
  99. package/skills/plan-product-vision/script.test.js +69 -0
  100. package/{agile-context-engineering/workflows/plan-product-vision.xml → skills/plan-product-vision/workflow.xml} +337 -342
  101. package/{commands/ace/plan-story.md → skills/plan-story/SKILL.md} +139 -159
  102. package/skills/plan-story/script.js +295 -0
  103. package/skills/plan-story/script.test.js +240 -0
  104. package/skills/plan-story/story-template.xml +458 -0
  105. package/{agile-context-engineering/workflows/plan-story.xml → skills/plan-story/workflow.xml} +1301 -944
  106. package/{commands/ace/research-external-solution.md → skills/research-external-solution/SKILL.md} +120 -138
  107. package/{agile-context-engineering/templates/product/external-solution.xml → skills/research-external-solution/external-solution-template.xml} +832 -832
  108. package/skills/research-external-solution/script.js +229 -0
  109. package/skills/research-external-solution/script.test.js +134 -0
  110. package/{agile-context-engineering/workflows/research-external-solution.xml → skills/research-external-solution/workflow.xml} +657 -659
  111. package/{commands/ace/research-integration-solution.md → skills/research-integration-solution/SKILL.md} +121 -135
  112. package/{agile-context-engineering/templates/product/story-integration-solution.xml → skills/research-integration-solution/integration-solution-template.xml} +1015 -1015
  113. package/skills/research-integration-solution/script.js +223 -0
  114. package/skills/research-integration-solution/script.test.js +134 -0
  115. package/{agile-context-engineering/workflows/research-integration-solution.xml → skills/research-integration-solution/workflow.xml} +711 -713
  116. package/{commands/ace/research-story-wiki.md → skills/research-story-wiki/SKILL.md} +101 -116
  117. package/skills/research-story-wiki/script.js +223 -0
  118. package/skills/research-story-wiki/script.test.js +138 -0
  119. package/{agile-context-engineering/templates/product/story-wiki.xml → skills/research-story-wiki/story-wiki-template.xml} +194 -194
  120. package/{agile-context-engineering/workflows/research-story-wiki.xml → skills/research-story-wiki/workflow.xml} +473 -475
  121. package/{commands/ace/research-technical-solution.md → skills/research-technical-solution/SKILL.md} +131 -147
  122. package/skills/research-technical-solution/script.js +223 -0
  123. package/skills/research-technical-solution/script.test.js +134 -0
  124. package/{agile-context-engineering/templates/product/story-technical-solution.xml → skills/research-technical-solution/technical-solution-template.xml} +1025 -1025
  125. package/{agile-context-engineering/workflows/research-technical-solution.xml → skills/research-technical-solution/workflow.xml} +761 -763
  126. package/{commands/ace/review-story.md → skills/review-story/SKILL.md} +99 -109
  127. package/skills/review-story/script.js +249 -0
  128. package/skills/review-story/script.test.js +169 -0
  129. package/skills/review-story/story-template.xml +451 -0
  130. package/{agile-context-engineering/workflows/review-story.xml → skills/review-story/workflow.xml} +279 -281
  131. package/{commands/ace/update.md → skills/update/SKILL.md} +65 -56
  132. package/{agile-context-engineering/workflows/update.xml → skills/update/workflow.xml} +33 -18
  133. package/agile-context-engineering/src/ace-tools.js +0 -2881
  134. package/agile-context-engineering/src/ace-tools.test.js +0 -1089
  135. package/agile-context-engineering/templates/_command.md +0 -54
  136. package/agile-context-engineering/templates/_workflow.xml +0 -17
  137. package/agile-context-engineering/templates/config.json +0 -0
  138. package/agile-context-engineering/templates/product/integration-solution.xml +0 -0
  139. package/commands/ace/help.md +0 -93
@@ -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,121 @@
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, runSkillScript,
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
+ runSkillScript({
31
+ init: cmdInit,
32
+ 'resolve-fields': (cwd, raw, args) => resolveFields(cwd, raw, args),
33
+ 'create-issue': (cwd, raw, args) => createIssue(cwd, raw, args),
34
+ 'fetch-issues': (cwd, raw, args) => fetchIssues(cwd, raw, args),
35
+ });
36
+
37
+ // ─── Init: Plan Backlog ─────────────────────────────────────────────────────
38
+
39
+ function cmdInit(cwd, raw, args, parsed) {
40
+ const config = loadConfig(cwd);
41
+ const brownfield = detectBrownfieldStatus(cwd);
42
+
43
+ // Wiki detection — system-wide
44
+ const wikiSystemDir = '.docs/wiki/system-wide';
45
+ const has_wiki_system_wide = pathExists(cwd, wikiSystemDir);
46
+ const has_system_architecture = pathExists(cwd, path.join(wikiSystemDir, 'system-architecture.md'));
47
+ const has_system_structure = pathExists(cwd, path.join(wikiSystemDir, 'system-structure.md'));
48
+ const has_testing_framework = pathExists(cwd, path.join(wikiSystemDir, 'testing-framework.md'));
49
+
50
+ // Wiki detection — subsystems
51
+ const wikiSubsystemsDir = '.docs/wiki/subsystems';
52
+ const has_wiki_subsystems = pathExists(cwd, wikiSubsystemsDir);
53
+
54
+ let wiki_subsystem_names = [];
55
+ if (has_wiki_subsystems) {
56
+ try {
57
+ const entries = fs.readdirSync(path.join(cwd, wikiSubsystemsDir), { withFileTypes: true });
58
+ wiki_subsystem_names = entries
59
+ .filter(e => e.isDirectory())
60
+ .map(e => e.name);
61
+ } catch {}
62
+ }
63
+
64
+ const has_wiki = has_wiki_system_wide || has_wiki_subsystems;
65
+
66
+ const result = {
67
+ // Models
68
+ product_owner_model: resolveModel(cwd, 'ace-product-owner'),
69
+ researcher_model: resolveModel(cwd, 'ace-project-researcher'),
70
+
71
+ // Config
72
+ commit_docs: config.commit_docs,
73
+
74
+ // Product artifacts
75
+ has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
76
+ has_product_backlog: pathExists(cwd, '.ace/artifacts/product/product-backlog.md'),
77
+
78
+ // Research artifacts (from previous runs)
79
+ has_features_research: pathExists(cwd, '.ace/research/FEATURES.md'),
80
+ has_architecture_research: pathExists(cwd, '.ace/research/ARCHITECTURE.md'),
81
+
82
+ // Wiki analysis cache (from previous runs)
83
+ has_wiki_analysis: pathExists(cwd, '.ace/artifacts/wiki/wiki-analysis.md'),
84
+
85
+ // Brownfield detection
86
+ ...brownfield,
87
+
88
+ // Wiki state — system-wide
89
+ has_wiki,
90
+ has_wiki_system_wide,
91
+ has_system_architecture,
92
+ has_system_structure,
93
+ has_testing_framework,
94
+
95
+ // Wiki state — subsystems
96
+ has_wiki_subsystems,
97
+ wiki_subsystem_names,
98
+
99
+ // Git state
100
+ has_git: pathExists(cwd, '.git'),
101
+
102
+ // GitHub CLI
103
+ has_gh_cli: (() => {
104
+ try {
105
+ const { execSync } = require('child_process');
106
+ execSync('gh --version', { stdio: 'pipe' });
107
+ return true;
108
+ } catch {
109
+ return false;
110
+ }
111
+ })(),
112
+
113
+ // GitHub Project settings (from settings.json)
114
+ github_project: (() => {
115
+ const settings = loadSettings(cwd);
116
+ return settings.github_project;
117
+ })(),
118
+ };
119
+
120
+ output(result, raw);
121
+ }