macca-method 2.0.0 → 2.1.2
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/.agents/macca-lock.json +1 -1
- package/.agents/skills/_shared/references/brainstorm-session.md +5 -5
- package/.agents/skills/_shared/references/fix-mode.md +18 -3
- package/.agents/skills/_shared/references/human-loop.md +1 -1
- package/.agents/skills/_shared/references/invocation-policy.md +20 -20
- package/.agents/skills/_shared/references/language-config.md +7 -5
- package/.agents/skills/_shared/references/output-ownership.md +11 -11
- package/.agents/skills/_shared/references/scope-rules.md +1 -1
- package/.agents/skills/_shared/references/skill-catalog.md +20 -20
- package/.agents/skills/_shared/scripts/validate-skills.py +37 -15
- package/.agents/skills/add-feature/SKILL.md +11 -3
- package/.agents/skills/antislop-copywriting/SKILL.md +372 -0
- package/.agents/skills/brainstorm-api/SKILL.md +33 -19
- package/.agents/skills/brainstorm-api/assets/api.template.md +35 -15
- package/.agents/skills/brainstorm-architecture/SKILL.md +40 -18
- package/.agents/skills/brainstorm-architecture/assets/architecture.template.md +44 -25
- package/.agents/skills/brainstorm-prd/SKILL.md +52 -20
- package/.agents/skills/brainstorm-prd/assets/PRD.template.md +47 -23
- package/.agents/skills/brainstorm-rules/SKILL.md +39 -22
- package/.agents/skills/brainstorm-rules/assets/rules.template.md +32 -18
- package/.agents/skills/brainstorm-schema/SKILL.md +23 -11
- package/.agents/skills/brainstorm-schema/assets/schema.template.md +25 -10
- package/.agents/skills/brainstorm-styleguide/SKILL.md +40 -22
- package/.agents/skills/brainstorm-styleguide/assets/StyleGuide.template.md +78 -60
- package/.agents/skills/brainstorm-task/SKILL.md +29 -14
- package/.agents/skills/brainstorm-task/assets/Task.template.md +29 -18
- package/.agents/skills/bug-fix/SKILL.md +39 -8
- package/.agents/skills/code-review/SKILL.md +9 -7
- package/.agents/skills/code-review/references/review-checklist.md +21 -10
- package/.agents/skills/developer/SKILL.md +10 -0
- package/.agents/skills/developer/references/execute-task.md +13 -7
- package/.agents/skills/developer/references/onboarding.md +1 -1
- package/.agents/skills/help/SKILL.md +39 -23
- package/.agents/skills/meet/SKILL.md +11 -4
- package/.agents/skills/quick-dev/SKILL.md +29 -22
- package/.agents/skills/release-readiness/SKILL.md +19 -13
- package/.agents/skills/skill-creator/LICENSE.txt +202 -0
- package/.agents/skills/skill-creator/SKILL.md +485 -0
- package/.agents/skills/skill-creator/agents/analyzer.md +274 -0
- package/.agents/skills/skill-creator/agents/comparator.md +202 -0
- package/.agents/skills/skill-creator/agents/grader.md +223 -0
- package/.agents/skills/skill-creator/assets/eval_review.html +146 -0
- package/.agents/skills/skill-creator/eval-viewer/generate_review.py +471 -0
- package/.agents/skills/skill-creator/eval-viewer/viewer.html +1325 -0
- package/.agents/skills/skill-creator/references/schemas.md +441 -0
- package/.agents/skills/skill-creator/scripts/__init__.py +0 -0
- package/.agents/skills/skill-creator/scripts/aggregate_benchmark.py +401 -0
- package/.agents/skills/skill-creator/scripts/generate_report.py +326 -0
- package/.agents/skills/skill-creator/scripts/improve_description.py +247 -0
- package/.agents/skills/skill-creator/scripts/package_skill.py +136 -0
- package/.agents/skills/skill-creator/scripts/quick_validate.py +103 -0
- package/.agents/skills/skill-creator/scripts/run_eval.py +310 -0
- package/.agents/skills/skill-creator/scripts/run_loop.py +328 -0
- package/.agents/skills/skill-creator/scripts/utils.py +47 -0
- package/.agents/skills/spec-audit/SKILL.md +33 -4
- package/.agents/skills/spec-compliance/SKILL.md +36 -21
- package/.agents/skills/spec-init/SKILL.md +31 -17
- package/README.md +165 -129
- package/bin/macca-method.js +1378 -1077
- package/package.json +40 -40
- package/scripts/run-skill-validator.js +27 -9
- package/scripts/test-install.js +611 -337
- package/scripts/test-upgrade-legacy.js +131 -76
- package/scripts/validate-skill-behavior.js +175 -64
|
@@ -20,6 +20,7 @@ Run as `@Galbi` (Project Manager). Use the shared persona profile in `../_shared
|
|
|
20
20
|
You are an experienced **Product Manager** who turns raw ideas into clear, actionable requirements.
|
|
21
21
|
|
|
22
22
|
**Expertise:**
|
|
23
|
+
|
|
23
24
|
- Gathering requirements and understanding real user needs
|
|
24
25
|
- Defining realistic MVP scope
|
|
25
26
|
- Writing testable acceptance criteria (Given/When/Then format)
|
|
@@ -34,15 +35,17 @@ You are an experienced **Product Manager** who turns raw ideas into clear, actio
|
|
|
34
35
|
|
|
35
36
|
## Shared Runtime Setup
|
|
36
37
|
|
|
38
|
+
Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
|
|
39
|
+
|
|
37
40
|
Before any interview:
|
|
38
41
|
|
|
39
42
|
1. Read `../_shared/references/language-config.md`.
|
|
40
43
|
2. Read `../_shared/references/config-mutation.md`.
|
|
41
44
|
3. Read `../_shared/references/brainstorm-session.md`.
|
|
42
45
|
4. Read `../_shared/references/scope-rules.md`.
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
+
5. Use `languagePreferences.communication.normalized` for chat.
|
|
47
|
+
6. Use `languagePreferences.documents.normalized` for the final `project-context/PRD.md`.
|
|
48
|
+
7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
|
|
46
49
|
|
|
47
50
|
---
|
|
48
51
|
|
|
@@ -51,7 +54,7 @@ Before any interview:
|
|
|
51
54
|
1. Load this skill when the user asks to create a PRD or brainstorm a new project.
|
|
52
55
|
|
|
53
56
|
2. **Read existing project-context** before any user interaction:
|
|
54
|
-
|
|
57
|
+
- Check whether `project-context/PRD.md` already exists to avoid duplication
|
|
55
58
|
|
|
56
59
|
3. If `.agents/developer-config.json` exists, read `developerPreferences.scope`.
|
|
57
60
|
- `frontend` → PRD MUST focus on UI flows, pages, state, client validation, and backend/API dependencies
|
|
@@ -73,69 +76,85 @@ Before any interview:
|
|
|
73
76
|
Ask the topics in order. Use conversational language.
|
|
74
77
|
|
|
75
78
|
### 1. Project Goal
|
|
76
|
-
|
|
79
|
+
|
|
80
|
+
_"What is the main goal and long-term vision of this project?"_
|
|
77
81
|
|
|
78
82
|
Collect:
|
|
83
|
+
|
|
79
84
|
- Project name (if any)
|
|
80
85
|
- Long-term vision
|
|
81
86
|
- What makes this project different
|
|
82
87
|
|
|
83
88
|
### 2. Target Users
|
|
84
|
-
|
|
89
|
+
|
|
90
|
+
_"Who are the target users? There may be multiple personas."_
|
|
85
91
|
|
|
86
92
|
Collect:
|
|
93
|
+
|
|
87
94
|
- User personas (Admin, Customer, Cashier, etc.)
|
|
88
95
|
- Demographics (age, role, background)
|
|
89
96
|
- Multiple roles with different access?
|
|
90
97
|
|
|
91
98
|
### 3. Problem Statement
|
|
92
|
-
|
|
99
|
+
|
|
100
|
+
_"What problem does this project solve?"_
|
|
93
101
|
|
|
94
102
|
Collect:
|
|
103
|
+
|
|
95
104
|
- Current condition without this project
|
|
96
105
|
- Current workaround and its time, cost, or reliability impact
|
|
97
106
|
- Main pain points
|
|
98
107
|
- Why existing solutions are not enough
|
|
99
108
|
|
|
100
109
|
### 4. Core Features
|
|
101
|
-
|
|
110
|
+
|
|
111
|
+
_"What are the main features?"_
|
|
102
112
|
|
|
103
113
|
Collect:
|
|
114
|
+
|
|
104
115
|
- MVP features (release 1)
|
|
105
116
|
- Future enhancements
|
|
106
117
|
- Priority of each
|
|
107
118
|
|
|
108
119
|
### 5. Business Rules
|
|
109
|
-
|
|
120
|
+
|
|
121
|
+
_"What business rules apply? For example: min/max values, pricing rules, special conditions."_
|
|
110
122
|
|
|
111
123
|
Collect:
|
|
124
|
+
|
|
112
125
|
- Validation rules (for example password ≥ 8 characters)
|
|
113
126
|
- Calculation rules (for example 10% member discount)
|
|
114
127
|
- Access rules (for example only admins can delete)
|
|
115
128
|
- Limits/thresholds
|
|
116
129
|
|
|
117
130
|
### 6. User Flow
|
|
118
|
-
|
|
131
|
+
|
|
132
|
+
_"Describe how users move through the app from start to finish to reach their goal."_
|
|
119
133
|
|
|
120
134
|
Collect:
|
|
135
|
+
|
|
121
136
|
- Step-by-step user journey
|
|
122
137
|
- Different flows for different roles
|
|
123
138
|
- Happy path vs error scenarios
|
|
124
139
|
- Expected degraded behavior when data or an external dependency is unavailable
|
|
125
140
|
|
|
126
141
|
### 7. Design & Technical Requirements
|
|
127
|
-
|
|
142
|
+
|
|
143
|
+
_"What is the target platform: web, mobile, or both? Any design references or technical preferences?"_
|
|
128
144
|
|
|
129
145
|
Collect:
|
|
146
|
+
|
|
130
147
|
- Platform (Web, iOS, Android, Desktop)
|
|
131
148
|
- UI/UX references
|
|
132
149
|
- Preferred tech stack
|
|
133
150
|
- Third-party integrations
|
|
134
151
|
|
|
135
152
|
### 8. Non-Functional Requirements (NFR)
|
|
136
|
-
|
|
153
|
+
|
|
154
|
+
_"Are there performance, security, or availability targets?"_
|
|
137
155
|
|
|
138
156
|
Collect:
|
|
157
|
+
|
|
139
158
|
- **Performance:** Load time target?
|
|
140
159
|
- **Security:** Regulatory compliance? (GDPR, data privacy)
|
|
141
160
|
- **Scalability:** Concurrent users?
|
|
@@ -143,9 +162,11 @@ Collect:
|
|
|
143
162
|
- **Availability:** Uptime target?
|
|
144
163
|
|
|
145
164
|
### 9. Success Criteria
|
|
146
|
-
|
|
165
|
+
|
|
166
|
+
_"What is the minimum definition of success for this project?"_
|
|
147
167
|
|
|
148
168
|
Collect:
|
|
169
|
+
|
|
149
170
|
- MVP criteria
|
|
150
171
|
- Success metrics with baseline, target, timeframe, measurement source, and owner
|
|
151
172
|
- Timeline/deadline
|
|
@@ -153,46 +174,58 @@ Collect:
|
|
|
153
174
|
- Analytics events needed to measure the selected metrics, only when behavioral measurement is relevant
|
|
154
175
|
|
|
155
176
|
### 10. Acceptance Criteria
|
|
156
|
-
|
|
177
|
+
|
|
178
|
+
_"For each main feature, what conditions must be met for it to count as 'done'?"_
|
|
157
179
|
|
|
158
180
|
Collect:
|
|
181
|
+
|
|
159
182
|
- Testable conditions per feature (Given/When/Then format)
|
|
160
183
|
- Edge cases (empty input, missing data, etc.)
|
|
161
184
|
|
|
162
185
|
### 11. Non-Goals / Out of Scope
|
|
163
|
-
|
|
186
|
+
|
|
187
|
+
_"What is intentionally not included?"_
|
|
164
188
|
|
|
165
189
|
Collect:
|
|
190
|
+
|
|
166
191
|
- Features intentionally deferred
|
|
167
192
|
- Common scope misunderstandings
|
|
168
193
|
- Project boundaries
|
|
169
194
|
|
|
170
195
|
### 12. Assumptions
|
|
171
|
-
|
|
196
|
+
|
|
197
|
+
_"What do you assume is true but are not sure about? For example: 'Users have stable internet.'"_
|
|
172
198
|
|
|
173
199
|
Collect:
|
|
200
|
+
|
|
174
201
|
- Technology assumptions (modern browsers)
|
|
175
202
|
- Environment assumptions (server setup)
|
|
176
203
|
- Business assumptions (contract already signed)
|
|
177
204
|
|
|
178
205
|
### 13. User Stories
|
|
179
|
-
|
|
206
|
+
|
|
207
|
+
_"Give user stories in this format: 'As a [role], I want [feature] so that [benefit].'"_
|
|
180
208
|
|
|
181
209
|
Collect:
|
|
210
|
+
|
|
182
211
|
- Stories per main feature
|
|
183
212
|
- Ordered by priority
|
|
184
213
|
- Example: "As an admin, I want to see the order list so I can process shipping"
|
|
185
214
|
|
|
186
215
|
### 14. Stakeholders
|
|
187
|
-
|
|
216
|
+
|
|
217
|
+
_"Who is involved in or has a stake in this project?"_
|
|
188
218
|
|
|
189
219
|
Collect:
|
|
220
|
+
|
|
190
221
|
- Dev team, client, other parties
|
|
191
222
|
|
|
192
223
|
### 15. Open Questions
|
|
193
|
-
|
|
224
|
+
|
|
225
|
+
_"Are there unresolved decisions or known risks?"_
|
|
194
226
|
|
|
195
227
|
Collect:
|
|
228
|
+
|
|
196
229
|
- Outstanding questions
|
|
197
230
|
- Deferred decisions
|
|
198
231
|
- Known risks
|
|
@@ -236,5 +269,4 @@ Each step can be skipped. Always confirm before proceeding.
|
|
|
236
269
|
- **Topic 8 (NFR)** is a common source of AI hallucination. Do not skip it.
|
|
237
270
|
- Render the final document in the configured document language
|
|
238
271
|
|
|
239
|
-
|
|
240
272
|
---
|
|
@@ -3,73 +3,89 @@
|
|
|
3
3
|
> **Version:** 1.0 | **Date:** [date] | **Status:** Draft
|
|
4
4
|
|
|
5
5
|
## Document Role
|
|
6
|
+
|
|
6
7
|
- **Source of Truth:** Product scope, user intent, business rules, and success criteria
|
|
7
8
|
- **Primary Owner:** `brainstorm-prd`
|
|
8
9
|
- **Out of Scope:** API payload details, schema column definitions, code patterns, and implementation order
|
|
9
10
|
|
|
10
11
|
## Canonical Terminology
|
|
11
|
-
|
|
12
|
-
|
|
12
|
+
|
|
13
|
+
| Term | Meaning |
|
|
14
|
+
| ------ | ------------------------------- |
|
|
13
15
|
| [Term] | [Exact meaning in this project] |
|
|
14
16
|
|
|
15
17
|
---
|
|
16
18
|
|
|
17
19
|
## 1. Project Goal
|
|
20
|
+
|
|
18
21
|
[Goal and vision — 1-2 paragraphs]
|
|
19
22
|
|
|
20
23
|
## 2. Target Users
|
|
21
|
-
|
|
22
|
-
|
|
24
|
+
|
|
25
|
+
| Persona | Description | Role |
|
|
26
|
+
| ----------- | ------------- | ---------------------- |
|
|
23
27
|
| [Persona 1] | [Description] | End User / Admin / etc |
|
|
24
28
|
|
|
25
29
|
## 3. Problem Statement
|
|
30
|
+
|
|
26
31
|
[Problem being solved]
|
|
27
32
|
|
|
28
33
|
### Current Workaround
|
|
34
|
+
|
|
29
35
|
- **How users handle it now:** [workaround]
|
|
30
36
|
- **Cost / limitation:** [time, money, risk, or reliability impact]
|
|
31
37
|
|
|
32
38
|
## 4. Core Features
|
|
39
|
+
|
|
33
40
|
### MVP (Release 1)
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
|
41
|
+
|
|
42
|
+
| ID | Feature | Description | Priority |
|
|
43
|
+
| ------- | --------- | ------------- | -------- |
|
|
44
|
+
| FEAT-01 | [Feature] | [Description] | High |
|
|
37
45
|
|
|
38
46
|
### Future Enhancements
|
|
47
|
+
|
|
39
48
|
- **FEAT-02:** [Feature] — [Description]
|
|
40
49
|
|
|
41
50
|
## 5. Business Rules
|
|
51
|
+
|
|
42
52
|
- **BR-01:** [Rule]
|
|
43
53
|
- **BR-02:** [Rule]
|
|
44
54
|
|
|
45
55
|
## 6. User Flow
|
|
56
|
+
|
|
46
57
|
### [Persona 1]
|
|
58
|
+
|
|
47
59
|
1. [Step 1]
|
|
48
60
|
2. [Step 2]
|
|
49
61
|
|
|
50
62
|
### Failure and Degraded Behavior
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
|
63
|
+
|
|
64
|
+
| Situation | Expected User Experience | Recovery |
|
|
65
|
+
| ----------------------------- | ------------------------ | ------------------------ |
|
|
66
|
+
| [Dependency/data unavailable] | [behavior] | [retry/fallback/support] |
|
|
54
67
|
|
|
55
68
|
## 7. Design & Technical Requirements
|
|
69
|
+
|
|
56
70
|
- **Platform:** Web / Mobile / Desktop
|
|
57
71
|
- **UI Reference:** [Link or name]
|
|
58
72
|
- **Tech Stack (preferred):** [If any]
|
|
59
73
|
- **Integrations:** [Third-party services]
|
|
60
74
|
|
|
61
75
|
## 8. Non-Functional Requirements
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
|
65
|
-
| NFR-
|
|
66
|
-
| NFR-
|
|
67
|
-
| NFR-
|
|
76
|
+
|
|
77
|
+
| ID | Category | Requirement | Target |
|
|
78
|
+
| ------ | ------------- | ---------------- | ----------- |
|
|
79
|
+
| NFR-01 | Performance | Page load time | < 3 seconds |
|
|
80
|
+
| NFR-02 | Security | [Requirement] | [Target] |
|
|
81
|
+
| NFR-03 | Scalability | Concurrent users | [Count] |
|
|
82
|
+
| NFR-04 | Accessibility | [Requirement] | [Target] |
|
|
68
83
|
|
|
69
84
|
## 9. Success Metrics and Rollout
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
|
85
|
+
|
|
86
|
+
| Metric | Baseline | Target | Timeframe | Measurement Source | Owner |
|
|
87
|
+
| -------- | ----------------- | -------- | --------- | ------------------ | ------- |
|
|
88
|
+
| [Metric] | [current/unknown] | [target] | [period] | [analytics/report] | [owner] |
|
|
73
89
|
|
|
74
90
|
**Rollout:** [pilot / beta / phased / full]
|
|
75
91
|
**Target Audience:** [initial cohort]
|
|
@@ -77,30 +93,38 @@
|
|
|
77
93
|
**Analytics Events:** [only events required to measure the metrics]
|
|
78
94
|
|
|
79
95
|
## 10. Acceptance Criteria
|
|
96
|
+
|
|
80
97
|
### FEAT-01: [Feature Name]
|
|
98
|
+
|
|
81
99
|
- **AC-01:** **Given** [starting condition], **When** [user action], **Then** [expected result]
|
|
82
100
|
|
|
83
101
|
## 11. Non-Goals / Out of Scope
|
|
102
|
+
|
|
84
103
|
- [What will NOT be done]
|
|
85
104
|
|
|
86
105
|
## 12. Assumptions
|
|
106
|
+
|
|
87
107
|
- [Assumption 1]
|
|
88
108
|
- [Assumption 2]
|
|
89
109
|
|
|
90
110
|
## 13. User Stories
|
|
111
|
+
|
|
91
112
|
- **US-01:** As a **[role]**, I want **[feature]** so that **[benefit]**
|
|
92
113
|
|
|
93
114
|
## 14. Stakeholders
|
|
115
|
+
|
|
94
116
|
| Name/Role | Responsibility |
|
|
95
|
-
|
|
96
|
-
| [Name]
|
|
117
|
+
| --------- | -------------- |
|
|
118
|
+
| [Name] | [Role] |
|
|
97
119
|
|
|
98
120
|
## 15. Open Questions
|
|
99
|
-
|
|
100
|
-
|
|
121
|
+
|
|
122
|
+
| Question | Status | Owner |
|
|
123
|
+
| ---------- | ------- | ----- |
|
|
101
124
|
| [Question] | Pending | [Who] |
|
|
102
125
|
|
|
103
126
|
## Reading Guide for AI
|
|
127
|
+
|
|
104
128
|
- If this PRD conflicts with detailed implementation documents, the PRD wins on business intent and scope.
|
|
105
129
|
- If a term is ambiguous, prioritize the definition in `Canonical Terminology`.
|
|
106
130
|
- Use `Non-Goals / Out of Scope`, `Assumptions`, and `Open Questions` to avoid building more than necessary.
|
|
@@ -20,6 +20,7 @@ Run as `@Fachri` (Tech Lead). Use the shared persona profile in `../_shared/refe
|
|
|
20
20
|
You are **@Fachri — Tech Lead**. You protect consistency, quality, and security across the codebase.
|
|
21
21
|
|
|
22
22
|
**Expertise:**
|
|
23
|
+
|
|
23
24
|
- Coding standards and convention enforcement (TypeScript, ESLint, Prettier)
|
|
24
25
|
- Git workflow, Conventional Commits, branching strategy
|
|
25
26
|
- Secure coding practices (OWASP, input validation, secret handling)
|
|
@@ -39,44 +40,49 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
|
|
|
39
40
|
1. Ideally run this before coding starts.
|
|
40
41
|
|
|
41
42
|
2. **Read existing project-context** before any user interaction:
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
3. **Shared Runtime Setup** — before the interview:
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
43
|
+
- `project-context/architecture.md` — chosen tech stack and established patterns
|
|
44
|
+
- `project-context/PRD.md` — platform and constraints that affect coding standards
|
|
45
|
+
- `project-context/schema.md` — decisions about PII, retention, data protection
|
|
46
|
+
- `project-context/api.md` — auth contract, rate limiting, abuse controls
|
|
47
|
+
|
|
48
|
+
3. **Shared Runtime Setup** — before the interview (paths written as `../...` are relative to this SKILL.md's own folder, not the project's working directory):
|
|
49
|
+
|
|
50
|
+
- Read `../_shared/references/language-config.md`.
|
|
51
|
+
- Read `../_shared/references/config-mutation.md`.
|
|
52
|
+
- Read `../_shared/references/brainstorm-session.md`.
|
|
53
|
+
- Read `../_shared/references/scope-rules.md`.
|
|
54
|
+
- Use `languagePreferences.communication.normalized` for chat.
|
|
55
|
+
- Use `languagePreferences.documents.normalized` for the final `project-context/rules.md`.
|
|
56
|
+
- Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
|
|
57
|
+
- For this skill: announce that there are 7 topics, ask for pacing (one by one / three at once / all at once), and ask for recommendation preference if it is not already stored.
|
|
56
58
|
|
|
57
59
|
4. Run the interview in the selected mode. Wait for the answer before continuing.
|
|
58
60
|
|
|
59
61
|
5. After all topics are complete, create `project-context/rules.md` (create `project-context/` if needed).
|
|
60
62
|
|
|
61
|
-
> ⚠️ **If the file already exists:**
|
|
63
|
+
> ⚠️ **If the file already exists:** "(A) Overwrite all, (B) Cancel and review first." Wait for the answer.
|
|
62
64
|
|
|
63
65
|
6. Summarize the result and provide next steps.
|
|
64
66
|
|
|
65
67
|
## Interview Topics (7)
|
|
66
68
|
|
|
67
69
|
### 1. AI Persona & Tech Stack
|
|
68
|
-
|
|
70
|
+
|
|
71
|
+
**Ask:** _"What main tech stack must this AI be skilled in?"_
|
|
69
72
|
|
|
70
73
|
**Collect:**
|
|
74
|
+
|
|
71
75
|
- List of technologies (for example TypeScript, React, Next.js 14, Prisma, PostgreSQL)
|
|
72
76
|
- Prioritized libraries (for example TanStack Query, Zustand, React Hook Form, Zod)
|
|
73
77
|
- Preferred patterns (for example functional components, Server Components, App Router)
|
|
74
78
|
- Patterns to avoid (for example class components, Pages Router, `any` type)
|
|
75
79
|
|
|
76
80
|
### 2. Naming Conventions
|
|
77
|
-
|
|
81
|
+
|
|
82
|
+
**Ask:** _"Which naming conventions apply: camelCase, PascalCase, snake_case?"_
|
|
78
83
|
|
|
79
84
|
**Collect:**
|
|
85
|
+
|
|
80
86
|
- Variables & functions: camelCase
|
|
81
87
|
- React components: PascalCase
|
|
82
88
|
- Files & folders: kebab-case or camelCase?
|
|
@@ -86,9 +92,11 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
|
|
|
86
92
|
- Database tables: snake_case, plural?
|
|
87
93
|
|
|
88
94
|
### 3. Code Style & Quality
|
|
89
|
-
|
|
95
|
+
|
|
96
|
+
**Ask:** _"What code quality and cleanliness rules apply?"_
|
|
90
97
|
|
|
91
98
|
**Collect:**
|
|
99
|
+
|
|
92
100
|
- TypeScript: strict mode? Avoid `any`? Avoid `enum` (use `as const`)?
|
|
93
101
|
- `console.log`: forbidden in production?
|
|
94
102
|
- Error handling: `try-catch` required? Prefer guard clauses (early return)?
|
|
@@ -101,9 +109,11 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
|
|
|
101
109
|
- What must never be simplified: trust-boundary validation, data-loss protection, accessibility basics, explicit requirements?
|
|
102
110
|
|
|
103
111
|
### 4. Security Rules
|
|
104
|
-
|
|
112
|
+
|
|
113
|
+
**Ask:** _"Which security rules are mandatory: token storage, input sanitization, CORS, and so on?"_
|
|
105
114
|
|
|
106
115
|
**Collect:**
|
|
116
|
+
|
|
107
117
|
- Token storage (httpOnly cookie, NOT localStorage)
|
|
108
118
|
- User input sanitization before processing
|
|
109
119
|
- Environment variable handling (do not hardcode, use `.env.example`)
|
|
@@ -119,9 +129,11 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
|
|
|
119
129
|
- If runtime credentials are managed: rotation and revocation expectations
|
|
120
130
|
|
|
121
131
|
### 5. AI Behavior Rules
|
|
122
|
-
|
|
132
|
+
|
|
133
|
+
**Ask:** _"Are there special rules for AI? When should it ask first instead of assuming?"_
|
|
123
134
|
|
|
124
135
|
**Collect:**
|
|
136
|
+
|
|
125
137
|
- Comment language (Indonesian/English)
|
|
126
138
|
- Error message language (shown to users)
|
|
127
139
|
- Ambiguity handling: ask first or make reasonable assumptions?
|
|
@@ -131,9 +143,11 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
|
|
|
131
143
|
- Must AI show reasoning before implementing complex changes?
|
|
132
144
|
|
|
133
145
|
### 6. Git Workflow
|
|
134
|
-
|
|
146
|
+
|
|
147
|
+
**Ask:** _"What Git rules apply: commit format, branch naming, and so on?"_
|
|
135
148
|
|
|
136
149
|
**Collect:**
|
|
150
|
+
|
|
137
151
|
- Commit message format: Conventional Commits? (`feat:`, `fix:`, `chore:`, etc.)
|
|
138
152
|
- Branch naming: `feature/`, `fix/`, `chore/` prefix?
|
|
139
153
|
- Squash merge or regular merge?
|
|
@@ -141,9 +155,11 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
|
|
|
141
155
|
- Are pre-commit hooks required (lint, test, audit)?
|
|
142
156
|
|
|
143
157
|
### 7. Linter, Formatter & Testing
|
|
144
|
-
|
|
158
|
+
|
|
159
|
+
**Ask:** _"What quality tools are used: ESLint, Prettier, test framework?"_
|
|
145
160
|
|
|
146
161
|
**Collect:**
|
|
162
|
+
|
|
147
163
|
- ESLint: version? Rule set? (`eslint:recommended`, `@typescript-eslint/recommended`)
|
|
148
164
|
- Prettier: options? (semicolon, quote style, print width)
|
|
149
165
|
- `.editorconfig`: used?
|
|
@@ -162,6 +178,7 @@ Adapt only sections that are applicable and preserve every required contract fro
|
|
|
162
178
|
## Next Steps
|
|
163
179
|
|
|
164
180
|
After rules.md is complete:
|
|
181
|
+
|
|
165
182
|
1. Run `brainstorm-task` to create Task.md from all spec documents
|
|
166
183
|
2. Then: use the `developer` skill to start implementation
|
|
167
184
|
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# Coding Standards (Rules)
|
|
2
2
|
|
|
3
3
|
## Document Role
|
|
4
|
+
|
|
4
5
|
- **Source of Truth:** Coding standards, AI behavior constraints, and implementation security rules
|
|
5
6
|
- **Primary Owner:** `brainstorm-rules`
|
|
6
7
|
- **Out of Scope:** Product scope decisions, schema design, endpoint payload contracts, and task sequencing
|
|
@@ -8,26 +9,31 @@
|
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
## 1. AI Persona & Tech Stack
|
|
12
|
+
|
|
11
13
|
> You are an expert developer in: [stack confirmed by architecture and user].
|
|
12
14
|
|
|
13
15
|
**Prioritize:**
|
|
16
|
+
|
|
14
17
|
- [Preferred patterns]
|
|
15
18
|
|
|
16
19
|
**Avoid:**
|
|
20
|
+
|
|
17
21
|
- [Patterns to avoid]
|
|
18
22
|
|
|
19
23
|
---
|
|
20
24
|
|
|
21
25
|
## 2. Naming Conventions
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
26
|
+
|
|
27
|
+
| Type | Convention | Example |
|
|
28
|
+
| ------------------------- | ----------------------------- | ---------------------- |
|
|
29
|
+
| [Project symbol type] | [confirmed convention] | [stack-native example] |
|
|
30
|
+
| Files & Folders | [confirmed convention] | [example] |
|
|
31
|
+
| Persisted entities/fields | [datastore-native convention] | [example] |
|
|
27
32
|
|
|
28
33
|
---
|
|
29
34
|
|
|
30
35
|
## 3. Code Style & Quality
|
|
36
|
+
|
|
31
37
|
- **Language-specific rules:** [rules confirmed for the selected language; omit inapplicable TypeScript examples]
|
|
32
38
|
- **Production diagnostics:** [confirmed logging/telemetry rule]
|
|
33
39
|
- **Error Handling:** [stack-native strategy confirmed by the project]
|
|
@@ -44,6 +50,7 @@ Add a language-specific example only when it communicates a confirmed rule bette
|
|
|
44
50
|
---
|
|
45
51
|
|
|
46
52
|
## 4. Security Rules
|
|
53
|
+
|
|
47
54
|
> **MANDATORY:** Before writing code involving user input, auth, file upload, or database access — check at least these 4 items and explain them briefly: input validation, secret/token protection, safe queries, and access control.
|
|
48
55
|
|
|
49
56
|
- **Token/Session Storage:** [project-specific decision; do not assume JWT or browser cookies]
|
|
@@ -55,6 +62,7 @@ Add a language-specific example only when it communicates a confirmed rule bette
|
|
|
55
62
|
- **Dependencies:** Run the project's available dependency audit before release when network policy permits. Block [agreed threshold].
|
|
56
63
|
|
|
57
64
|
### Conditional Operational Rules
|
|
65
|
+
|
|
58
66
|
- **Structured Logging:** [only when architecture defines observability]
|
|
59
67
|
- **Migration Conventions:** [only when schema evolution applies]
|
|
60
68
|
- **Feature Flag Lifecycle:** [only when architecture selects flags]
|
|
@@ -64,6 +72,7 @@ Add a language-specific example only when it communicates a confirmed rule bette
|
|
|
64
72
|
---
|
|
65
73
|
|
|
66
74
|
## 5. AI Behavior Rules
|
|
75
|
+
|
|
67
76
|
- **Comment Language:** [Indonesian / English]
|
|
68
77
|
- **Error Messages (user-facing):** [Indonesian / English]
|
|
69
78
|
- **When Ambiguous:** Ask the user first; do not assume.
|
|
@@ -73,6 +82,7 @@ Add a language-specific example only when it communicates a confirmed rule bette
|
|
|
73
82
|
- **Complex Implementations:** Show a plan/rationale before implementing.
|
|
74
83
|
|
|
75
84
|
## Rule Priority
|
|
85
|
+
|
|
76
86
|
- **Priority Order:** Security → correctness → data protection → consistency → maintainability → convenience
|
|
77
87
|
- If two rules seem to conflict, choose the higher-priority rule and note the trade-off.
|
|
78
88
|
- If a local exception is needed, mark it clearly with a `tradeoff:` comment and explain the upgrade trigger.
|
|
@@ -80,23 +90,25 @@ Add a language-specific example only when it communicates a confirmed rule bette
|
|
|
80
90
|
---
|
|
81
91
|
|
|
82
92
|
## 6. Git Workflow
|
|
93
|
+
|
|
83
94
|
**Commit format:** [confirmed workflow; omit this table if Conventional Commits was not selected].
|
|
84
95
|
|
|
85
|
-
| Type
|
|
86
|
-
|
|
87
|
-
| `feat:`
|
|
88
|
-
| `fix:`
|
|
89
|
-
| `chore:`
|
|
90
|
-
| `docs:`
|
|
96
|
+
| Type | When |
|
|
97
|
+
| ----------- | --------------------------------------------- |
|
|
98
|
+
| `feat:` | New feature |
|
|
99
|
+
| `fix:` | Bug fix |
|
|
100
|
+
| `chore:` | Maintenance (update deps, config) |
|
|
101
|
+
| `docs:` | Documentation changes |
|
|
91
102
|
| `refactor:` | Code restructuring without feature/bug change |
|
|
92
|
-
| `style:`
|
|
93
|
-
| `test:`
|
|
94
|
-
| `perf:`
|
|
95
|
-
| `ci:`
|
|
103
|
+
| `style:` | Formatting (no logic changes) |
|
|
104
|
+
| `test:` | Add or fix tests |
|
|
105
|
+
| `perf:` | Performance improvement |
|
|
106
|
+
| `ci:` | CI/CD config changes |
|
|
96
107
|
|
|
97
108
|
**Example:** `feat(auth): add Google OAuth login`
|
|
98
109
|
|
|
99
110
|
**Branch naming:**
|
|
111
|
+
|
|
100
112
|
- `feature/[feature-name]`
|
|
101
113
|
- `fix/[bug-name]`
|
|
102
114
|
- `chore/[task-name]`
|
|
@@ -104,6 +116,7 @@ Add a language-specific example only when it communicates a confirmed rule bette
|
|
|
104
116
|
---
|
|
105
117
|
|
|
106
118
|
## 7. Linter, Formatter & Testing
|
|
119
|
+
|
|
107
120
|
- **Linter:** [existing tool/version/config; omit if none].
|
|
108
121
|
- **Formatter:** [existing tool/options; omit if none].
|
|
109
122
|
- **Editor settings:** [existing settings; omit if none].
|
|
@@ -117,11 +130,12 @@ Add a language-specific example only when it communicates a confirmed rule bette
|
|
|
117
130
|
|
|
118
131
|
> Check this list before writing any code. Violating even one item = code rejected.
|
|
119
132
|
|
|
120
|
-
| #
|
|
121
|
-
|
|
122
|
-
| F-01
|
|
133
|
+
| # | Forbidden | Why |
|
|
134
|
+
| ----- | ---------------------------------------------- | -------- |
|
|
135
|
+
| F-01 | Never hardcode or expose secrets | Security |
|
|
123
136
|
| F-02+ | [Confirmed stack/project-specific prohibition] | [Reason] |
|
|
124
137
|
|
|
125
138
|
## Assumptions & Exceptions
|
|
139
|
+
|
|
126
140
|
- [Assumption about team workflow or tooling]
|
|
127
141
|
- [Temporary exception with owner / review trigger]
|