@llipe.com/dev-tasks 0.6.1 → 0.6.5

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 (143) hide show
  1. package/.claude/agents/developer.md +294 -0
  2. package/.claude/agents/github-ops.md +407 -0
  3. package/.claude/agents/housekeeping.md +109 -0
  4. package/.claude/agents/technical-writer.md +390 -0
  5. package/.claude/agents/ux-engineer.md +184 -0
  6. package/.claude/agents/verifier.md +276 -0
  7. package/.claude/commands/developer.md +272 -0
  8. package/.claude/commands/github-ops.md +10 -0
  9. package/.claude/commands/housekeeping.md +10 -0
  10. package/.claude/commands/planner.md +506 -0
  11. package/.claude/commands/product-engineer.md +263 -0
  12. package/.claude/commands/technical-writer.md +10 -0
  13. package/.claude/commands/ux-engineer.md +10 -0
  14. package/.claude/commands/verifier-audit.md +10 -0
  15. package/.claude/commands/verifier-design.md +10 -0
  16. package/.claude/hooks/git-guard.sh +95 -0
  17. package/.claude/skills/activity-contract-test-design/SKILL.md +122 -0
  18. package/.claude/skills/activity-drift-reconciliation/SKILL.md +133 -0
  19. package/.claude/skills/activity-e2e-test-design/SKILL.md +124 -0
  20. package/.claude/skills/activity-edge-case-refinement/SKILL.md +146 -0
  21. package/.claude/skills/activity-generate-spec/SKILL.md +137 -0
  22. package/.claude/skills/activity-generate-stories/SKILL.md +243 -0
  23. package/.claude/skills/activity-init/SKILL.md +162 -0
  24. package/.claude/skills/activity-publish-github/SKILL.md +116 -0
  25. package/.claude/skills/activity-random-test-tactics/SKILL.md +181 -0
  26. package/.claude/skills/activity-refine/SKILL.md +236 -0
  27. package/.claude/skills/git-ops/SKILL.md +221 -0
  28. package/.claude/skills/implement/SKILL.md +129 -0
  29. package/.claude/skills/memo-cli-usage/REFERENCE.md +798 -0
  30. package/.claude/skills/memo-cli-usage/SKILL.md +144 -0
  31. package/.claude/skills/plan/SKILL.md +145 -0
  32. package/.claude/skills/webapp-mockup/SKILL.md +76 -0
  33. package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
  34. package/.github/agents/developer.agent.md +293 -0
  35. package/.github/agents/github-ops.agent.md +416 -0
  36. package/.github/agents/housekeeping.agent.md +109 -0
  37. package/.github/agents/planner.agent.md +496 -0
  38. package/.github/agents/product-engineer.agent.md +262 -0
  39. package/.github/agents/technical-writer.agent.md +389 -0
  40. package/.github/agents/ux-engineer.agent.md +183 -0
  41. package/.github/agents/verifier.agent.md +275 -0
  42. package/.github/instructions/domain/nextjs-pages-components.instructions.md +375 -0
  43. package/.github/instructions/implement.instructions.md +128 -0
  44. package/.github/instructions/plan.instructions.md +144 -0
  45. package/.github/prompts/developer-execute.prompt.md +13 -0
  46. package/.github/prompts/github-ops.prompt.md +16 -0
  47. package/.github/prompts/housekeeping.prompt.md +16 -0
  48. package/.github/prompts/planner-resume.prompt.md +13 -0
  49. package/.github/prompts/planner.prompt.md +18 -0
  50. package/.github/prompts/product-engineer-feature.prompt.md +21 -0
  51. package/.github/prompts/product-engineer-init.prompt.md +16 -0
  52. package/.github/prompts/product-engineer-issue.prompt.md +19 -0
  53. package/.github/prompts/technical-writer.prompt.md +21 -0
  54. package/.github/prompts/ux-engineer.prompt.md +14 -0
  55. package/.github/prompts/verifier-audit.prompt.md +33 -0
  56. package/.github/prompts/verifier-design.prompt.md +28 -0
  57. package/.github/skills/activity-contract-test-design/SKILL.md +117 -0
  58. package/.github/skills/activity-drift-reconciliation/SKILL.md +128 -0
  59. package/.github/skills/activity-e2e-test-design/SKILL.md +119 -0
  60. package/.github/skills/activity-edge-case-refinement/SKILL.md +141 -0
  61. package/.github/skills/activity-generate-spec/SKILL.md +132 -0
  62. package/.github/skills/activity-generate-stories/SKILL.md +238 -0
  63. package/.github/skills/activity-init/SKILL.md +157 -0
  64. package/.github/skills/activity-publish-github/SKILL.md +111 -0
  65. package/.github/skills/activity-random-test-tactics/SKILL.md +176 -0
  66. package/.github/skills/activity-refine/SKILL.md +231 -0
  67. package/.github/skills/git-ops/SKILL.md +216 -0
  68. package/.github/skills/memo-cli-usage/REFERENCE.md +798 -0
  69. package/.github/skills/memo-cli-usage/SKILL.md +144 -0
  70. package/.github/skills/webapp-mockup/SKILL.md +71 -0
  71. package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
  72. package/.kiro/agents/developer.md +305 -0
  73. package/.kiro/agents/github-ops.md +428 -0
  74. package/.kiro/agents/housekeeping.md +122 -0
  75. package/.kiro/agents/planner.md +530 -0
  76. package/.kiro/agents/product-engineer.md +294 -0
  77. package/.kiro/agents/technical-writer.md +408 -0
  78. package/.kiro/agents/ux-engineer.md +200 -0
  79. package/.kiro/agents/verifier.md +275 -0
  80. package/.kiro/hooks/git-guard.json +16 -0
  81. package/.kiro/hooks/scripts/git-guard.sh +116 -0
  82. package/.kiro/skills/activity-contract-test-design/SKILL.md +122 -0
  83. package/.kiro/skills/activity-drift-reconciliation/SKILL.md +133 -0
  84. package/.kiro/skills/activity-e2e-test-design/SKILL.md +124 -0
  85. package/.kiro/skills/activity-edge-case-refinement/SKILL.md +146 -0
  86. package/.kiro/skills/activity-generate-spec/SKILL.md +137 -0
  87. package/.kiro/skills/activity-generate-stories/SKILL.md +243 -0
  88. package/.kiro/skills/activity-init/SKILL.md +162 -0
  89. package/.kiro/skills/activity-publish-github/SKILL.md +116 -0
  90. package/.kiro/skills/activity-random-test-tactics/SKILL.md +181 -0
  91. package/.kiro/skills/activity-refine/SKILL.md +236 -0
  92. package/.kiro/skills/git-ops/SKILL.md +221 -0
  93. package/.kiro/skills/memo-cli-usage/REFERENCE.md +798 -0
  94. package/.kiro/skills/memo-cli-usage/SKILL.md +144 -0
  95. package/.kiro/skills/webapp-mockup/SKILL.md +76 -0
  96. package/.kiro/steering/git-guard-notice.md +11 -0
  97. package/.kiro/steering/implement.md +129 -0
  98. package/.kiro/steering/nextjs-pages-components.md +376 -0
  99. package/.kiro/steering/plan.md +145 -0
  100. package/AGENTS.md +122 -0
  101. package/CHANGELOG.md +40 -2
  102. package/CLAUDE.md +94 -0
  103. package/README.md +33 -18
  104. package/dist/adapters/cli/extract-all.js +4 -4
  105. package/dist/adapters/cli/extract-component.d.ts +1 -1
  106. package/dist/adapters/cli/extract-component.js +4 -4
  107. package/dist/adapters/cli/parse-args.d.ts +1 -0
  108. package/dist/adapters/cli/parse-args.d.ts.map +1 -1
  109. package/dist/adapters/cli/parse-args.js +4 -0
  110. package/dist/adapters/cli/parse-args.js.map +1 -1
  111. package/dist/bin/dev-tasks.js +23 -9
  112. package/dist/bin/dev-tasks.js.map +1 -1
  113. package/dist/bin/dt.js +3 -3
  114. package/dist/core/distribution/index.d.ts +5 -3
  115. package/dist/core/distribution/index.d.ts.map +1 -1
  116. package/dist/core/distribution/index.js +3 -2
  117. package/dist/core/distribution/index.js.map +1 -1
  118. package/dist/core/distribution/install.d.ts +20 -8
  119. package/dist/core/distribution/install.d.ts.map +1 -1
  120. package/dist/core/distribution/install.js +76 -36
  121. package/dist/core/distribution/install.js.map +1 -1
  122. package/dist/core/distribution/manifest.d.ts +25 -2
  123. package/dist/core/distribution/manifest.d.ts.map +1 -1
  124. package/dist/core/distribution/manifest.js +29 -2
  125. package/dist/core/distribution/manifest.js.map +1 -1
  126. package/dist/core/distribution/migrate.d.ts +6 -3
  127. package/dist/core/distribution/migrate.d.ts.map +1 -1
  128. package/dist/core/distribution/migrate.js +21 -19
  129. package/dist/core/distribution/migrate.js.map +1 -1
  130. package/dist/core/distribution/profiles.d.ts +30 -0
  131. package/dist/core/distribution/profiles.d.ts.map +1 -0
  132. package/dist/core/distribution/profiles.js +57 -0
  133. package/dist/core/distribution/profiles.js.map +1 -0
  134. package/dist/core/distribution/update.d.ts +6 -4
  135. package/dist/core/distribution/update.d.ts.map +1 -1
  136. package/dist/core/distribution/update.js +22 -22
  137. package/dist/core/distribution/update.js.map +1 -1
  138. package/dist/core/extract/component.d.ts +9 -9
  139. package/dist/core/extract/component.js +5 -5
  140. package/dist/core/extract/report.d.ts +1 -1
  141. package/dist/core/extract/report.js +1 -1
  142. package/package.json +37 -18
  143. package/skills/.gitkeep +0 -0
