@llipe.com/dev-tasks 0.6.4 → 0.6.6
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.
- package/.claude/agents/developer.md +294 -0
- package/.claude/agents/github-ops.md +407 -0
- package/.claude/agents/housekeeping.md +109 -0
- package/.claude/agents/technical-writer.md +390 -0
- package/.claude/agents/ux-engineer.md +184 -0
- package/.claude/agents/verifier.md +276 -0
- package/.claude/commands/developer.md +272 -0
- package/.claude/commands/github-ops.md +10 -0
- package/.claude/commands/housekeeping.md +10 -0
- package/.claude/commands/planner.md +506 -0
- package/.claude/commands/product-engineer.md +263 -0
- package/.claude/commands/technical-writer.md +10 -0
- package/.claude/commands/ux-engineer.md +10 -0
- package/.claude/commands/verifier-audit.md +10 -0
- package/.claude/commands/verifier-design.md +10 -0
- package/.claude/hooks/git-guard.sh +95 -0
- package/.claude/skills/activity-contract-test-design/SKILL.md +122 -0
- package/.claude/skills/activity-drift-reconciliation/SKILL.md +133 -0
- package/.claude/skills/activity-e2e-test-design/SKILL.md +124 -0
- package/.claude/skills/activity-edge-case-refinement/SKILL.md +146 -0
- package/.claude/skills/activity-generate-spec/SKILL.md +137 -0
- package/.claude/skills/activity-generate-stories/SKILL.md +243 -0
- package/.claude/skills/activity-init/SKILL.md +162 -0
- package/.claude/skills/activity-publish-github/SKILL.md +116 -0
- package/.claude/skills/activity-random-test-tactics/SKILL.md +181 -0
- package/.claude/skills/activity-refine/SKILL.md +236 -0
- package/.claude/skills/git-ops/SKILL.md +221 -0
- package/.claude/skills/implement/SKILL.md +129 -0
- package/.claude/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.claude/skills/memo-cli-usage/SKILL.md +144 -0
- package/.claude/skills/plan/SKILL.md +145 -0
- package/.claude/skills/webapp-mockup/SKILL.md +76 -0
- package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
- package/.github/agents/developer.agent.md +293 -0
- package/.github/agents/github-ops.agent.md +416 -0
- package/.github/agents/housekeeping.agent.md +109 -0
- package/.github/agents/planner.agent.md +496 -0
- package/.github/agents/product-engineer.agent.md +262 -0
- package/.github/agents/technical-writer.agent.md +389 -0
- package/.github/agents/ux-engineer.agent.md +183 -0
- package/.github/agents/verifier.agent.md +275 -0
- package/.github/instructions/domain/nextjs-pages-components.instructions.md +375 -0
- package/.github/instructions/implement.instructions.md +128 -0
- package/.github/instructions/plan.instructions.md +144 -0
- package/.github/prompts/developer-execute.prompt.md +13 -0
- package/.github/prompts/github-ops.prompt.md +16 -0
- package/.github/prompts/housekeeping.prompt.md +16 -0
- package/.github/prompts/planner-resume.prompt.md +13 -0
- package/.github/prompts/planner.prompt.md +18 -0
- package/.github/prompts/product-engineer-feature.prompt.md +21 -0
- package/.github/prompts/product-engineer-init.prompt.md +16 -0
- package/.github/prompts/product-engineer-issue.prompt.md +19 -0
- package/.github/prompts/technical-writer.prompt.md +21 -0
- package/.github/prompts/ux-engineer.prompt.md +14 -0
- package/.github/prompts/verifier-audit.prompt.md +33 -0
- package/.github/prompts/verifier-design.prompt.md +28 -0
- package/.github/skills/activity-contract-test-design/SKILL.md +117 -0
- package/.github/skills/activity-drift-reconciliation/SKILL.md +128 -0
- package/.github/skills/activity-e2e-test-design/SKILL.md +119 -0
- package/.github/skills/activity-edge-case-refinement/SKILL.md +141 -0
- package/.github/skills/activity-generate-spec/SKILL.md +132 -0
- package/.github/skills/activity-generate-stories/SKILL.md +238 -0
- package/.github/skills/activity-init/SKILL.md +157 -0
- package/.github/skills/activity-publish-github/SKILL.md +111 -0
- package/.github/skills/activity-random-test-tactics/SKILL.md +176 -0
- package/.github/skills/activity-refine/SKILL.md +231 -0
- package/.github/skills/git-ops/SKILL.md +216 -0
- package/.github/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.github/skills/memo-cli-usage/SKILL.md +144 -0
- package/.github/skills/webapp-mockup/SKILL.md +71 -0
- package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
- package/.kiro/agents/developer.md +305 -0
- package/.kiro/agents/github-ops.md +428 -0
- package/.kiro/agents/housekeeping.md +122 -0
- package/.kiro/agents/planner.md +530 -0
- package/.kiro/agents/product-engineer.md +294 -0
- package/.kiro/agents/technical-writer.md +408 -0
- package/.kiro/agents/ux-engineer.md +200 -0
- package/.kiro/agents/verifier.md +275 -0
- package/.kiro/hooks/git-guard.json +16 -0
- package/.kiro/hooks/scripts/git-guard.sh +116 -0
- package/.kiro/skills/activity-contract-test-design/SKILL.md +122 -0
- package/.kiro/skills/activity-drift-reconciliation/SKILL.md +133 -0
- package/.kiro/skills/activity-e2e-test-design/SKILL.md +124 -0
- package/.kiro/skills/activity-edge-case-refinement/SKILL.md +146 -0
- package/.kiro/skills/activity-generate-spec/SKILL.md +137 -0
- package/.kiro/skills/activity-generate-stories/SKILL.md +243 -0
- package/.kiro/skills/activity-init/SKILL.md +162 -0
- package/.kiro/skills/activity-publish-github/SKILL.md +116 -0
- package/.kiro/skills/activity-random-test-tactics/SKILL.md +181 -0
- package/.kiro/skills/activity-refine/SKILL.md +236 -0
- package/.kiro/skills/git-ops/SKILL.md +221 -0
- package/.kiro/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.kiro/skills/memo-cli-usage/SKILL.md +144 -0
- package/.kiro/skills/webapp-mockup/SKILL.md +76 -0
- package/.kiro/steering/git-guard-notice.md +11 -0
- package/.kiro/steering/implement.md +129 -0
- package/.kiro/steering/nextjs-pages-components.md +376 -0
- package/.kiro/steering/plan.md +145 -0
- package/AGENTS.md +122 -0
- package/CHANGELOG.md +28 -2
- package/CLAUDE.md +94 -0
- package/README.md +6 -6
- package/dist/adapters/cli/extract-all.js +4 -4
- package/dist/adapters/cli/extract-component.d.ts +1 -1
- package/dist/adapters/cli/extract-component.js +4 -4
- package/dist/adapters/cli/parse-args.d.ts +1 -0
- package/dist/adapters/cli/parse-args.d.ts.map +1 -1
- package/dist/adapters/cli/parse-args.js +19 -8
- package/dist/adapters/cli/parse-args.js.map +1 -1
- package/dist/bin/dev-tasks.js +23 -9
- package/dist/bin/dev-tasks.js.map +1 -1
- package/dist/bin/dt.js +3 -3
- package/dist/core/distribution/index.d.ts +5 -3
- package/dist/core/distribution/index.d.ts.map +1 -1
- package/dist/core/distribution/index.js +3 -2
- package/dist/core/distribution/index.js.map +1 -1
- package/dist/core/distribution/install.d.ts +20 -8
- package/dist/core/distribution/install.d.ts.map +1 -1
- package/dist/core/distribution/install.js +76 -36
- package/dist/core/distribution/install.js.map +1 -1
- package/dist/core/distribution/manifest.d.ts +25 -2
- package/dist/core/distribution/manifest.d.ts.map +1 -1
- package/dist/core/distribution/manifest.js +29 -2
- package/dist/core/distribution/manifest.js.map +1 -1
- package/dist/core/distribution/migrate.d.ts +6 -3
- package/dist/core/distribution/migrate.d.ts.map +1 -1
- package/dist/core/distribution/migrate.js +21 -19
- package/dist/core/distribution/migrate.js.map +1 -1
- package/dist/core/distribution/profiles.d.ts +30 -0
- package/dist/core/distribution/profiles.d.ts.map +1 -0
- package/dist/core/distribution/profiles.js +57 -0
- package/dist/core/distribution/profiles.js.map +1 -0
- package/dist/core/distribution/update.d.ts +6 -4
- package/dist/core/distribution/update.d.ts.map +1 -1
- package/dist/core/distribution/update.js +22 -22
- package/dist/core/distribution/update.js.map +1 -1
- package/dist/core/extract/component.d.ts +9 -9
- package/dist/core/extract/component.js +5 -5
- package/dist/core/extract/report.d.ts +1 -1
- package/dist/core/extract/report.js +1 -1
- package/package.json +15 -2
- 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.
|