moicle 1.3.1 → 1.4.0

package/assets/skills/refactor/SKILL.md

@@ -1,756 +1,338 @@
 ---
 name: refactor
-description: Refactoring workflow for improving code quality without changing behavior. Use when refactoring, cleaning up code, improving structure, or when user says "refactor", "clean up", "improve code", "restructure".
+description: DDD refactoring workflow with phase-based checks and review loop. Refactor existing code to DDD architecture or improve existing DDD structure. Use when user says "refactor", "clean up", "improve code", "restructure", "migrate to ddd", "refactor ddd".
+args: "[MODULE] [DOMAIN]"
 ---
 
-# Refactoring Workflow
+# DDD Refactor Workflow
 
-Systematic workflow for improving code quality and structure without changing external behavior.
+Refactor existing code into DDD architecture, or improve existing DDD structure. Execute phases sequentially, run rule checks after each phase.
 
-## IMPORTANT: Read Architecture First
+**ARGUMENTS:** `<module> <domain>` — e.g., `marketing notification`, `users identity`, `products catalog`
 
-**Before refactoring, you MUST read the appropriate architecture reference:**
+## Read Architecture First
 
-### Global Architecture Files
-```
-~/.claude/architecture/
-├── clean-architecture.md    # Core principles for all projects
-├── flutter-mobile.md        # Flutter + Riverpod
-├── react-frontend.md        # React + Vite + TypeScript
-├── go-backend.md            # Go + Gin
-├── laravel-backend.md       # Laravel + PHP
-├── remix-fullstack.md       # Remix fullstack
-└── monorepo.md              # Monorepo structure
-```
+**Before starting, MUST read TWO files:**
 
-### Project-specific (if exists)
-```
-.claude/architecture/        # Project overrides
-```
+1. **Core DDD spec**: `.claude/architecture/ddd-architecture.md`
+2. **Stack-specific doc**: detect stack → read the corresponding architecture doc
 
-**Refactoring should align code with these architecture patterns.**
-
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| ANALYZE | `@refactor` | Identify refactoring opportunities |
-| ANALYZE | `@code-reviewer` | Code smell detection |
-| PLAN | `@clean-architect` | Architecture alignment strategy |
-| REFACTOR | `@react-frontend-dev`, `@go-backend-dev`, `@laravel-backend-dev`, `@flutter-mobile-dev`, `@remix-fullstack-dev` | Stack-specific refactoring |
-| TEST | `@test-writer` | Regression tests |
-| REVIEW | `@code-reviewer` | Final quality check |
-| REVIEW | `@perf-optimizer` | Performance validation |
-
-## Workflow Overview
+### Stack Detection
+| File | Stack Doc |
+|------|-----------|
+| `go.mod` | `go-backend.md` |
+| `package.json` + `vite.config.*` | `react-frontend.md` |
+| `pubspec.yaml` | `flutter-mobile.md` |
+| `composer.json` | `laravel-backend.md` |
+| `remix.config.*` | `remix-fullstack.md` |
 
+### Architecture Files Location
 ```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-│1. ANALYZE│──▶│ 2. PLAN  │──▶│3. REFACTOR──▶│ 4. TEST  │──▶│5. REVIEW │
-└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
-                                    │              │              │
-                                    │     Fail?    │              │
-                                    └──────◀───────┴──────◀───────┘
-                                          Feedback Loop
+.claude/architecture/{name}.md     # Project-specific (priority)
+~/.claude/architecture/{name}.md   # Global
 ```
 
 ---
 
-## Phase 1: ANALYZE
+## Workflow
 
