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.
Files changed (64) hide show
  1. package/.agents/macca-lock.json +1 -1
  2. package/.agents/skills/_shared/references/brainstorm-session.md +5 -5
  3. package/.agents/skills/_shared/references/fix-mode.md +18 -3
  4. package/.agents/skills/_shared/references/human-loop.md +1 -1
  5. package/.agents/skills/_shared/references/invocation-policy.md +20 -20
  6. package/.agents/skills/_shared/references/language-config.md +7 -5
  7. package/.agents/skills/_shared/references/output-ownership.md +11 -11
  8. package/.agents/skills/_shared/references/scope-rules.md +1 -1
  9. package/.agents/skills/_shared/references/skill-catalog.md +20 -20
  10. package/.agents/skills/_shared/scripts/validate-skills.py +37 -15
  11. package/.agents/skills/add-feature/SKILL.md +11 -3
  12. package/.agents/skills/antislop-copywriting/SKILL.md +372 -0
  13. package/.agents/skills/brainstorm-api/SKILL.md +33 -19
  14. package/.agents/skills/brainstorm-api/assets/api.template.md +35 -15
  15. package/.agents/skills/brainstorm-architecture/SKILL.md +40 -18
  16. package/.agents/skills/brainstorm-architecture/assets/architecture.template.md +44 -25
  17. package/.agents/skills/brainstorm-prd/SKILL.md +52 -20
  18. package/.agents/skills/brainstorm-prd/assets/PRD.template.md +47 -23
  19. package/.agents/skills/brainstorm-rules/SKILL.md +39 -22
  20. package/.agents/skills/brainstorm-rules/assets/rules.template.md +32 -18
  21. package/.agents/skills/brainstorm-schema/SKILL.md +23 -11
  22. package/.agents/skills/brainstorm-schema/assets/schema.template.md +25 -10
  23. package/.agents/skills/brainstorm-styleguide/SKILL.md +40 -22
  24. package/.agents/skills/brainstorm-styleguide/assets/StyleGuide.template.md +78 -60
  25. package/.agents/skills/brainstorm-task/SKILL.md +29 -14
  26. package/.agents/skills/brainstorm-task/assets/Task.template.md +29 -18
  27. package/.agents/skills/bug-fix/SKILL.md +39 -8
  28. package/.agents/skills/code-review/SKILL.md +9 -7
  29. package/.agents/skills/code-review/references/review-checklist.md +21 -10
  30. package/.agents/skills/developer/SKILL.md +10 -0
  31. package/.agents/skills/developer/references/execute-task.md +13 -7
  32. package/.agents/skills/developer/references/onboarding.md +1 -1
  33. package/.agents/skills/help/SKILL.md +39 -23
  34. package/.agents/skills/meet/SKILL.md +11 -4
  35. package/.agents/skills/quick-dev/SKILL.md +29 -22
  36. package/.agents/skills/release-readiness/SKILL.md +19 -13
  37. package/.agents/skills/skill-creator/LICENSE.txt +202 -0
  38. package/.agents/skills/skill-creator/SKILL.md +485 -0
  39. package/.agents/skills/skill-creator/agents/analyzer.md +274 -0
  40. package/.agents/skills/skill-creator/agents/comparator.md +202 -0
  41. package/.agents/skills/skill-creator/agents/grader.md +223 -0
  42. package/.agents/skills/skill-creator/assets/eval_review.html +146 -0
  43. package/.agents/skills/skill-creator/eval-viewer/generate_review.py +471 -0
  44. package/.agents/skills/skill-creator/eval-viewer/viewer.html +1325 -0
  45. package/.agents/skills/skill-creator/references/schemas.md +441 -0
  46. package/.agents/skills/skill-creator/scripts/__init__.py +0 -0
  47. package/.agents/skills/skill-creator/scripts/aggregate_benchmark.py +401 -0
  48. package/.agents/skills/skill-creator/scripts/generate_report.py +326 -0
  49. package/.agents/skills/skill-creator/scripts/improve_description.py +247 -0
  50. package/.agents/skills/skill-creator/scripts/package_skill.py +136 -0
  51. package/.agents/skills/skill-creator/scripts/quick_validate.py +103 -0
  52. package/.agents/skills/skill-creator/scripts/run_eval.py +310 -0
  53. package/.agents/skills/skill-creator/scripts/run_loop.py +328 -0
  54. package/.agents/skills/skill-creator/scripts/utils.py +47 -0
  55. package/.agents/skills/spec-audit/SKILL.md +33 -4
  56. package/.agents/skills/spec-compliance/SKILL.md +36 -21
  57. package/.agents/skills/spec-init/SKILL.md +31 -17
  58. package/README.md +165 -129
  59. package/bin/macca-method.js +1378 -1077
  60. package/package.json +40 -40
  61. package/scripts/run-skill-validator.js +27 -9
  62. package/scripts/test-install.js +611 -337
  63. package/scripts/test-upgrade-legacy.js +131 -76
  64. 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
