moicle 2.0.0 → 2.2.0

package/assets/skills/review/architect/SKILL.md

@@ -6,86 +6,69 @@ args: "[ARCHITECTURE_NAME] [DOMAIN]"
 
 # DDD Architecture Review
 
-Review codebase against DDD architecture guidelines with automated checks and a review loop that keeps fixing until all checks pass.
+Audit a codebase (or a single domain) against DDD rules with automated checks, manual review, and a fix loop until score ≥ B.
 
 ## When to use this skill
 
-- ✅ Verify DDD compliance for a domain after `/feature:new` or `refactor`
+- ✅ Verify DDD compliance after `/feature:new` or `/feature:refactor`
 - ✅ Periodic audit of an existing codebase
-- ✅ As a quality gate before merging architectural changes
-- ❌ Reviewing a PR end-to-end (code quality + arch) → use `/review:pr`
-- ❌ Reviewing own branch before push → use `/review:branch`
-- ❌ Looking for security bugs → use `@security-audit` agent
+- ✅ Quality gate before merging architectural changes
+- ❌ Full PR review (arch + code + security + tests) → use `/review:pr`
+- ❌ Self-review own branch before push → use `/review:branch`
+- ❌ Security-only audit → use `@security-audit` agent
 
 ## Usage
 
-```bash
-/review:architect go-backend wallet
-/review:architect react-frontend
-/review:architect
 ```
+/review:architect <architecture> [domain]
+/review:architect              # auto-detect stack
+```
+
+Examples: `/review:architect go-backend wallet`, `/review:architect react-frontend`.
 
-## Supported Architectures
+## Supported architectures
 
-Check for architecture files in these locations (in order):
-1. **Project-specific**: `.claude/architecture/`
-2. **Global**: `~/.claude/architecture/`
+Aliases: `ddd → ddd-architecture`, `go → go-backend`, `react → react-frontend`, `flutter → flutter-mobile`, `laravel → laravel-backend`, `remix → remix-fullstack`, `nestjs → nodejs-nestjs`, `mono → monorepo`.
+
+Files live at `.claude/architecture/{name}.md` (project) → `~/.claude/architecture/{name}.md` (global).
+
+---
 
-### Built-in Architectures
+## Workflow
 
-| Name | File | Aliases |
-|------|------|---------|
-| `ddd-architecture` | `ddd-architecture.md` | `ddd`, `core` |
-| `go-backend` | `go-backend.md` | `go` |
-| `react-frontend` | `react-frontend.md` | `react` |
-| `flutter-mobile` | `flutter-mobile.md` | `flutter` |
-| `laravel-backend` | `laravel-backend.md` | `laravel` |
-| `remix-fullstack` | `remix-fullstack.md` | `remix` |
-| `monorepo` | `monorepo.md` | `mono` |
+```
+RESOLVE → LOAD RULES → AUTOMATED CHECKS → MANUAL REVIEW → REPORT → FIX LOOP
+```
 
 ---
 
 ## Phase 0: RESOLVE ARCHITECTURE
 
-### If argument provided
-1. Normalize name using alias table
-2. Search: `.claude/architecture/{name}.md` → `~/.claude/architecture/{name}.md`
-3. Found → Phase 1
-4. Not found → REJECT with available architectures list. **STOP.**
-
-### If NO argument
-1. Auto-detect stack from project files:
-   - `go.mod` → `go-backend`
-   - `package.json` + `vite.config` → `react-frontend`
-   - `pubspec.yaml` → `flutter-mobile`
-   - `composer.json` → `laravel-backend`
-   - `remix.config` → `remix-fullstack`
-2. If detected → confirm with user
-3. If not detected → list available, ask user to select
+### Argument provided
+1. Normalize via alias table → search project then global
+2. Found → Phase 1. Not found → reject with available list, STOP.
+
+### No argument
+1. Detect stack via `~/.claude/architecture/_shared/stack-detection.md`
+2. Detected → confirm with user. Not detected → list options, ask.
 
 ### Gate
 - [ ] Architecture file loaded
-- [ ] Domain name identified (if provided)
+- [ ] Domain identified (if scoped)
 
 ---
 
-## Phase 1: LOAD GUIDELINE & EXTRACT RULES
+## Phase 1: LOAD RULES
 
-Read the architecture file completely. Also read `ddd-architecture.md` (core DDD spec) as the base reference.
-
-### Extract from architecture doc:
-
-1. **DDD Directory Structure** — expected folder layout
-2. **Layer Rules** — import/dependency rules per layer
-3. **Hard Rules** — forbidden imports, naming conventions
-4. **Forbidden Imports** — specific packages/modules NOT allowed in domain
-5. **Check Scripts** — automated bash commands for validation
-6. **Wiring Pattern** — how modules are registered
-7. **Test Patterns** — how each layer should be tested
+Read `ddd-architecture.md` (core) + the stack doc. Extract:
+- DDD directory layout
+- Layer import rules + forbidden imports
+- Hard rules (HR1-HR15)
+- Stack-specific check scripts
+- Wiring + test patterns
 
 ### Gate
-- [ ] Core DDD rules loaded
-- [ ] Stack-specific rules loaded
+- [ ] Core + stack rules loaded
 - [ ] Check scripts extracted
 - [ ] Review checklist prepared
 
@@ -93,215 +76,130 @@ Read the architecture file completely. Also read `ddd-architecture.md` (core DDD
 
 ## Phase 2: AUTOMATED CHECKS
 
-Run the check scripts from the architecture doc. These vary per stack but follow this pattern:
-
-### Standard Checks (all stacks)
+Run the stack-specific check scripts from the architecture doc. They follow this universal pattern (adapt per stack):
 
 ```bash