-**Goal**: Identify code smells and improvement opportunities
-
-### Actions
-1. **Identify project stack and read architecture doc**
-
-2. Analyze codebase for common issues:
-   ```
-   Code Smells:
-   - Long methods (> 50 lines)
-   - Large classes (> 300 lines)
-   - Duplicate code
-   - Deep nesting (> 3 levels)
-   - Long parameter lists (> 4 params)
-   - God classes/modules
-   - Feature envy
-   - Data clumps
-   - Primitive obsession
-   ```
-
-3. Check architecture compliance:
-   - [ ] Layer boundaries violated?
-   - [ ] Circular dependencies?
-   - [ ] Missing abstractions?
-   - [ ] Wrong patterns used?
-   - [ ] Naming conventions violated?
-
-4. Assess technical debt:
-   ```bash
-   # Find TODOs and FIXMEs
-   grep -r "TODO\|FIXME\|HACK\|XXX" --exclude-dir=node_modules --exclude-dir=vendor
-
-   # Check test coverage
-   [use coverage tool from architecture doc]
-
-   # Find large files
-   find . -type f -name "*.ts" -o -name "*.go" -o -name "*.php" -o -name "*.dart" | xargs wc -l | sort -rn | head -20
-   ```
-
-### Output
-```markdown
-## Refactoring Analysis
-
-### Stack & Architecture
-- Stack: [Flutter/React/Go/Laravel/Remix]
-- Architecture Doc: [path to doc]
-
-### Code Smells Found
-1. [Smell]: [location] - [description]
-2. [Smell]: [location] - [description]
-
-### Architecture Violations
-- [ ] Layer X depends on Layer Y (should be reversed)
-- [ ] Missing [pattern] from architecture doc
-- [ ] Naming doesn't follow [convention from doc]
-
-### Technical Debt Areas
-- [ ] Area 1: [description]
-- [ ] Area 2: [description]
-
-### Metrics
-- Large files (> 300 lines): [count]
-- Duplicate code blocks: [count]
-- Test coverage: [percentage]
-- TODO/FIXME count: [count]
+```
+PHASE 0: Foundation Check
+  → PHASE 1: Analyze Current Module
+  → PHASE 2: Build Domain Layer
+  → PHASE 3: Build Infrastructure Layer
+  → PHASE 4: Build Application Layer
+  → PHASE 5: Domain Tests
+  → PHASE 6: Integration & Cleanup
+  → REVIEW LOOP (run /architect-review, fix, repeat until clean)
 ```
 
-### Gate
-- [ ] Architecture doc read
-- [ ] Code smells identified
-- [ ] Architecture violations documented
-- [ ] Scope defined
+Each phase has a Rule Check. DO NOT skip any phase.
 
 ---
 
-## Phase 2: PLAN
+## PHASE 0: Foundation Check
 
-**Goal**: Design refactoring strategy aligned with architecture
+Verify DDD foundation exists in the project.
 
-### Actions
-1. **Re-read architecture doc** for target patterns
-
-2. Prioritize refactorings:
-   ```
-   Priority Matrix:
-   HIGH IMPACT + LOW RISK → Do first
-   HIGH IMPACT + HIGH RISK → Plan carefully
-   LOW IMPACT + LOW RISK  → Do if time permits
-   LOW IMPACT + HIGH RISK → Skip
-   ```
-
-3. Break down into incremental steps:
-   - Each step should be small
-   - Each step should be testable
-   - Each step should compile
-   - Follow architecture patterns
-
-4. Identify risks:
-   - [ ] Breaking changes possible?
-   - [ ] Performance impact?
-   - [ ] Dependencies affected?
-   - [ ] Rollback plan needed?
-
-### Planning Template
-```markdown
-## Refactoring Plan
-
-### Architecture Reference
-- Doc: [path to architecture doc]
-- Target patterns: [patterns from doc]
-
-### Strategy
-Move from: [current structure]
-Move to: [architecture-compliant structure]
-
-### Incremental Steps (smallest possible)
-1. [Step 1] - Risk: [Low/Medium/High]
-   - Files: [list]
-   - Pattern: [pattern from doc]
-   - Estimated effort: [time]
-
-2. [Step 2] - Risk: [Low/Medium/High]
-   - Files: [list]
-   - Pattern: [pattern from doc]
-   - Estimated effort: [time]
-
-3. [Continue...]
-
-### Risks & Mitigation
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| [Risk 1] | [High/Medium/Low] | [How to mitigate] |
-
-### Success Criteria
-- [ ] Code follows architecture doc
-- [ ] All tests pass
-- [ ] No behavior changes
-- [ ] Performance maintained/improved
-- [ ] Complexity reduced
+### For new DDD projects (no domain/ dir yet)
+Create shared foundation:
+- `domain/shared/` — base event types, event collector, event dispatcher interface
+- Event bus / dispatcher infrastructure
+- Bootstrap/app config struct
+
+### For existing DDD projects
+Verify foundation is intact:
+```bash
+# Check shared domain types exist
+ls {domain_root}/shared/ 2>/dev/null && echo "PASS" || echo "NEED SETUP"
+
+# Check event infrastructure exists (if applicable)
+ls {eventbus_path}/ 2>/dev/null && echo "PASS" || echo "NEED SETUP"
 ```
 
