moicle 1.3.1 → 1.6.0

package/assets/skills/deep-debug/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: deep-debug
+description: Deep bug investigation workflow for hard-to-trace errors. Systematic root cause analysis — no guessing, no blind fixes. Use when user says "deep debug", "deep-debug", "trace bug", "find root cause", "hard bug", "investigate bug".
+---
+
+# Deep Bug Investigation Workflow
+
+For hard bugs that have been "fixed" multiple times without success. DO NOT guess — trace step by step to the root cause.
+
+## Step 1: Collect evidence
+
+Record exactly, DO NOT interpret:
+
+- Exact error message
+- Stack trace: file, line number, call chain
+- Which environment is affected (production/staging/local)
+- Happens every time or only in certain cases
+
+## Step 2: Verify the code that is actually running
+
+DO NOT assume the code on production = the code on local.
+
+- Identify the exact version/commit currently deployed
+- Compare it against the code you are reading locally
+- If they DIFFER → read the deployed version before analyzing further
+
+## Step 3: Trace the execution path
+
+This is the most important step. Go from entry point → to the failing line. Trace EVERY step, DO NOT skip.
+
+### 3a. Entry point → Error line
+
+- Where does the request/event/job enter from?
+- Which function calls which function? Follow the stack trace exactly.
+- How is data passed through each layer?
+
+### 3b. Where does the data at the failing line come from?
+
+- Where is the faulty variable created/loaded from?
+- Loaded directly from source (DB, API) or from cache/session?
+- Does it go through serialize → unserialize?
+- Does it go through any transform/convert?
+
+### 3c. Type & state at the moment of failure
+
+- What is the actual type of the variable? (string, object, null, enum...)
+- What type does the code expect?
+- Why does the actual type differ from the expected one?
+
+### 3d. Framework internals (when the error is inside vendor/library)
+
+- Read the source code at the EXACT line number from the stack trace
+- Trace backwards: who calls that method, and with what arguments
+- What condition drives the code into the failing branch
+
+## Step 4: Find the root cause — Answer 3 questions
+
+1. **Why does it fail?** — The specific technical cause
+2. **Why didn't it fail before?** — What changed
+3. **Reproduction conditions?** — When it fails, when it doesn't
+
+If you can't answer all 3 → go back to Step 3, trace further.
+
+## Step 5: Check hidden state sources
+
+"Sometimes works, sometimes doesn't" bugs are usually caused by hidden state. Check in this order:
+
+### Cache / Serialization
+
+- Does the object pulled from cache lose any internal state? (transient fields, lazy-loaded properties, runtime caches)
+- Does stale cache contain the old data format while new code expects the new format?
+- Does serialize/unserialize change the type? (int↔float, null handling, enum↔string)
+
+### Database / Storage
+
+- Do collation/encoding affect comparisons?
+- Do default values in the DB match the code's expectations?
+- Has the schema been updated on production yet?
+
+### Runtime cache / Compiled cache
+
+- Any compiled/cached config, routes, or views that haven't been cleared?
+- Does the bytecode cache (OPcache, compiled assets) serve the old file?
+- Does CDN/proxy cache serve a stale asset?
+
+### Environment
+
+- Are env vars on production correct/complete?
+- Does the runtime version (PHP, Node, Go, Python, etc.) differ from local?
+- Do dependency versions differ?
+
+## Step 6: Fix
+
+Only fix once you have answered the 3 questions from Step 4. The fix must:
+
+- Address the root cause, not the symptom
+- Handle the edge case discovered (stale cache, type mismatch)
+- Be defensive at data boundaries (cache, DB, external API) — not in internal logic
+- Not break the normal code path in order to patch an edge case
+
+## Step 7: Verify
+
+- Reproduce the failure conditions from Step 4 → confirm the fix works
+- Check the normal code path still works
+- If cache-related → test both fresh load and cached load
+- Verify against the actually deployed version (repeat Step 2)
+
+## IMPORTANT
+
+- **DO NOT GUESS** — Trace evidence, do not infer from variable names or "maybe it's..."
+- **DO NOT FIX BEFORE UNDERSTANDING** — Fixing without knowing the root cause = creating a new bug
+- **VERIFY DEPLOYED CODE** — Always check the running version, never assume production = local
+- **CHECK CACHE FIRST** — Most "sometimes works, sometimes doesn't" bugs come from stale cached state
+- **ONE ROOT CAUSE** — Every bug has one root cause. If multiple possibilities remain → trace further