- 4. Use `languagePreferences.communication.normalized` for chat.
44
- 5. Use `languagePreferences.documents.normalized` for the final `project-context/PRD.md`.
45
- 6. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
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
- - Check whether `project-context/PRD.md` already exists to avoid duplication
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
- *"What is the main goal and long-term vision of this project?"*
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
- *"Who are the target users? There may be multiple personas."*
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
- *"What problem does this project solve?"*
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
- *"What are the main features?"*
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
- *"What business rules apply? For example: min/max values, pricing rules, special conditions."*
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
- *"Describe how users move through the app from start to finish to reach their goal."*
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
- *"What is the target platform: web, mobile, or both? Any design references or technical preferences?"*
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
- *"Are there performance, security, or availability targets?"*
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
- *"What is the minimum definition of success for this project?"*
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
- *"For each main feature, what conditions must be met for it to count as 'done'?"*
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
- *"What is intentionally not included?"*
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
- *"What do you assume is true but are not sure about? For example: 'Users have stable internet.'"*
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
- *"Give user stories in this format: 'As a [role], I want [feature] so that [benefit].'"*
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
- *"Who is involved in or has a stake in this project?"*
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
- *"Are there unresolved decisions or known risks?"*
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
- | Term | Meaning |
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
- | Persona | Description | Role |
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
- | ID | Feature | Description | Priority |
35
- |----|---------|-------------|----------|
36
- | FEAT-01 | [Feature] | [Description] | High |
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
- | Situation | Expected User Experience | Recovery |
52
- |-----------|--------------------------|----------|
53
- | [Dependency/data unavailable] | [behavior] | [retry/fallback/support] |
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
- | ID | Category | Requirement | Target |
63
- |----|----------|-------------|--------|
64
- | NFR-01 | Performance | Page load time | < 3 seconds |
65
- | NFR-02 | Security | [Requirement] | [Target] |
66
- | NFR-03 | Scalability | Concurrent users | [Count] |
67
- | NFR-04 | Accessibility | [Requirement] | [Target] |
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
- | Metric | Baseline | Target | Timeframe | Measurement Source | Owner |
71
- |--------|----------|--------|-----------|--------------------|-------|
72
- | [Metric] | [current/unknown] | [target] | [period] | [analytics/report] | [owner] |
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] | [Role] |
117
+ | --------- | -------------- |
118
+ | [Name] | [Role] |
97
119
 
98
120
  ## 15. Open Questions
99
- | Question | Status | Owner |
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
- - `project-context/architecture.md` — chosen tech stack and established patterns
43
- - `project-context/PRD.md` — platform and constraints that affect coding standards
44
- - `project-context/schema.md` — decisions about PII, retention, data protection
45
- - `project-context/api.md` — auth contract, rate limiting, abuse controls
46
-
47
- 3. **Shared Runtime Setup** — before the interview:
48
- - Read `../_shared/references/language-config.md`.
49
- - Read `../_shared/references/config-mutation.md`.
50
- - Read `../_shared/references/brainstorm-session.md`.
51
- - Read `../_shared/references/scope-rules.md`.
52
- - Use `languagePreferences.communication.normalized` for chat.
53
- - Use `languagePreferences.documents.normalized` for the final `project-context/rules.md`.
54
- - Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
55
- - 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.
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:** ask the user before overwriting — "(A) Replace the entire file, (B) cancel and review first." Wait for the answer.
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
- **Ask:** *"What main tech stack must this AI be skilled in?"*
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
- **Ask:** *"Which naming conventions apply: camelCase, PascalCase, snake_case?"*
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
- **Ask:** *"What code quality and cleanliness rules apply?"*
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
- **Ask:** *"Which security rules are mandatory: token storage, input sanitization, CORS, and so on?"*
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
- **Ask:** *"Are there special rules for AI? When should it ask first instead of assuming?"*
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
- **Ask:** *"What Git rules apply: commit format, branch naming, and so on?"*
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
- **Ask:** *"What quality tools are used: ESLint, Prettier, test framework?"*
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
- | Type | Convention | Example |
23
- |------|------------|---------|
24
- | [Project symbol type] | [confirmed convention] | [stack-native example] |
25
- | Files & Folders | [confirmed convention] | [example] |
26
- | Persisted entities/fields | [datastore-native convention] | [example] |
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 | When |
86
- |------|------|
87
- | `feat:` | New feature |
88
- | `fix:` | Bug fix |
89
- | `chore:` | Maintenance (update deps, config) |
90
- | `docs:` | Documentation changes |
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:` | Formatting (no logic changes) |
93
- | `test:` | Add or fix tests |
94
- | `perf:` | Performance improvement |
95
- | `ci:` | CI/CD config changes |
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
- | # | Forbidden | Why |
121
- |---|-----------|-----|
122
- | F-01 | Never hardcode or expose secrets | Security |
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]