-### Gate
-- [ ] Plan follows architecture doc
-- [ ] Steps are incremental
-- [ ] Risks identified
-- [ ] Rollback plan exists
+If any FAIL → create foundation first before proceeding.
 
 ---
 
-## Phase 3: REFACTOR
+## PHASE 1: Analyze Current Module
 
-**Goal**: Execute refactoring incrementally following architecture
-
-### Principles
-1. **Red-Green-Refactor** - Tests must pass after each step
-2. **Small steps** - One pattern at a time
-3. **Frequent commits** - Commit after each successful step
-4. **No behavior change** - External behavior stays same
-5. **Follow architecture** - Align with patterns from doc
+Read ALL source files before making any changes.
 
 ### Actions
+1. Read all files in the current module/feature directory
+2. Read related models/types
+3. Read related enums/constants
+4. Read current routes/screens/providers for this module
+
+### Output (report to user)
+- All entities/models and their fields
+- All usecases (functions/methods) and their logic
+- All DTOs (request/response structs)
+- All validators (if any)
+- All cross-module calls
+- All events/side-effects (notifications, SSE, analytics)
+- All external dependencies (DB, cache, messaging, etc.)
+- All endpoints/screens/UI elements
+
+### Rule Check Phase 1
+- [ ] All module files read and understood
+- [ ] All entities, usecases, dependencies, endpoints listed
+- [ ] Report presented to user and **CONFIRM received** before continuing
 
-1. Create refactor branch:
-   ```bash
-   git checkout -b refactor/[scope]-[description]
-   ```
-
-2. **Read architecture doc** for implementation patterns
-
-3. For each refactoring step:
-
-   a. **Before refactoring**:
-   ```bash
-   # Run tests to establish baseline
-   [test command from architecture doc]
-
-   # Create checkpoint
-   git add .
-   git commit -m "refactor: checkpoint before [step description]"
-   ```
-
-   b. **Apply one refactoring pattern**:
-   - Extract Method
-   - Extract Class
-   - Rename for Clarity
-   - Move Method
-   - Replace Conditional with Polymorphism
-   - Introduce Parameter Object
-   - Remove Duplication
-   - Simplify Conditional Logic
-   - Break Up Large Class
-   - Extract Interface
-
-   Follow patterns and naming from architecture doc
-
-   c. **After refactoring**:
-   ```bash
-   # Verify tests still pass
-   [test command from architecture doc]
-
-   # Commit if successful
-   git add .
-   git commit -m "refactor: [what was done]"
-   ```
-
-   d. **If tests fail**:
-   ```bash
-   # Rollback
-   git reset --hard HEAD
-
-   # Re-analyze and try smaller step
-   ```
-
-4. Follow directory structure from architecture doc:
-   ```
-   [Use exact structure defined in architecture doc]
-   ```
-
-### Common Refactoring Patterns
-
-#### Extract Method
-```
-Before:
-function processOrder() {
-  // 50 lines of code
-  // validation logic
-  // business logic
-  // persistence logic
-}
-
-After (following architecture doc):
-function processOrder() {
-  validateOrder();
-  applyBusinessRules();
-  persistOrder();
-}
-```
-
-#### Extract Class (following architecture layers)
-```
-Before:
-class User {
-  // user data
-  // authentication logic
-  // email sending logic
-  // persistence logic
-}
-
-After (following architecture doc):
-- entities/User (domain)
-- services/AuthService (use case)
-- services/EmailService (use case)
-- repositories/UserRepository (data)
-```
+---
 