package/assets/skills/new-feature/SKILL.md

@@ -1,317 +1,297 @@
 ---
 name: new-feature
-description: Complete feature development workflow from start to finish. Use when implementing new features, building functionality, or when user says "implement feature", "add feature", "build feature", "create feature", "new feature".
+description: DDD feature development workflow with phase-based checks and review loop. Use when implementing new features, building functionality, or when user says "implement feature", "add feature", "build feature", "create feature", "new feature".
+args: "[DOMAIN] [FEATURE]"
 ---
 
-# Feature Development Workflow
+# DDD Feature Development Workflow
 
-End-to-end workflow for developing features with feedback loops and quality gates.
+Build a new feature following DDD architecture, with automated checks after each phase and a review loop that keeps fixing until all checks pass.
 
-## IMPORTANT: Read Architecture First
+**ARGUMENTS:** `<domain> <feature>` — e.g., `wallet savings`, `notification broadcast`, `catalog products`
 
-**Before starting any phase, 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
-```
-
-### Project-specific (if exists)
-```
-.claude/architecture/        # Project overrides
-```
-
-**Follow the structure and patterns defined in these files exactly.**
+**Before starting, MUST read TWO files:**
 
-## Recommended Agents
+1. **Core DDD spec**: `.claude/architecture/ddd-architecture.md`
+2. **Stack-specific doc**: detect stack → read the corresponding architecture doc
 
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| DESIGN | `@clean-architect` | Design based on architecture docs |
-| IMPLEMENT | `@react-frontend-dev`, `@go-backend-dev`, `@laravel-backend-dev`, `@flutter-mobile-dev`, `@remix-fullstack-dev` | Stack-specific implementation |
-| IMPLEMENT | `@db-designer` | Database schema design |
-| IMPLEMENT | `@api-designer` | API design (REST/GraphQL) |
-| REVIEW | `@code-reviewer` | Code quality review |
-| REVIEW | `@security-audit` | Security vulnerabilities check |
-| REVIEW | `@perf-optimizer` | Performance optimization |
-| TEST | `@test-writer` | Unit/integration/e2e tests |
-| COMPLETE | `@docs-writer` | Documentation (if needed) |
-
-## 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. PLAN  │──▶│ 2. DESIGN│──▶│3. IMPLEMENT──▶│ 4. REVIEW│──▶│ 5. TEST  │──▶│6. COMPLETE
-└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
-                                                   │              │
-                                                   └──────◀───────┘
-                                                    Feedback Loop
+.claude/architecture/{name}.md     # Project-specific (priority)
+~/.claude/architecture/{name}.md   # Global
 ```
 
 ---
 
-## Phase 1: PLAN
-
-**Goal**: Understand requirements and break down into tasks
-
-### Actions
-1. Clarify requirements with user
-2. **Identify project stack** (Flutter, React, Go, Laravel, Remix, etc.)
-3. **Read the appropriate architecture doc** for this stack
-4. Identify affected files/modules based on architecture
-5. List acceptance criteria
-6. Create task breakdown using TodoWrite
-
-### Output
-```markdown
-## Feature: [Name]
-
-### Stack & Architecture
-- Stack: [Flutter/React/Go/Laravel/Remix]
-- Architecture Doc: [path to architecture file]
-
-### Requirements
-- [ ] Requirement 1
-- [ ] Requirement 2
+## Workflow
 
-### Affected Areas (based on architecture)
-- [Layer/Module 1]
-- [Layer/Module 2]
-
-### Tasks
-1. Task 1
-2. Task 2
 ```
