moicle 1.7.0 → 2.1.0

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

@@ -0,0 +1,277 @@
+---
+name: review-branch
+description: Review local branch changes for architecture compliance, conventions, and code quality before pushing/PR. Stack-aware — detects the project stack and applies the matching rules. Use when user says "review changes", "review branch", "check branch", "check changes", "review my code", "review before pr".
+args: "[BASE_BRANCH]"
+---
+
+# Review Local Branch Changes
+
+Self-review your branch vs a base branch before pushing or opening a PR. Checks architecture compliance, stack conventions, and code quality — on **changed files only**, not the whole codebase.
+
+**ARGUMENTS:** (optional) base branch. Default: `main` (fallback to `master`).
+
+## When to use this skill
+
+- ✅ Before pushing your branch / opening a PR
+- ✅ Before asking a teammate to review (catch easy issues first)
+- ✅ Quick sanity check on a feature you've been working on
+- ❌ Reviewing someone else's PR → use `/review:pr`
+- ❌ Only checking DDD architecture → use `/review:architect`
+- ❌ Security-only sweep → use `@security-audit` agent
+
+## Read Architecture First
+
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Load `ddd-architecture.md` + the stack doc — extract forbidden imports + conventions before reviewing.
+
+Severity definitions: `~/.claude/architecture/_shared/severity-levels.md` (code severity table).
+
+---
+
+## Workflow
+
+```
+0 DETECT → 1 COLLECT → 2 BUILD+LINT → 3 ARCH → 4 CONVENTIONS → 5 QUALITY → 6 TESTS → 7 REPORT → 8 FIX
+```
+
+---
+
+## Phase 0: DETECT
+
+- [ ] Stack detected (ask user if ambiguous, e.g., monorepo)
+- [ ] Architecture doc loaded
+- [ ] Forbidden-imports list extracted
+
+---
+
+## Phase 1: COLLECT
+
+```bash
+BASE=${1:-main}
+git rev-parse --verify "$BASE" >/dev/null 2>&1 || BASE=master
+
+git log "$BASE"..HEAD --oneline
+git diff "$BASE"...HEAD --stat
+git diff "$BASE"...HEAD --name-only --diff-filter=ACMR
+```
+
+Categorize changed files by layer:
+
+| Layer | Typical paths |
+|-------|---------------|
+| Domain | `domain/`, `internal/domain/`, `src/domain/`, `lib/domain/` |
+| Application | `application/`, `internal/application/`, `src/application/` |
+| Infrastructure | `infrastructure/`, `internal/infrastructure/`, `src/infrastructure/` |
+| Presentation / UI | `controllers/`, `pages/`, `components/`, `views/`, `ports/http/` |
+| Persistence | `models/`, `entities/` (ORM), `prisma/`, `migrations/` |
+| Config / Bootstrap | `config/`, `bootstrap/`, `cmd/`, `main.*` |
+
+Read **all** changed files before reviewing — never skim.
+
+---
+
+## Phase 2: BUILD + LINT
+
+Run the stack's build + typecheck + lint commands. If any fail → mark **CRITICAL** and stop further review until they pass.
+
+```bash
+# Go:       go build ./... && go vet ./...
+# NestJS:   pnpm typecheck && pnpm lint
+# Laravel:  composer dump-autoload && ./vendor/bin/phpstan analyse
+# Flutter:  dart analyze
+# React/Remix: pnpm typecheck && pnpm lint
+```
+
+---
+
+## Phase 3: ARCHITECTURE (changed files only)
+
+Apply the stack's rules. Common checks per layer:
+
+### 3.1 Domain (if changed)
+| # | Rule |
+|---|------|
+| D1 | Domain purity — no forbidden imports (ORM, HTTP, cache, queue, auth SDK) |
+| D2 | No cross-domain imports (only shared kernel allowed) |
+| D3 | No persistence-model imports in domain |
+| D4 | Entities have behavior (not anemic data bags) |
+| D5 | Entities raise events on state change (if architecture uses events) |
+| D6 | Ports in `ports/` dir (not inline in usecases) |
+| D7 | One port per file |
+| D8 | Ports return domain types, not primitives |
+| D9 | Value objects stdlib-only |
+| D10 | Usecases have no infra imports |
+
+Quick check:
+```bash
+CHANGED_DOMAIN=$(git diff "$BASE"...HEAD --name-only --diff-filter=ACMR \
+  | grep -E '^(src|internal|lib)/domain/')
+[ -n "$CHANGED_DOMAIN" ] && echo "$CHANGED_DOMAIN" \
+  | xargs grep -lEn '<STACK_FORBIDDEN_REGEX>' 2>/dev/null \
+  && echo FAIL || echo PASS
+```
+
+### 3.2 Application (if changed)
+| # | Rule |
+|---|------|
+| A1 | Handler is thin (parse → service → respond, no business logic) |
+| A2 | Service justified only when ≥2 usecases orchestrated |
+| A3 | Listener is side-effect only (no business logic) |
+| A4 | Listener registered in event bus |
+| A5 | Event name string matches registry |
+| A6 | DTOs validated at boundary |
+| A7 | Composition root only — no inline wiring in handlers |
+
+### 3.3 Infrastructure (if changed)
+| # | Rule |
+|---|------|
+| I1 | Repository has no business logic |
+| I2 | Mappers exist (domain ↔ ORM model) |
+| I3 | Implements port interface (returns domain types) |
+| I4 | Context / transaction propagation correct |
+
+### 3.4 Persistence models (if changed)
+| # | Rule |
+|---|------|
+| M1 | ORM models in infrastructure, NOT domain |
+| M2 | Schema change → matching migration |
+| M3 | Nullable columns use nullable types |
+
+---
+
+## Phase 4: CONVENTIONS (cross-stack)
+
+| # | Rule |
+|---|------|
+| G1 | No swallowed errors (no empty catch / `if err != nil {}`) |
+| G2 | Async work uses background context, NOT request context |
+| G3 | API-facing types have serialization tags (`json:`, decorators, etc.) |
+| G4 | No hardcoded secrets / tokens / keys |
+| G5 | Parameterized queries only — no string-interpolated SQL |
+| G6 | Input validation at boundary before reaching domain |
+
+Plus any stack-specific Hard Rules from the architecture doc.
+
+---
+
+## Phase 5: QUALITY (manual)
+
+Read the diff. Look for:
+
+| # | Area | What to look for |
+|---|------|------------------|
+| Q1 | Logic correctness | Off-by-one, nil deref, wrong condition, missed edge case |
+| Q2 | Error handling | Errors propagated/wrapped, not silently ignored |
+| Q3 | Concurrency | Race conditions, shared mutable state, async leaks |
+| Q4 | Resource leaks | Unclosed connections, HTTP bodies, file handles |
+| Q5 | Naming | Reveals intent (no `data`, `info`, `manager`, `helper`) |
+| Q6 | Dead code | Unreachable, unused, commented-out |
+| Q7 | Duplication | Real duplication across changed files (not coincidental) |
+| Q8 | Breaking change | API contract change, removed field, behavior change |
+| Q9 | Over-engineering | Abstraction not justified by the change |
+| Q10 | Test coverage | New logic has tests; bug fixes have regression tests |
+
+---
+
+## Phase 6: TESTS
+
+```bash
+# Tests for changed domains only
+CHANGED_DOMAINS=$(git diff "$BASE"...HEAD --name-only --diff-filter=ACMR \
+  | grep -E '/(domain|modules|features)/' \
+  | sed -E 's|.*(domain\|modules\|features)/([^/]+)/.*|\2|' | sort -u)
+
+for d in $CHANGED_DOMAINS; do
+  # Go:      go test ./internal/domain/$d/... -v
+  # NestJS:  npx jest src/domain/$d
+  # Laravel: ./vendor/bin/phpunit --filter $d
+  # Flutter: flutter test test/domain/$d
+  echo "Test $d"
+done
+
+# Full suite
+{full_test_command}
+```
+
+---
+
+## Phase 7: REPORT
+
+```markdown
+## Code Review: {branch} → {base}
+
+**Stack:** {stack} · **Commits:** {N} · **Files:** {N} (+{add} / -{del})
+
+### Build / Lint / Types
+| Check | Status |
+|-------|--------|
+| Build | PASS/FAIL |
+| Lint | PASS/FAIL |
+| Types | PASS/FAIL |
+
+### Architecture / Conventions / Quality
+| # | Rule | Status | File:line |
+|---|------|--------|-----------|
+| D1 | Domain purity | PASS | — |
+| G4 | No secrets | FAIL | `config/db.ts:42` hardcoded token |
+| Q1 | Logic correctness | OK | — |
+
+### Tests
+| Check | Status |
+|-------|--------|
+| Changed area tests | PASS/FAIL |
+| Full suite | PASS/FAIL |
+
+### Issues (sorted by severity)
+| # | Severity | File:line | Issue | Suggested fix |
+|---|----------|-----------|-------|---------------|
+| 1 | CRITICAL | config/db.ts:42 | hardcoded token | move to env |
+| 2 | HIGH | handlers/user.ts:88 | business logic in handler | extract to usecase |
+
+### Verdict
+{APPROVED / CHANGES REQUESTED}
+```
+
+### Verdict rules
+- **CRITICAL or HIGH found** → CHANGES REQUESTED
+- **MEDIUM only** → CHANGES REQUESTED (should fix)
+- **LOW only or nothing** → APPROVED (with suggestions if any)
+
+---
+
+## Phase 8: FIX (if user confirms)
+
+1. Fix in order: CRITICAL → HIGH → MEDIUM → LOW
+2. Re-run build + lint + tests after each batch
+3. Re-run full review when all fixed
+4. Report final status
+
+---
+
+## Hard Rules
+
+- **Changed files only** — don't expand scope to drive-by reviews
+- **Stop on CRITICAL** — fix build / lint / type errors before everything else
+- **File:line for every issue** — no vague "somewhere in handlers"
+- **Match severity honestly** — don't grade-inflate
+- **Test changed areas** — don't only rely on global test run
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Reviewing teammate's PR | `/review:pr` |
+| Deep DDD audit of a domain | `/review:architect` |
+| Fixing review comments on your PR | `/fix:pr-comment` |
+| Fixing bugs surfaced here | `/fix:hotfix` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| 3 Architecture | `@clean-architect` | DDD compliance |
+| 4 Conventions | `@security-audit` | Vulnerability sweep |
+| 5 Quality | `@code-reviewer` | Code smells |
+| 6 Tests | `@test-writer` | Coverage check |
+| 8 Fix | Stack-specific dev agent | Apply fixes |

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