-echo "=== R1: Build ==="
-{stack_build_command} && echo "PASS" || echo "FAIL"
-
-echo "=== R2: Lint/Vet ==="
-{stack_lint_command} && echo "PASS" || echo "FAIL"
-
-echo "=== R3: Domain Purity (no framework imports) ==="
-{grep_forbidden_imports_in_domain} && echo "FAIL" || echo "PASS"
-
-echo "=== R4: No Cross-Domain Imports ==="
-{check_domain_A_not_importing_domain_B} && echo "FAIL" || echo "PASS"
-
-echo "=== R5: No Circular Imports ==="
-{build_and_check_cycles} && echo "FAIL" || echo "PASS"
-
-echo "=== R6: Tests Exist ==="
-{find_test_files_in_domain} | wc -l
-
-echo "=== R7: Tests Pass ==="
-{stack_test_command} && echo "PASS" || echo "FAIL"
-
-echo "=== R8: Wiring Registered ==="
-{check_routes_or_providers_registered}
-
-echo "=== R9: Event Names Match Registry ==="
-{check_event_names_consistency}
-
-echo "=== R10: Async Context Safety ==="
-{check_no_request_context_in_goroutines}
+echo "R1: Build"        ; {build}        && echo PASS || echo FAIL
+echo "R2: Lint/Vet"     ; {lint}         && echo PASS || echo FAIL
+echo "R3: Domain pure"  ; {grep_forbidden in domain/} && echo FAIL || echo PASS
+echo "R4: No cross-dom" ; {grep_domain_A in domain_B} && echo FAIL || echo PASS
+echo "R5: No cycles"    ; {cycle_check}  && echo FAIL || echo PASS
+echo "R6: Tests exist"  ; {find_tests_in_domain} | wc -l
+echo "R7: Tests pass"   ; {test}         && echo PASS || echo FAIL
+echo "R8: Wiring reg"   ; {check_routes_registered}
+echo "R9: Event names"  ; {check_event_consistency}
+echo "R10: Async ctx"   ; {check_no_request_context_in_goroutines}
 ```
 
-### Stack-Specific Check Scripts
-
-Read the **Check Scripts** section from the loaded architecture doc and run those exact commands.
-
-### Output
-Record PASS/FAIL for each check. Continue to Phase 3 regardless — manual review catches what automated checks miss.
+Record PASS/FAIL per check. Continue to Phase 3 either way — manual review catches what automated misses.
 
 ### Gate
-- [ ] All automated checks executed
-- [ ] Results recorded
+- [ ] All 10 automated checks run
+- [ ] PASS/FAIL recorded
 
 ---
 
-## Phase 3: ARCHITECTURE REVIEW (Manual)
-
-Read files and check DDD compliance. Focus on **architecture structure**, NOT business logic correctness.
-
-### 3.1 Directory Structure
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| D1 | Domain dir exists | `domain/{domain}/` with proper subdirs |
-| D2 | Required subdirs | `entities/`, `ports/`, `usecases/` at minimum |
-| D3 | Value objects separate | `valueobjects/` dir, NOT mixed in `entities/` |
-| D4 | Events separate | `events/` dir with 1 file per event |
-| D5 | Application layer | `application/ports/{transport}/`, `services/`, `listeners/` |
-| D6 | Infrastructure layer | Implements port interfaces |
-| D7 | No legacy dirs | No `modules/`, `pkg/` (for Go), or flat structure |
-
-### 3.2 Entities
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| E1 | Has constructor | Factory function/method: `New{Entity}()`, `create()`, etc. |
-| E2 | Has behavior methods | State transitions, calculations, guard checks — NOT anemic |
-| E3 | Raises domain events | Collects/emits events on state changes |
-| E4 | No framework imports | Only stdlib + domain/shared + valueobjects |
-| E5 | Has mappers (if applicable) | ToModel/FromModel or equivalent for persistence mapping |
-
-### 3.3 Value Objects
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| VO1 | Separate directory | In `valueobjects/`, NOT in `entities/` |
-| VO2 | Only stdlib imports | No external packages, no domain/shared |
-| VO3 | Immutable with behavior | Typed values with query methods (IsPending, CanTransitionTo) |
-| VO4 | Used by entities/ports | Entities and ports reference VO types, not raw strings |
-
-### 3.4 Ports
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| P1 | `ports/` folder exists | MUST have `ports/` — inline interfaces in usecases is a violation |
-| P2 | One file per port | `{store_name}.go/.ts/.dart/.php` — not all in one file |
-| P3 | Interface + related DTOs | Each file has interface + its param/result types |
-| P4 | Domain types in signatures | Return entities/VOs, not primitives for typed values |
-| P5 | Platform-agnostic naming | `URLParser`, NOT `ShopeeURLParser` |
-| P6 | No infrastructure imports | Only stdlib + entities + valueobjects + shared |
-
-### 3.5 Events
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| EV1 | One file per event | `{event_name}` naming, not multiple events in one file |
-| EV2 | Extends base event | Embeds/extends shared BaseEvent |
-| EV3 | Carries data for listeners | UserID, amounts, names — enough for side-effects |
-| EV4 | Name matches registry | Event name string matches event bus registration |
-
-### 3.6 UseCases
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| U1 | Uses port interfaces | From `ports/` package, NOT inline interface definitions |
-| U2 | Split by concern | One file per action group, max ~200 lines per file |
-| U3 | Business logic lives here | Not in controller, not in store, not in service |
-| U4 | No infrastructure imports | No ORM, no HTTP framework, no cache client |
-| U5 | Dispatches domain events | After successful persistence, dispatches collected events |
-| U6 | No `deps.go` or similar | Interfaces MUST be in `ports/`, not inline |
-
-### 3.7 Services
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| SVC1 | Thin wrapper | Delegates to usecases, no business logic |
-| SVC2 | No infrastructure imports | No ORM, no HTTP framework |
-
-### 3.8 Handlers/Controllers
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| H1 | Registration function | `Register{Module}Routes` or equivalent wiring |
-| H2 | Thin handlers | Parse input -> call service -> return output |
-| H3 | No business logic | Logic is in usecases, not here |
-| H4 | DTOs separate | Request/Response types in separate file |
-
-### 3.9 Listeners
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| L1 | One per event | `on_{event_name}` naming |
-| L2 | Side-effects only | Notifications, SSE, analytics — no business logic |
-| L3 | Registered in event bus | Listed in registry/event bus setup |
-| L4 | Background context | Async work uses background context, not request context |
-
-### 3.10 Infrastructure/Store
-
-| # | Check | What to look for |
-|---|-------|-----------------|
-| I1 | Implements port interface | All methods from the port interface |
-| I2 | Has mappers | Converts between domain entities and persistence models |
-| I3 | No business logic | Pure persistence — queries, saves, deletes |
-| I4 | Compile-time check | Interface compliance verified at compile time (where possible) |
+## Phase 3: MANUAL REVIEW
+
+Focus on **architecture structure**, not business correctness. 10 areas:
+
+### D — Directory Structure
+- D1 `domain/{domain}/` exists with proper subdirs
+- D2 Has `entities/`, `ports/`, `usecases/` at minimum
+- D3 `valueobjects/` separate (not mixed in entities)
+- D4 `events/` separate, 1 file per event
+- D5 Application layer: `ports/{transport}/`, `services/`, `listeners/`
+- D6 Infrastructure implements ports
+- D7 No legacy dirs (`modules/`, flat structure)
+
+### E — Entities
+- E1 Has constructor (`New{Entity}` / `create()`)
+- E2 Has behavior methods (NOT anemic)
+- E3 Raises domain events on state change
+- E4 No framework imports
+- E5 Has mappers (if persisted)
+
+### VO — Value Objects
+- VO1 In `valueobjects/`, not entities
+- VO2 Only stdlib imports
+- VO3 Immutable with behavior methods
+- VO4 Used by entities + ports (not raw strings)
+
+### P — Ports
+- P1 `ports/` dir exists (no inline interfaces in usecases)
+- P2 One file per port
+- P3 Each file has interface + related DTOs
+- P4 Domain types in signatures (not primitives)
+- P5 Platform-agnostic naming (`URLParser` not `ShopeeURLParser`)
+- P6 No infrastructure imports
+
+### EV — Events
+- EV1 One file per event
+- EV2 Extends base event type
+- EV3 Carries data for listeners
+- EV4 Name matches registry
+
+### U — UseCases
+- U1 Uses port interfaces (not inline)
+- U2 Split by concern (≤200 lines/file)
+- U3 Business logic lives here (not in handler / store / service)
+- U4 No infrastructure imports
+- U5 Dispatches events after persistence
+- U6 No `deps.go` inline interfaces
+
+### SVC — Services
+- SVC1 Thin wrapper, delegates to usecases
+- SVC2 No infrastructure imports
+
+### H — Handlers / Controllers
+- H1 Has registration function
+- H2 Thin (parse → service → respond)
+- H3 No business logic
+- H4 DTOs in separate file
+
+### L — Listeners
+- L1 One per event (`on_{event}` naming)
+- L2 Side-effects only
+- L3 Registered in event bus
+- L4 Background context (not request ctx)
+
+### I — Infrastructure
+- I1 Implements port interface
+- I2 Has mappers (domain ↔ persistence)
+- I3 No business logic
+- I4 Compile-time interface check (where possible)
 
 ### Gate
 - [ ] All 10 areas reviewed
-- [ ] Findings categorized by severity
+- [ ] Findings categorized by severity (see `~/.claude/architecture/_shared/severity-levels.md`)
 
 ---
 
 ## Phase 4: REPORT
 
-### Severity Levels
-
-| Level | Meaning | Examples |
-|-------|---------|---------|
-| **CRITICAL** | Architecture broken | Build fails, circular imports, domain imports framework |
-| **HIGH** | DDD violation | Cross-domain import, business logic in wrong layer, no ports dir, inline interfaces |
-| **MEDIUM** | Structure issue | Anemic entity, fat controller, missing events, missing tests, missing json tags |
-| **LOW** | Convention issue | File naming, redundant code, DTOs in wrong package |
-
-**ALL levels must be fixed.**
-
-### Report Template
-
 ```markdown
 ## Architecture Review: {architecture} / {domain}
 