-
-### Gate
-- [ ] Requirements clear
-- [ ] Architecture doc read
-- [ ] Scope defined based on architecture
-- [ ] Tasks broken down
+PHASE 1: Analyze & Plan
+  → PHASE 2: Build Domain Layer
+  → PHASE 3: Build Infrastructure Layer
+  → PHASE 4: Build Application Layer
+  → PHASE 5: Registration & Wiring
+  → PHASE 6: Domain Tests
+  → REVIEW LOOP (run /architect-review, fix issues, repeat until clean)
+```
 
 ---
 
-## Phase 2: DESIGN
+## PHASE 1: Analyze & Plan
+
+### 1.1 Read Architecture Docs
+1. Read `ddd-architecture.md` (core DDD rules)
+2. Read stack-specific architecture doc
+3. Extract: DDD directory structure, layer rules, hard rules, forbidden imports, check scripts
+
+### 1.2 Read Reference Module
+Pick a SMALL existing module in the project as reference. Read ALL its files to understand exact patterns:
+- Entities, value objects, events, ports, usecases
+- Service, handler, DTOs, listeners
+- Infrastructure store/API implementations
+- Registration in router/provider/registry
+
+### 1.3 Plan Feature
+Present to user:
+- All entities and their fields
+- All endpoints/screens/UI (depending on stack)
+- All domain events
+- All value objects
+- Business rules summary
+- Files to create/modify
+
+### Rule Check Phase 1
+- [ ] Architecture docs read and understood
+- [ ] Reference module read
+- [ ] Plan presented and **user CONFIRMED** before continuing
 
-**Goal**: Design feature following the project's architecture
-
-### Actions
-1. **Re-read architecture doc** for the specific stack
-2. Apply architecture principles from the doc:
-   - Identify which layers are affected
-   - Define components for each layer
-   - Follow naming conventions from doc
+---
 
-3. Design data flow based on architecture patterns
+## PHASE 2: Build Domain Layer
+
+Create in order: value objects → entities → events → ports → usecases
+
+### 2.1 Value Objects (`valueobjects/`)
+- Typed values with behavior methods
+- Status with `IsTerminal()`, `CanTransitionTo()`
+- **Only stdlib imports** — read Forbidden Imports from architecture doc
+
+### 2.2 Entities (`entities/`)
+- Constructor function/method
+- Behavior methods that raise events (state transitions, calculations)
+- Guard methods (isActive, canXxx)
+- Business error types
+- Only imports: stdlib + valueobjects + domain/shared
+
+### 2.3 Events (`events/`)
+- One file per event
+- Extend/embed base event type
+- Carry data needed by listeners (userID, amounts, names)
+
+### 2.4 Ports (`ports/`)
+- One file per interface
+- Store interfaces use domain entity types and value objects
+- DTOs for complex query results live here
+- No infrastructure imports
+
+### 2.5 UseCases (`usecases/`)
+- Constructor with port dependencies + event dispatcher
+- Split by concern: one file per action group
+- Business logic lives HERE
+- Dispatch entity events after successful save
+- **No infrastructure imports** — read Forbidden Imports from architecture doc
+
+### Rule Check Phase 2
+Run the **Domain Purity** check scripts from the stack architecture doc:
+```bash
+# Example (Go):
+go build ./internal/domain/$DOMAIN/... && echo "PASS" || echo "FAIL"
+go vet ./internal/domain/$DOMAIN/... && echo "PASS" || echo "FAIL"
+grep -rn {forbidden_imports} internal/domain/$DOMAIN/ && echo "FAIL" || echo "PASS"
+
+# Example (React):
+npx tsc --noEmit && echo "PASS" || echo "FAIL"
+grep -rn "from 'react'" src/domain/$DOMAIN/ && echo "FAIL" || echo "PASS"
+
+# Example (Flutter):
+dart analyze lib/domain/$DOMAIN/ && echo "PASS" || echo "FAIL"
+grep -rn "package:flutter" lib/domain/$DOMAIN/ && echo "FAIL" || echo "PASS"
+```
 
-### Design Template
-```markdown
-## Architecture Design
+---
 
-### Reference
-- Architecture Doc: [path]
-- Pattern: [pattern from doc]
+## PHASE 3: Build Infrastructure Layer
 
-### Layers Affected (from architecture doc)
-- Layer 1: [components]
-- Layer 2: [components]
-- Layer 3: [components]
+### 3.1 Persistence Models (if applicable)
+- ORM models, Prisma schema, Freezed classes
+- Table/collection configuration
+- Helper functions for atomic updates
 