@@ -0,0 +1,231 @@
+---
+name: review-pr
+description: Thorough pull request review workflow with architecture compliance checks. Use when reviewing pull requests, checking code changes, or when user says "review pr", "check pr", "review code", "pr review", "review pull request".
+---
+
+# Pull Request Review Workflow
+
+Review someone else's PR across 5 dimensions and post structured feedback to GitHub.
+
+## When to use this skill
+
+- ✅ Reviewing someone else's open PR (`gh pr view <number>` accessible)
+- ✅ Need to post structured feedback (APPROVE / REQUEST CHANGES / COMMENT)
+- ✅ Want a multi-dimensional review (architecture + security + perf + tests)
+- ❌ Self-review of own branch before push → use `/review:branch`
+- ❌ Only checking DDD compliance → use `/review:architect`
+- ❌ Addressing comments on your own PR → use `/fix:pr-comment`
+
+## Read Architecture First
+
+Load `~/.claude/architecture/ddd-architecture.md` + the stack-specific doc. Detect stack via `~/.claude/architecture/_shared/stack-detection.md`.
+
+---
+
+## Workflow
+
+```
+FETCH → ANALYZE → REVIEW (5 dims) → FEEDBACK → POST
+```
+
+---
+
+## Phase 1: FETCH
+
+**Goal:** load PR + diff + context in one pass.
+
+```bash
+PR={number}
+gh pr view $PR --json number,title,body,author,state,headRefName,baseRefName,commits,files
+gh pr diff $PR
+gh pr checks $PR
+gh pr view $PR --comments
+```
+
+### Gate
+- [ ] PR metadata + diff + CI status loaded
+- [ ] PR description explains "what / why" — if missing, ask author before deep review
+- [ ] CI status known (don't review red builds — ask author to fix first)
+
+---
+
+## Phase 2: ANALYZE
+
+**Goal:** understand scope before going line-by-line.
+
+1. **Scope check**: does the diff match the PR title / description? Mixed-scope PRs (e.g., feature + drive-by refactor) → ask author to split.
+2. **Risk profile**: which files? domain logic, infra config, migrations, auth — high risk vs UI tweak — low risk.
+3. **Test delta**: are new tests in the diff? coverage % up or down?
+4. **Reference module**: open 1 existing similar module to compare conventions.
+
+### Gate
+- [ ] PR scope is single-purpose (or split requested)
+- [ ] Risk level identified (low / medium / high)
+- [ ] Test delta noted
+
+---
+
+## Phase 3: REVIEW — 5 dimensions
+
+Severity definitions: `~/.claude/architecture/_shared/severity-levels.md` (code severity table).
+
+### 3.1 Architecture (CRITICAL / HIGH)
+
+For DDD-aware code, check against architecture doc:
+- Domain has zero framework imports
+- No cross-domain imports
+- Business logic in usecases, not handlers / stores
+- Ports in `ports/` dir (not inline interfaces)
+- Entities raise events on state changes
+- Listeners use background context, not request context
+
+**For deep DDD audit:** call `/review:architect` instead and link result.
+
+### 3.2 Security (CRITICAL / HIGH)
+
+- Input validation at trust boundary (handler / DTO)
+- AuthN + AuthZ checked before sensitive ops
+- No secrets / tokens in code or logs
+- SQL via parameterized queries / ORM — no string concatenation
+- File paths / shell commands sanitized
+- Rate limiting + idempotency on state-mutating endpoints
+- Crypto: standard library, no roll-your-own
+
+### 3.3 Performance (HIGH / MEDIUM)
+
+- No N+1 queries (eager-load relations the handler uses)
+- Indexes match new query patterns (check `EXPLAIN`)
+- Pagination on list endpoints (cursor preferred)
+- Background work for slow operations (don't block request)
+- Caching where appropriate, invalidation thought through
+- Synchronous external API calls have timeouts
+
+### 3.4 Testing (HIGH / MEDIUM)
+
+- New business logic has unit tests (usecases, entities, value objects)
+- New endpoints have at least 1 integration test (happy + error)
+- Tests assert on behavior, not implementation
+- Tests don't depend on order, time, or env
+- Coverage didn't drop for touched files
+
+### 3.5 Code quality (MEDIUM / LOW)
+
+- Names reveal intent (no `data`, `info`, `manager`, `helper`)
+- Functions do one thing
+- No dead branches or commented-out code
+- DRY only where the duplication is real (not coincidental)
+- Errors handled at boundary, not swallowed mid-flow
+
+---
+
+## Phase 4: FEEDBACK
+
+**Goal:** turn findings into actionable comments at the right place.
+
+### Decision (pick one)
+
+| Decision | When |
+|----------|------|
+| **APPROVE** | 0 CRITICAL / HIGH; LOW only |
+| **REQUEST CHANGES** | Any CRITICAL or HIGH; or multiple MEDIUM in same area |
+| **COMMENT** | Only style / nit comments; or asking questions before final review |
+
+### Inline comment format
+
+Be specific. File + line + rationale + suggested fix:
+
+```
+file: internal/wallet/usecases/withdraw.go:42
+severity: HIGH
+issue: Business logic in handler — `if wallet.Balance < amount` should live in
+the Withdraw usecase, not here. The handler should just call usecase and
+return the error.
+suggest:
+  // handler
+  result, err := s.WithdrawUsecase.Execute(ctx, req)
+
+  // usecase
+  func (u *WithdrawUsecase) Execute(ctx, req) (Result, error) {
+      if !wallet.HasSufficientBalance(amount) { return ErrInsufficient }
+      // ...
+  }
+```
+
+### Summary comment (top of PR)
+
+```markdown
+## Review Summary
+**Decision:** REQUEST CHANGES
+
+**Must fix (HIGH):**
+- [ ] `withdraw.go:42` — business logic moved out of handler
+- [ ] `withdraw.go:88` — missing input validation on `amount`
+
+**Should fix (MEDIUM):**
+- [ ] `withdraw_test.go` — only happy path tested, add insufficient-balance case
+- [ ] `wallet_store.go:120` — N+1 query loading transactions
+
+**Nits (LOW):**
+- [ ] `helper.go:5` — rename `helper` to something specific
+
+**What looked great:**
+- Clean port interface, good test naming, clear PR description.
+```
+
+### Gate
+- [ ] Decision matches severity rules
+- [ ] Every HIGH+ has file:line + suggested fix
+- [ ] Summary lists must-fix vs should-fix vs nits
+- [ ] Acknowledged what's good (not just criticism)
+
+---
+
+## Phase 5: POST
+
+```bash
+# Inline comments (one per finding)
+gh pr review $PR --request-changes --body "$(cat summary.md)"
+# or
+gh pr review $PR --approve --body "LGTM, see one nit"
+# or
+gh pr review $PR --comment --body "Questions before final review"
+
+# Optional: label
+gh pr edit $PR --add-label "needs-changes"
+```
+
+### Gate
+- [ ] Review posted to GitHub
+- [ ] Author has clear next-step list
+
+---
+
+## Hard Rules
+
+- **Don't review red CI** — ask author to fix tests / lint first
+- **Don't bikeshed style** when the team has a linter — let the tool flag it
+- **Always include "what went well"** — pure-criticism reviews demoralize
+- **One severity per finding** — don't grade-inflate to push for a fix
+- **File:line for every HIGH+** — author shouldn't have to grep for what you mean
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Reviewing own branch before push | `/review:branch` |
+| Only checking DDD architecture | `/review:architect` |
+| Fixing comments on your own PR | `/fix:pr-comment` |
+| Bug surfaced by review | `/fix:hotfix` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| ANALYZE | `@clean-architect` | Architecture context |
+| REVIEW 3.1 | `@clean-architect` | Architecture compliance |
+| REVIEW 3.2 | `@security-audit` | Security findings |
+| REVIEW 3.3 | `@perf-optimizer` | N+1, indexes, slow paths |
+| REVIEW 3.4 | `@test-writer` | Coverage + test quality |
+| REVIEW 3.5 | `@code-reviewer` | Naming + quality |