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