-#### Introduce Parameter Object
-```
-Before:
-function createUser(name, email, phone, address, city, zip)
-
-After:
-interface CreateUserDTO {
-  name: string;
-  email: string;
-  phone: string;
-  address: Address;
-}
-function createUser(dto: CreateUserDTO)
+## PHASE 2: Create Domain Layer
+
+Create `domain/{domain}/` (if first module in this domain) or add to existing.
+
+### 2.1 Value Objects (`valueobjects/`)
+- Extract typed values from existing code (status strings, rates, amounts)
+- Immutable with behavior methods
+- **Only stdlib imports** — check Forbidden Imports from architecture doc
+
+### 2.2 Entities (`entities/`)
+- Convert existing model fields to domain entity
+- Add constructor function/method
+- Add behavior methods (state transitions, calculations)
+- Add event collection (collect events on state changes)
+- Add mappers to/from persistence models (if applicable)
+- **No framework imports**
+
+### 2.3 Events (`events/`)
+- One file per domain event
+- Extend/embed base event type
+- Carry data needed by listeners
+- Extract from existing direct side-effect calls (SSE, notifications, etc.)
+
+### 2.4 Ports (`ports/`)
+- One file per port interface
+- Store ports: persistence interface from existing repository/DB calls
+- Adapter ports: external service interfaces
+- Platform-agnostic naming
+- **No infrastructure imports**
+
+### 2.5 UseCases (`usecases/`)
+- Extract business logic from existing controllers/handlers/services
+- Import port interfaces from `ports/`
+- Split by concern: one file per action group
+- Business logic lives HERE
+- **No infrastructure imports**
+
+### Rule Check Phase 2
+Run check scripts from architecture doc:
+```bash
+# Build domain layer
+{stack_build_command_for_domain}
+
+# Check domain purity
+{grep_forbidden_imports_in_domain} && echo "FAIL" || echo "PASS"
+
+# Check no cross-domain imports
+{check_cross_domain_imports}
 ```
 
-### Gate
-- [ ] All refactoring steps completed
-- [ ] Code follows architecture doc patterns
-- [ ] Tests pass after each step
-- [ ] Code compiles without warnings
-- [ ] No behavior changes
-
 ---
 
-## Phase 4: TEST
-
-**Goal**: Ensure refactoring didn't break anything
+## PHASE 3: Create Infrastructure Layer
 
-### Actions
+### 3.1 Store/API Implementation
+- Implement interfaces from `domain/{domain}/ports/`
+- Use mapper functions (domain entity ↔ persistence model)
+- Compile-time interface check (where possible)
+- NO business logic — pure persistence
+- Keep existing persistence models where they are
 
-1. **Read testing section from architecture doc**
-
-2. Run full test suite (command from doc):
-   ```bash
-   flutter test              # Flutter
-   flutter test --coverage
-
-   go test ./...             # Go
-   go test -cover ./...
-
-   bun test                  # React/Remix
-   bun test --coverage
-
-   php artisan test          # Laravel
-   php artisan test --coverage
-   ```
-
-3. Verify test coverage didn't decrease:
-   ```bash
-   # Compare coverage before/after
-   # Coverage should stay same or improve
-   ```
-
-4. Add tests for refactored areas (following doc patterns):
-   ```
-   Before refactor: 70% coverage
-   After refactor: 70%+ coverage (should not decrease)
-   ```
-
-5. Manual smoke testing:
-   - [ ] Critical user flows work
-   - [ ] No visual regressions (if UI)
-   - [ ] Performance is same/better
-   - [ ] Error handling works
-
-6. Run linter/formatter (tools from architecture doc):
-   ```bash
-   # Use tools specified in architecture doc
-   flutter analyze         # Flutter
-   golangci-lint run      # Go
-   eslint . --fix         # React/Remix
-   ./vendor/bin/pint      # Laravel
-   ```
-
-### Testing Checklist
-```markdown
-## Test Results
-
-### Automated Tests
-- [ ] Unit tests: [X/Y passed]
-- [ ] Integration tests: [X/Y passed]
-- [ ] E2E tests: [X/Y passed]
-
-### Coverage
-- Before: [percentage]
-- After: [percentage]
-- Change: [+/-]
-
-### Manual Tests
-- [ ] Critical flow 1: [Pass/Fail]
-- [ ] Critical flow 2: [Pass/Fail]
-- [ ] Error scenarios: [Pass/Fail]
-
-### Quality Checks
-- [ ] Linter: [Pass/Fail]
-- [ ] Type checker: [Pass/Fail]
-- [ ] Build: [Pass/Fail]
+### Rule Check Phase 3
+```bash
+# Build infrastructure
+{stack_build_command_for_infra}
 ```
 