@@ -0,0 +1,243 @@
1
+ ---
2
+ name: activity-generate-stories
3
+ description: "Break a technical specification into user stories with coverage validation. Use after generate-spec."
4
+ ---
5
+
6
+ # Activity: Generate User Stories
7
+
8
+ Create structured, implementation-ready User Stories from a Technical Specification with built-in coverage validation against the PRD. Use this skill after the specification is approved. Invoked by the `product-engineer` agent in Feature Mode.
9
+
10
+ ---
11
+
12
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
13
+
14
+ ## Goal
15
+
16
+ Create structured, implementation-ready User Stories from a Technical Specification, then validate that all PRD requirements are covered. Each user story **MUST** provide value independently, fit into a single Pull Request, and contain the detail needed for implementation.
17
+
18
+ This activity combines story generation and coverage validation into a single pass.
19
+
20
+ ## Context
21
+
22
+ This activity assumes the following documents already exist:
23
+
24
+ - `prd-[feature-name].md` — Feature requirements
25
+ - `specification-[prd-name].md` — Technical specification
26
+
27
+ ## Document Changelog Convention
28
+
29
+ The user stories document **MUST** include a **Changelog** table as the **first section** after the document title. The changelog tracks the version history of the document.
30
+
31
+ - The initial version **MUST** be `1.0`.
32
+ - Every subsequent update **MUST** increment the minor version (e.g., `1.1`, `1.2`, …).
33
+ - Major structural rewrites **SHOULD** increment the major version (e.g., `2.0`).
34
+ - The **Author** column **MUST** include the name of the person or agent responsible for the change (e.g., `@username`, `developer-agent`, `planner-agent`).
35
+
36
+ ```markdown
37
+ ## Changelog
38
+
39
+ | Version | Date | Summary | Author |
40
+ | ------- | ---------- | --------------- | ------------------ |
41
+ | 1.0 | YYYY-MM-DD | Initial version | @user / agent-name |
42
+ ```
43
+
44
+ ## Process
45
+
46
+ 1. **Receive Specification:** User provides reference to the Technical Specification document.
47
+ 2. **Analyze Specification:** You **MUST** read and analyze the specification to identify story boundaries.
48
+ 3. **Ask Story-Specific Questions:** You **SHOULD** ask about prioritization, sequencing, and story preferences.
49
+ 4. **Generate User Stories:** You **MUST** create detailed stories using the structure below.
50
+ 5. **Validate Coverage:** You **MUST** run a coverage check (see Coverage Validation section below) before presenting stories.
51
+ 6. **Save Output.**
52
+
53
+ ## Clarifying Questions
54
+
55
+ - **Story Priority & Sequencing:** "In what order should these stories be prioritized? Are there dependencies?"
56
+ - **MVP vs. Future:** "Which stories are essential for MVP? Which are nice-to-have?"
57
+ - **Story Scope:** "Should we break this into more granular stories, or combine some? (Target: 1-3 days per story)"
58
+ - **Definition of Done:** "What definition of done applies?"
59
+ - **User Acceptance:** "Who will validate that stories meet acceptance criteria?"
60
+
61
+ ## User Story Structure
62
+
63
+ Each User Story **MUST** include:
64
+
65
+ ```markdown
66
+ ### Story [ID]: [Title]
67
+
68
+ **Priority:** [Critical/High/Medium/Low]
69
+ **Estimated Size:** [XS/S/M/L]
70
+ **Dependencies:** [List any dependent stories or systems]
71
+
72
+ #### User Story
73
+
74
+ As a [user role],
75
+ I want [goal/capability],
76
+ So that [business value/benefit].
77
+
78
+ #### Context
79
+
80
+ [Why this story matters, how it fits the larger feature.]
81
+
82
+ #### Acceptance Criteria
83
+
84
+ - [ ] [Criterion 1: Specific, testable condition]
85
+ - [ ] [Criterion 2]
86
+ - [ ] [Criterion 3]
87
+
88
+ #### Business Rules
89
+
90
+ - [Business rule 1]
91
+ - [Business rule 2]
92
+
93
+ #### Technical Notes
94
+
95
+ - [Key technical decisions or patterns to follow]
96
+ - [Reference to Technical Guidelines sections]
97
+ - [Integration points]
98
+
99
+ #### Testing Requirements
100
+
101
+ - **Unit Tests:** [Specific scenarios]
102
+ - **Integration Tests:** [Cross-component scenarios]
103
+ - **Manual/UI Testing:** [User-visible checks and access path]
104
+ - **Edge-Case Matrix:** [Boundary, error, empty-state, concurrency/idempotency cases]
105
+ - **Acceptance-Criteria Mapping:** [AC -> test case IDs or commands]
106
+ - **Execution Commands:** [Canonical scripts, prefer `pnpm run <script>`]
107
+
108
+ #### Migration Requirements (When Data Model Changes)
109
+
110
+ - Migration artifact: [required by default; add explicit opt-out rationale if omitted]
111
+ - Rollback/impact notes: [required]
112
+ - Apply step: [requires explicit user confirmation before running]
113
+ - Verification after apply: [required]
114
+
115
+ #### Implementation Steps
116
+
117
+ 1. [Step 1]
118
+ 2. [Step 2]
119
+ 3. [Step 3]
120
+
121
+ #### Files to Create/Modify
122
+
123
+ - `path/to/file1.ts` - Brief description
124
+ - `path/to/file1.test.ts` - Unit tests
125
+
126
+ #### Definition of Done Checklist
127
+
128
+ - [ ] Code implemented per technical guidelines
129
+ - [ ] Unit/integration/manual/edge-case tests written and passing
130
+ - [ ] Quality gates passing (`lint`, `format:check`, `typecheck`, `test`, `audit`)
131
+ - [ ] Code reviewed and approved
132
+ - [ ] Acceptance criteria verified
133
+ - [ ] Acceptance criteria explicitly mapped to test evidence
134
+ - [ ] Migration lifecycle complete (or documented opt-out) when schema/data-model changes exist
135
+ - [ ] Pull Request created and merged
136
+ ```
137
+
138
+ ## Package Manager and Script Conventions
139
+
140
+ - For JS/TS projects, you **MUST** prefer `pnpm` over `npm`.
141
+ - You **MAY** use `npm` only when `pnpm` is unavailable or the project is explicitly npm-locked.
142
+ - When stories reference commands, you **MUST** prefer canonical script names:
143
+ - `lint`, `lint:fix`
144
+ - `format`, `format:check`
145
+ - `typecheck`
146
+ - `test`, `test:unit`, `test:integration`, `test:e2e`
147
+ - `audit`
148
+ - `validate` (aggregate quality gate)
149
+
150
+ ## Story Quality Criteria
151
+
152
+ **Good User Stories:**
153
+
154
+ - Provide clear business value that can be demonstrated
155
+ - Are independent and avoid blocking other stories
156
+ - **SHOULD** be completable in 1-3 days by a capable developer
157
+ - **MUST** fit into a single Pull Request
158
+ - **MUST** have clear acceptance criteria
159
+ - **MUST** include sufficient technical guidance for implementation
160
+
161
+ **Poor User Stories:**
162
+
163
+ - Too large or vague (epic-sized)
164
+ - Have circular dependencies
165
+ - Mix multiple concerns or features
166
+ - Lack clear acceptance criteria
167
+
168
+ ## Story Sequencing
169
+
170
+ You **SHOULD** consider these factors when sequencing:
171
+
172
+ 1. **Dependencies:** Stories with fewer dependencies first
173
+ 2. **Value:** High-value core stories early
174
+ 3. **Risk:** Risky or uncertain stories prioritized to de-risk
175
+ 4. **Infrastructure:** Setup stories first
176
+ 5. **Team Skills:** Consider capabilities and learning curve
177
+
178
+ ---
179
+
180
+ ## Coverage Validation (Built-in Quality Gate)
181
+
182
+ Before finalizing stories, you **MUST** validate coverage against the PRD.
183
+
184
+ ### Validation Steps
185
+
186
+ 1. **Extract ALL requirements** from the PRD: user stories, functional requirements, non-functional requirements, business rules, acceptance criteria, data requirements.
187
+ 2. **Map each requirement** to the User Story(ies) that address it.
188
+ 3. **Identify gaps** — requirements NOT covered by any story.
189
+ 4. **Verify non-goals** — confirm out-of-scope items are NOT covered (scope is respected).
190
+
191
+ ### Coverage Report
192
+
193
+ You **MUST** include a summary coverage report at the end of the stories document:
194
+
195
+ ```markdown
196
+ ## Coverage Validation
197
+
198
+ ### Summary
199
+
200
+ - **Total PRD Requirements:** [#]
201
+ - **Total User Stories:** [#]
202
+ - **Coverage:** [X%]
203
+ - **Status:** [Complete / Gaps Identified]
204
+
205
+ ### Requirement Mapping
206
+
207
+ | PRD Requirement | Story ID(s) | Status |
208
+ | --------------- | ------------ | ---------- |
209
+ | [Req 1] | S-001 | ✅ Covered |
210
+ | [Req 2] | S-002, S-003 | ✅ Covered |
211
+ | [Uncovered Req] | — | ❌ GAP |
212
+
213
+ ### Gaps (if any)
214
+
215
+ - **Gap [#]:** [Requirement not covered] — **Recommendation:** [Create new story / Modify existing story]
216
+
217
+ ### Non-Goals Validation
218
+
219
+ - [ ] [Out-of-scope item 1] — Confirmed NOT in any story
220
+ - [ ] [Out-of-scope item 2] — Confirmed NOT in any story
221
+ ```
222
+
223
+ If gaps are found, you **MUST** propose additional stories or modifications to close them before presenting for review.
224
+
225
+ ## Output
226
+
227
+ - **Format:** Markdown (`.md`)
228
+ - **Location:** `/workstream/`
229
+ - **Filename:** `user-stories-[prd-name].md`
230
+
231
+ ## Final Instructions
232
+
233
+ 1. You **MUST NOT** start implementing.
234
+ 2. You **MUST** read the referenced Technical Specification and PRD.
235
+ 3. You **MUST** identify logical story boundaries that provide independent value.
236
+ 4. You **SHOULD** ask clarifying questions about prioritization and sequencing.
237
+ 5. You **MUST** generate detailed User Stories with all required sections.
238
+ 6. You **MUST** ensure stories are appropriately sized (1-3 days of work).
239
+ 7. You **MUST** run the coverage validation and include the report.
240
+ 8. You **MUST** close any gaps before presenting stories for review.
241
+ 9. You **MUST** present stories for user review and save the finalized version.
242
+ 10. You **MUST** provide a summary of total stories and a high-level execution plan.
243
+ 11. When updating an existing user stories document, you **MUST** add a new row to the Changelog table with an incremented version, the current date, a summary of changes, and the responsible author/agent.
@@ -0,0 +1,162 @@
1
+ ---
2
+ name: activity-init
3
+ description: "Establish product-context.md and technical-guidelines.md foundation docs. Use in product-engineer Init Mode."
4
+ ---
5
+
6
+ # Activity: Initialize Project Foundation
7
+
8
+ Establish the foundational documents for a project: Product Context and Technical Guidelines. Use this skill when starting a new project, performing a strategic pivot, or refreshing stale foundation documents. Invoked by the `product-engineer` agent in Init Mode.
9
+
10
+ ---
11
+
12
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
13
+
14
+ ## Goal
15
+
16
+ Guide an AI assistant in establishing the foundational documents for a project: **Product Context** and **Technical Guidelines**. These documents serve as the "constitution" for all future development — every PRD, specification, user story, and implementation decision **SHOULD** be informed by them.
17
+
18
+ Run this activity **once per project** (or when a major strategic or technical pivot occurs).
19
+
20
+ ## Document Changelog Convention
21
+
22
+ Every document produced by this activity **MUST** include a **Changelog** table as the **first section** after the document title. The changelog tracks the version history of the document.
23
+
24
+ - The initial version **MUST** be `1.0`.
25
+ - Every subsequent update **MUST** increment the minor version (e.g., `1.1`, `1.2`, …).
26
+ - Major structural rewrites **SHOULD** increment the major version (e.g., `2.0`).
27
+ - The **Author** column **MUST** include the name of the person or agent responsible for the change (e.g., `@username`, `developer-agent`, `planner-agent`).
28
+
29
+ ```markdown
30
+ ## Changelog
31
+
32
+ | Version | Date | Summary | Author |
33
+ | ------- | ---------- | --------------- | ------------------ |
34
+ | 1.0 | YYYY-MM-DD | Initial version | @user / agent-name |
35
+ ```
36
+
37
+ ## Process
38
+
39
+ 1. **Receive Initial Brief:** The user describes the product, project, or technology stack.
40
+ 2. **Ask Clarifying Questions:** Gather information for both product context and technical guidelines in a single interview. Group questions by domain.
41
+ 3. **Generate Product Context Document:** Create `product-context.md` using the structure below.
42
+ 4. **Generate Technical Guidelines Document:** Create `technical-guidelines.md` using the structure below.
43
+ 5. **Save Output:** Save both documents in `/docs/` and present them for user review.
44
+
45
+ ---
46
+
47
+ ## Part 1 — Product Context
48
+
49
+ ### Clarifying Questions
50
+
51
+ Adapt questions based on context provided:
52
+
53
+ - **Product Definition:** "What is this product/project, and what does it do?"
54
+ - **Problem Statement:** "What core problem does this product solve?"
55
+ - **Target Users/Market:** "Who are the primary users or target audience?"
56
+ - **Strategic Goals:** "What are the 3-5 key strategic objectives?"
57
+ - **Success Metrics:** "How do we measure success?"
58
+ - **Competitive Landscape:** "Are there competing solutions? What differentiates this product?"
59
+ - **Current State:** "Is this a new product, MVP, or mature? What stage?"
60
+ - **Vision/Roadmap:** "What is the long-term vision? Are there planned phases?"
61
+ - **Key Constraints:** "Budget, timeline, technology, or regulatory constraints?"
62
+ - **Stakeholders:** "Who are the key decision-makers?"
63
+
64
+ ### Output Structure: `product-context.md`
65
+
66
+ 0. **Changelog** — Version history table (see Document Changelog Convention above)
67
+ 1. **Executive Summary** — 2-3 sentence overview
68
+ 2. **Problem Statement** — What problem(s) does this product solve?
69
+ 3. **Target Users/Market** — Primary and secondary users, market segments
70
+ 4. **Strategic Goals** — 3-5 key objectives
71
+ 5. **Current State** — New, MVP, or mature? Stage description.
72
+ 6. **Vision & Roadmap** — Long-term vision and planned phases
73
+ 7. **Success Metrics** — How success will be measured
74
+ 8. **Competitive Landscape** — Competitors and differentiation
75
+ 9. **Key Constraints** — Budget, timeline, technology, regulatory
76
+ 10. **Key Stakeholders** — Decision-makers and their interests
77
+ 11. **Assumptions** — Major assumptions underlying the strategy
78
+ 12. **Open Questions** — Remaining areas needing clarification
79
+
80
+ ---
81
+
82
+ ## Part 2 — Technical Guidelines
83
+
84
+ ### Clarifying Questions
85
+
86
+ - **Technology Stack:** "What languages, frameworks, and libraries? Any constraints?"
87
+ - **Architecture:** "Overall pattern (monolith, microservices, serverless, etc.)?"
88
+ - **Data & Database:** "What databases? Schema or data model guidelines?"
89
+ - **API Design:** "APIs exposed? Style (REST, GraphQL, gRPC)? Naming conventions?"
90
+ - **Authentication & Authorization:** "How are users authenticated? Authorization model?"
91
+ - **Security Requirements:** "Key security requirements (encryption, compliance)?"
92
+ - **Performance & Scalability:** "Performance targets? Scalability requirements?"
93
+ - **Testing Strategy:** "Testing approach and coverage expectations?"
94
+ - **Code Organization:** "Folder structure conventions? Module boundaries?"
95
+ - **External Integrations:** "Required third-party integrations?"
96
+ - **Deployment & DevOps:** "Deployment targets? CI/CD practices?"
97
+ - **Monitoring & Logging:** "Observability tools and standards?"
98
+ - **Design Patterns:** "Preferred patterns (MVC, Repository, etc.)?"
99
+ - **Code Quality Standards:** "Linting, formatting, review standards?"
100
+ - **Package Manager Standard:** "Can we standardize on `pnpm` for JS/TS projects?"
101
+ - **Script Naming Standard:** "Should canonical `package.json` scripts (`lint`, `format:check`, `typecheck`, `test`, `audit`, `validate`) be enforced?"
102
+
103
+ ### Output Structure: `technical-guidelines.md`
104
+
105
+ 0. **Changelog** — Version history table (see Document Changelog Convention above)
106
+ 1. **Overview** — Technical vision and guiding principles
107
+ 2. **Technology Stack** — Backend/frontend languages, frameworks, databases, key dependencies
108
+ 3. **Architecture Patterns** — System architecture, key decisions and rationale, component organization
109
+ 4. **API Design Standards** — Style, naming, request/response formats, error handling
110
+ 5. **Authentication & Authorization** — Mechanism, model, permission levels, session management
111
+ 6. **Security Requirements** — Encryption, OWASP compliance, API key management, PII handling
112
+ 7. **Data & Database Guidelines** — Schema patterns, naming conventions, query optimization, backup
113
+ 8. **Integration Methods** — External integrations, patterns, retry/failure handling
114
+ 9. **Code Organization & Structure** — Folder/file conventions, module boundaries, naming
115
+ 10. **Design Patterns & Principles** — Preferred patterns, SOLID, DRY/KISS/YAGNI
116
+ 11. **Testing Strategy** — Frameworks, testing pyramid, coverage, mock strategies
117
+ 12. **Code Quality & Standards** — Linting, static analysis, reviews, documentation
118
+ 13. **Deployment & DevOps** — Environments, CI/CD, infrastructure-as-code, containers
119
+ 14. **Monitoring, Logging & Observability** — Levels, frameworks, alerting, error tracking
120
+ 15. **Performance & Scalability** — Response targets, throughput, caching, optimization
121
+ 16. **Dependency Management** — Management approach, version pinning, vulnerability scanning
122
+ 17. **Development Workflow** — Branching strategy, commit conventions, PR process
123
+ 18. **Known Constraints & Trade-offs** — Limitations and rationale
124
+
125
+ ### JS/TS Package Manager and Script Defaults
126
+
127
+ When the project includes JavaScript/TypeScript:
128
+
129
+ - `pnpm` **MUST** be the default package manager.
130
+ - `npm` **MAY** be used only when `pnpm` is unavailable or explicitly disallowed by project constraints.
131
+ - `package.json` scripts **SHOULD** include canonical names:
132
+ - `lint`, `lint:fix`
133
+ - `format`, `format:check`
134
+ - `typecheck`
135
+ - `test`, `test:unit`, `test:integration`, `test:e2e`
136
+ - `audit`
137
+ - `validate` (aggregate quality gate script)
138
+
139
+ ---
140
+
141
+ ## Output
142
+
143
+ - **Format:** Markdown (`.md`)
144
+ - **Location:** `/docs/`
145
+ - **Filenames:** `product-context.md`, `technical-guidelines.md`
146
+
147
+ ## AGENTS.md Sizing
148
+
149
+ When generating or updating `AGENTS.md` during project initialization, you **MUST** follow the sizing guidelines in `docs/agents-md-guidelines.md`:
150
+
151
+ - Target ~1,000 words (~1,350 tokens)
152
+ - Include only operational per-turn guidance (agent roster, skill roster, instructions table, general rules)
153
+ - Move reference content (workflow chains, prompt tables, verbose explanations) to `docs/`
154
+
155
+ ## Final Instructions
156
+
157
+ 1. You **MUST NOT** start implementing anything.
158
+ 2. You **MUST** ask clarifying questions to fill gaps — cover both product and technical domains.
159
+ 3. You **SHOULD** use answers to create both documents in a single pass.
160
+ 4. You **MUST** save both files and present them for user review.
161
+ 5. You **SHOULD** iterate based on user feedback before finalizing.
162
+ 6. When updating an existing document, you **MUST** add a new row to the Changelog table with an incremented version, the current date, a summary of changes, and the responsible author/agent.
@@ -0,0 +1,116 @@
1
+ ---
2
+ name: activity-publish-github
3
+ description: "Publish user stories as GitHub Issues following github-ops conventions. Use after generate-stories."
4
+ ---
5
+
6
+ # Activity: Publish to GitHub
7
+
8
+ Publish user stories as GitHub Issues so GitHub becomes the source of truth for execution tracking. Use this skill after stories are approved. Invoked by the `product-engineer` agent in Feature Mode.
9
+
10
+ ---
11
+
12
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
13
+
14
+ ## Goal
15
+
16
+ Take a list of user stories and publish them as GitHub Issues using GitHub MCP or `gh` CLI, so GitHub becomes the source of truth for execution tracking.
17
+
18
+ ## Context
19
+
20
+ This activity assumes the following document exists:
21
+
22
+ - `user-stories-[prd-name].md` — The comprehensive list of user stories (produced by the **generate-stories** activity)
23
+
24
+ ## Process
25
+
26
+ 1. **Receive Input:** User provides the reference to the user stories file and the GitHub repository target.
27
+ 2. **Clarify Publishing Rules:** You **MUST** ask for labeling, milestones, assignees, and any issue template constraints, and you **MUST** align them with `github-ops` conventions.
28
+ 3. **Map Stories to Issues:** You **MUST** create one GitHub Issue per user story.
29
+ 4. **Publish to GitHub:** You **MUST** delegate issue creation and metadata application to `github-ops` whenever possible.
30
+ 5. **Save Output.**
31
+
32
+ Execution method rules:
33
+
34
+ - GitHub MCP **SHOULD** be used when available.
35
+ - If MCP is unavailable, `gh` CLI **MAY** be used.
36
+ - The selected method (`github-mcp` or `gh-cli`) **MUST** be recorded in the publication report.
37
+
38
+ If `github-ops` delegation is unavailable in the current runtime, you **MUST** apply `github-ops` issue, label, milestone, and comment conventions directly and explicitly note that fallback in your status output.
39
+
40
+ Attribution rules:
41
+
42
+ - Any PR creation or issue closure performed during this workflow **MUST** include `Assisted-by: <assistant name and version>` in the corresponding PR body or closing comment.
43
+
44
+ ## Clarifying Questions
45
+
46
+ - "Which GitHub repository should I publish to? (`owner/repo`)"
47
+ - "Do you want labels, milestones, or assignees added?"
48
+ - "Should I use a specific issue template or format?"
49
+ - "Do you want a parent epic issue or project board association?"
50
+ - "Should I skip stories below a certain priority or size?"
51
+
52
+ ## Issue Formatting Rules
53
+
54
+ Each GitHub Issue **MUST** be created using:
55
+
56
+ - **Title:** `[PRD-<prd-number or name>] Story [ID]: [Title]`
57
+ - **Body:**
58
+ - User Story (role, goal, benefit)
59
+ - Context
60
+ - Acceptance Criteria (checklist)
61
+ - Acceptance-Criteria-to-Test Mapping
62
+ - Business Rules
63
+ - Technical Notes
64
+ - Testing Requirements
65
+ - Quality Gate Commands (`lint`, `format:check`, `typecheck`, `test`, `audit`, optionally `validate`)
66
+ - Implementation Steps
67
+ - Migration Plan (when schema/data-model changes apply): artifact, rollback notes, confirmation gate before apply, verification step
68
+ - Files to Create/Modify
69
+ - Definition of Done Checklist
70
+ - Open Questions
71
+
72
+ For JS/TS projects, command examples in issues **MUST** prefer `pnpm` and canonical scripts (`pnpm run <script>`).
73
+
74
+ All issue formatting and metadata **MUST** conform to `github-ops` conventions.
75
+
76
+ ## Output Structure
77
+
78
+ You **MUST** create a publication report:
79
+
80
+ ```markdown
81
+ # GitHub Publication Report: [PRD Name]
82
+
83
+ ## Target Repository
84
+
85
+ - Repo: owner/repo
86
+ - Date: YYYY-MM-DD
87
+
88
+ ## Created Issues
89
+
90
+ | Story ID | Story Title | Issue URL | Labels | Milestone | Assignee |
91
+ | -------- | ----------- | ---------------------------------------- | ------------- | --------- | -------- |
92
+ | S-001 | [Title] | https://github.com/owner/repo/issues/123 | backend, auth | v1 | @user |
93
+ | ... | ... | ... | ... | ... | ... |
94
+
95
+ ## Notes
96
+
97
+ - Any skipped stories and why
98
+ - Any template or permission limitations
99
+ - Any manual follow-up needed
100
+ - Execution method used: `github-mcp` or `gh-cli`
101
+ - Assisted-by value used for PR creation/issue closure (if applicable)
102
+ ```
103
+
104
+ ## Output
105
+
106
+ - **Format:** Markdown (`.md`)
107
+ - **Location:** `/workstream/`
108
+ - **Filename:** `github-publication-[prd-name].md`
109
+
110
+ ## Final Instructions
111
+
112
+ 1. You **MUST** read the user stories file.
113
+ 2. You **MUST** ask clarifying questions and confirm the target repo.
114
+ 3. You **MUST** publish each story as a GitHub Issue by delegating to `github-ops` whenever possible.
115
+ 4. You **MUST** save the publication report with issue links.
116
+ 5. You **MUST** inform the user that GitHub is now the source of truth for execution tracking.