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