-### Gate
-- [ ] All tests pass
-- [ ] Coverage maintained/improved
-- [ ] Manual tests pass
-- [ ] Quality checks pass
+---
 
-### Feedback Loop
-If tests fail:
-1. Identify which refactoring step broke it
-2. Use git bisect if needed: `git bisect start`
-3. Return to REFACTOR phase
-4. Fix or rollback that step
-5. Re-test
+## PHASE 4: Create Application Layer
 
----
+### 4.1 Listeners (extract from existing side-effects)
+- **CRITICAL:** Side-effects (notifications, SSE, analytics, async jobs) MUST NOT be called directly in usecases or infrastructure
+- They MUST flow through: entity collects events → usecase dispatches → listener handles
+- One file per event listener
+- Register in event bus/registry
 
-## Phase 5: REVIEW
+### 4.2 Service
+- Thin wrapper delegating to domain usecases
+- NO business logic
 
-**Goal**: Verify improvements and architecture compliance
+### 4.3 Handler/Controller/Screen
+- Registration/wiring function
+- Thin: parse input → call service → return output
+- DTOs in separate file
+- All endpoints/routes must match the old ones (same path + method)
 
-### Actions
+### Rule Check Phase 4
+```bash
+# Build application layer
+{stack_build_command_for_application}
+```
 
