@llipe.com/dev-tasks 0.6.4 → 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 +18 -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 +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 +15 -2
  143. package/skills/.gitkeep +0 -0
@@ -0,0 +1,181 @@
1
+ ---
2
+ name: activity-random-test-tactics
3
+ description: "Generate randomized, fuzz, and property-inspired tests with reproducible seeds. Use for randomized compliance testing."
4
+ ---
5
+
6
+ # Activity: Randomized Test Tactics
7
+
8
+ 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.
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
+ 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.
17
+
18
+ ## Context
19
+
20
+ This activity assumes:
21
+
22
+ - A numbered list of acceptance criteria is available (produced by Phase 2 of `verifier`).
23
+ - E2E scenarios and edge cases have been drafted.
24
+ - The output feeds into the randomized-tactics section of the test plan assembled by `verifier`.
25
+
26
+ ## Tactic Types
27
+
28
+ ### 1. Fuzz Testing
29
+
30
+ Generate malformed, unexpected, or random inputs to discover crashes, unhandled exceptions, or security vulnerabilities.
31
+
32
+ **When to apply:** Any endpoint or function that accepts user input — forms, API bodies, file uploads, query parameters.
33
+
34
+ **Approach:**
35
+
36
+ 1. Identify input surfaces from the spec (fields, parameters, headers).
37
+ 2. Define a fuzz corpus: valid base inputs + mutations (truncation, injection payloads, binary data, oversized values).
38
+ 3. Define the oracle: what constitutes a failure (5xx status, stack trace in response, timeout, data corruption).
39
+ 4. Set iteration count and seed.
40
+
41
+ ### 2. Property-Based Testing
42
+
43
+ Define invariants (properties) that must hold for all valid inputs, then generate many random valid inputs to verify.
44
+
45
+ **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").
46
+
47
+ **Approach:**
48
+
49
+ 1. Extract properties from ACs and business rules.
50
+ 2. Define input generators that produce valid inputs within the domain.
51
+ 3. Run N iterations with random seeds.
52
+ 4. On failure, shrink the input to the minimal failing case.
53
+
54
+ ### 3. Stateful Random Walks
55
+
56
+ Execute random sequences of valid API calls to discover state-dependent bugs.
57
+
58
+ **When to apply:** Systems with stateful resources (CRUD workflows, multi-step processes, session-based interactions).
59
+
60
+ **Approach:**
61
+
62
+ 1. Model valid actions and their preconditions as a state machine.
63
+ 2. Generate random action sequences that respect preconditions.
64
+ 3. After each sequence, verify invariants hold (e.g., resource counts match, no orphaned records).
65
+ 4. Capture the full action sequence and seed for replay.
66
+
67
+ ## Reproducibility Requirements
68
+
69
+ Every randomized tactic **MUST** satisfy these controls:
70
+
71
+ | Requirement | Description |
72
+ | ------------------------ | ------------------------------------------------------------------------------------------------- |
73
+ | **Seed capture** | Record the PRNG seed used for each run. |
74
+ | **Seed replay** | Provide a command or instruction to re-run the exact same sequence using the captured seed. |
75
+ | **Iteration count** | Document the number of iterations per tactic. |
76
+ | **Deterministic oracle** | The pass/fail oracle **MUST** be deterministic for a given input — no "sometimes fails" verdicts. |
77
+ | **Environment snapshot** | Record runtime environment details (OS, runtime version, relevant config) alongside results. |
78
+
79
+ ### Seed Policy
80
+
81
+ ```
82
+ Seed format: <tactic-type>-<AC-id>-<unix-timestamp>-<random-4-hex>
83
+ Example: fuzz-AC3-1719849600-a3f1
84
+
85
+ Replay command template:
86
+ <test-runner> --seed=<captured-seed> --tactic=<tactic-id> --iterations=1
87
+ ```
88
+
89
+ Seeds **MUST** be included in the test plan and in any failure reports.
90
+
91
+ ## Tactic Template
92
+
93
+ ```markdown
94
+ ### RT-{id}: {Tactic Title}
95
+
96
+ | Field | Value |
97
+ | ---------------------- | ---------------------------------------------------------------------- |
98
+ | **AC(s)** | AC-{n} |
99
+ | **Tactic type** | fuzz / property-based / stateful-random-walk |
100
+ | **Input surface** | {What is being fuzzed or randomized} |
101
+ | **Property / Oracle** | {Invariant that must hold, or failure condition} |
102
+ | **Iterations** | {Number of random iterations} |
103
+ | **Seed** | {To be captured at execution time} |
104
+ | **Replay instruction** | {Command to reproduce with captured seed} |
105
+ | **Shrink strategy** | {How to minimize failing input — binary search, delta debugging, etc.} |
106
+ ```
107
+
108
+ ## Example
109
+
110
+ Given AC-2: "API returns paginated results with at most 50 items per page."
111
+
112
+ ### RT-1: Fuzz pagination parameters
113
+
114
+ | Field | Value |
115
+ | ---------------------- | -------------------------------------------------------------------------- |
116
+ | **AC(s)** | AC-2 |
117
+ | **Tactic type** | fuzz |
118
+ | **Input surface** | Query parameters `page` and `pageSize` on `GET /api/items` |
119
+ | **Property / Oracle** | Response always returns ≤50 items. Status is never 5xx. Response time <2s. |
120
+ | **Iterations** | 500 |
121
+ | **Seed** | `fuzz-AC2-{timestamp}-{hex}` |
122
+ | **Replay instruction** | `test-runner --seed=<seed> --tactic=RT-1 --iterations=1` |
123
+ | **Shrink strategy** | Binary search on `pageSize` value to find minimum trigger. |
124
+
125
+ **Mutation corpus for `page`/`pageSize`:**
126
+
127
+ - Valid range: `page=1..1000`, `pageSize=1..50`
128
+ - Mutations: `page=-1`, `page=0`, `page=999999`, `pageSize=0`, `pageSize=51`, `pageSize=-1`, `pageSize=NaN`, `pageSize=""`, `pageSize=1.5`, omit parameter entirely
129
+
130
+ ### RT-2: Property — response length never exceeds pageSize
131
+
132
+ | Field | Value |
133
+ | ---------------------- | --------------------------------------------------------------- |
134
+ | **AC(s)** | AC-2 |
135
+ | **Tactic type** | property-based |
136
+ | **Input surface** | Random valid `pageSize` values (1–50) with random `page` values |
137
+ | **Property / Oracle** | `len(response.items) <= pageSize` for all inputs. |
138
+ | **Iterations** | 200 |
139
+ | **Seed** | `prop-AC2-{timestamp}-{hex}` |
140
+ | **Replay instruction** | `test-runner --seed=<seed> --tactic=RT-2 --iterations=1` |
141
+ | **Shrink strategy** | Reduce `pageSize` to find smallest value where property fails. |
142
+
143
+ ## Failure Triage Workflow
144
+
145
+ When a randomized test fails, the `verifier` agent follows this workflow:
146
+
147
+ 1. **Capture** — Record seed, full input, observed output, and expected oracle result.
148
+ 2. **Replay** — Re-run with captured seed to confirm deterministic reproduction.
149
+ 3. **Minimize** — Apply shrink strategy to find the smallest failing input.
150
+ 4. **Classify:**
151
+ - **Spec gap:** Behavior is undefined → escalate to `product-engineer`.
152
+ - **Implementation defect:** Behavior contradicts an AC → file for `developer`.
153
+ - **Flaky/environmental:** Cannot reproduce → log with environment details, mark `inconclusive`.
154
+ 5. **Report** — Add triaged failure to validation report with classification and minimized input.
155
+ 6. **Retry limit** — At most 3 reproduction attempts for non-reproducing failures.
156
+
157
+ ## Execution Checklist
158
+
159
+ Use this checklist to verify completeness before returning results:
160
+
161
+ - [ ] At least one randomized tactic defined per input surface identified in the spec.
162
+ - [ ] Every tactic has a seed policy and replay instruction.
163
+ - [ ] Every tactic maps to ≥1 AC.
164
+ - [ ] Iteration counts are documented and justified.
165
+ - [ ] Shrink strategy defined for every tactic.
166
+ - [ ] Failure triage workflow referenced for handling failures.
167
+ - [ ] No tactic relies on internal implementation details.
168
+
169
+ ## Output
170
+
171
+ 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.
172
+
173
+ ## Final Instructions
174
+
175
+ 1. You **MUST** produce at least one randomized tactic per significant input surface.
176
+ 2. You **MUST** include seed capture and replay instructions for every tactic.
177
+ 3. You **MUST** define a shrink strategy for every tactic.
178
+ 4. You **MUST** specify the oracle/property that determines pass or fail.
179
+ 5. You **MUST NOT** reference internal implementation details — all assertions are based on observable behavior.
180
+ 6. You **MUST** reference the failure triage workflow for handling randomized test failures.
181
+ 7. You **SHOULD** prefer property-based tactics for business rules expressing universal constraints.
@@ -0,0 +1,236 @@
1
+ ---
2
+ name: activity-refine
3
+ description: "Clarify scope: produce a lightweight issue refinement or a full PRD. Use in product-engineer Feature or Issue Mode."
4
+ ---
5
+
6
+ # Activity: Refine Scope
7
+
8
+ 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.
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
+ 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.
17
+
18
+ ## Context
19
+
20
+ This step assumes foundation documents exist:
21
+
22
+ - `product-context.md` — Understanding the overall product
23
+ - `technical-guidelines.md` — Understanding technical constraints and patterns
24
+
25
+ If the user provides a **GitHub Issue number**, you **MUST** produce a lightweight refinement.
26
+ If the user provides a **feature description**, you **MUST** produce a full PRD.
27
+
28
+ ---
29
+
30
+ ## Document Changelog Convention
31
+
32
+ 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.
33
+
34
+ - The initial version **MUST** be `1.0`.
35
+ - Every subsequent update **MUST** increment the minor version (e.g., `1.1`, `1.2`, …).
36
+ - Major structural rewrites **SHOULD** increment the major version (e.g., `2.0`).
37
+ - The **Author** column **MUST** include the name of the person or agent responsible for the change (e.g., `@username`, `developer-agent`, `planner-agent`).
38
+
39
+ ```markdown
40
+ ## Changelog
41
+
42
+ | Version | Date | Summary | Author |
43
+ | ------- | ---------- | --------------- | ------------------ |
44
+ | 1.0 | YYYY-MM-DD | Initial version | @user / agent-name |
45
+ ```
46
+
47
+ ---
48
+
49
+ ## Mode Detection
50
+
51
+ | Input | Mode | Output |
52
+ | --------------------------- | -------------------- | ---------------------------------- |
53
+ | GitHub Issue number + repo | **Issue Refinement** | Lightweight refinement doc |
54
+ | Feature description or idea | **PRD Creation** | Full product requirements document |
55
+
56
+ ---
57
+
58
+ ## Mode A — Issue Refinement
59
+
60
+ ### Process
61
+
62
+ 1. **Receive Issue Reference:** User provides GitHub Issue number and repo.
63
+ 2. **Read Issue:** Delegate to `github-ops` to fetch issue body, comments, labels, and status whenever possible.
64
+ 3. **Ask Clarifying Questions:** Focus on missing scope, acceptance criteria, and constraints.
65
+ 4. **Refine Scope:** Summarize scope, non-goals, risks, and dependencies.
66
+ 5. **Update GitHub Issue:** Delegate to `github-ops` to add or update a "Refined Scope" section in the issue body.
67
+ 6. **Save Output.**
68
+
69
+ 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.
70
+
71
+ ### Clarifying Questions (ask only what is missing)
72
+
73
+ - "What is the exact user-visible behavior change?"
74
+ - "What is explicitly out of scope?"
75
+ - "What are the acceptance criteria? (3-7 testable statements)"
76
+ - "Are there performance, security, or compatibility constraints?"
77
+ - "What is the definition of done?"
78
+ - "Are there related issues or dependencies?"
79
+
80
+ ### Acceptance Criteria Quality Standard
81
+
82
+ Acceptance criteria in refinement outputs **MUST** be:
83
+
84
+ - specific and observable (user-visible behavior or measurable system behavior)
85
+ - testable with clear pass/fail outcomes
86
+ - mapped to at least one validation method (automated test or manual/UI check)
87
+ - inclusive of relevant edge-case behavior (error, boundary, and empty-state handling)
88
+
89
+ For each criterion, you **SHOULD** use a concise "Given / When / Then" style when it improves clarity.
90
+
91
+ ### Output Structure
92
+
93
+ ```markdown
94
+ # Issue Refinement: [Issue Number] - [Issue Title]
95
+
96
+ ## Changelog
97
+
98
+ | Version | Date | Summary | Author |
99
+ | ------- | ---------- | ------------------ | ------------------ |
100
+ | 1.0 | YYYY-MM-DD | Initial refinement | @user / agent-name |
101
+
102
+ ## Summary
103
+
104
+ - Goal:
105
+ - Primary user impact:
106
+ - Non-goals:
107
+
108
+ ## Acceptance Criteria
109
+
110
+ - [ ] [Criterion 1]
111
+ - [ ] [Criterion 2]
112
+ - [ ] [Criterion 3]
113
+
114
+ ## Constraints
115
+
116
+ - [Performance/compatibility/security constraints]
117
+
118
+ ## Risks and Edge Cases
119
+
120
+ - [Risk 1]
121
+ - [Edge case 1]
122
+
123
+ ## Dependencies
124
+
125
+ - [Related issues, services, or teams]
126
+
127
+ ## Testing Notes
128
+
129
+ - Unit tests:
130
+ - Integration tests:
131
+ - Manual checks:
132
+ - Edge-case checks:
133
+ - Acceptance-criteria-to-test mapping:
134
+
135
+ ## Open Questions
136
+
137
+ - [Remaining unknowns]
138
+ ```
139
+
140
+ ### Output
141
+
142
+ - **Location:** `/workstream/`
143
+ - **Filename:** `issue-[issue-number]-[issue-name]-refinement.md`
144
+
145
+ ---
146
+
147
+ ## Mode B — PRD Creation
148
+
149
+ ### Process
150
+
151
+ 1. **Receive Feature Scope:** User describes the features or feature set.
152
+ 2. **Ask Clarifying Questions:** Gather detail about requirements, prioritization, and acceptance criteria.
153
+ 3. **Reference Existing Documents:** Consider product context and technical guidelines.
154
+ 4. **Generate PRD.**
155
+ 5. **Save Output.**
156
+
157
+ ### Clarifying Questions
158
+
159
+ - **Feature Title & Scope:** "What is the main feature? What is included?"
160
+ - **Affected Repositories:** "Which repositories will be affected by this feature? (e.g., `owner/repo-frontend`, `owner/repo-backend`)"
161
+ - **Problem/Goal:** "What problem does this feature solve? How does it align with product goals?"
162
+ - **Target User:** "Who is the primary user?"
163
+ - **User Stories:** "Main user stories? (As a [role], I want [goal] so that [benefit])"
164
+ - **Functional Requirements:** "What specific functions must this feature support?"
165
+ - **Acceptance Criteria:** "What are the success criteria?"
166
+ - **Priority & Scope:** "Priority? Explicitly excluded features?"
167
+ - **Data Requirements:** "What data is required?"
168
+ - **Business Rules:** "Specific business rules or constraints?"
169
+ - **UI/UX Expectations:** "Mockups, wireframes, or design direction?"
170
+ - **Edge Cases:** "Edge cases or error conditions?"
171
+
172
+ ### Output Structure
173
+
174
+ 0. **Changelog** — Version history table (see Document Changelog Convention above)
175
+ 1. **Executive Summary** — Feature overview and strategic importance (2-3 sentences)
176
+ 2. **Feature Overview** — What the feature is and enables
177
+ 3. **Goals & Objectives** — Specific, measurable goals
178
+ 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)
179
+ 5. **Target Users** — Primary and secondary personas
180
+ 6. **User Stories** — 3-10 stories in "As a [role]..." format
181
+ 7. **Functional Requirements** — Numbered list, explicit and unambiguous
182
+ 8. **Business Rules** — Logic and policy constraints
183
+ 9. **Data Requirements** — Entities, data collected/stored, sensitivity
184
+ 10. **Non-Goals (Out of Scope)** — What this does NOT include
185
+ 11. **Design Considerations** — Mockups, UI/UX patterns, accessibility
186
+ 12. **Technical Considerations** — Dependencies, integrations, performance, alignment with technical guidelines
187
+ 13. **Acceptance Criteria** — Clear, testable criteria
188
+ 14. **Success Metrics** — How success is measured
189
+ 15. **Assumptions** — Key assumptions
190
+ 16. **Constraints & Dependencies** — Timeline, resource, external dependencies
191
+ 17. **Security & Compliance** — Security, privacy, auth requirements
192
+ 18. **Open Questions** — Ambiguities needing clarification
193
+
194
+ ### Diagram Guidelines
195
+
196
+ The PRD **SHOULD** include embedded Mermaid diagrams to visually clarify relationships and processes. Use fenced code blocks with the `mermaid` language tag.
197
+
198
+ Recommended diagrams (include whichever add clarity — skip those that don't apply):
199
+
200
+ | Diagram Type | When to Include | Suggested Section |
201
+ | ------------------------------- | -------------------------------------------------- | ------------------------------------------- |
202
+ | **Component diagram** | Feature spans multiple services, repos, or modules | Technical Considerations |
203
+ | **Entity-Relationship diagram** | Feature introduces or modifies data entities | Data Requirements |
204
+ | **Sequence / Flow diagram** | Key user or system interactions need clarification | Feature Overview or Functional Requirements |
205
+ | **User journey / Flowchart** | Complex multi-step user workflows | User Stories or Design Considerations |
206
+
207
+ Rules:
208
+
209
+ - Diagrams **MUST** be embedded inline in the relevant section, not collected at the end.
210
+ - Each diagram **SHOULD** have a brief introductory sentence explaining what it shows.
211
+ - Keep diagrams focused — one concern per diagram.
212
+ - Use consistent naming across diagrams and prose.
213
+
214
+ ### Scope Guidance
215
+
216
+ - A PRD **SHOULD** define a coherent feature set deliverable in 1-3 iterations.
217
+ - Total user stories **SHOULD NOT** exceed 50.
218
+ - If scope is too large, you **SHOULD** break it into multiple PRDs.
219
+
220
+ ### Output
221
+
222
+ - **Location:** `/docs/requirements/`
223
+ - **Filename:** `prd-[feature-name].md`
224
+
225
+ ---
226
+
227
+ ## Final Instructions
228
+
229
+ 1. You **MUST NOT** start implementing anything.
230
+ 2. You **MUST** detect the mode based on user input (issue number vs. feature description).
231
+ 3. You **MUST** ask clarifying questions to fill gaps.
232
+ 4. You **MUST** present the document for user review.
233
+ 5. You **SHOULD** iterate based on feedback.
234
+ 6. You **MUST** save the finalized document.
235
+ 7. In Issue Refinement mode, you **MUST** update the GitHub Issue with a "Refined Scope" section by delegating to `github-ops` whenever possible.
236
+ 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.
@@ -0,0 +1,221 @@
1
+ ---
2
+ name: git-ops
3
+ description: "Branch management, rebase, merge, conflict resolution, and recovery procedures. Use for complex git operations during implementation or orchestration."
4
+ ---
5
+
6
+ # Git Operations
7
+
8
+ Reusable procedures for git branch management, merge, rebase, and conflict resolution. This skill describes _procedures_ — merge authority policies remain in `github-ops.agent.md`. Any agent can invoke this skill when encountering git operations.
9
+
10
+ ---
11
+
12
+ ## When to Use
13
+
14
+ - Creating feature or story branches
15
+ - Rebasing a branch onto a target
16
+ - Merging PRs or branches
17
+ - Resolving merge conflicts
18
+ - Recovering from failed git operations
19
+
20
+ ---
21
+
22
+ ## Procedures
23
+
24
+ ### 1. Create Branch from Latest Default
25
+
26
+ ```bash
27
+ # Fetch latest remote state
28
+ git fetch origin
29
+
30
+ # Switch to the default branch and pull
31
+ git checkout main
32
+ git pull origin main
33
+
34
+ # Create and switch to the new branch
35
+ git checkout -b <branch-name>
36
+ ```
37
+
38
+ **Naming conventions** (defer to `github-ops` for policy):
39
+
40
+ - Story branches: `story/<story-id>-<short-description>`
41
+ - Issue branches: `issue/<issue-number>-<short-description>`
42
+ - Integration branches: `integrate/<milestone-or-prd-name>`
43
+
44
+ ### 2. Create Branch from Integration Branch
45
+
46
+ When working under a `planner` orchestration with an integration branch:
47
+
48
+ ```bash
49
+ git fetch origin
50
+ git checkout <integration-branch>
51
+ git pull origin <integration-branch>
52
+ git checkout -b <story-branch>
53
+ ```
54
+
55
+ ### 3. Update Branch (Rebase onto Target)
56
+
57
+ Preferred method to keep a branch up-to-date with its target:
58
+
59
+ ```bash
60
+ git fetch origin
61
+ git rebase origin/<target-branch>
62
+ ```
63
+
64
+ **If conflicts occur** → jump to [Resolve Merge Conflicts](#6-resolve-merge-conflicts).
65
+
66
+ **If rebase is too complex** (many commits, repeated conflicts), fall back to merge:
67
+
68
+ ```bash
69
+ git fetch origin
70
+ git merge origin/<target-branch>
71
+ ```
72
+
73
+ ### 4. Pre-Merge Checks
74
+
75
+ Before merging any PR or branch, verify:
76
+
77
+ 1. **Branch is up-to-date** with the target:
78
+ ```bash
79
+ git fetch origin
80
+ git log --oneline origin/<target-branch>..HEAD # should show only your commits
81
+ ```
82
+ 2. **No merge conflicts**:
83
+ ```bash
84
+ git merge-tree $(git merge-base HEAD origin/<target-branch>) HEAD origin/<target-branch>
85
+ ```
86
+ 3. **Tests pass locally** (if applicable):
87
+ ```bash
88
+ # Run project-specific test command
89
+ ```
90
+ 4. **CI status is green** (check via GitHub API or `gh` CLI):
91
+ ```bash
92
+ gh pr checks <pr-number>
93
+ ```
94
+
95
+ ### 5. Merge Strategies
96
+
97
+ Choose the appropriate strategy based on context:
98
+
99
+ | Strategy | When to Use | Command |
100
+ | ---------------- | ----------------------------------------------------------------------------------- | --------------------------- |
101
+ | **Squash merge** | Story/issue PRs → integration or main branch. Produces clean single-commit history. | `gh pr merge <pr> --squash` |
102
+ | **Merge commit** | Integration branch → main. Preserves the full story history. | `gh pr merge <pr> --merge` |
103
+ | **Rebase merge** | Small PRs with clean linear history. Avoid for multi-commit stories. | `gh pr merge <pr> --rebase` |
104
+
105
+ **Default**: Squash merge for story PRs, merge commit for integration PRs to main.
106
+
107
+ ### 6. Resolve Merge Conflicts
108
+
109
+ When a rebase or merge produces conflicts:
110
+
111
+ #### Step 1: Identify conflicting files
112
+
113
+ ```bash
114
+ git diff --name-only --diff-filter=U
115
+ ```
116
+
117
+ #### Step 2: For each conflicting file
118
+
119
+ 1. Open the file and locate conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
120
+ 2. Determine ownership:
121
+ - If the file was primarily modified by the current branch → prefer current branch changes
122
+ - If the file was primarily modified by the target → prefer target changes
123
+ - If both branches made meaningful changes → manual merge required
124
+ 3. Resolve the conflict by editing the file to the correct final state
125
+ 4. Remove all conflict markers
126
+
127
+ #### Step 3: Mark resolved and continue
128
+
129
+ ```bash
130
+ # After resolving each file
131
+ git add <resolved-file>
132
+
133
+ # Continue the rebase or complete the merge
134
+ git rebase --continue # if rebasing
135
+ git commit # if merging
136
+ ```
137
+
138
+ #### Step 4: Verify
139
+
140
+ ```bash
141
+ # Ensure no remaining conflict markers in the codebase
142
+ grep -rn '<<<<<<<\|=======\|>>>>>>>' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.json' --include='*.md' .
143
+
144
+ # Run tests to verify the resolution is correct
145
+ ```
146
+
147
+ ### 7. Recovery from Failed Rebase
148
+
149
+ If a rebase goes wrong or produces unexpected results:
150
+
151
+ ```bash
152
+ # Abort the in-progress rebase
153
+ git rebase --abort
154
+
155
+ # Verify you're back to the pre-rebase state
156
+ git log --oneline -5
157
+ git status
158
+ ```
159
+
160
+ If you already completed a bad rebase:
161
+
162
+ ```bash
163
+ # Find the pre-rebase commit using reflog
164
+ git reflog
165
+
166
+ # Reset to the state before the rebase
167
+ git reset --hard <pre-rebase-sha>
168
+ ```
169
+
170
+ **Always report** what happened to the user before and after recovery.
171
+
172
+ ### 8. Recovery from Failed Merge
173
+
174
+ ```bash
175
+ # Abort an in-progress merge
176
+ git merge --abort
177
+
178
+ # Verify clean state
179
+ git status
180
+ ```
181
+
182
+ If a merge was already committed but is wrong:
183
+
184
+ ```bash
185
+ # Revert the merge commit (keeps history clean)
186
+ git revert -m 1 <merge-commit-sha>
187
+ ```
188
+
189
+ ### 9. Force Push Safety
190
+
191
+ Force pushing **MUST** only be used on branches owned exclusively by the current agent/developer. Never force push shared branches.
192
+
193
+ ```bash
194
+ # Safe force push (fails if someone else pushed)
195
+ git push --force-with-lease origin <branch-name>
196
+ ```
197
+
198
+ **Never use** `git push --force` without `--with-lease`.
199
+
200
+ ---
201
+
202
+ ## Conflict Resolution Heuristics
203
+
204
+ When resolving conflicts automatically, apply these heuristics in order:
205
+
206
+ 1. **Non-overlapping changes**: Accept both sides (most common — different parts of the file changed)
207
+ 2. **Import/dependency additions**: Accept both sides (both branches added different imports)
208
+ 3. **Configuration file conflicts**: Merge both entries, ensure no duplicates
209
+ 4. **Schema/migration conflicts**: **Stop and ask the user** — schema conflicts require human judgment
210
+ 5. **Test file conflicts**: Accept both sides if tests are additive; flag if test logic conflicts
211
+ 6. **Business logic conflicts**: **Stop and ask the user** — business logic requires human judgment
212
+
213
+ ---
214
+
215
+ ## Integration with Agents
216
+
217
+ | Agent | Typical Usage |
218
+ | ------------ | ---------------------------------------------------------------------------------------------- |
219
+ | `developer` | Branch creation, rebase before PR, conflict resolution during implementation |
220
+ | `planner` | Integration branch management, merging story PRs, rebasing integration onto main |
221
+ | `github-ops` | PR merge execution (policy enforcement stays with github-ops, procedures come from this skill) |