moicle 1.1.2 → 1.2.0
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.
|
@@ -0,0 +1,473 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: architect-review
|
|
3
|
+
description: Architecture compliance review workflow. Reviews codebase against specific architecture guidelines. Use when user says "architect-review", "architecture review", "review architecture", "check architecture compliance".
|
|
4
|
+
args: ARCHITECTURE_NAME
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Architecture Review Workflow
|
|
8
|
+
|
|
9
|
+
Review codebase compliance against a specific architecture guideline.
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# With architecture name - review immediately
|
|
15
|
+
/architect-review clean-architecture
|
|
16
|
+
/architect-review react-frontend
|
|
17
|
+
/architect-review go-backend
|
|
18
|
+
|
|
19
|
+
# Without argument - will ask user to select
|
|
20
|
+
/architect-review
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Supported Architectures
|
|
24
|
+
|
|
25
|
+
Check for architecture files in these locations (in order):
|
|
26
|
+
|
|
27
|
+
1. **Project-specific**: `.claude/architecture/`
|
|
28
|
+
2. **Global**: `~/.claude/architecture/`
|
|
29
|
+
|
|
30
|
+
### Built-in Architectures
|
|
31
|
+
|
|
32
|
+
| Name | File | Description |
|
|
33
|
+
|------|------|-------------|
|
|
34
|
+
| `clean-architecture` | `clean-architecture.md` | Clean Architecture layers & principles |
|
|
35
|
+
| `react-frontend` | `react-frontend.md` | React + Vite + TypeScript |
|
|
36
|
+
| `go-backend` | `go-backend.md` | Go + Gin |
|
|
37
|
+
| `laravel-backend` | `laravel-backend.md` | Laravel + PHP |
|
|
38
|
+
| `remix-fullstack` | `remix-fullstack.md` | Remix fullstack |
|
|
39
|
+
| `flutter-mobile` | `flutter-mobile.md` | Flutter + Dart + Riverpod |
|
|
40
|
+
| `monorepo` | `monorepo.md` | Monorepo structure |
|
|
41
|
+
|
|
42
|
+
### Name Aliases
|
|
43
|
+
|
|
44
|
+
Support short names for convenience:
|
|
45
|
+
|
|
46
|
+
| Alias | Maps to |
|
|
47
|
+
|-------|---------|
|
|
48
|
+
| `clean` | `clean-architecture` |
|
|
49
|
+
| `react` | `react-frontend` |
|
|
50
|
+
| `go` | `go-backend` |
|
|
51
|
+
| `laravel` | `laravel-backend` |
|
|
52
|
+
| `remix` | `remix-fullstack` |
|
|
53
|
+
| `flutter` | `flutter-mobile` |
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Phase 0: RESOLVE ARCHITECTURE
|
|
58
|
+
|
|
59
|
+
**Goal**: Determine which architecture to review against
|
|
60
|
+
|
|
61
|
+
### If argument provided (`/architect-review {ARCHITECTURE_NAME}`)
|
|
62
|
+
|
|
63
|
+
1. Normalize the name using alias table above
|
|
64
|
+
2. Search for the architecture file:
|
|
65
|
+
- First check: `.claude/architecture/{name}.md`
|
|
66
|
+
- Then check: `~/.claude/architecture/{name}.md`
|
|
67
|
+
3. If file found → proceed to Phase 1
|
|
68
|
+
4. If file NOT found → **REJECT** with message:
|
|
69
|
+
|
|
70
|
+
```markdown
|
|
71
|
+
## ❌ Architecture Not Supported
|
|
72
|
+
|
|
73
|
+
Architecture `{ARCHITECTURE_NAME}` is not available.
|
|
74
|
+
|
|
75
|
+
### Available architectures:
|
|
76
|
+
[List all .md files found in both architecture directories]
|
|
77
|
+
|
|
78
|
+
### To add a custom architecture:
|
|
79
|
+
Place your architecture guideline file at:
|
|
80
|
+
- Project: `.claude/architecture/{name}.md`
|
|
81
|
+
- Global: `~/.claude/architecture/{name}.md`
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**STOP HERE. Do not proceed with review.**
|
|
85
|
+
|
|
86
|
+
### If NO argument provided (`/architect-review`)
|
|
87
|
+
|
|
88
|
+
1. Scan both architecture directories for available `.md` files:
|
|
89
|
+
```bash
|
|
90
|
+
ls .claude/architecture/*.md 2>/dev/null
|
|
91
|
+
ls ~/.claude/architecture/*.md 2>/dev/null
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
2. If NO architecture files found → **REJECT**:
|
|
95
|
+
```markdown
|
|
96
|
+
## ❌ No Architecture Guidelines Found
|
|
97
|
+
|
|
98
|
+
No architecture guideline files found in:
|
|
99
|
+
- `.claude/architecture/`
|
|
100
|
+
- `~/.claude/architecture/`
|
|
101
|
+
|
|
102
|
+
Install moicle to get built-in architecture guidelines:
|
|
103
|
+
```bash
|
|
104
|
+
npm install -g moicle && moicle install
|
|
105
|
+
```
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**STOP HERE.**
|
|
109
|
+
|
|
110
|
+
3. If files found → **ASK USER** to select which architecture to review against. Present the list of available architectures.
|
|
111
|
+
|
|
112
|
+
4. User selects → proceed to Phase 1
|
|
113
|
+
|
|
114
|
+
### Gate
|
|
115
|
+
- [ ] Architecture name resolved
|
|
116
|
+
- [ ] Architecture file exists and is readable
|
|
117
|
+
- [ ] Architecture guideline content loaded
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Phase 1: LOAD GUIDELINE
|
|
122
|
+
|
|
123
|
+
**Goal**: Read and understand the architecture guideline
|
|
124
|
+
|
|
125
|
+
### Actions
|
|
126
|
+
|
|
127
|
+
1. **Read the architecture file** completely
|
|
128
|
+
2. Extract key review criteria:
|
|
129
|
+
- Layer structure & boundaries
|
|
130
|
+
- Dependency rules (what depends on what)
|
|
131
|
+
- Directory/folder structure conventions
|
|
132
|
+
- Naming conventions
|
|
133
|
+
- Design patterns required
|
|
134
|
+
- Data flow patterns
|
|
135
|
+
- Testing patterns
|
|
136
|
+
- Anti-patterns to avoid
|
|
137
|
+
|
|
138
|
+
### Output
|
|
139
|
+
```markdown
|
|
140
|
+
## Architecture Guideline Summary
|
|
141
|
+
|
|
142
|
+
### Architecture: {name}
|
|
143
|
+
### Source: {file path}
|
|
144
|
+
|
|
145
|
+
### Key Principles
|
|
146
|
+
1. {principle 1}
|
|
147
|
+
2. {principle 2}
|
|
148
|
+
3. {principle 3}
|
|
149
|
+
|
|
150
|
+
### Layer Structure
|
|
151
|
+
{layer diagram or description from guideline}
|
|
152
|
+
|
|
153
|
+
### Dependency Rules
|
|
154
|
+
- {rule 1}
|
|
155
|
+
- {rule 2}
|
|
156
|
+
|
|
157
|
+
### Required Patterns
|
|
158
|
+
- {pattern 1}
|
|
159
|
+
- {pattern 2}
|
|
160
|
+
|
|
161
|
+
### Directory Structure
|
|
162
|
+
{expected structure from guideline}
|
|
163
|
+
|
|
164
|
+
### Naming Conventions
|
|
165
|
+
- {convention 1}
|
|
166
|
+
- {convention 2}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Gate
|
|
170
|
+
- [ ] Guideline fully read
|
|
171
|
+
- [ ] Key criteria extracted
|
|
172
|
+
- [ ] Review checklist prepared
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## Phase 2: SCAN CODEBASE
|
|
177
|
+
|
|
178
|
+
**Goal**: Analyze current codebase structure against the architecture
|
|
179
|
+
|
|
180
|
+
### Actions
|
|
181
|
+
|
|
182
|
+
1. **Map project structure**:
|
|
183
|
+
```bash
|
|
184
|
+
# Get overall structure (exclude common non-source dirs)
|
|
185
|
+
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.go" -o -name "*.php" -o -name "*.dart" -o -name "*.js" -o -name "*.jsx" \) \
|
|
186
|
+
-not -path "*/node_modules/*" -not -path "*/vendor/*" -not -path "*/.dart_tool/*" -not -path "*/build/*" -not -path "*/dist/*" | head -100
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
2. **Check directory structure** against guideline:
|
|
190
|
+
- Does folder structure match expected layout?
|
|
191
|
+
- Are there unexpected directories?
|
|
192
|
+
- Are required directories missing?
|
|
193
|
+
|
|
194
|
+
3. **Check layer boundaries**:
|
|
195
|
+
- Read key files in each layer
|
|
196
|
+
- Check imports/dependencies
|
|
197
|
+
- Verify dependency direction follows guideline rules
|
|
198
|
+
|
|
199
|
+
4. **Check naming conventions**:
|
|
200
|
+
- File names follow convention?
|
|
201
|
+
- Class/function names follow convention?
|
|
202
|
+
- Module/package names follow convention?
|
|
203
|
+
|
|
204
|
+
5. **Check design patterns**:
|
|
205
|
+
- Required patterns implemented?
|
|
206
|
+
- Anti-patterns present?
|
|
207
|
+
- Correct use of dependency injection?
|
|
208
|
+
|
|
209
|
+
6. **Check data flow**:
|
|
210
|
+
- Data flows in correct direction per guideline?
|
|
211
|
+
- Proper DTOs/entities at layer boundaries?
|
|
212
|
+
|
|
213
|
+
### Output
|
|
214
|
+
```markdown
|
|
215
|
+
## Codebase Scan Results
|
|
216
|
+
|
|
217
|
+
### Directory Structure
|
|
218
|
+
- Expected: {from guideline}
|
|
219
|
+
- Actual: {current structure}
|
|
220
|
+
- Match: [✅ Yes / ⚠️ Partial / ❌ No]
|
|
221
|
+
|
|
222
|
+
### Files Analyzed: {count}
|
|
223
|
+
### Layers Identified: {list}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Gate
|
|
227
|
+
- [ ] Project structure mapped
|
|
228
|
+
- [ ] Key files identified per layer
|
|
229
|
+
- [ ] Dependencies analyzed
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Phase 3: REVIEW
|
|
234
|
+
|
|
235
|
+
**Goal**: Detailed compliance review with findings
|
|
236
|
+
|
|
237
|
+
### Review Dimensions
|
|
238
|
+
|
|
239
|
+
#### 1. Layer Boundaries ⚠️ CRITICAL
|
|
240
|
+
|
|
241
|
+
- [ ] Each layer only depends on allowed layers (per guideline)
|
|
242
|
+
- [ ] No circular dependencies between layers
|
|
243
|
+
- [ ] Infrastructure doesn't leak into domain
|
|
244
|
+
- [ ] Presentation doesn't directly access data layer
|
|
245
|
+
- [ ] Business logic is in the correct layer
|
|
246
|
+
|
|
247
|
+
#### 2. Directory Structure
|
|
248
|
+
|
|
249
|
+
- [ ] Folders match guideline layout
|
|
250
|
+
- [ ] Files are in correct locations
|
|
251
|
+
- [ ] No misplaced files across layers
|
|
252
|
+
- [ ] Required directories exist
|
|
253
|
+
|
|
254
|
+
#### 3. Naming Conventions
|
|
255
|
+
|
|
256
|
+
- [ ] Files follow naming pattern from guideline
|
|
257
|
+
- [ ] Classes/structs/types follow naming convention
|
|
258
|
+
- [ ] Functions/methods follow naming convention
|
|
259
|
+
- [ ] Variables follow naming convention
|
|
260
|
+
- [ ] Constants follow naming convention
|
|
261
|
+
|
|
262
|
+
#### 4. Design Patterns
|
|
263
|
+
|
|
264
|
+
- [ ] Required patterns are implemented (Repository, UseCase, etc.)
|
|
265
|
+
- [ ] Patterns are used correctly
|
|
266
|
+
- [ ] No anti-patterns present
|
|
267
|
+
- [ ] Dependency injection done properly
|
|
268
|
+
|
|
269
|
+
#### 5. Data Flow
|
|
270
|
+
|
|
271
|
+
- [ ] Data flows in correct direction
|
|
272
|
+
- [ ] Proper DTOs at boundaries
|
|
273
|
+
- [ ] No domain entities exposed to presentation
|
|
274
|
+
- [ ] Proper mapping between layers
|
|
275
|
+
|
|
276
|
+
#### 6. Testing Structure
|
|
277
|
+
|
|
278
|
+
- [ ] Tests follow guideline test structure
|
|
279
|
+
- [ ] Test files in correct locations
|
|
280
|
+
- [ ] Mocking follows guideline patterns
|
|
281
|
+
- [ ] Test naming conventions followed
|
|
282
|
+
|
|
283
|
+
### Severity Levels
|
|
284
|
+
|
|
285
|
+
| Level | Description | Action |
|
|
286
|
+
|-------|-------------|--------|
|
|
287
|
+
| 🚨 **Critical** | Core architecture violation | Must fix |
|
|
288
|
+
| ⚠️ **Major** | Significant deviation from guideline | Should fix |
|
|
289
|
+
| ℹ️ **Minor** | Small inconsistency | Nice to fix |
|
|
290
|
+
| 💡 **Suggestion** | Improvement opportunity | Optional |
|
|
291
|
+
|
|
292
|
+
### Gate
|
|
293
|
+
- [ ] All 6 dimensions reviewed
|
|
294
|
+
- [ ] Findings categorized by severity
|
|
295
|
+
- [ ] Specific file:line references provided
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## Phase 4: REPORT
|
|
300
|
+
|
|
301
|
+
**Goal**: Generate comprehensive architecture compliance report
|
|
302
|
+
|
|
303
|
+
### Report Template
|
|
304
|
+
|
|
305
|
+
```markdown
|
|
306
|
+
# Architecture Compliance Report
|
|
307
|
+
|
|
308
|
+
## Overview
|
|
309
|
+
- **Architecture**: {name}
|
|
310
|
+
- **Guideline**: {file path}
|
|
311
|
+
- **Project**: {project name/path}
|
|
312
|
+
- **Date**: {date}
|
|
313
|
+
- **Overall Score**: {A/B/C/D/F}
|
|
314
|
+
|
|
315
|
+
## Score Breakdown
|
|
316
|
+
|
|
317
|
+
| Dimension | Score | Status |
|
|
318
|
+
|-----------|-------|--------|
|
|
319
|
+
| Layer Boundaries | {1-10} | {✅/⚠️/❌} |
|
|
320
|
+
| Directory Structure | {1-10} | {✅/⚠️/❌} |
|
|
321
|
+
| Naming Conventions | {1-10} | {✅/⚠️/❌} |
|
|
322
|
+
| Design Patterns | {1-10} | {✅/⚠️/❌} |
|
|
323
|
+
| Data Flow | {1-10} | {✅/⚠️/❌} |
|
|
324
|
+
| Testing Structure | {1-10} | {✅/⚠️/❌} |
|
|
325
|
+
|
|
326
|
+
## Grading Scale
|
|
327
|
+
- **A (9-10)**: Excellent compliance, follows guideline closely
|
|
328
|
+
- **B (7-8)**: Good compliance, minor deviations
|
|
329
|
+
- **C (5-6)**: Moderate compliance, notable gaps
|
|
330
|
+
- **D (3-4)**: Poor compliance, significant violations
|
|
331
|
+
- **F (1-2)**: Non-compliant, does not follow architecture
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## 🚨 Critical Violations ({count})
|
|
336
|
+
|
|
337
|
+
### Violation 1: {title}
|
|
338
|
+
- **Dimension**: {Layer Boundaries / Design Patterns / etc.}
|
|
339
|
+
- **Location**: `{file}:{line}`
|
|
340
|
+
- **Guideline Says**: {what the guideline requires}
|
|
341
|
+
- **Actual**: {what the code does}
|
|
342
|
+
- **Impact**: {why this matters}
|
|
343
|
+
- **Fix**:
|
|
344
|
+
```
|
|
345
|
+
{suggested fix or approach}
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
### Violation 2: ...
|
|
349
|
+
|
|
350
|
+
---
|
|
351
|
+
|
|
352
|
+
## ⚠️ Major Issues ({count})
|
|
353
|
+
|
|
354
|
+
### Issue 1: {title}
|
|
355
|
+
- **Dimension**: {dimension}
|
|
356
|
+
- **Location**: `{file}:{line}`
|
|
357
|
+
- **Guideline Says**: {requirement}
|
|
358
|
+
- **Actual**: {current state}
|
|
359
|
+
- **Fix**: {how to fix}
|
|
360
|
+
|
|
361
|
+
---
|
|
362
|
+
|
|
363
|
+
## ℹ️ Minor Issues ({count})
|
|
364
|
+
|
|
365
|
+
- [{file}:{line}] - {description}
|
|
366
|
+
- [{file}:{line}] - {description}
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## 💡 Suggestions ({count})
|
|
371
|
+
|
|
372
|
+
- {suggestion 1}
|
|
373
|
+
- {suggestion 2}
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
## Compliance Summary
|
|
378
|
+
|
|
379
|
+
### What's Done Well ✅
|
|
380
|
+
- {strength 1}
|
|
381
|
+
- {strength 2}
|
|
382
|
+
- {strength 3}
|
|
383
|
+
|
|
384
|
+
### What Needs Improvement ⚠️
|
|
385
|
+
- {area 1}
|
|
386
|
+
- {area 2}
|
|
387
|
+
|
|
388
|
+
### Recommended Action Plan
|
|
389
|
+
|
|
390
|
+
#### Priority 1 (Critical - Fix Immediately)
|
|
391
|
+
1. {action 1}
|
|
392
|
+
2. {action 2}
|
|
393
|
+
|
|
394
|
+
#### Priority 2 (Major - Fix Soon)
|
|
395
|
+
1. {action 1}
|
|
396
|
+
2. {action 2}
|
|
397
|
+
|
|
398
|
+
#### Priority 3 (Minor - Fix When Possible)
|
|
399
|
+
1. {action 1}
|
|
400
|
+
2. {action 2}
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## Architecture Reference
|
|
405
|
+
|
|
406
|
+
Key sections from the guideline that are most relevant:
|
|
407
|
+
- {section 1}: {brief summary}
|
|
408
|
+
- {section 2}: {brief summary}
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
### Gate
|
|
412
|
+
- [ ] Report generated with all sections
|
|
413
|
+
- [ ] Score calculated
|
|
414
|
+
- [ ] Action plan provided
|
|
415
|
+
- [ ] Specific file references included
|
|
416
|
+
|
|
417
|
+
---
|
|
418
|
+
|
|
419
|
+
## Recommended Agents
|
|
420
|
+
|
|
421
|
+
| Phase | Agent | Purpose |
|
|
422
|
+
|-------|-------|---------|
|
|
423
|
+
| SCAN | `@clean-architect` | Architecture compliance analysis |
|
|
424
|
+
| REVIEW | `@code-reviewer` | Code quality check |
|
|
425
|
+
| REVIEW | `@security-audit` | Security pattern compliance |
|
|
426
|
+
| REPORT | `@docs-writer` | Generate detailed report |
|
|
427
|
+
|
|
428
|
+
---
|
|
429
|
+
|
|
430
|
+
## Quick Reference
|
|
431
|
+
|
|
432
|
+
### Architecture Files Location
|
|
433
|
+
```
|
|
434
|
+
# Project-specific (priority)
|
|
435
|
+
.claude/architecture/{name}.md
|
|
436
|
+
|
|
437
|
+
# Global
|
|
438
|
+
~/.claude/architecture/{name}.md
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
### Supported Architectures
|
|
442
|
+
```
|
|
443
|
+
clean-architecture (alias: clean)
|
|
444
|
+
react-frontend (alias: react)
|
|
445
|
+
go-backend (alias: go)
|
|
446
|
+
laravel-backend (alias: laravel)
|
|
447
|
+
remix-fullstack (alias: remix)
|
|
448
|
+
flutter-mobile (alias: flutter)
|
|
449
|
+
monorepo
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
### Review Dimensions
|
|
453
|
+
| # | Dimension | Weight |
|
|
454
|
+
|---|-----------|--------|
|
|
455
|
+
| 1 | Layer Boundaries | Critical |
|
|
456
|
+
| 2 | Directory Structure | High |
|
|
457
|
+
| 3 | Naming Conventions | Medium |
|
|
458
|
+
| 4 | Design Patterns | High |
|
|
459
|
+
| 5 | Data Flow | High |
|
|
460
|
+
| 6 | Testing Structure | Medium |
|
|
461
|
+
|
|
462
|
+
---
|
|
463
|
+
|
|
464
|
+
## Success Criteria
|
|
465
|
+
|
|
466
|
+
Architecture review is complete when:
|
|
467
|
+
1. Architecture guideline loaded and understood
|
|
468
|
+
2. Codebase scanned thoroughly
|
|
469
|
+
3. All 6 dimensions reviewed
|
|
470
|
+
4. Findings categorized by severity
|
|
471
|
+
5. Compliance score calculated
|
|
472
|
+
6. Action plan provided with priorities
|
|
473
|
+
7. Specific file:line references for all findings
|