-1. **Compare with architecture doc**:
-   - [ ] Layers properly separated
-   - [ ] Dependencies flow correctly (from doc)
-   - [ ] Patterns used correctly
-   - [ ] Naming follows conventions
-   - [ ] Directory structure matches doc
-
-2. Measure improvements:
-   ```markdown
-   ## Metrics Comparison
-
-   | Metric | Before | After | Change |
-   |--------|--------|-------|--------|
-   | Avg method length | X lines | Y lines | -Z% |
-   | Avg class size | X lines | Y lines | -Z% |
-   | Cyclomatic complexity | X | Y | -Z% |
-   | Duplicate code | X blocks | Y blocks | -Z% |
-   | Test coverage | X% | Y% | +Z% |
-   | Build time | X sec | Y sec | -Z% |
-   ```
-
-3. Code review checklist:
-   - [ ] Code is more readable
-   - [ ] Code is more maintainable
-   - [ ] Complexity reduced
-   - [ ] Duplication removed
-   - [ ] Architecture violations fixed
-   - [ ] No over-engineering
-
-4. Performance check:
-   ```bash
-   # Run performance tests
-   # Compare with baseline
-   # Should be same or better
-   ```
-
-5. Security check:
-   - [ ] No new vulnerabilities introduced
-   - [ ] Security patterns still apply
-   - [ ] Input validation intact
-   - [ ] Authentication/authorization unchanged
-
-### Review Output
-```markdown
-## Refactoring Review
+---
 
-### Architecture Compliance: [Pass/Fail]
-- Reference: [architecture doc path]
-- Violations fixed: [list]
-- Remaining issues: [list]
+## PHASE 5: Domain Tests
 
-### Quality Improvements: [Good/Excellent]
-| Aspect | Rating | Notes |
-|--------|--------|-------|
-| Readability | [1-5] | [comments] |
-| Maintainability | [1-5] | [comments] |
-| Testability | [1-5] | [comments] |
-| Simplicity | [1-5] | [comments] |
+**CRITICAL:** MUST read old tests before writing new ones. Copy all test cases and business scenarios to domain tests. Do not lose any test coverage.
 
-### Metrics: [Improved/Same/Worse]
-[Insert metrics table from above]
+### 5.1 Process
+1. Read ALL test files in old module
+2. List all test cases and business scenarios
+3. Write domain tests covering all those scenarios
+4. Focus on business logic (pure unit tests, no integration needed yet)
 
-### Performance: [Improved/Same/Worse]
-[Performance test results]
+### 5.2 Entity Tests
+- Behavior methods (state transitions, validations, calculations)
+- Edge cases (zero values, boundary conditions)
+- Business rules
+- NO mocking needed — pure tests
 
-### Security: [Pass/Fail]
-[Security check results]
+### 5.3 UseCase Tests
+- Mock port interfaces
+- All business flows (happy path + error cases)
+- Input validation
+- Domain event collection (if applicable)
 
-### Recommendation: [Approve/Revise]
+### Rule Check Phase 5
+```bash
+# Run domain tests
+{stack_test_command_for_domain}
 ```
 
-### Gate
-- [ ] Architecture doc followed
-- [ ] Code quality improved
-- [ ] Metrics show improvement
-- [ ] Performance maintained/improved
-- [ ] Security maintained
+---
 
-### Feedback Loop
-If review fails:
-- Return to REFACTOR phase
-- Address issues found
-- Re-test and re-review
+## PHASE 6: Integration & Cleanup
 
----
+### 6.1 Update Router/Provider/Registry
+- Add new registration calls
+- Remove old module routes/registrations
+- All endpoints/screens must match the old ones
 
-## Phase 6: COMPLETE
+### 6.2 Remove Old Module
+- Delete old module directory ONLY AFTER verifying build + test pass
+- DO NOT delete shared models/types that other modules still use
 
-**Goal**: Finalize and document the refactoring
+### Rule Check Phase 6
+```bash
+# Full build
+{stack_full_build_command}
 
-### Actions
+# Verify old module removed
+test -d {old_module_path} && echo "FAIL: old module exists" || echo "PASS"
 