-### Data Flow (from architecture doc)
-[Follow the data flow pattern defined in doc]
+### 3.2 Store/API Implementation
+- Implements port interfaces from domain
+- Compile-time interface check (where language supports it)
+- Mapper functions: domain entity ↔ persistence model
+- NO business logic — pure persistence/communication
+- Use context consistently
 
-### Dependencies
-[List dependencies following DI pattern from doc]
+### Rule Check Phase 3
+```bash
+# Build infrastructure layer
+{stack_build_command_for_infra}
 ```
 
-### Gate
-- [ ] Design follows architecture doc
-- [ ] Layers properly defined
-- [ ] Dependencies follow doc patterns
-
 ---
 
-## Phase 3: IMPLEMENT
+## PHASE 4: Build Application Layer
 
-**Goal**: Code the feature following the architecture doc
+### 4.1 Service
+- Thin wrapper delegating to usecases
+- Can orchestrate cross-domain calls if needed
 
-### Actions
-1. **Read implementation order from architecture doc**
-2. Follow the directory structure from doc
-3. Follow naming conventions from doc
-4. Use patterns defined in doc (DI, state management, etc.)
+### 4.2 Transport/Handler/Controller/Screen
+- Registration/wiring function: create store → usecase → service → handler → routes
+- Thin handlers: parse input → call service → return output
+- DTOs in separate file
 
-### Implementation Checklist
-```markdown
-## Implementation (following [stack] architecture)
-
-Reference: [architecture doc path]
-
-### Directory Structure (from doc)
-[Follow exact structure from architecture doc]
+### 4.3 Listeners (if domain has events)
+- One file per event
+- Side-effects only (notifications, SSE, analytics, async jobs)
+- Use background context for async work
+- Register in event bus/registry
 
-### Implementation Order (from doc)
-[Follow order defined in architecture doc]
-
-### Code Conventions (from doc)
-[Follow conventions defined in architecture doc]
+### Rule Check Phase 4
+```bash
+# Build application layer
+{stack_build_command_for_application}
 ```
 
-### Gate
-- [ ] Structure matches architecture doc
-- [ ] All layers implemented per doc
-- [ ] Code compiles without errors
-- [ ] Basic functionality works
-
 ---
 
-## Phase 4: REVIEW
-
-**Goal**: Review code quality against architecture doc
+## PHASE 5: Registration & Wiring
 
-### Actions
-1. **Compare implementation with architecture doc**
-2. Check architecture rules are followed:
-   - [ ] Layer boundaries respected
-   - [ ] Dependencies flow correctly
-   - [ ] Patterns used correctly
+### 5.1 Router/Provider Registration
+- Add routes/screens/providers for the new module
+- Wire service dependencies between modules if needed
 
-3. Security check:
-   - [ ] Input validation
-   - [ ] No sensitive data exposure
-   - [ ] Proper authentication/authorization
+### 5.2 Persistence Setup
+- Add model migrations/schemas
+- Run migrations if needed
 
-4. Performance check:
-   - [ ] Efficient queries
-   - [ ] Proper caching (if in doc)
-   - [ ] No obvious bottlenecks
+### 5.3 Event Registry
+- Register all new event listeners
+- Verify event name strings match between events and registry
 
-### Review Output
-```markdown
-## Code Review Summary
-
-### Architecture Compliance: [Pass/Fail]
-- Reference: [architecture doc]
-- Issues: [list]
-
-### Quality: [Good/Needs Work]
-- Issues: [list]
-
-### Security: [Pass/Fail]
-- Issues: [list]
-
-### Performance: [Pass/Fail]
-- Issues: [list]
+### Rule Check Phase 5
+```bash
+# Full build
+{stack_full_build_command}
 ```
 
-### Gate
-- [ ] Architecture doc followed
-- [ ] No critical issues
-- [ ] Security issues resolved
+---
 