-### Automated Checks
+### Automated (R1-R10)
 | # | Check | Status |
 |---|-------|--------|
 | R1 | Build | PASS/FAIL |
-| R2 | Lint/Vet | PASS/FAIL |
-| R3 | Domain purity | PASS/FAIL |
-| R4 | No cross-domain imports | PASS/FAIL |
-| R5 | No circular imports | PASS/FAIL |
-| R6 | Tests exist | PASS/WARN |
-| R7 | Tests pass | PASS/FAIL |
-| R8 | Wiring registered | PASS/FAIL |
-| R9 | Event names consistent | PASS/N/A |
-| R10 | Async context safety | PASS/N/A |
-
-### Architecture Review
+| ... | ... | ... |
+
+### Manual review
 | Area | Status | Violations |
 |------|--------|------------|
-| Directory Structure (D1-D7) | OK/ISSUE | ... |
-| Entities (E1-E5) | OK/ISSUE | ... |
-| Value Objects (VO1-VO4) | OK/ISSUE | ... |
-| Ports (P1-P6) | OK/ISSUE | ... |
-| Events (EV1-EV4) | OK/N/A | ... |
-| UseCases (U1-U6) | OK/ISSUE | ... |
-| Services (SVC1-SVC2) | OK/ISSUE | ... |
-| Handlers (H1-H4) | OK/ISSUE | ... |
-| Listeners (L1-L4) | OK/N/A | ... |
-| Infrastructure (I1-I4) | OK/ISSUE | ... |
-
-### Violations Found
-1. [SEVERITY] Code — file:line — description
-2. ...
+| Directory (D1-D7) | OK / ISSUE | ... |
+| Entities (E1-E5) | OK / ISSUE | ... |
+| ... | ... | ... |
 