-1. Final cleanup:
-   - [ ] Remove debug code
-   - [ ] Remove commented code
-   - [ ] Update documentation
-   - [ ] Remove TODOs added during refactor
-   - [ ] Format code (using tool from doc)
-
-2. Squash commits (optional):
-   ```bash
-   # If many small commits, consider squashing
-   git rebase -i HEAD~[number of commits]
-   ```
-
-3. Create meaningful commit:
-   ```bash
-   git add .
-   git commit -m "$(cat <<'EOF'
-   refactor: [scope] - [what was improved]
-
-   Architecture compliance:
-   - [Pattern 1 from doc applied]
-   - [Pattern 2 from doc applied]
-
-   Improvements:
-   - [Improvement 1]
-   - [Improvement 2]
-
-   Metrics:
-   - Complexity: -X%
-   - Duplication: -Y%
-   - Test coverage: +Z%
-   EOF
-   )"
-   ```
-
-4. Create PR:
-   ```bash
-   gh pr create --title "refactor: [scope] - [description]" --body "$(cat <<'EOF'
-   ## Summary
-   Refactored [area] to align with [architecture doc patterns]
-
-   ## Architecture Reference
-   - Doc: [path to architecture doc]
-   - Patterns applied: [list]
-
-   ## What Changed
-   - [Change 1]
-   - [Change 2]
-   - [Change 3]
-
-   ## Why
-   - [Reason 1]
-   - [Reason 2]
-
-   ## Metrics
-   | Metric | Before | After | Change |
-   |--------|--------|-------|--------|
-   | [Metric 1] | X | Y | -Z% |
-   | [Metric 2] | X | Y | +Z% |
-
-   ## Testing
-   - [ ] All tests pass
-   - [ ] Coverage maintained: [X%]
-   - [ ] Manual testing complete
-   - [ ] Performance validated
-
-   ## Behavior
-   - [ ] No external behavior changes
-   - [ ] API unchanged (if applicable)
-   - [ ] UI unchanged (if applicable)
-
-   ## Checklist
-   - [ ] Follows architecture doc
-   - [ ] Tests pass
-   - [ ] Code reviewed
-   - [ ] Metrics improved
-   EOF
-   )"
-   ```
-
-5. Documentation (if needed):
-   - Update README if structure changed
-   - Update architecture docs if patterns evolved
-   - Add migration guide if needed
-
-### Completion Checklist
-- [ ] Code follows architecture doc
-- [ ] All tests passing
-- [ ] Metrics improved
-- [ ] Performance maintained/improved
-- [ ] Documentation updated
-- [ ] PR created
-- [ ] No behavior changes
+# Verify no old imports remain
+grep -r "{old_module_import}" --include="*.{ext}" . && echo "FAIL: old imports" || echo "PASS"
+```
 
 ---
 
-## Quick Reference
-
-### Architecture Docs
-| Stack | Doc |
-|-------|-----|
-| All | `clean-architecture.md` |
-| Flutter | `flutter-mobile.md` |
-| React | `react-frontend.md` |
-| Go | `go-backend.md` |
-| Laravel | `laravel-backend.md` |
-| Remix | `remix-fullstack.md` |
-| Monorepo | `monorepo.md` |
-
-### Common Code Smells
-
-| Smell | Description | Refactoring |
-|-------|-------------|-------------|
-| Long Method | Method > 50 lines | Extract Method |
-| Large Class | Class > 300 lines | Extract Class |
-| Long Parameter List | > 4 parameters | Introduce Parameter Object |
-| Duplicate Code | Same code in multiple places | Extract Method/Class |
-| Data Clumps | Same data items together | Introduce Value Object |
-| Primitive Obsession | Using primitives instead of objects | Introduce Value Object |
-| Feature Envy | Method uses another class more | Move Method |
-| God Class | Class does too much | Extract Class, Split Responsibilities |
-| Deep Nesting | > 3 levels of nesting | Extract Method, Guard Clauses |
-| Dead Code | Unused code | Delete |
-
-### Refactoring Patterns
-
-| Pattern | When to Use | Risk |
-|---------|-------------|------|
-| Extract Method | Long method, duplicate code | Low |
-| Extract Class | Large class, god class | Medium |
-| Rename | Unclear names | Low |
-| Move Method | Feature envy | Medium |
-| Extract Interface | Tight coupling | Medium |
-| Replace Conditional with Polymorphism | Complex conditionals | High |
-| Introduce Parameter Object | Long parameter list | Low |
-| Remove Duplication | Duplicate code | Low |
-| Simplify Conditional | Complex boolean logic | Low |
-| Break Dependencies | Circular dependencies | High |
-
-### Refactoring Safety
+## REVIEW LOOP
+
+After all phases complete, run the full architecture review. **Keep looping until ALL checks pass.**
 
 ```
