@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,141 @@
1
+ # Activity: Edge-Case Refinement
2
+
3
+ Systematic edge-case discovery by category with concrete examples for each. Produces a categorized edge-case catalog mapped to acceptance criteria, ensuring no high-risk boundary goes untested. Invoked by the `verifier` agent in Design Mode.
4
+
5
+ ---
6
+
7
+ > **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).
8
+
9
+ ## Goal
10
+
11
+ Discover and catalog edge cases across all relevant categories for the feature under test. Every edge case **MUST** be tied to at least one acceptance criterion and include a concrete, testable example.
12
+
13
+ ## Context
14
+
15
+ This activity assumes:
16
+
17
+ - A numbered list of acceptance criteria is available (produced by Phase 2 of `verifier`).
18
+ - E2E scenarios and contract scenarios have already been drafted (or will be composed alongside).
19
+ - The output feeds into the edge-case section of the test plan assembled by `verifier`.
20
+
21
+ ## Edge-Case Categories
22
+
23
+ You **MUST** evaluate every category below against the source artifact. For each category that applies, produce ≥1 concrete edge case. For categories that do not apply, explicitly note `N/A — {reason}`.
24
+
25
+ ### 1. Input Domain
26
+
27
+ Boundary values, empty/null/missing inputs, maximum-length strings, special characters, Unicode, encoding mismatches.
28
+
29
+ **Example:** A name field accepts 1–100 characters. Edge cases: empty string, 1 character, 100 characters, 101 characters, string with only whitespace, string with emoji, string with null bytes.
30
+
31
+ ### 2. State Transitions
32
+
33
+ Invalid state transitions, re-entrant operations, concurrent state changes, transitions from terminal states.
34
+
35
+ **Example:** An order can move `pending → confirmed → shipped → delivered`. Edge cases: attempt `pending → shipped` (skip confirmed), attempt `delivered → pending` (reverse), call confirm twice on the same order.
36
+
37
+ ### 3. Timing & Concurrency
38
+
39
+ Race conditions, timeouts, out-of-order events, duplicate submissions, slow network responses.
40
+
41
+ **Example:** Two users submit the same promo code simultaneously. Edge case: both requests arrive before either is committed — does the system apply the code twice or correctly reject one?
42
+
43
+ ### 4. Idempotency
44
+
45
+ Repeated identical requests, retry storms, duplicate webhook deliveries.
46
+
47
+ **Example:** `POST /api/payments` is called twice with the same idempotency key. Edge case: second call should return the same result without creating a duplicate payment.
48
+
49
+ ### 5. Failure Modes
50
+
51
+ Network failures mid-operation, partial writes, downstream service unavailability, disk full, database connection loss.
52
+
53
+ **Example:** Payment gateway returns a timeout after charging the card. Edge case: system must not create a second charge on retry — check for charge-before-confirm pattern.
54
+
55
+ ### 6. Auth & Permissions
56
+
57
+ Expired tokens, revoked permissions mid-session, privilege escalation, cross-tenant data access.
58
+
59
+ **Example:** User A has `read` access to project X. Edge case: User A attempts `DELETE /api/projects/X` — should receive 403, not 404 or 500.
60
+
61
+ ### 7. Data Boundaries
62
+
63
+ Integer overflow, float precision, date boundaries (leap years, DST transitions, epoch limits), empty collections, maximum record counts.
64
+
65
+ **Example:** A date picker allows selecting a delivery date. Edge cases: Feb 29 in a leap year, Feb 29 in a non-leap year, Dec 31 23:59:59 UTC, Jan 1 00:00:00 UTC, dates in year 2038.
66
+
67
+ ### 8. Resource Exhaustion
68
+
69
+ Memory pressure, connection pool depletion, rate limiting, disk space, file descriptor limits.
70
+
71
+ **Example:** API rate limit is 100 requests/minute. Edge cases: 100th request (should succeed), 101st request (should return 429), requests resume after the window resets.
72
+
73
+ ### 9. API Versioning
74
+
75
+ Backward compatibility, deprecated field handling, schema migration, version header omission.
76
+
77
+ **Example:** API v2 renames `userName` to `username`. Edge cases: v1 client sends `userName` to v2 endpoint, v2 client sends `username` to v1 endpoint, request with no version header.
78
+
79
+ ## Edge-Case Template
80
+
81
+ ```markdown
82
+ ### EC-{id}: {Edge-Case Title}
83
+
84
+ | Field | Value |
85
+ | ------------------- | --------------------------------------------------------------------------------------- |
86
+ | **AC(s)** | AC-{n} |
87
+ | **Category** | {category name from list above} |
88
+ | **Input / Setup** | {Concrete input or precondition} |
89
+ | **Expected Result** | {Observable behavior} |
90
+ | **Risk if Missed** | {Consequence of not testing this — data loss, security breach, silent corruption, etc.} |
91
+ ```
92
+
93
+ ## Example Walkthrough: "Requested vs Delivered" Validation
94
+
95
+ Given a user story with AC-5: "Discount code can only be used once per user."
96
+
97
+ **Deriving the edge case:**
98
+
99
+ 1. **Parse AC:** "used once per user" → requires per-user uniqueness check.
100
+ 2. **Category:** Idempotency + Timing & Concurrency.
101
+ 3. **Concrete edge case:**
102
+
103
+ ### EC-7: Same discount code submitted twice simultaneously
104
+
105
+ | Field | Value |
106
+ | ------------------- | --------------------------------------------------------------------------------------------------- |
107
+ | **AC(s)** | AC-5 |
108
+ | **Category** | Idempotency, Timing & Concurrency |
109
+ | **Input / Setup** | User sends two `POST /api/cart/discount` requests with the same code in parallel (within 50ms). |
110
+ | **Expected Result** | Exactly one application succeeds. The second returns an error indicating the code was already used. |
111
+ | **Risk if Missed** | User gets double discount — revenue loss, potential abuse vector. |
112
+
113
+ **Validating "requested vs delivered":**
114
+
115
+ - **Requested (AC-5):** Code used once per user.
116
+ - **Delivered:** Run the edge case; if both requests succeed → **DRIFT** detected. If exactly one succeeds → **PASS**.
117
+
118
+ ## Output
119
+
120
+ This skill returns a categorized list of edge cases in the template format above. The calling agent (`verifier`) assembles them into the edge-case section of the test plan.
121
+
122
+ ## Execution Checklist
123
+
124
+ Use this checklist to verify completeness before returning results:
125
+
126
+ - [ ] All 9 categories evaluated against the source artifact.
127
+ - [ ] Each applicable category has ≥1 concrete edge case with filled template.
128
+ - [ ] Non-applicable categories marked `N/A` with reason.
129
+ - [ ] Every edge case maps to ≥1 AC.
130
+ - [ ] Risk-if-missed populated for every edge case.
131
+ - [ ] No edge case references internal implementation details.
132
+ - [ ] Edge cases are numbered sequentially (`EC-1`, `EC-2`, …).
133
+
134
+ ## Final Instructions
135
+
136
+ 1. You **MUST** evaluate all 9 categories — do not skip any.
137
+ 2. You **MUST** produce at least one concrete edge case per applicable category.
138
+ 3. You **MUST** include the "Risk if Missed" field for every edge case.
139
+ 4. You **MUST NOT** reference internal implementation details — all edge cases describe observable behavior.
140
+ 5. You **MUST** flag ACs that appear to have no meaningful edge cases and explain why.
141
+ 6. You **SHOULD** prioritize edge cases by risk severity when the catalog is large.
@@ -0,0 +1,132 @@
1
+ # Activity: Generate Technical Specification
2
+
3
+ Transform refined requirements (PRD) into an actionable technical design by synthesizing them with the project's Technical Guidelines. Use this skill when a PRD is approved and ready for technical breakdown. Invoked by the `product-engineer` agent in Feature Mode.
4
+
5
+ ---
6
+
7
+ > **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).
8
+
9
+ ## Goal
10
+
11
+ Transform refined requirements (PRD) into an actionable technical design by synthesizing them with the project's Technical Guidelines. The specification bridges "what to build" (PRD) and "how to build it" (implementation).
12
+
13
+ ## Context
14
+
15
+ This activity assumes the following documents already exist:
16
+
17
+ - `product-context.md` — Product understanding
18
+ - `technical-guidelines.md` — Technical standards and patterns
19
+ - `prd-[feature-name].md` — Feature requirements (produced by the **refine** activity)
20
+
21
+ ## Document Changelog Convention
22
+
23
+ Every specification 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.
24
+
25
+ - The initial version **MUST** be `1.0`.
26
+ - Every subsequent update **MUST** increment the minor version (e.g., `1.1`, `1.2`, …).
27
+ - Major structural rewrites **SHOULD** increment the major version (e.g., `2.0`).
28
+ - The **Author** column **MUST** include the name of the person or agent responsible for the change (e.g., `@username`, `developer-agent`, `planner-agent`).
29
+
30
+ ```markdown
31
+ ## Changelog
32
+
33
+ | Version | Date | Summary | Author |
34
+ | ------- | ---------- | --------------- | ------------------ |
35
+ | 1.0 | YYYY-MM-DD | Initial version | @user / agent-name |
36
+ ```
37
+
38
+ ## Process
39
+
40
+ 1. **Receive References:** User points to the existing PRD and confirms Technical Guidelines are available.
41
+ 2. **Analyze Documents:** You **MUST** read and analyze both the PRD and Technical Guidelines to identify integration points.
42
+ 3. **Ask Specification Questions:** You **SHOULD** ask targeted questions about specific technical decisions and implementation approach.
43
+ 4. **Generate Specification:** You **MUST** create a comprehensive technical specification using the structure below.
44
+ 5. **Save Output.**
45
+
46
+ ## Clarifying Questions
47
+
48
+ Focus on technical decisions and implementation approach:
49
+
50
+ - **Affected Repositories:** "Which repositories are affected? What role does each play (backend, frontend, shared lib, infra)?"
51
+ - **System Design:** "Based on the feature requirements and our technical guidelines, what is the proposed system architecture for this feature?"
52
+ - **Data Model:** "What data entities and relationships are needed? How do they map to our database design?"
53
+ - **API Endpoints:** "What API endpoints will be needed? How do they fit our API design standards?"
54
+ - **Integration Points:** "Which existing systems or services will we integrate with? What integration method?"
55
+ - **Authentication/Authorization:** "How will this feature enforce authentication and authorization per our guidelines?"
56
+ - **Performance Approach:** "How will we ensure performance targets are met? Any caching or optimization strategies?"
57
+ - **Error Handling:** "How should errors be handled and reported to users?"
58
+ - **Validation Logic:** "What validation rules need to be enforced? Client-side and/or server-side?"
59
+ - **External Dependencies:** "Are there new third-party services or tools to integrate?"
60
+ - **Feature Flags:** "Will feature flags or toggles be used for rollout?"
61
+ - **Backward Compatibility:** "Are there backward compatibility concerns with existing APIs or data?"
62
+
63
+ ## Output Structure
64
+
65
+ The generated Specification document **MUST** include:
66
+
67
+ 0. **Changelog** — Version history table (see Document Changelog Convention above)
68
+ 1. **Executive Summary** — How the PRD will be technically implemented (2-3 sentences)
69
+ 2. **Reference Documents** — Links to the PRD and relevant Technical Guidelines sections
70
+ 3. **Affected Repositories** — Table of repositories impacted by this specification. For each repo, describe the role it plays (e.g., API backend, web frontend, shared library) and the scope of changes expected. Format: `| Repository | Role | Scope of Changes |`
71
+ 4. **System Architecture** — Data flow, component interactions, external integrations, how this fits the broader system
72
+ 5. **Data Model & Database Design** — Entity relationships, schema overview, naming conventions, migration strategy
73
+ 6. **API Design** — Endpoint specifications, request/response schemas, auth per endpoint, rate limiting, versioning
74
+ 7. **Authentication & Authorization Design** — Auth implementation, permission matrix, session/token management
75
+ 8. **Business Logic Implementation** — Key algorithms, business rule enforcement locations, validation rules, state machines
76
+ 9. **Integration Details** — Third-party integrations, methods, retry/failure handling, credentials
77
+ 10. **User Interface & Client Behavior** — Page/screen flow, UI components, client-side validation, responsive design
78
+ 11. **Performance & Scalability Approach** — Caching, query optimization, pagination, expected metrics
79
+ 12. **Security Implementation** — Encryption, input sanitization, OWASP considerations, PII handling, audit logging
80
+ 13. **Error Handling & Logging** — Error formats, logging strategy, recovery behavior, monitoring
81
+ 14. **Testing Strategy** — Unit/integration/E2E scope, mock strategy, coverage targets
82
+ 15. **Deployment & Rollout** — Feature flags, migration steps, backward compatibility, rollback plan
83
+ 16. **Dependencies & Risks** — Technology dependencies, known risks, mitigation strategies
84
+ 17. **Open Questions** — Remaining technical decisions
85
+
86
+ ## Diagram Guidelines
87
+
88
+ The specification **MUST** include embedded Mermaid diagrams to visually communicate architecture, data models, and key flows. Use fenced code blocks with the `mermaid` language tag.
89
+
90
+ Required and recommended diagrams:
91
+
92
+ | Diagram Type | Requirement | Target Section |
93
+ | -------------------------------- | ------------------------------------------------------------------ | ------------------------------------------- |
94
+ | **Component / C4-style diagram** | **MUST** include — shows services, repos, and their interactions | System Architecture |
95
+ | **Entity-Relationship diagram** | **MUST** include when new or modified data entities exist | Data Model & Database Design |
96
+ | **Sequence diagram** | **SHOULD** include for key API flows or multi-service interactions | API Design or Business Logic Implementation |
97
+ | **State diagram** | **SHOULD** include when entities have meaningful state transitions | Business Logic Implementation |
98
+ | **Deployment diagram** | **MAY** include for complex multi-environment rollouts | Deployment & Rollout |
99
+
100
+ Rules:
101
+
102
+ - Diagrams **MUST** be embedded inline in the relevant section, not collected at the end.
103
+ - Each diagram **MUST** have a brief introductory sentence explaining what it shows.
104
+ - Keep diagrams focused — one concern per diagram.
105
+ - Use consistent naming across diagrams and prose.
106
+ - ER diagrams **SHOULD** include cardinality and key attributes.
107
+ - Sequence diagrams **SHOULD** include error/alternate paths when relevant.
108
+
109
+ ## Key Synthesis Points
110
+
111
+ The specification **MUST** clearly show how:
112
+
113
+ - Each PRD requirement is addressed technically
114
+ - Technical Guidelines are applied to this specific feature
115
+ - The system integrates with existing architecture
116
+ - Technology stack choices support the requirements
117
+
118
+ ## Output
119
+
120
+ - **Format:** Markdown (`.md`)
121
+ - **Location:** `/workstream/`
122
+ - **Filename:** `specification-[prd-name].md`
123
+
124
+ ## Final Instructions
125
+
126
+ 1. You **MUST NOT** start implementing.
127
+ 2. You **MUST** read the referenced PRD and Technical Guidelines documents.
128
+ 3. You **SHOULD** ask clarifying questions about the technical implementation approach.
129
+ 4. You **MUST** ensure the specification clearly maps PRD requirements to technical solutions.
130
+ 5. You **MUST** present the specification for user review.
131
+ 6. You **MUST** save the finalized version.
132
+ 7. When updating an existing specification, 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,238 @@
1
+ # Activity: Generate User Stories
2
+
3
+ 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.
4
+
5
+ ---
6
+
7
+ > **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).
8
+
9
+ ## Goal
10
+
11
+ 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.
12
+
13
+ This activity combines story generation and coverage validation into a single pass.
14
+
15
+ ## Context
16
+
17
+ This activity assumes the following documents already exist:
18
+
19
+ - `prd-[feature-name].md` — Feature requirements
20
+ - `specification-[prd-name].md` — Technical specification
21
+
22
+ ## Document Changelog Convention
23
+
24
+ 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.
25
+
26
+ - The initial version **MUST** be `1.0`.
27
+ - Every subsequent update **MUST** increment the minor version (e.g., `1.1`, `1.2`, …).
28
+ - Major structural rewrites **SHOULD** increment the major version (e.g., `2.0`).
29
+ - The **Author** column **MUST** include the name of the person or agent responsible for the change (e.g., `@username`, `developer-agent`, `planner-agent`).
30
+
31
+ ```markdown
32
+ ## Changelog
33
+
34
+ | Version | Date | Summary | Author |
35
+ | ------- | ---------- | --------------- | ------------------ |
36
+ | 1.0 | YYYY-MM-DD | Initial version | @user / agent-name |
37
+ ```
38
+
39
+ ## Process
40
+
41
+ 1. **Receive Specification:** User provides reference to the Technical Specification document.
42
+ 2. **Analyze Specification:** You **MUST** read and analyze the specification to identify story boundaries.
43
+ 3. **Ask Story-Specific Questions:** You **SHOULD** ask about prioritization, sequencing, and story preferences.
44
+ 4. **Generate User Stories:** You **MUST** create detailed stories using the structure below.
45
+ 5. **Validate Coverage:** You **MUST** run a coverage check (see Coverage Validation section below) before presenting stories.
46
+ 6. **Save Output.**
47
+
48
+ ## Clarifying Questions
49
+
50
+ - **Story Priority & Sequencing:** "In what order should these stories be prioritized? Are there dependencies?"
51
+ - **MVP vs. Future:** "Which stories are essential for MVP? Which are nice-to-have?"
52
+ - **Story Scope:** "Should we break this into more granular stories, or combine some? (Target: 1-3 days per story)"
53
+ - **Definition of Done:** "What definition of done applies?"
54
+ - **User Acceptance:** "Who will validate that stories meet acceptance criteria?"
55
+
56
+ ## User Story Structure
57
+
58
+ Each User Story **MUST** include:
59
+
60
+ ```markdown
61
+ ### Story [ID]: [Title]
62
+
63
+ **Priority:** [Critical/High/Medium/Low]
64
+ **Estimated Size:** [XS/S/M/L]
65
+ **Dependencies:** [List any dependent stories or systems]
66
+
67
+ #### User Story
68
+
69
+ As a [user role],
70
+ I want [goal/capability],
71
+ So that [business value/benefit].
72
+
73
+ #### Context
74
+
75
+ [Why this story matters, how it fits the larger feature.]
76
+
77
+ #### Acceptance Criteria
78
+
79
+ - [ ] [Criterion 1: Specific, testable condition]
80
+ - [ ] [Criterion 2]
81
+ - [ ] [Criterion 3]
82
+
83
+ #### Business Rules
84
+
85
+ - [Business rule 1]
86
+ - [Business rule 2]
87
+
88
+ #### Technical Notes
89
+
90
+ - [Key technical decisions or patterns to follow]
91
+ - [Reference to Technical Guidelines sections]
92
+ - [Integration points]
93
+
94
+ #### Testing Requirements
95
+
96
+ - **Unit Tests:** [Specific scenarios]
97
+ - **Integration Tests:** [Cross-component scenarios]
98
+ - **Manual/UI Testing:** [User-visible checks and access path]
99
+ - **Edge-Case Matrix:** [Boundary, error, empty-state, concurrency/idempotency cases]
100
+ - **Acceptance-Criteria Mapping:** [AC -> test case IDs or commands]
101
+ - **Execution Commands:** [Canonical scripts, prefer `pnpm run <script>`]
102
+
103
+ #### Migration Requirements (When Data Model Changes)
104
+
105
+ - Migration artifact: [required by default; add explicit opt-out rationale if omitted]
106
+ - Rollback/impact notes: [required]
107
+ - Apply step: [requires explicit user confirmation before running]
108
+ - Verification after apply: [required]
109
+
110
+ #### Implementation Steps
111
+
112
+ 1. [Step 1]
113
+ 2. [Step 2]
114
+ 3. [Step 3]
115
+
116
+ #### Files to Create/Modify
117
+
118
+ - `path/to/file1.ts` - Brief description
119
+ - `path/to/file1.test.ts` - Unit tests
120
+
121
+ #### Definition of Done Checklist
122
+
123
+ - [ ] Code implemented per technical guidelines
124
+ - [ ] Unit/integration/manual/edge-case tests written and passing
125
+ - [ ] Quality gates passing (`lint`, `format:check`, `typecheck`, `test`, `audit`)
126
+ - [ ] Code reviewed and approved
127
+ - [ ] Acceptance criteria verified
128
+ - [ ] Acceptance criteria explicitly mapped to test evidence
129
+ - [ ] Migration lifecycle complete (or documented opt-out) when schema/data-model changes exist
130
+ - [ ] Pull Request created and merged
131
+ ```
132
+
133
+ ## Package Manager and Script Conventions
134
+
135
+ - For JS/TS projects, you **MUST** prefer `pnpm` over `npm`.
136
+ - You **MAY** use `npm` only when `pnpm` is unavailable or the project is explicitly npm-locked.
137
+ - When stories reference commands, you **MUST** prefer canonical script names:
138
+ - `lint`, `lint:fix`
139
+ - `format`, `format:check`
140
+ - `typecheck`
141
+ - `test`, `test:unit`, `test:integration`, `test:e2e`
142
+ - `audit`
143
+ - `validate` (aggregate quality gate)
144
+
145
+ ## Story Quality Criteria
146
+
147
+ **Good User Stories:**
148
+
149
+ - Provide clear business value that can be demonstrated
150
+ - Are independent and avoid blocking other stories
151
+ - **SHOULD** be completable in 1-3 days by a capable developer
152
+ - **MUST** fit into a single Pull Request
153
+ - **MUST** have clear acceptance criteria
154
+ - **MUST** include sufficient technical guidance for implementation
155
+
156
+ **Poor User Stories:**
157
+
158
+ - Too large or vague (epic-sized)
159
+ - Have circular dependencies
160
+ - Mix multiple concerns or features
161
+ - Lack clear acceptance criteria
162
+
163
+ ## Story Sequencing
164
+
165
+ You **SHOULD** consider these factors when sequencing:
166
+
167
+ 1. **Dependencies:** Stories with fewer dependencies first
168
+ 2. **Value:** High-value core stories early
169
+ 3. **Risk:** Risky or uncertain stories prioritized to de-risk
170
+ 4. **Infrastructure:** Setup stories first
171
+ 5. **Team Skills:** Consider capabilities and learning curve
172
+
173
+ ---
174
+
175
+ ## Coverage Validation (Built-in Quality Gate)
176
+
177
+ Before finalizing stories, you **MUST** validate coverage against the PRD.
178
+
179
+ ### Validation Steps
180
+
181
+ 1. **Extract ALL requirements** from the PRD: user stories, functional requirements, non-functional requirements, business rules, acceptance criteria, data requirements.
182
+ 2. **Map each requirement** to the User Story(ies) that address it.
183
+ 3. **Identify gaps** — requirements NOT covered by any story.
184
+ 4. **Verify non-goals** — confirm out-of-scope items are NOT covered (scope is respected).
185
+
186
+ ### Coverage Report
187
+
188
+ You **MUST** include a summary coverage report at the end of the stories document:
189
+
190
+ ```markdown
191
+ ## Coverage Validation
192
+
193
+ ### Summary
194
+
195
+ - **Total PRD Requirements:** [#]
196
+ - **Total User Stories:** [#]
197
+ - **Coverage:** [X%]
198
+ - **Status:** [Complete / Gaps Identified]
199
+
200
+ ### Requirement Mapping
201
+
202
+ | PRD Requirement | Story ID(s) | Status |
203
+ | --------------- | ------------ | ---------- |
204
+ | [Req 1] | S-001 | ✅ Covered |
205
+ | [Req 2] | S-002, S-003 | ✅ Covered |
206
+ | [Uncovered Req] | — | ❌ GAP |
207
+
208
+ ### Gaps (if any)
209
+
210
+ - **Gap [#]:** [Requirement not covered] — **Recommendation:** [Create new story / Modify existing story]
211
+
212
+ ### Non-Goals Validation
213
+
214
+ - [ ] [Out-of-scope item 1] — Confirmed NOT in any story
215
+ - [ ] [Out-of-scope item 2] — Confirmed NOT in any story
216
+ ```
217
+
218
+ If gaps are found, you **MUST** propose additional stories or modifications to close them before presenting for review.
219
+
220
+ ## Output
221
+
222
+ - **Format:** Markdown (`.md`)
223
+ - **Location:** `/workstream/`
224
+ - **Filename:** `user-stories-[prd-name].md`
225
+
226
+ ## Final Instructions
227
+
228
+ 1. You **MUST NOT** start implementing.
229
+ 2. You **MUST** read the referenced Technical Specification and PRD.
230
+ 3. You **MUST** identify logical story boundaries that provide independent value.
231
+ 4. You **SHOULD** ask clarifying questions about prioritization and sequencing.
232
+ 5. You **MUST** generate detailed User Stories with all required sections.
233
+ 6. You **MUST** ensure stories are appropriately sized (1-3 days of work).
234
+ 7. You **MUST** run the coverage validation and include the report.
235
+ 8. You **MUST** close any gaps before presenting stories for review.
236
+ 9. You **MUST** present stories for user review and save the finalized version.
237
+ 10. You **MUST** provide a summary of total stories and a high-level execution plan.
238
+ 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,157 @@
1
+ # Activity: Initialize Project Foundation
2
+
3
+ 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.
4
+
5
+ ---
6
+
7
+ > **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).
8
+
9
+ ## Goal
10
+
11
+ 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.
12
+
13
+ Run this activity **once per project** (or when a major strategic or technical pivot occurs).
14
+
15
+ ## Document Changelog Convention
16
+
17
+ 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.
18
+
19
+ - The initial version **MUST** be `1.0`.
20
+ - Every subsequent update **MUST** increment the minor version (e.g., `1.1`, `1.2`, …).
21
+ - Major structural rewrites **SHOULD** increment the major version (e.g., `2.0`).
22
+ - The **Author** column **MUST** include the name of the person or agent responsible for the change (e.g., `@username`, `developer-agent`, `planner-agent`).
23
+
24
+ ```markdown
25
+ ## Changelog
26
+
27
+ | Version | Date | Summary | Author |
28
+ | ------- | ---------- | --------------- | ------------------ |
29
+ | 1.0 | YYYY-MM-DD | Initial version | @user / agent-name |
30
+ ```
31
+
32
+ ## Process
33
+
34
+ 1. **Receive Initial Brief:** The user describes the product, project, or technology stack.
35
+ 2. **Ask Clarifying Questions:** Gather information for both product context and technical guidelines in a single interview. Group questions by domain.
36
+ 3. **Generate Product Context Document:** Create `product-context.md` using the structure below.
37
+ 4. **Generate Technical Guidelines Document:** Create `technical-guidelines.md` using the structure below.
38
+ 5. **Save Output:** Save both documents in `/docs/` and present them for user review.
39
+
40
+ ---
41
+
42
+ ## Part 1 — Product Context
43
+
44
+ ### Clarifying Questions
45
+
46
+ Adapt questions based on context provided:
47
+
48
+ - **Product Definition:** "What is this product/project, and what does it do?"
49
+ - **Problem Statement:** "What core problem does this product solve?"
50
+ - **Target Users/Market:** "Who are the primary users or target audience?"
51
+ - **Strategic Goals:** "What are the 3-5 key strategic objectives?"
52
+ - **Success Metrics:** "How do we measure success?"
53
+ - **Competitive Landscape:** "Are there competing solutions? What differentiates this product?"
54
+ - **Current State:** "Is this a new product, MVP, or mature? What stage?"
55
+ - **Vision/Roadmap:** "What is the long-term vision? Are there planned phases?"
56
+ - **Key Constraints:** "Budget, timeline, technology, or regulatory constraints?"
57
+ - **Stakeholders:** "Who are the key decision-makers?"
58
+
59
+ ### Output Structure: `product-context.md`
60
+
61
+ 0. **Changelog** — Version history table (see Document Changelog Convention above)
62
+ 1. **Executive Summary** — 2-3 sentence overview
63
+ 2. **Problem Statement** — What problem(s) does this product solve?
64
+ 3. **Target Users/Market** — Primary and secondary users, market segments
65
+ 4. **Strategic Goals** — 3-5 key objectives
66
+ 5. **Current State** — New, MVP, or mature? Stage description.
67
+ 6. **Vision & Roadmap** — Long-term vision and planned phases
68
+ 7. **Success Metrics** — How success will be measured
69
+ 8. **Competitive Landscape** — Competitors and differentiation
70
+ 9. **Key Constraints** — Budget, timeline, technology, regulatory
71
+ 10. **Key Stakeholders** — Decision-makers and their interests
72
+ 11. **Assumptions** — Major assumptions underlying the strategy
73
+ 12. **Open Questions** — Remaining areas needing clarification
74
+
75
+ ---
76
+
77
+ ## Part 2 — Technical Guidelines
78
+
79
+ ### Clarifying Questions
80
+
81
+ - **Technology Stack:** "What languages, frameworks, and libraries? Any constraints?"
82
+ - **Architecture:** "Overall pattern (monolith, microservices, serverless, etc.)?"
83
+ - **Data & Database:** "What databases? Schema or data model guidelines?"
84
+ - **API Design:** "APIs exposed? Style (REST, GraphQL, gRPC)? Naming conventions?"
85
+ - **Authentication & Authorization:** "How are users authenticated? Authorization model?"
86
+ - **Security Requirements:** "Key security requirements (encryption, compliance)?"
87
+ - **Performance & Scalability:** "Performance targets? Scalability requirements?"
88
+ - **Testing Strategy:** "Testing approach and coverage expectations?"
89
+ - **Code Organization:** "Folder structure conventions? Module boundaries?"
90
+ - **External Integrations:** "Required third-party integrations?"
91
+ - **Deployment & DevOps:** "Deployment targets? CI/CD practices?"
92
+ - **Monitoring & Logging:** "Observability tools and standards?"
93
+ - **Design Patterns:** "Preferred patterns (MVC, Repository, etc.)?"
94
+ - **Code Quality Standards:** "Linting, formatting, review standards?"
95
+ - **Package Manager Standard:** "Can we standardize on `pnpm` for JS/TS projects?"
96
+ - **Script Naming Standard:** "Should canonical `package.json` scripts (`lint`, `format:check`, `typecheck`, `test`, `audit`, `validate`) be enforced?"
97
+
98
+ ### Output Structure: `technical-guidelines.md`
99
+
100
+ 0. **Changelog** — Version history table (see Document Changelog Convention above)
101
+ 1. **Overview** — Technical vision and guiding principles
102
+ 2. **Technology Stack** — Backend/frontend languages, frameworks, databases, key dependencies
103
+ 3. **Architecture Patterns** — System architecture, key decisions and rationale, component organization
104
+ 4. **API Design Standards** — Style, naming, request/response formats, error handling
105
+ 5. **Authentication & Authorization** — Mechanism, model, permission levels, session management
106
+ 6. **Security Requirements** — Encryption, OWASP compliance, API key management, PII handling
107
+ 7. **Data & Database Guidelines** — Schema patterns, naming conventions, query optimization, backup
108
+ 8. **Integration Methods** — External integrations, patterns, retry/failure handling
109
+ 9. **Code Organization & Structure** — Folder/file conventions, module boundaries, naming
110
+ 10. **Design Patterns & Principles** — Preferred patterns, SOLID, DRY/KISS/YAGNI
111
+ 11. **Testing Strategy** — Frameworks, testing pyramid, coverage, mock strategies
112
+ 12. **Code Quality & Standards** — Linting, static analysis, reviews, documentation
113
+ 13. **Deployment & DevOps** — Environments, CI/CD, infrastructure-as-code, containers
114
+ 14. **Monitoring, Logging & Observability** — Levels, frameworks, alerting, error tracking
115
+ 15. **Performance & Scalability** — Response targets, throughput, caching, optimization
116
+ 16. **Dependency Management** — Management approach, version pinning, vulnerability scanning
117
+ 17. **Development Workflow** — Branching strategy, commit conventions, PR process
118
+ 18. **Known Constraints & Trade-offs** — Limitations and rationale
119
+
120
+ ### JS/TS Package Manager and Script Defaults
121
+
122
+ When the project includes JavaScript/TypeScript:
123
+
124
+ - `pnpm` **MUST** be the default package manager.
125
+ - `npm` **MAY** be used only when `pnpm` is unavailable or explicitly disallowed by project constraints.
126
+ - `package.json` scripts **SHOULD** include canonical names:
127
+ - `lint`, `lint:fix`
128
+ - `format`, `format:check`
129
+ - `typecheck`
130
+ - `test`, `test:unit`, `test:integration`, `test:e2e`
131
+ - `audit`
132
+ - `validate` (aggregate quality gate script)
133
+
134
+ ---
135
+
136
+ ## Output
137
+
138
+ - **Format:** Markdown (`.md`)
139
+ - **Location:** `/docs/`
140
+ - **Filenames:** `product-context.md`, `technical-guidelines.md`
141
+
142
+ ## AGENTS.md Sizing
143
+
144
+ When generating or updating `AGENTS.md` during project initialization, you **MUST** follow the sizing guidelines in `docs/agents-md-guidelines.md`:
145
+
146
+ - Target ~1,000 words (~1,350 tokens)
147
+ - Include only operational per-turn guidance (agent roster, skill roster, instructions table, general rules)
148
+ - Move reference content (workflow chains, prompt tables, verbose explanations) to `docs/`
149
+
150
+ ## Final Instructions
151
+
152
+ 1. You **MUST NOT** start implementing anything.
153
+ 2. You **MUST** ask clarifying questions to fill gaps — cover both product and technical domains.
154
+ 3. You **SHOULD** use answers to create both documents in a single pass.
155
+ 4. You **MUST** save both files and present them for user review.
156
+ 5. You **SHOULD** iterate based on user feedback before finalizing.
157
+ 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.