agile-context-engineering 0.1.0 → 0.2.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 (83) hide show
  1. package/LICENSE +30 -0
  2. package/README.md +272 -78
  3. package/agents/ace-code-discovery-analyst.md +245 -0
  4. package/agents/ace-code-integration-analyst.md +248 -0
  5. package/agents/ace-code-reviewer.md +375 -0
  6. package/agents/ace-product-owner.md +361 -0
  7. package/agents/ace-project-researcher.md +606 -0
  8. package/agents/ace-research-synthesizer.md +228 -0
  9. package/agents/ace-technical-application-architect.md +287 -0
  10. package/agents/ace-wiki-mapper.md +334 -0
  11. package/agile-context-engineering/src/ace-tools.js +2881 -0
  12. package/agile-context-engineering/src/ace-tools.test.js +1089 -0
  13. package/agile-context-engineering/templates/_command.md +54 -0
  14. package/agile-context-engineering/templates/_workflow.xml +17 -0
  15. package/agile-context-engineering/templates/config.json +0 -0
  16. package/agile-context-engineering/templates/product/external-solution.xml +832 -0
  17. package/agile-context-engineering/templates/product/feature.xml +361 -0
  18. package/agile-context-engineering/templates/product/integration-solution.xml +0 -0
  19. package/agile-context-engineering/templates/product/product-backlog.xml +231 -0
  20. package/agile-context-engineering/templates/product/product-vision.xml +227 -0
  21. package/agile-context-engineering/templates/product/story-integration-solution.xml +1014 -0
  22. package/agile-context-engineering/templates/product/story-technical-solution.xml +1025 -0
  23. package/agile-context-engineering/templates/product/story-wiki.xml +190 -0
  24. package/agile-context-engineering/templates/product/story.xml +451 -0
  25. package/agile-context-engineering/templates/wiki/coding-standards.xml +493 -0
  26. package/agile-context-engineering/templates/wiki/decizions.xml +115 -0
  27. package/agile-context-engineering/templates/wiki/guide.xml +137 -0
  28. package/agile-context-engineering/templates/wiki/module-discovery.xml +174 -0
  29. package/agile-context-engineering/templates/wiki/pattern.xml +159 -0
  30. package/agile-context-engineering/templates/wiki/subsystem-architecture.xml +343 -0
  31. package/agile-context-engineering/templates/wiki/subsystem-structure.xml +235 -0
  32. package/agile-context-engineering/templates/wiki/system-architecture.xml +254 -0
  33. package/agile-context-engineering/templates/wiki/system-cross-cutting.xml +197 -0
  34. package/agile-context-engineering/templates/wiki/system-structure.xml +178 -0
  35. package/agile-context-engineering/templates/wiki/system.xml +381 -0
  36. package/agile-context-engineering/templates/wiki/tech-debt-index.xml +125 -0
  37. package/agile-context-engineering/templates/wiki/testing-framework.xml +283 -0
  38. package/agile-context-engineering/utils/questioning.xml +111 -0
  39. package/agile-context-engineering/utils/ui-formatting.md +300 -0
  40. package/agile-context-engineering/workflows/execute-story.xml +1145 -0
  41. package/agile-context-engineering/workflows/help.xml +540 -0
  42. package/agile-context-engineering/workflows/init-coding-standards.xml +386 -0
  43. package/agile-context-engineering/workflows/map-story.xml +797 -0
  44. package/agile-context-engineering/workflows/map-subsystem.xml +1177 -0
  45. package/agile-context-engineering/workflows/map-system.xml +647 -0
  46. package/agile-context-engineering/workflows/plan-backlog.xml +1356 -0
  47. package/agile-context-engineering/workflows/plan-feature.xml +1495 -0
  48. package/agile-context-engineering/workflows/plan-product-vision.xml +342 -0
  49. package/agile-context-engineering/workflows/plan-story.xml +909 -0
  50. package/agile-context-engineering/workflows/research-external-solution.xml +659 -0
  51. package/agile-context-engineering/workflows/research-integration-solution.xml +712 -0
  52. package/agile-context-engineering/workflows/research-story-wiki.xml +474 -0
  53. package/agile-context-engineering/workflows/research-technical-solution.xml +762 -0
  54. package/agile-context-engineering/workflows/review-story.xml +281 -0
  55. package/bin/install.js +102 -166
  56. package/commands/ace/execute-story.md +137 -0
  57. package/commands/ace/help.md +93 -0
  58. package/commands/ace/init-coding-standards.md +83 -0
  59. package/commands/ace/map-story.md +156 -0
  60. package/commands/ace/map-subsystem.md +138 -0
  61. package/commands/ace/map-system.md +90 -0
  62. package/commands/ace/plan-backlog.md +83 -0
  63. package/commands/ace/plan-feature.md +89 -0
  64. package/commands/ace/plan-product-vision.md +81 -0
  65. package/commands/ace/plan-story.md +145 -0
  66. package/commands/ace/research-external-solution.md +138 -0
  67. package/commands/ace/research-integration-solution.md +135 -0
  68. package/commands/ace/research-story-wiki.md +116 -0
  69. package/commands/ace/research-technical-solution.md +147 -0
  70. package/commands/ace/review-story.md +109 -0
  71. package/package.json +5 -8
  72. package/agents/executor.md +0 -88
  73. package/agents/planner.md +0 -78
  74. package/agents/researcher.md +0 -77
  75. package/agents/verifier.md +0 -116
  76. package/commands/ace-execute-story.md +0 -114
  77. package/commands/ace-init.md +0 -254
  78. package/commands/ace-plan-epic.md +0 -79
  79. package/commands/ace-plan-feature.md +0 -78
  80. package/commands/ace-plan-project.md +0 -205
  81. package/commands/ace-plan-story.md +0 -97
  82. package/commands/ace-refine-story.md +0 -90
  83. package/commands/ace-verify-story.md +0 -127