-Safe (Low Risk):
-- Rename
-- Extract Method (within same class)
-- Inline temp variable
-- Remove dead code
-
-Medium Risk:
-- Extract Class
-- Move Method
-- Extract Interface
-- Change signature
-
-High Risk:
-- Replace inheritance with delegation
-- Replace conditional with polymorphism
-- Major architecture changes
+LOOP:
+  1. Run /architect-review {stack} {domain}
+  2. Collect violations
+  3. IF violations with severity >= MEDIUM:
+     a. Fix all violations
+     b. Run full build to verify
+     c. Run all tests to verify
+     d. GOTO 1
+  4. IF score >= B:
+     BREAK → Final Report
 ```
 
-### Phase Summary
-
-| Phase | Key Actions | Output |
-|-------|-------------|--------|
-| ANALYZE | Read arch doc, find smells | Analysis report |
-| PLAN | Design strategy per doc | Incremental plan |
-| REFACTOR | Apply patterns from doc | Clean code |
-| TEST | Verify behavior unchanged | Test results |
-| REVIEW | Check compliance, metrics | Review report |
-| COMPLETE | Commit, PR, docs | Merged refactor |
-
-### When to Stop
-
-Stop refactoring when:
-- [ ] Code follows architecture doc
-- [ ] All code smells addressed
-- [ ] Metrics show improvement
-- [ ] Diminishing returns (over-engineering)
-- [ ] Time budget exceeded
-
-### Success Criteria
-
-Refactoring is successful when:
-1. Code follows architecture doc patterns
-2. Code is more readable and maintainable
-3. Complexity reduced (measurably)
-4. Duplication removed
-5. All tests pass
-6. No behavior changes
-7. Performance maintained/improved
-8. Team can understand changes
-
 ---
 
-## Anti-Patterns to Avoid
+## Final Report
 
-### Over-Engineering
-```
-DON'T: Add unnecessary abstractions
-DON'T: Create patterns not in architecture doc
-DON'T: Refactor without clear benefit
-```
+When review loop passes with score >= B:
 
-### Big Bang Refactoring
-```
-DON'T: Refactor entire codebase at once
-DO: Incremental, step-by-step refactoring
+```markdown
+## Refactor Complete: {module} → {domain}
+
+### Files Created
+- List all new files
+
+### Files Modified
+- List all modified files
+
+### Files Deleted
+- List old module files removed
+
+### Endpoints/Screens Preserved
+| Before | After | Status |
+|--------|-------|--------|
+| All old routes | Same routes, new handlers | Verified |
+
+### Domain Events
+| Event | Listeners |
+|-------|-----------|
+
+### Test Coverage
+- X test files, Y test functions
+- All old test cases migrated: YES
+- Areas covered: value objects, entities, usecases
+
+### Review Status: ALL CHECKS PASS
+- Build: PASS
+- Lint: PASS
+- Domain purity: PASS
+- Old module removed: PASS
+- No old imports: PASS
+- Tests: PASS (X/X)
+- Architecture score: {A/B}
 ```
 
-### Changing Behavior
-```
-DON'T: Fix bugs during refactoring
-DON'T: Add features during refactoring
-DO: Pure refactoring only
-```
+---
 
-### Ignoring Tests
-```
-DON'T: Skip running tests
-DON'T: Disable failing tests
-DO: Tests pass after every step
-```
+## Interaction Rules
 
-### Ignoring Architecture
-```
-DON'T: Invent your own patterns
-DON'T: Violate architecture doc
-DO: Follow architecture doc exactly
-```
+1. After each phase, report Rule Check results to user
+2. If a rule fails → auto-fix if you know how, otherwise ask user
+3. **DO NOT skip any phase** — all rules must pass before moving to next
+4. If unsure about business logic → **READ the old code carefully, DO NOT invent new logic**
+5. Preserve behavior — refactor structure only, DO NOT change logic
+6. **MUST read old test files** before writing new tests
+7. When multiple modules map to same domain → first module creates domain dir, subsequent add to it
+8. After completing a module, ask user if they want to refactor the next module
+
+---
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| ANALYZE | `@refactor` | Identify refactoring opportunities |
+| ANALYZE | `@code-reviewer` | Code smell detection |
+| PLAN | `@clean-architect` | Architecture alignment |
+| REFACTOR | Stack-specific dev agent | Code per architecture |
+| TEST | `@test-writer` | Write domain tests |
+| REVIEW | `@code-reviewer` | Final quality check |