-### Feedback Loop
-If issues found → Return to IMPLEMENT phase → Fix → Re-review
+## PHASE 6: Domain Tests
+
+### 6.1 Value Object Tests
+- All status transitions
+- Terminal states
+- Behavior methods
+- Edge cases
+
+### 6.2 Entity Tests
+- Constructor
+- State transitions
+- Event collection after state change
+- Guard methods
+- Edge cases (boundary values)
+
+### 6.3 UseCase Tests
+- Mock port interfaces
+- Happy path for each method
+- Validation errors
+- Business rules
+- Event dispatching
+
+### Rule Check Phase 6
+```bash
+# Run domain tests
+{stack_test_command_for_domain}
+```
 
 ---
 
-## Phase 5: TEST
+## REVIEW LOOP
 
-**Goal**: Ensure feature works with tests
+After all phases complete, run the architecture review. **Keep looping until ALL checks pass.**
 
-### Actions
-1. **Read testing patterns from architecture doc**
-2. Write tests following doc conventions:
-   - Test locations from doc
-   - Mocking patterns from doc
-   - Coverage expectations from doc
+```
+LOOP:
+  1. Run /architect-review {stack} {domain}
+  2. Collect violations
+  3. IF violations with severity >= MEDIUM:
+     a. Fix all violations
+     b. Run build to verify
+     c. Run tests to verify
+     d. GOTO 1
+  4. IF score >= B:
+     BREAK → Final Report
+```
 
-3. Run tests:
-   ```bash
-   # Use test command from architecture doc
-   flutter test           # Flutter
-   go test ./...          # Go
-   bun test               # React/Remix
-   php artisan test       # Laravel
-   ```
+---
 
-### Gate
-- [ ] Tests follow architecture doc patterns
-- [ ] All tests pass
-- [ ] Coverage acceptable
+## Final Report
 
-### Feedback Loop
-If tests fail → Return to IMPLEMENT → Fix → Re-test
+When review loop passes:
 
----
+```markdown
+## Feature Complete: {domain}/{feature}
 
-## Phase 6: COMPLETE
+### Files Created
+- List all new files
 
-**Goal**: Finalize and deliver the feature
+### Files Modified
+- List all modified files
 
-### Actions
-1. Final checks:
-   - [ ] All gates passed
-   - [ ] Code formatted (use formatter from doc)
-   - [ ] No TODO comments left
+### Endpoints/Screens (depending on stack)
+| Method/Route | Description |
+|-------------|-------------|
 
-2. Git operations:
-   ```bash
-   git add .
-   git commit -m "feat: [feature description]"
-   ```
+### Domain Events
+| Event | Listeners |
+|-------|-----------|
 
-3. Create PR (if applicable):
-   ```bash
-   gh pr create --title "feat: [feature]" --body "[description]"
-   ```
+### Test Coverage
+- X test files, Y test functions
+- Areas covered: value objects, entities, usecases
 
-### Completion Checklist
-- [ ] Feature follows architecture doc
-- [ ] Tests passing
-- [ ] Code reviewed
-- [ ] Committed/PR created
+### Review Status: ALL CHECKS PASS
+- Build: PASS
+- Lint: PASS
+- Domain purity: PASS
+- Tests: PASS (X/X)
+- Architecture score: {A/B}
+```
 
 ---
 
-## 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` |
-
-### Phase Summary
-| Phase | Key Actions |
-|-------|-------------|
-| PLAN | Read arch doc, clarify, breakdown |
-| DESIGN | Design per arch doc |
-| IMPLEMENT | Code per arch doc |
-| REVIEW | Check arch compliance |
-| TEST | Test per arch doc patterns |
-| COMPLETE | Commit, PR |
-
-### When to Loop Back
-- **REVIEW fails** → Return to IMPLEMENT
-- **TEST fails** → Return to IMPLEMENT
-- **Requirements change** → Return to PLAN
-
-### Success Criteria
-Feature is complete when:
-1. Follows architecture doc
-2. All acceptance criteria met
-3. All tests passing
-4. Code review passed
-5. Committed/PR created
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| PLAN | `@clean-architect` | Architecture design |
+| IMPLEMENT | Stack-specific dev agent | Code per architecture |
+| IMPLEMENT | `@db-designer` | Database schema |
+| IMPLEMENT | `@api-designer` | API design |
+| REVIEW | `@code-reviewer` | Code quality |
+| REVIEW | `@security-audit` | Security check |
+| TEST | `@test-writer` | Write tests |