@@ -0,0 +1,361 @@
1
+ <feature>
2
+
3
+ <purpose>
4
+ Template for `.ace/artifacts/product/&lt;id-epic_name&gt;/&lt;id-feature_name&gt;/&lt;id-feature_name&gt;.md` —
5
+ a feature specification document that describes a complete vertical slice of functionality,
6
+ its benefit hypothesis, acceptance criteria, and story breakdown. Stories are captured as
7
+ comprehensive plain-text descriptions; formal story specification (Gherkin) is
8
+ handled later by the `plan-story` command using a separate `story.xml` template.
9
+ </purpose>
10
+
11
+ <output-format>
12
+
13
+ <section name="header">
14
+ # [ID]: [Feature Title]
15
+
16
+ **Epic**: [Epic ID] [Epic Title] | **Status**: [Status] | **Priority**: [Priority]
17
+ **Size**: [Size] | **Sprint**: [Sprint] | **Milestone**: [Milestone] | **Link**: [Link]
18
+
19
+ &lt;!-- Example:
20
+ # F3: OAuth2 Login Flow
21
+ **Epic**: #45 User Authentication | **Status**: Refined | **Priority**: High
22
+ **Size**: 30 | **Sprint**: — | **Milestone**: mvp | **Link**: [#78](https://github.com/owner/repo/issues/78)
23
+ --&gt;
24
+ </section>
25
+
26
+ <section name="description">
27
+ ## Description
28
+
29
+ [What this feature delivers as a complete vertical slice of functionality. 2-4 sentences.
30
+ Describe end-to-end user-facing behavior — what the user can do when this feature is done.
31
+ Focus on WHAT is delivered and WHY it matters, not HOW it is implemented.
32
+ Must cut through all/most architectural layers: domain, application, infrastructure, presentation.
33
+ It also may cut througn multiple modules.]
34
+ </section>
35
+
36
+ <section name="benefit-hypothesis">
37
+ ## Benefit Hypothesis
38
+
39
+ &gt; We believe [measurable business outcome] will be achieved if [target users/personas]
40
+ &gt; successfully [user outcome / what they can do] with [this feature / what we deliver].
41
+
42
+ &lt;!-- The hypothesis MUST be:
43
+ - Measurable: includes a quantifiable or observable outcome
44
+ - Falsifiable: you can determine if it was wrong
45
+ - User-focused: describes user benefit, not system behavior
46
+ Example:
47
+ "We believe a 25% reduction in login support tickets will be achieved if returning
48
+ customers successfully authenticate via OAuth2 providers with the Social Login feature."
49
+ --&gt;
50
+ </section>
51
+
52
+ <section name="scope">
53
+ ## Scope
54
+
55
+ ### Includes
56
+
57
+ &lt;!-- ALL functionality bundled within this feature. Be exhaustive — if it's not listed,
58
+ it's not in scope. Each item should be a concrete behavior or capability. --&gt;
59
+
60
+ - [Capability or behavior 1]
61
+ - [Capability or behavior 2]
62
+ - [Capability or behavior 3]
63
+
64
+ ### Out of Scope
65
+
66
+ &lt;!-- Explicitly excluded items to prevent scope creep. Name things that someone might
67
+ reasonably assume are included but are NOT part of this feature. --&gt;
68
+
69
+ - [Excluded item 1 — brief reason why]
70
+ - [Excluded item 2 — brief reason why]
71
+ </section>
72
+
73
+ <section name="acceptance-criteria">
74
+ ## Acceptance Criteria
75
+
76
+ &lt;!-- High-level, measurable success conditions that validate the benefit hypothesis.
77
+ These are FEATURE-level criteria — NOT Gherkin scenarios (those belong in stories).
78
+ 3-7 criteria. Each must be independently verifiable. --&gt;
79
+
80
+ - [ ] [Criterion 1 — observable, measurable condition]
81
+ - [ ] [Criterion 2 — observable, measurable condition]
82
+ - [ ] [Criterion 3 — observable, measurable condition]
83
+ </section>
84
+
85
+ <section name="existing-implementation">
86
+ ## Existing Implementation
87
+
88
+ &lt;!-- BROWNFIELD ONLY — omit this entire section for greenfield features.
89
+ What already exists in the codebase that this feature builds on, integrates with,
90
+ or must account for. Sourced from relevant-code.md research. --&gt;
91
+
92
+ ### Components &amp; Modules
93
+ - [Existing component/module — what it does, how it relates to this feature]
94
+
95
+ ### APIs &amp; Interfaces
96
+ - [Existing API/interface — current capabilities, what this feature extends or uses]
97
+
98
+ ### Partial Implementations
99
+ - [What's already partially built — what remains to be done]
100
+
101
+ ### Architectural Constraints
102
+ - [Constraint from existing architecture — how it affects this feature's design]
103
+ </section>
104
+
105
+ <section name="story-index">
106
+ ## Story Breakdown
107
+
108
+ &lt;!-- Summary table of all stories. Story details follow below.
109
+ Stories are ordered by delivery sequence within this feature. --&gt;
110
+
111
+ | ID | Title | Size | Status | Sprint | Link |
112
+ |------|--------------------------------|------|-------------|----------|---------------------------------------------------------|
113
+ | S1 | [Short descriptive name] | — | Todo | — | — |
114
+ | S2 | [Short descriptive name] | — | Todo | — | — |
115
+ </section>
116
+
117
+ <section name="story-details" repeat="once per story">
118
+ ### [ID]: [Story Title]
119
+
120
+ [Comprehensive plain-text description of what this story covers.
121
+
122
+ This should be rich and detailed — multiple paragraphs if needed. Cover:
123
+ - What the story is about (scope, user-facing behavior)
124
+ - Why it matters (value to the user within this feature)
125
+ - Key behaviors and edge cases to consider
126
+ - Any known constraints or technical considerations
127
+ - How it relates to other stories in this feature
128
+
129
+ This is NOT a formal user story. It is a thorough description of intent and scope.
130
+ The `plan-story` command will later restructure this into a proper INVEST story
131
+ with Gherkin acceptance criteria, a Definition of Done.]
132
+ </section>
133
+
134
+ <section name="technical-context">
135
+ ## Technical Context
136
+
137
+ &lt;!-- Architecture considerations across layers. NOT implementation details — those
138
+ belong in individual stories and tasks. This section captures the technical
139
+ landscape that informs story decomposition and estimation.
140
+ Informed by relevant-code.md and relevant-wiki.md research. --&gt;
141
+
142
+ ### System Boundaries
143
+ - [Where this feature sits in the system architecture]
144
+ - [What external systems or services it interacts with]
145
+
146
+ ### Integration Points
147
+ - [APIs, events, data flows this feature connects to]
148
+
149
+ ### Cross-Cutting Concerns
150
+ - [Security, performance, accessibility, observability considerations]
151
+
152
+ ### Non-Functional Requirements
153
+ - [Performance targets, scalability needs, compliance requirements]
154
+ </section>
155
+
156
+ <section name="dependencies">
157
+ ## Dependencies
158
+
159
+ ### Requires
160
+ &lt;!-- Features, epics, or external items that must be completed before this feature. --&gt;
161
+ - [Dependency — what it is and why this feature needs it]
162
+
163
+ ### Enables
164
+ &lt;!-- Features or capabilities that depend on this feature being done. --&gt;
165
+ - [Dependent feature — what it needs from this feature]
166
+
167
+ ### External
168
+ &lt;!-- Third-party services, APIs, libraries, or approvals needed. --&gt;
169
+ - [External dependency — status and risk]
170
+ </section>
171
+
172
+ <section name="metadata">
173
+ ---
174
+ *Created: [date] | Last refined: [date] | Refinements: [count]*
175
+
176
+ **Research artifacts:**
177
+ - Wiki analysis: [relative path to relevant-wiki.md or "—"]
178
+ - Code analysis: [relative path to relevant-code.md or "—"]
179
+ </section>
180
+
181
+ </output-format>
182
+
183
+ <field-definitions>
184
+
185
+ <field name="ID">
186
+ F[number] for local features, #[issue_number] for GitHub-linked.
187
+ Same identity rules as product-backlog.xml — IDs are stable, never renumber.
188
+ </field>
189
+
190
+ <field name="Status">
191
+ <allowed-values>
192
+ <value name="Todo">Not yet started or refined</value>
193
+ <value name="Refined">Requirements clear, broken into stories, ready for sprint planning</value>
194
+ <value name="In Progress">Has active stories being implemented</value>
195
+ <value name="Done">All stories complete, acceptance criteria met</value>
196
+ </allowed-values>
197
+ </field>
198
+
199
+ <field name="Priority">
200
+ <allowed-values>
201
+ <value name="Critical">Blocks other work or has external deadline</value>
202
+ <value name="High">Core functionality, high user impact</value>
203
+ <value name="Medium">Important but not blocking</value>
204
+ <value name="Low">Nice to have, can be deferred</value>
205
+ </allowed-values>
206
+ </field>
207
+
208
+ <field name="Size">
209
+ <allowed-values>
210
+ <value name="10">Small feature — 1-2 sprints</value>
211
+ <value name="20">Small-Medium — 2-3 sprints</value>
212
+ <value name="30">Medium — 3-4 sprints</value>
213
+ <value name="50">Large — 4-6 sprints</value>
214
+ <value name="80">Very large — 6+ sprints, consider splitting</value>
215
+ </allowed-values>
216
+ Fibonacci×10 relative sizing. If larger than 80, split into smaller features.
217
+ </field>
218
+
219
+ <field name="Story table">
220
+ The story breakdown table uses the same column conventions as product-backlog.xml.
221
+ Story IDs: S[N] local or #[issue_number] GitHub-linked.
222
+ Story sizes: Fibonacci (1, 2, 3, 5, 8) — not ×10.
223
+ </field>
224
+
225
+ </field-definitions>
226
+
227
+ <guidelines>
228
+
229
+ <guideline name="vertical-slicing">
230
+ Features AND stories MUST be vertical slices delivering end-to-end user-facing value.
231
+
232
+ Features MAY cut through multiple modules.
233
+ Features MAY cut through ALL/MOST architectural layers — domain, application,
234
+ infrastructure, and presentation of a module. A feature that only touches one layer
235
+ (e.g., "set up the database schema") is NOT a feature; it's a technical story.
236
+
237
+ Stories follow the same principle: each story MUST cut through the layers needed
238
+ to deliver a complete, user-facing capability. In most cases this means both
239
+ backend AND frontend in the same story. A story like "Create API endpoints" or
240
+ "Build UI components" is a horizontal slice — not acceptable in most cases.
241
+ </guideline>
242
+
243
+ <guideline name="feature-scope">
244
+ Features are sized using Fibonacci×10: 10, 20, 30, 50, 80 points.
245
+ If a feature is less than 10 points, it's probably a story — promote it down.
246
+ If a feature exceeds 80 points (~6 sprints), it should be split into
247
+ smaller features. Features describe WHAT will be delivered, not HOW.
248
+ </guideline>
249
+
250
+ <guideline name="benefit-hypothesis">
251
+ The Benefit Hypothesis MUST follow the SAFe template format exactly:
252
+ "We believe [outcome] will be achieved if [users] successfully [action] with [feature]."
253
+ The outcome must be measurable and falsifiable.
254
+
255
+ Bad: "Users will like the new login." (not measurable)
256
+ Bad: "We will build OAuth2 support." (describes output, not outcome)
257
+ Good: "We believe a 25% reduction in login support tickets will be achieved
258
+ if returning customers successfully authenticate via social providers
259
+ with the OAuth2 Login feature."
260
+ </guideline>
261
+
262
+ <guideline name="acceptance-criteria-levels">
263
+ Feature acceptance criteria are HIGH-LEVEL business validation — checkboxes
264
+ that can be verified by a product owner or stakeholder. They validate the
265
+ benefit hypothesis, not implementation details.
266
+
267
+ Story acceptance criteria (Gherkin Given/When/Then) are created later by
268
+ the plan-story command. Do NOT mix feature-level and story-level criteria
269
+ in this document.
270
+ </guideline>
271
+
272
+ <guideline name="story-breakdown">
273
+ Stories are plain-text descriptions of intent and scope — NOT formal user stories.
274
+ The `plan-story` command handles formal specification later.
275
+ The number of stories emerges naturally from the feature's scope — do not
276
+ target a specific count. Let the requirements drive decomposition.
277
+ </guideline>
278
+
279
+ <guideline name="brownfield-context">
280
+ The "Existing Implementation" section is populated from the relevant-code.md
281
+ research artifact. It captures what already exists in the codebase that this
282
+ feature builds upon or must integrate with.
283
+
284
+ This section directly informs story decomposition — knowing what exists
285
+ affects which stories need to be written and how they are scoped.
286
+
287
+ For greenfield features (no existing codebase), omit this section entirely.
288
+ </guideline>
289
+
290
+ <guideline name="refinement-support">
291
+ Every run of plan-feature should produce a COMPLETE, high-quality feature
292
+ document — description, hypothesis, scope, acceptance criteria, story breakdown
293
+ with estimates, and technical context. Do not defer work to "later passes."
294
+
295
+ Re-running plan-feature on the same feature is supported for cases where
296
+ scope changes, new information surfaces, or something was missed — but it
297
+ is the exception, not the workflow.
298
+
299
+ When re-running, increment the metadata refinement count and update
300
+ the "Last refined" date.
301
+ </guideline>
302
+
303
+ <guideline name="github-identity">
304
+ - GitHub-linked items: ID = #[issue_number], Title = EXACT GitHub title
305
+ - Local items: ID = S[N], sequential within the feature
306
+ - IDs are stable — never renumber after assignment
307
+ - When a story gets a GitHub issue, ID changes from S[N] to #[issue_number]
308
+ </guideline>
309
+
310
+ <guideline name="table-formatting">
311
+ Tables MUST be column-aligned for readability. Pad every cell with spaces so
312
+ that column separators (`|`) line up vertically across all rows.
313
+
314
+ Minimum column widths:
315
+ - **ID**: 6 chars (e.g. `| S1 |` or `| #92 |`)
316
+ - **Title**: pad to the longest title in the table
317
+ - **Size**: 6 chars
318
+ - **Status**: 14 chars (longest value: "In Progress")
319
+ - **Sprint**: 10 chars
320
+ - **Link**: pad to the longest link in the table
321
+
322
+ The separator row must match column widths using dashes.
323
+
324
+ Example of properly aligned table:
325
+ ```
326
+ | ID | Title | Size | Status | Sprint | Link |
327
+ |------|--------------------------------|------|-------------|----------|---------------------------------------------------------|
328
+ | #92 | Social provider integration | 5 | In Progress | Sprint 2 | [#92](https://github.com/owner/repo/issues/92) |
329
+ | S2 | Token refresh handling | 3 | Todo | — | — |
330
+ | S3 | Login error states | 2 | Refined | Sprint 3 | — |
331
+ ```
332
+ </guideline>
333
+
334
+ </guidelines>
335
+
336
+ <evolution>
337
+
338
+ **Creation (plan-feature):**
339
+ A single run produces the complete document — all sections filled, stories
340
+ described and estimated, acceptance criteria defined, technical context populated.
341
+
342
+ **Refinement (plan-feature re-run — exception, not norm):**
343
+ Only when scope changes, new information surfaces, or gaps are found.
344
+ Updates metadata refinement count and "Last refined" date.
345
+
346
+ **Story planning (plan-story on individual stories):**
347
+ Story status moves from "Todo" to "Refined" in the index.
348
+ Individual story files are created in the same directory.
349
+ The plain-text description here remains as the source seed.
350
+
351
+ **During implementation:**
352
+ Story statuses update in the index (In Progress → Done).
353
+ Feature status reflects aggregate of story statuses.
354
+
355
+ **Completion:**
356
+ All stories Done, feature acceptance criteria checked off.
357
+ Benefit hypothesis reviewed — validated, partially validated, or invalidated.
358
+
359
+ </evolution>
360
+
361
+ </feature>
@@ -0,0 +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>