-### Recommended Fixes
-1. Fix description
+### Violations
+1. [SEVERITY] code:file:line — description
 2. ...
 
+### Recommended fixes
+1. ...
+
 ### Overall Score: {A/B/C/D/F}
 ```
 
@@ -309,97 +207,50 @@ Read files and check DDD compliance. Focus on **architecture structure**, NOT bu
 
 | Score | Criteria |
 |-------|----------|
-| **A** | 0 violations, all automated checks PASS |
+| **A** | 0 violations, all R1-R10 PASS |
 | **B** | 0 CRITICAL/HIGH, max 3 MEDIUM |
 | **C** | 0 CRITICAL, max 2 HIGH |
 | **D** | Has CRITICAL or 3+ HIGH |
-| **F** | Multiple CRITICAL, architecture fundamentally broken |
+| **F** | Multiple CRITICAL — architecture broken |
 
 ### Gate
 - [ ] Report generated
 - [ ] Score calculated
-- [ ] All violations listed with file:line
+- [ ] All violations have file:line
 
 ---
 
-## Phase 5: REVIEW LOOP (if user confirms fix)
-
-**Keep looping until ALL checks pass and score is A or B.**
+## Phase 5: FIX LOOP (if user confirms)
 
 ```
 LOOP:
-  1. Fix all violations found in report
-  2. Run automated checks (Phase 2)
-  3. Run architecture review (Phase 3)
-  4. Collect violations
-  5. IF violations with severity >= MEDIUM:
-     a. Fix violations
-     b. GOTO 1
-  6. IF only LOW violations or none:
-     BREAK → Report final status
+  1. Fix all violations
+  2. Re-run automated checks (Phase 2)
+  3. Re-run manual review (Phase 3)
+  4. IF violations severity ≥ MEDIUM → GOTO 1
+  5. IF only LOW or none → BREAK, final report
 ```
 
-### After Each Fix Iteration
-```bash
-# Verify build still works
-{stack_build_command}
-
-# Verify tests still pass
-{stack_test_command}
-
-# Re-check domain purity
-{grep_forbidden_imports_in_domain}
-```
+Verify after each iteration: build passes, tests pass, domain purity holds.
 
 ---
 
-## Calling from Other Skills
-
-This skill is designed to be called by `/feature:new` and `/feature:refactor`s at the end of their workflows:
+## Calling from other skills
 
-```
-# From new-feature skill, after Phase 5 (registration):
-→ Run /review:architect {detected_stack} {domain}
-→ Review loop until score >= B
-
-# From refactor skill, after Phase 4 (cleanup):
-→ Run /review:architect {detected_stack} {domain}
-→ Review loop until score >= B
-```
-
-When called from another skill:
+`/feature:new` and `/feature:refactor` call this skill at the end of their workflows. When called from another skill:
 - Skip Phase 0 (architecture already known)
 - Skip user confirmation for fixes (auto-fix in loop)
-- Report final score back to calling skill
+- Report final score back to caller
 
 ---
 
-## Quick Reference
-
-### Architecture Files Location
-```
-.claude/architecture/{name}.md     # Project-specific (priority)
-~/.claude/architecture/{name}.md   # Global
-```
-
-### Aliases
-```
-ddd → ddd-architecture
-go → go-backend
-react → react-frontend
-flutter → flutter-mobile
-laravel → laravel-backend
-remix → remix-fullstack
-mono → monorepo
-```
+## Hard Rules
 
-### Review Areas (10)
-```
-D: Directory Structure    E: Entities        VO: Value Objects
-P: Ports                  EV: Events         U: UseCases
-SVC: Services             H: Handlers        L: Listeners
-I: Infrastructure
-```
+- **All CRITICAL/HIGH must be fixed** before merge
+- **MEDIUM allowed with waiver** (explicit decision + comment)
+- **Don't grade-inflate** — if it's a HIGH, mark HIGH
+- **Don't skip Phase 3** — automated checks miss structural issues
+- **File:line for every violation** — author shouldn't have to grep
 
 ---
 
@@ -407,17 +258,17 @@ I: Infrastructure
 
 | When | Use |
 |------|-----|
-| Full PR review (arch + code quality + security + tests) | `/review:pr` |
+| Full PR review (arch + code + security + tests) | `/review:pr` |
 | Self-review own branch before push | `/review:branch` |
-| Refactor to fix violations found here | `refactor` |
+| Refactor to fix violations | `/feature:refactor` |
 | Add tests if missing | `/review:tdd` |
-| Called from `/feature:new` / `refactor` review loop | (automatic — no manual invoke) |
+| Called from `/feature:new` / `/feature:refactor` | automatic |
 
 ## Recommended Agents
 
 | Phase | Agent | Purpose |
 |-------|-------|---------|
 | LOAD | `@clean-architect` | Interpret architecture rules |
-| AUTOMATED CHECKS | `@devops` | Build / lint / test scripts |
-| MANUAL REVIEW | `@code-reviewer` | Spot violations |
+| AUTOMATED | `@devops` | Build / lint / test scripts |
+| MANUAL | `@code-reviewer` | Spot violations |
 | FIX | Stack-specific dev agent | Apply fixes |