@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.
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 +28 -2
  102. package/CLAUDE.md +94 -0
  103. package/README.md +6 -6
  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 +19 -8
  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 +15 -2
  143. package/skills/.gitkeep +0 -0
@@ -0,0 +1,111 @@
1
+ # Activity: Publish to GitHub
2
+
3
+ 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.
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
+ 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.
12
+
13
+ ## Context
14
+
15
+ This activity assumes the following document exists:
16
+
17
+ - `user-stories-[prd-name].md` — The comprehensive list of user stories (produced by the **generate-stories** activity)
18
+
19
+ ## Process
20
+
21
+ 1. **Receive Input:** User provides the reference to the user stories file and the GitHub repository target.
22
+ 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.
23
+ 3. **Map Stories to Issues:** You **MUST** create one GitHub Issue per user story.
24
+ 4. **Publish to GitHub:** You **MUST** delegate issue creation and metadata application to `github-ops` whenever possible.
25
+ 5. **Save Output.**
26
+
27
+ Execution method rules:
28
+
29
+ - GitHub MCP **SHOULD** be used when available.
30
+ - If MCP is unavailable, `gh` CLI **MAY** be used.
31
+ - The selected method (`github-mcp` or `gh-cli`) **MUST** be recorded in the publication report.
32
+
33
+ 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.
34
+
35
+ Attribution rules:
36
+
37
+ - 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.
38
+
39
+ ## Clarifying Questions
40
+
41
+ - "Which GitHub repository should I publish to? (`owner/repo`)"
42
+ - "Do you want labels, milestones, or assignees added?"
43
+ - "Should I use a specific issue template or format?"
44
+ - "Do you want a parent epic issue or project board association?"
45
+ - "Should I skip stories below a certain priority or size?"
46
+
47
+ ## Issue Formatting Rules
48
+
49
+ Each GitHub Issue **MUST** be created using:
50
+
51
+ - **Title:** `[PRD-<prd-number or name>] Story [ID]: [Title]`
52
+ - **Body:**
53
+ - User Story (role, goal, benefit)
54
+ - Context
55
+ - Acceptance Criteria (checklist)
56
+ - Acceptance-Criteria-to-Test Mapping
57
+ - Business Rules
58
+ - Technical Notes
59
+ - Testing Requirements
60
+ - Quality Gate Commands (`lint`, `format:check`, `typecheck`, `test`, `audit`, optionally `validate`)
61
+ - Implementation Steps
62
+ - Migration Plan (when schema/data-model changes apply): artifact, rollback notes, confirmation gate before apply, verification step
63
+ - Files to Create/Modify
64
+ - Definition of Done Checklist
65
+ - Open Questions
66
+
67
+ For JS/TS projects, command examples in issues **MUST** prefer `pnpm` and canonical scripts (`pnpm run <script>`).
68
+
69
+ All issue formatting and metadata **MUST** conform to `github-ops` conventions.
70
+
71
+ ## Output Structure
72
+
73
+ You **MUST** create a publication report:
74
+
75
+ ```markdown
76
+ # GitHub Publication Report: [PRD Name]
77
+
78
+ ## Target Repository
79
+
80
+ - Repo: owner/repo
81
+ - Date: YYYY-MM-DD
82
+
83
+ ## Created Issues
84
+
85
+ | Story ID | Story Title | Issue URL | Labels | Milestone | Assignee |
86
+ | -------- | ----------- | ---------------------------------------- | ------------- | --------- | -------- |
87
+ | S-001 | [Title] | https://github.com/owner/repo/issues/123 | backend, auth | v1 | @user |
88
+ | ... | ... | ... | ... | ... | ... |
89
+
90
+ ## Notes
91
+
92
+ - Any skipped stories and why
93
+ - Any template or permission limitations
94
+ - Any manual follow-up needed
95
+ - Execution method used: `github-mcp` or `gh-cli`
96
+ - Assisted-by value used for PR creation/issue closure (if applicable)
97
+ ```
98
+
99
+ ## Output
100
+
101
+ - **Format:** Markdown (`.md`)
102
+ - **Location:** `/workstream/`
103
+ - **Filename:** `github-publication-[prd-name].md`
104
+
105
+ ## Final Instructions
106
+
107
+ 1. You **MUST** read the user stories file.
108
+ 2. You **MUST** ask clarifying questions and confirm the target repo.
109
+ 3. You **MUST** publish each story as a GitHub Issue by delegating to `github-ops` whenever possible.
110
+ 4. You **MUST** save the publication report with issue links.
111
+ 5. You **MUST** inform the user that GitHub is now the source of truth for execution tracking.
@@ -0,0 +1,176 @@
1
+ # Activity: Randomized Test Tactics
2
+
3
+ Generate randomized, fuzz, and property-inspired test strategies with reproducibility controls. Produces test tactics that detect behavior drift and hidden defects through non-deterministic inputs while maintaining deterministic replay. 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
+ Design randomized and property-based testing tactics that complement structured E2E and edge-case tests. Every tactic **MUST** include seed capture and deterministic replay instructions so that failures can be reproduced and triaged.
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 edge cases have been drafted.
19
+ - The output feeds into the randomized-tactics section of the test plan assembled by `verifier`.
20
+
21
+ ## Tactic Types
22
+
23
+ ### 1. Fuzz Testing
24
+
25
+ Generate malformed, unexpected, or random inputs to discover crashes, unhandled exceptions, or security vulnerabilities.
26
+
27
+ **When to apply:** Any endpoint or function that accepts user input — forms, API bodies, file uploads, query parameters.
28
+
29
+ **Approach:**
30
+
31
+ 1. Identify input surfaces from the spec (fields, parameters, headers).
32
+ 2. Define a fuzz corpus: valid base inputs + mutations (truncation, injection payloads, binary data, oversized values).
33
+ 3. Define the oracle: what constitutes a failure (5xx status, stack trace in response, timeout, data corruption).
34
+ 4. Set iteration count and seed.
35
+
36
+ ### 2. Property-Based Testing
37
+
38
+ Define invariants (properties) that must hold for all valid inputs, then generate many random valid inputs to verify.
39
+
40
+ **When to apply:** Business rules that express universal constraints (e.g., "total is always ≥ 0", "output list is always sorted", "idempotent endpoint returns same result on retry").
41
+
42
+ **Approach:**
43
+
44
+ 1. Extract properties from ACs and business rules.
45
+ 2. Define input generators that produce valid inputs within the domain.
46
+ 3. Run N iterations with random seeds.
47
+ 4. On failure, shrink the input to the minimal failing case.
48
+
49
+ ### 3. Stateful Random Walks
50
+
51
+ Execute random sequences of valid API calls to discover state-dependent bugs.
52
+
53
+ **When to apply:** Systems with stateful resources (CRUD workflows, multi-step processes, session-based interactions).
54
+
55
+ **Approach:**
56
+
57
+ 1. Model valid actions and their preconditions as a state machine.
58
+ 2. Generate random action sequences that respect preconditions.
59
+ 3. After each sequence, verify invariants hold (e.g., resource counts match, no orphaned records).
60
+ 4. Capture the full action sequence and seed for replay.
61
+
62
+ ## Reproducibility Requirements
63
+
64
+ Every randomized tactic **MUST** satisfy these controls:
65
+
66
+ | Requirement | Description |
67
+ | ------------------------ | ------------------------------------------------------------------------------------------------- |
68
+ | **Seed capture** | Record the PRNG seed used for each run. |
69
+ | **Seed replay** | Provide a command or instruction to re-run the exact same sequence using the captured seed. |
70
+ | **Iteration count** | Document the number of iterations per tactic. |
71
+ | **Deterministic oracle** | The pass/fail oracle **MUST** be deterministic for a given input — no "sometimes fails" verdicts. |
72
+ | **Environment snapshot** | Record runtime environment details (OS, runtime version, relevant config) alongside results. |
73
+
74
+ ### Seed Policy
75
+
76
+ ```
77
+ Seed format: <tactic-type>-<AC-id>-<unix-timestamp>-<random-4-hex>
78
+ Example: fuzz-AC3-1719849600-a3f1
79
+
80
+ Replay command template:
81
+ <test-runner> --seed=<captured-seed> --tactic=<tactic-id> --iterations=1
82
+ ```
83
+
84
+ Seeds **MUST** be included in the test plan and in any failure reports.
85
+
86
+ ## Tactic Template
87
+
88
+ ```markdown
89
+ ### RT-{id}: {Tactic Title}
90
+
91
+ | Field | Value |
92
+ | ---------------------- | ---------------------------------------------------------------------- |
93
+ | **AC(s)** | AC-{n} |
94
+ | **Tactic type** | fuzz / property-based / stateful-random-walk |
95
+ | **Input surface** | {What is being fuzzed or randomized} |
96
+ | **Property / Oracle** | {Invariant that must hold, or failure condition} |
97
+ | **Iterations** | {Number of random iterations} |
98
+ | **Seed** | {To be captured at execution time} |
99
+ | **Replay instruction** | {Command to reproduce with captured seed} |
100
+ | **Shrink strategy** | {How to minimize failing input — binary search, delta debugging, etc.} |
101
+ ```
102
+
103
+ ## Example
104
+
105
+ Given AC-2: "API returns paginated results with at most 50 items per page."
106
+
107
+ ### RT-1: Fuzz pagination parameters
108
+
109
+ | Field | Value |
110
+ | ---------------------- | -------------------------------------------------------------------------- |
111
+ | **AC(s)** | AC-2 |
112
+ | **Tactic type** | fuzz |
113
+ | **Input surface** | Query parameters `page` and `pageSize` on `GET /api/items` |
114
+ | **Property / Oracle** | Response always returns ≤50 items. Status is never 5xx. Response time <2s. |
115
+ | **Iterations** | 500 |
116
+ | **Seed** | `fuzz-AC2-{timestamp}-{hex}` |
117
+ | **Replay instruction** | `test-runner --seed=<seed> --tactic=RT-1 --iterations=1` |
118
+ | **Shrink strategy** | Binary search on `pageSize` value to find minimum trigger. |
119
+
120
+ **Mutation corpus for `page`/`pageSize`:**
121
+
122
+ - Valid range: `page=1..1000`, `pageSize=1..50`
123
+ - Mutations: `page=-1`, `page=0`, `page=999999`, `pageSize=0`, `pageSize=51`, `pageSize=-1`, `pageSize=NaN`, `pageSize=""`, `pageSize=1.5`, omit parameter entirely
124
+
125
+ ### RT-2: Property — response length never exceeds pageSize
126
+
127
+ | Field | Value |
128
+ | ---------------------- | --------------------------------------------------------------- |
129
+ | **AC(s)** | AC-2 |
130
+ | **Tactic type** | property-based |
131
+ | **Input surface** | Random valid `pageSize` values (1–50) with random `page` values |
132
+ | **Property / Oracle** | `len(response.items) <= pageSize` for all inputs. |
133
+ | **Iterations** | 200 |
134
+ | **Seed** | `prop-AC2-{timestamp}-{hex}` |
135
+ | **Replay instruction** | `test-runner --seed=<seed> --tactic=RT-2 --iterations=1` |
136
+ | **Shrink strategy** | Reduce `pageSize` to find smallest value where property fails. |
137
+
138
+ ## Failure Triage Workflow
139
+
140
+ When a randomized test fails, the `verifier` agent follows this workflow:
141
+
142
+ 1. **Capture** — Record seed, full input, observed output, and expected oracle result.
143
+ 2. **Replay** — Re-run with captured seed to confirm deterministic reproduction.
144
+ 3. **Minimize** — Apply shrink strategy to find the smallest failing input.
145
+ 4. **Classify:**
146
+ - **Spec gap:** Behavior is undefined → escalate to `product-engineer`.
147
+ - **Implementation defect:** Behavior contradicts an AC → file for `developer`.
148
+ - **Flaky/environmental:** Cannot reproduce → log with environment details, mark `inconclusive`.
149
+ 5. **Report** — Add triaged failure to validation report with classification and minimized input.
150
+ 6. **Retry limit** — At most 3 reproduction attempts for non-reproducing failures.
151
+
152
+ ## Execution Checklist
153
+
154
+ Use this checklist to verify completeness before returning results:
155
+
156
+ - [ ] At least one randomized tactic defined per input surface identified in the spec.
157
+ - [ ] Every tactic has a seed policy and replay instruction.
158
+ - [ ] Every tactic maps to ≥1 AC.
159
+ - [ ] Iteration counts are documented and justified.
160
+ - [ ] Shrink strategy defined for every tactic.
161
+ - [ ] Failure triage workflow referenced for handling failures.
162
+ - [ ] No tactic relies on internal implementation details.
163
+
164
+ ## Output
165
+
166
+ This skill returns a list of randomized tactics in the template format above. The calling agent (`verifier`) assembles them into the randomized-tactics section of the test plan.
167
+
168
+ ## Final Instructions
169
+
170
+ 1. You **MUST** produce at least one randomized tactic per significant input surface.
171
+ 2. You **MUST** include seed capture and replay instructions for every tactic.
172
+ 3. You **MUST** define a shrink strategy for every tactic.
173
+ 4. You **MUST** specify the oracle/property that determines pass or fail.
174
+ 5. You **MUST NOT** reference internal implementation details — all assertions are based on observable behavior.
175
+ 6. You **MUST** reference the failure triage workflow for handling randomized test failures.
176
+ 7. You **SHOULD** prefer property-based tactics for business rules expressing universal constraints.
@@ -0,0 +1,231 @@
1
+ # Activity: Refine Scope
2
+
3
+ Clarify the scope, acceptance criteria, and constraints of a feature or issue before implementation begins. Produces a lightweight refinement for a GitHub Issue, or a full PRD for a new feature description. Invoked by the `product-engineer` agent in Issue Mode or 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
+ Clarify the scope, acceptance criteria, and constraints of a feature or issue before implementation begins. This activity adapts to the input — it produces a **lightweight refinement** for a single GitHub Issue, or a **full PRD** for a new feature description.
12
+
13
+ ## Context
14
+
15
+ This step assumes foundation documents exist:
16
+
17
+ - `product-context.md` — Understanding the overall product
18
+ - `technical-guidelines.md` — Understanding technical constraints and patterns
19
+
20
+ If the user provides a **GitHub Issue number**, you **MUST** produce a lightweight refinement.
21
+ If the user provides a **feature description**, you **MUST** produce a full PRD.
22
+
23
+ ---
24
+
25
+ ## Document Changelog Convention
26
+
27
+ 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.
28
+
29
+ - The initial version **MUST** be `1.0`.
30
+ - Every subsequent update **MUST** increment the minor version (e.g., `1.1`, `1.2`, …).
31
+ - Major structural rewrites **SHOULD** increment the major version (e.g., `2.0`).
32
+ - The **Author** column **MUST** include the name of the person or agent responsible for the change (e.g., `@username`, `developer-agent`, `planner-agent`).
33
+
34
+ ```markdown
35
+ ## Changelog
36
+
37
+ | Version | Date | Summary | Author |
38
+ | ------- | ---------- | --------------- | ------------------ |
39
+ | 1.0 | YYYY-MM-DD | Initial version | @user / agent-name |
40
+ ```
41
+
42
+ ---
43
+
44
+ ## Mode Detection
45
+
46
+ | Input | Mode | Output |
47
+ | --------------------------- | -------------------- | ---------------------------------- |
48
+ | GitHub Issue number + repo | **Issue Refinement** | Lightweight refinement doc |
49
+ | Feature description or idea | **PRD Creation** | Full product requirements document |
50
+
51
+ ---
52
+
53
+ ## Mode A — Issue Refinement
54
+
55
+ ### Process
56
+
57
+ 1. **Receive Issue Reference:** User provides GitHub Issue number and repo.
58
+ 2. **Read Issue:** Delegate to `github-ops` to fetch issue body, comments, labels, and status whenever possible.
59
+ 3. **Ask Clarifying Questions:** Focus on missing scope, acceptance criteria, and constraints.
60
+ 4. **Refine Scope:** Summarize scope, non-goals, risks, and dependencies.
61
+ 5. **Update GitHub Issue:** Delegate to `github-ops` to add or update a "Refined Scope" section in the issue body.
62
+ 6. **Save Output.**
63
+
64
+ If `github-ops` delegation is unavailable in the current runtime, you **MUST** apply `github-ops` conventions directly and explicitly note that fallback in your status output.
65
+
66
+ ### Clarifying Questions (ask only what is missing)
67
+
68
+ - "What is the exact user-visible behavior change?"
69
+ - "What is explicitly out of scope?"
70
+ - "What are the acceptance criteria? (3-7 testable statements)"
71
+ - "Are there performance, security, or compatibility constraints?"
72
+ - "What is the definition of done?"
73
+ - "Are there related issues or dependencies?"
74
+
75
+ ### Acceptance Criteria Quality Standard
76
+
77
+ Acceptance criteria in refinement outputs **MUST** be:
78
+
79
+ - specific and observable (user-visible behavior or measurable system behavior)
80
+ - testable with clear pass/fail outcomes
81
+ - mapped to at least one validation method (automated test or manual/UI check)
82
+ - inclusive of relevant edge-case behavior (error, boundary, and empty-state handling)
83
+
84
+ For each criterion, you **SHOULD** use a concise "Given / When / Then" style when it improves clarity.
85
+
86
+ ### Output Structure
87
+
88
+ ```markdown
89
+ # Issue Refinement: [Issue Number] - [Issue Title]
90
+
91
+ ## Changelog
92
+
93
+ | Version | Date | Summary | Author |
94
+ | ------- | ---------- | ------------------ | ------------------ |
95
+ | 1.0 | YYYY-MM-DD | Initial refinement | @user / agent-name |
96
+
97
+ ## Summary
98
+
99
+ - Goal:
100
+ - Primary user impact:
101
+ - Non-goals:
102
+
103
+ ## Acceptance Criteria
104
+
105
+ - [ ] [Criterion 1]
106
+ - [ ] [Criterion 2]
107
+ - [ ] [Criterion 3]
108
+
109
+ ## Constraints
110
+
111
+ - [Performance/compatibility/security constraints]
112
+
113
+ ## Risks and Edge Cases
114
+
115
+ - [Risk 1]
116
+ - [Edge case 1]
117
+
118
+ ## Dependencies
119
+
120
+ - [Related issues, services, or teams]
121
+
122
+ ## Testing Notes
123
+
124
+ - Unit tests:
125
+ - Integration tests:
126
+ - Manual checks:
127
+ - Edge-case checks:
128
+ - Acceptance-criteria-to-test mapping:
129
+
130
+ ## Open Questions
131
+
132
+ - [Remaining unknowns]
133
+ ```
134
+
135
+ ### Output
136
+
137
+ - **Location:** `/workstream/`
138
+ - **Filename:** `issue-[issue-number]-[issue-name]-refinement.md`
139
+
140
+ ---
141
+
142
+ ## Mode B — PRD Creation
143
+
144
+ ### Process
145
+
146
+ 1. **Receive Feature Scope:** User describes the features or feature set.
147
+ 2. **Ask Clarifying Questions:** Gather detail about requirements, prioritization, and acceptance criteria.
148
+ 3. **Reference Existing Documents:** Consider product context and technical guidelines.
149
+ 4. **Generate PRD.**
150
+ 5. **Save Output.**
151
+
152
+ ### Clarifying Questions
153
+
154
+ - **Feature Title & Scope:** "What is the main feature? What is included?"
155
+ - **Affected Repositories:** "Which repositories will be affected by this feature? (e.g., `owner/repo-frontend`, `owner/repo-backend`)"
156
+ - **Problem/Goal:** "What problem does this feature solve? How does it align with product goals?"
157
+ - **Target User:** "Who is the primary user?"
158
+ - **User Stories:** "Main user stories? (As a [role], I want [goal] so that [benefit])"
159
+ - **Functional Requirements:** "What specific functions must this feature support?"
160
+ - **Acceptance Criteria:** "What are the success criteria?"
161
+ - **Priority & Scope:** "Priority? Explicitly excluded features?"
162
+ - **Data Requirements:** "What data is required?"
163
+ - **Business Rules:** "Specific business rules or constraints?"
164
+ - **UI/UX Expectations:** "Mockups, wireframes, or design direction?"
165
+ - **Edge Cases:** "Edge cases or error conditions?"
166
+
167
+ ### Output Structure
168
+
169
+ 0. **Changelog** — Version history table (see Document Changelog Convention above)
170
+ 1. **Executive Summary** — Feature overview and strategic importance (2-3 sentences)
171
+ 2. **Feature Overview** — What the feature is and enables
172
+ 3. **Goals & Objectives** — Specific, measurable goals
173
+ 4. **Affected Repositories** — List of repositories impacted by this feature, with a brief description of the expected changes per repo (table format: Repo | Role / Impact)
174
+ 5. **Target Users** — Primary and secondary personas
175
+ 6. **User Stories** — 3-10 stories in "As a [role]..." format
176
+ 7. **Functional Requirements** — Numbered list, explicit and unambiguous
177
+ 8. **Business Rules** — Logic and policy constraints
178
+ 9. **Data Requirements** — Entities, data collected/stored, sensitivity
179
+ 10. **Non-Goals (Out of Scope)** — What this does NOT include
180
+ 11. **Design Considerations** — Mockups, UI/UX patterns, accessibility
181
+ 12. **Technical Considerations** — Dependencies, integrations, performance, alignment with technical guidelines
182
+ 13. **Acceptance Criteria** — Clear, testable criteria
183
+ 14. **Success Metrics** — How success is measured
184
+ 15. **Assumptions** — Key assumptions
185
+ 16. **Constraints & Dependencies** — Timeline, resource, external dependencies
186
+ 17. **Security & Compliance** — Security, privacy, auth requirements
187
+ 18. **Open Questions** — Ambiguities needing clarification
188
+
189
+ ### Diagram Guidelines
190
+
191
+ The PRD **SHOULD** include embedded Mermaid diagrams to visually clarify relationships and processes. Use fenced code blocks with the `mermaid` language tag.
192
+
193
+ Recommended diagrams (include whichever add clarity — skip those that don't apply):
194
+
195
+ | Diagram Type | When to Include | Suggested Section |
196
+ | ------------------------------- | -------------------------------------------------- | ------------------------------------------- |
197
+ | **Component diagram** | Feature spans multiple services, repos, or modules | Technical Considerations |
198
+ | **Entity-Relationship diagram** | Feature introduces or modifies data entities | Data Requirements |
199
+ | **Sequence / Flow diagram** | Key user or system interactions need clarification | Feature Overview or Functional Requirements |
200
+ | **User journey / Flowchart** | Complex multi-step user workflows | User Stories or Design Considerations |
201
+
202
+ Rules:
203
+
204
+ - Diagrams **MUST** be embedded inline in the relevant section, not collected at the end.
205
+ - Each diagram **SHOULD** have a brief introductory sentence explaining what it shows.
206
+ - Keep diagrams focused — one concern per diagram.
207
+ - Use consistent naming across diagrams and prose.
208
+
209
+ ### Scope Guidance
210
+
211
+ - A PRD **SHOULD** define a coherent feature set deliverable in 1-3 iterations.
212
+ - Total user stories **SHOULD NOT** exceed 50.
213
+ - If scope is too large, you **SHOULD** break it into multiple PRDs.
214
+
215
+ ### Output
216
+
217
+ - **Location:** `/docs/requirements/`
218
+ - **Filename:** `prd-[feature-name].md`
219
+
220
+ ---
221
+
222
+ ## Final Instructions
223
+
224
+ 1. You **MUST NOT** start implementing anything.
225
+ 2. You **MUST** detect the mode based on user input (issue number vs. feature description).
226
+ 3. You **MUST** ask clarifying questions to fill gaps.
227
+ 4. You **MUST** present the document for user review.
228
+ 5. You **SHOULD** iterate based on feedback.
229
+ 6. You **MUST** save the finalized document.
230
+ 7. In Issue Refinement mode, you **MUST** update the GitHub Issue with a "Refined Scope" section by delegating to `github-ops` whenever possible.
231
+ 8. 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.