@nano-step/skill-manager 5.6.1 → 5.7.0

package/skills/pr-code-reviewer/checklists/frontend-vue-nuxt.md

@@ -0,0 +1,426 @@
+# Frontend Vue/Nuxt Checklist
+
+Comprehensive review checklist for Vue 3/Nuxt 3 frontend PRs (tradeit, tradeit-admin, audit-dashboard-frontend, etc.)
+
+---
+
+## 1. State Management
+
+### CRITICAL - Must Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| Vuex vs Pinia correct | `rootState.x` vs `useXStore()` | Vuex can't access Pinia |
+| Store registered | Module in `store/index.js` | Undefined state |
+| Computed get/set pattern | `computed({ get, set })` | Two-way binding |
+| storeToRefs for destructuring | `storeToRefs(store)` | Maintains reactivity |
+
+### Detection Patterns
+
+```javascript
+// CRITICAL: Vuex accessing Pinia store (will be undefined)
+// In Vuex action:
+const rate = rootState.currency.selectedRate  // currency is Pinia!
+
+// SECURE: Use Pinia directly
+import { useCurrencyStore } from '~/store/useCurrencyStore'
+const currencyStore = useCurrencyStore()
+const rate = currencyStore.selectedRate
+
+// CRITICAL: Store not registered
+// store/index.js missing:
+modules: {
+  // currency: currencyModule  // MISSING!
+}
+
+// WARNING: Destructuring loses reactivity
+const { items, loading } = useInventoryStore()  // Not reactive!
+
+// SECURE: Use storeToRefs
+const store = useInventoryStore()
+const { items, loading } = storeToRefs(store)
+
+// CRITICAL: Direct mutation (Vuex)
+state.items.push(newItem)  // Mutation outside mutation handler!
+
+// SECURE: Use mutation
+commit('ADD_ITEM', newItem)
+```
+
+---
+
+## 2. Reactivity
+
+### CRITICAL - Must Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| ref() for primitives | `ref(0)` not `reactive(0)` | reactive() doesn't work on primitives |
+| .value in script | `count.value++` | Required for refs in script |
+| toRefs for destructuring | `toRefs(props)` | Maintains reactivity |
+| No direct prop mutation | `emit('update:x', newVal)` | One-way data flow |
+
+### Detection Patterns
+
+```javascript
+// WARNING: reactive() on primitive
+const count = reactive(0)  // Won't work!
+
+// SECURE: ref() for primitives
+const count = ref(0)
+
+// CRITICAL: Missing .value in script
+const count = ref(0)
+count++  // Wrong! count is a ref object
+
+// SECURE: Use .value
+count.value++
+
+// CRITICAL: Mutating prop directly
+props.items.push(newItem)  // Mutating parent state!
+
+// SECURE: Emit event
+emit('add-item', newItem)
+
+// WARNING: Destructuring props loses reactivity
+const { modelValue } = defineProps(['modelValue'])
+watch(modelValue, ...)  // Won't trigger!
+
+// SECURE: Use toRefs or computed
+const props = defineProps(['modelValue'])
+watch(() => props.modelValue, ...)
+```
+
+---
+
+## 3. Network Calls
+
+### CRITICAL - Must Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| Use getAxiosInstance() | Not raw axios | Includes auth, base URL |
+| Error handling | try/catch or .catch() | User feedback |
+| Loading state managed | `loading.value = true/false` | UX |
+| Response fields validated | Check before access | Defensive coding |
+
+### Detection Patterns
+
+```javascript
+// WARNING: Raw axios
+import axios from 'axios'
+const { data } = await axios.get('/api/user')
+
+// SECURE: Use instance
+import { getAxiosInstance } from '~/network/axiosInstance'
+const axios = getAxiosInstance()
+const { data } = await axios.get('/api/user')
+
+// CRITICAL: No error handling
+const fetchData = async () => {
+  const { data } = await axios.get('/api/items')
+  items.value = data.items
+}
+
+// SECURE: With error handling
+const fetchData = async () => {
+  try {
+    loading.value = true
+    const { data } = await axios.get('/api/items')
+    items.value = data.items
+  } catch (e) {
+    error.value = e.message
+  } finally {
+    loading.value = false
+  }
+}
+
+// CRITICAL: Assuming response field exists (PR #1101 issue!)
+const imgUrl = item.imgURL  // undefined if backend changed!
+
+// SECURE: Defensive access
+const imgUrl = item.imgURL ?? getFallbackImage(item.groupId)
+```
+
+---
+
+## 4. Component Patterns
+
+### CRITICAL - Must Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| Props typed | `defineProps<{ x: string }>()` | Type safety |
+| Emits declared | `defineEmits(['update:x'])` | Documentation |
+| v-if/v-for not on same element | Use template wrapper | Vue limitation |
+| Key on v-for | `:key="item.id"` | Efficient updates |
+
+### Detection Patterns
+
+```vue
+<!-- CRITICAL: v-if and v-for on same element -->
+<div v-for="item in items" v-if="item.active">  <!-- Wrong! -->
+
+<!-- SECURE: Use template -->
+<template v-for="item in items" :key="item.id">
+  <div v-if="item.active">...</div>
+</template>
+
+<!-- WARNING: Missing key -->
+<div v-for="item in items">  <!-- No key! -->
+
+<!-- SECURE: With key -->
+<div v-for="item in items" :key="item.id">
+
+<!-- WARNING: Untyped props -->
+const props = defineProps(['modelValue', 'items'])
+
+<!-- SECURE: Typed props -->
+interface Props {
+  modelValue: string
+  items: Item[]
+}
+const props = defineProps<Props>()
+```
+
+---
+
+## 5. Composables
+
+### CRITICAL - Must Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| Returns reactive refs | `return { items, loading }` | Reactivity preserved |
+| No `this` usage | Composables don't have `this` | Runtime error |
+| Cleanup on unmount | `onUnmounted(() => ...)` | Memory leaks |
+| Named exports | `export function useX()` | Tree shaking |
+
+### Detection Patterns
+
+```javascript
+// CRITICAL: Using this in composable
+export function useInventory() {
+  this.items = []  // TypeError! No 'this' in composables
+}
+
+// SECURE: Use refs
+export function useInventory() {
+  const items = ref([])
+  return { items }
+}
+
+// WARNING: Not returning reactive
+export function useCounter() {
+  let count = 0  // Not reactive!
+  return { count }
+}
+
+// SECURE: Return refs
+export function useCounter() {
+  const count = ref(0)
+  return { count }
+}
+
+// WARNING: No cleanup
+export function useWebSocket() {
+  const ws = new WebSocket(url)
+  // Never closed!
+}
+
+// SECURE: Cleanup on unmount
+export function useWebSocket() {
+  const ws = new WebSocket(url)
+  onUnmounted(() => ws.close())
+  return { ws }
+}
+```
+
+---
+
+## 6. Nuxt-Specific
+
+### CRITICAL - Must Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| Client-only code guarded | `import.meta.client` | SSR errors |
+| Auto-imports from composables/ | Not utils/ | Only composables auto-imported |
+| useFetch for SSR data | Not axios in setup | SSR hydration |
+| definePageMeta for layouts | `definePageMeta({ layout: 'x' })` | Nuxt convention |
+
+### Detection Patterns
+
+```javascript
+// CRITICAL: Browser API in SSR
+const width = window.innerWidth  // ReferenceError on server!
+
+// SECURE: Guard with import.meta.client
+const width = import.meta.client ? window.innerWidth : 0
+
+// Or use onMounted
+onMounted(() => {
+  width.value = window.innerWidth
+})
+
+// CRITICAL: Using function from utils/ without import
+// In component:
+stripImageSizeFromUrl(url)  // undefined! utils/ not auto-imported
+
+// SECURE: Import explicitly
+import { stripImageSizeFromUrl } from '~/utils/helpers'
+
+// WARNING: axios in setup (SSR issues)
+const { data } = await axios.get('/api/items')
+
+// SECURE: useFetch for SSR
+const { data } = await useFetch('/api/items')
+```
+
+---
+
+## 7. i18n / Localization
+
+### WARNING - Should Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| No hardcoded strings | Use `$t('key')` | Localization |
+| Keys exist in locale files | Check en.js | Runtime errors |
+| Interpolation correct | `$t('key', { name })` | Dynamic content |
+
+### Detection Patterns
+
+```vue
+<!-- WARNING: Hardcoded string -->
+<button>Submit</button>
+
+<!-- SECURE: Use i18n -->
+<button>{{ $t('common.submit') }}</button>
+
+<!-- WARNING: Missing interpolation -->
+<p>{{ $t('welcome') }}</p>  <!-- "Welcome, {name}" shows literally -->
+
+<!-- SECURE: With interpolation -->
+<p>{{ $t('welcome', { name: user.name }) }}</p>
+```
+
+---
+
+## 8. Images & CDN
+
+### CRITICAL - Must Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| Use useCDNImage() | Not raw URLs | CDN optimization |
+| ImageWithFallback component | For item images | Handles missing images |
+| Lazy loading | `loading="lazy"` | Performance |
+
+### Detection Patterns
+
+```vue
+<!-- WARNING: Raw image URL -->
+<img :src="item.imgURL">  <!-- No fallback if undefined! -->
+
+<!-- SECURE: Use ImageWithFallback -->
+<ImageWithFallback :src="item.imgURL" :fallback="getFallback(item)" />
+
+<!-- WARNING: No lazy loading -->
+<img :src="url">
+
+<!-- SECURE: Lazy load -->
+<img :src="url" loading="lazy">
+```
+
+---
+
+## 9. Breaking Change Detection
+
+### Auto-Flag These Changes
+
+| Signal | Severity | Action |
+|--------|----------|--------|
+| Store module removed | CRITICAL | Search all consumers |
+| Composable return value changed | CRITICAL | Search all usages |
+| Network function signature changed | CRITICAL | Search all callers |
+| Component prop removed | WARNING | Search all usages |
+| Emit event renamed | WARNING | Search parent listeners |
+
+### Consumer Search Required
+
+```bash
+# For store changes
+grep -rn "useXStore" ./
+grep -rn "rootState.x" ./
+
+# For composable changes
+grep -rn "useComposable" ./
+
+# For component changes
+grep -rn "<ComponentName" ./
+```
+
+---
+
+## 10. Performance Checks
+
+### WARNING - Should Check
+
+| Check | Pattern | Why |
+|-------|---------|-----|
+| Large lists virtualized | `vue-virtual-scroller` | Memory |
+| Computed for derived state | Not methods | Caching |
+| v-once for static content | `<div v-once>` | Skip re-renders |
+| Async components for heavy | `defineAsyncComponent` | Code splitting |
+
+---
+
+## Quick Checklist
+
+Copy this for PR reviews:
+
+```markdown
+## Vue/Nuxt Frontend Review
+
+### State Management
+- [ ] Vuex/Pinia used correctly (not mixed)
+- [ ] Store modules registered
+- [ ] storeToRefs used for destructuring
+- [ ] No direct state mutation
+
+### Reactivity
+- [ ] ref() for primitives, reactive() for objects
+- [ ] .value used in script
+- [ ] Props not mutated directly
+
+### Network
+- [ ] getAxiosInstance() used (not raw axios)
+- [ ] Error handling present
+- [ ] Loading states managed
+- [ ] Response fields validated (defensive)
+
+### Components
+- [ ] Props typed with TypeScript
+- [ ] Emits declared
+- [ ] v-if/v-for not on same element
+- [ ] Keys on v-for
+
+### Nuxt-Specific
+- [ ] Client-only code guarded (import.meta.client)
+- [ ] Auto-imports only from composables/
+- [ ] useFetch for SSR data
+
+### i18n
+- [ ] No hardcoded user-facing strings
+- [ ] $t() keys exist in locale files
+
+### Images
+- [ ] useCDNImage() or ImageWithFallback used
+- [ ] Fallbacks for missing images
+
+### Breaking Changes
+- [ ] No store modules removed without consumer check
+- [ ] No composable signatures changed without search
+- [ ] No component props removed without search
+```

package/skills/pr-code-reviewer/checklists/review-checklist.md

@@ -0,0 +1,149 @@
+# PR Review Checklist
+
+Use this checklist for every PR review. Check off each item as you complete it.
+
+## Setup Check (Phase -2)
+
+- [ ] Check if `.opencode/code-reviewer.json` exists
+- [ ] If exists: read `stack` field → resolve framework rule files → store as `$FRAMEWORK_RULES`
+- [ ] If exists: read `agents` field → validate workspace_root, AGENTS.md, .agents/ dirs exist
+- [ ] If missing (or `/review --setup`): read `references/setup-wizard.md`, run wizard, write config
+- [ ] Confirm which framework rule files will be loaded (only stack-matching files)
+- [ ] Confirm agents knowledge base paths (workspace_root + which dirs found)
+
+## Resume Detection (Phase -1)
+
+- [ ] Look for existing checkpoint: `find /tmp -maxdepth 1 -type d -name "pr-review-${repo}-${pr_number}-*"`
+- [ ] If found: read `manifest.json` from `.checkpoints/`
+- [ ] Validate checkpoint: check PR number and head SHA match
+- [ ] Ask user: "Resume from phase {next_phase}? (y/n)"
+- [ ] If yes: load manifest + phase files, jump to `next_phase`
+- [ ] If no or invalid: delete old directory, start fresh from Phase 0
+
+## Pre-Review (Phase 0)
+
+- [ ] Extract repo info: `owner/repo`, `pr_number`, `head_branch`
+- [ ] Create unique temp dir: `/tmp/pr-review-{repo}-{pr}-{timestamp}`
+- [ ] Clone repo to temp dir (shallow clone with `--depth=1`)
+- [ ] Verify correct branch is checked out (`git log --oneline -1`)
+- [ ] Record `$REVIEW_DIR` path for all subsequent phases
+- [ ] Print confirmation with path and branch name
+- [ ] Save checkpoint: `.checkpoints/phase-0-clone.json`
+- [ ] Update manifest: `completed_phase: 0`, `next_phase: 1`
+
+## Context Gathering (Phase 1)
+
+- [ ] Read `{workspace_root}/AGENTS.md` → identify PR repo's domain
+- [ ] Read `.agents/_repos/{repo-name}.md` → repo-specific context
+- [ ] Read `.agents/_domains/{domain}.md` → domain context
+- [ ] Store combined as `$AGENTS_CONTEXT`
+- [ ] Get PR metadata: title, description, author, base branch
+- [ ] Get changed files with diff
+- [ ] Read full file context from `$REVIEW_DIR` (not workspace repo)
+- [ ] Classify each file: LOGIC / DELETION / STYLE / REFACTOR / NEW
+- [ ] Query nano-brain for past context on changed modules
+- [ ] Save checkpoint: `.checkpoints/phase-1-context.json`
+- [ ] Update manifest: `completed_phase: 1`, `next_phase: 1.5`
+
+## Linear Ticket Context (Phase 1.5)
+
+- [ ] Extract ticket ID from branch name, PR description, or PR title
+- [ ] If found: `linear_get_issue(id)` → fetch ticket details
+- [ ] If found: `linear_list_comments(issueId)` → fetch discussion
+- [ ] Extract acceptance criteria from ticket description
+- [ ] If images in description: `linear_extract_images(description)`
+- [ ] If not found: skip silently, continue without ticket context
+- [ ] Save checkpoint: `.checkpoints/phase-1.5-linear.json`
+- [ ] Update manifest: `completed_phase: 1.5`, `next_phase: 2`
+
+## Smart Tracing (Phase 2)
+
+- [ ] LOGIC changes: trace callers, callees, tests, types, data flow
+- [ ] STYLE changes: verify no hidden logic changes
+- [ ] REFACTOR changes: verify behavior preservation
+- [ ] Query nano-brain for known issues on changed functions
+- [ ] Save checkpoint: `.checkpoints/phase-2-tracing.json`
+- [ ] Update manifest: `completed_phase: 2`, `next_phase: 2.5`
+
+## PR Summary (Phase 2.5)
+
+- [ ] Write "What This PR Does" (1-3 sentences)
+- [ ] Categorize key changes (Feature/Bugfix/Refactor/etc.)
+- [ ] File-by-file summary with line numbers
+- [ ] Save checkpoint: `.checkpoints/phase-2.5-summary.json`
+- [ ] Update manifest: `completed_phase: 2.5`, `next_phase: 3`
+
+## Subagent Execution (Phase 3)
+
+- [ ] Include `$REVIEW_DIR` path in ALL subagent prompts
+- [ ] Launch Code Quality agent (explore)
+- [ ] After Code Quality completes: update `.checkpoints/phase-3-subagents.json` + manifest subagent_status
+- [ ] Launch Security & Logic agent (oracle)
+- [ ] After Security & Logic completes: update `.checkpoints/phase-3-subagents.json` + manifest subagent_status
+- [ ] Launch Docs & Best Practices agent (librarian)
+- [ ] After Docs & Best Practices completes: update `.checkpoints/phase-3-subagents.json` + manifest subagent_status
+- [ ] Launch Tests & Integration agent (general/quick)
+- [ ] After Tests & Integration completes: update `.checkpoints/phase-3-subagents.json` + manifest subagent_status
+- [ ] Collect ALL results (especially Oracle — never skip)
+- [ ] Update manifest: `completed_phase: 3`, `next_phase: 4`
+
+## Refinement (Phase 4)
+
+- [ ] Merge and deduplicate findings across agents
+- [ ] Consensus scoring: 2+ agents flagged same issue → boost confidence to high
+- [ ] Auto-downgrade: single agent + no evidence + critical/warning → suggestion
+- [ ] Apply severity filter (critical/warning keep, suggestion count-only)
+- [ ] Gap analysis — any subagent fail? Unreviewed files?
+- [ ] Second pass on gaps if needed
+- [ ] Save checkpoint: `.checkpoints/phase-4-refined.json`
+- [ ] Update manifest: `completed_phase: 4`, `next_phase: 4.5`
+
+## Verification Spot-Check (Phase 4.5)
+
+- [ ] Read `references/verification-protocol.md`
+- [ ] For each critical/warning finding: read cited code at evidence file:line in `$REVIEW_DIR`
+- [ ] Mark each: `verified:true` (keep) | `verified:false` (drop) | `verified:unverifiable` (downgrade to suggestion)
+- [ ] If no critical/warning findings: skip to Phase 4.6
+- [ ] Save checkpoint: `.checkpoints/phase-4.5-verification.json`
+- [ ] Update manifest: `completed_phase: 4.5`, `next_phase: 4.6`
+
+## Confidence Scoring (Phase 4.6)
+
+- [ ] Read `references/confidence-scoring.md`
+- [ ] Compute accuracy_rate, consensus_rate, evidence_rate
+- [ ] Compute overall score (0–100)
+- [ ] Apply gate: < 60 → add 🔴 warning, 60–79 → add ⚠️ warning, 80+ → proceed normally
+- [ ] Save checkpoint: `.checkpoints/phase-4.6-confidence.json`
+- [ ] Update manifest: `completed_phase: 4.6`, `next_phase: 5`
+
+## Report (Phase 5)
+
+- [ ] Save to `.opencode/reviews/{type}_{identifier}_{date}.md`
+- [ ] TL;DR with verdict and counts
+- [ ] Critical issues with full detail
+- [ ] Warnings with full detail
+- [ ] Improvements as one-liners
+- [ ] File summary table
+- [ ] Save checkpoint: `.checkpoints/phase-5-report.md`
+- [ ] Update manifest: `completed_phase: 5`, `next_phase: 5.5`
+
+## Save to Memory (Phase 5.5)
+
+- [ ] Write key findings to nano-brain with tags: review, {repo}
+- [ ] Verify searchable (`curl -s localhost:3100/api/search -d '{"query":"PR {number}"}'`)
+- [ ] Update manifest: `completed_phase: 5.5`, `next_phase: 6`
+
+## Cleanup (Phase 6)
+
+- [ ] Show temp folder path and size to user
+- [ ] **ASK user** before removing (NEVER auto-delete)
+- [ ] If user confirms → `rm -rf "$REVIEW_DIR"` (also removes `.checkpoints/`)
+- [ ] If user declines → remind them to clean up later
+- [ ] For multiple PRs: ask about each temp folder individually
+- [ ] Note: Checkpoints auto-removed with clone dir (PR reviews) or remain in `.checkpoints/` (local reviews)
+
+## Final Notification
+
+- [ ] Report path shown to user
+- [ ] Issue counts (critical/warning/suggestion) displayed
+- [ ] Temp folder cleanup status communicated

package/skills/pr-code-reviewer/references/checkpoint-system.md

@@ -0,0 +1,58 @@
+# Checkpoint System
+
+Reviews are resumable via checkpoints saved at each phase. If the agent crashes mid-review, you can resume from the last completed phase instead of starting over.
+
+## Checkpoint Directory
+
+**For PR Reviews:** `$REVIEW_DIR/.checkpoints/` (inside the temp clone directory)
+**For Local Reviews (`--staged`):** `{current_working_directory}/.checkpoints/`
+
+Checkpoints are automatically removed when the clone directory is deleted (Phase 6 cleanup).
+
+## Checkpoint Files
+
+| File | Content | Updated When |
+|------|---------|--------------|
+| `manifest.json` | Master state tracker | After every phase |
+| `phase-0-clone.json` | Clone metadata (clone_dir, branches, head_sha, files_changed) | Phase 0 |
+| `phase-1-context.json` | PR metadata, file classifications | Phase 1 |
+| `phase-1.5-linear.json` | Linear ticket context, acceptance criteria | Phase 1.5 |
+| `phase-2-tracing.json` | Smart tracing results per file | Phase 2 |
+| `phase-2.5-summary.json` | PR summary text | Phase 2.5 |
+| `phase-3-subagents.json` | Subagent findings (updated after EACH subagent completes) | Phase 3 |
+| `phase-4-refined.json` | Deduplicated/filtered findings | Phase 4 |
+| `phase-4.5-verification.json` | Verification results (verified/false/unverifiable counts, dropped/downgraded findings) | Phase 4.5 |
+| `phase-4.6-confidence.json` | Result confidence score, per-finding confidence, gate action | Phase 4.6 |
+| `phase-5-report.md` | Copy of final report | Phase 5 |
+
+## Manifest Schema
+
+```json
+{
+  "version": "1.0",
+  "pr": { "repo": "owner/repo", "number": 123, "url": "..." },
+  "clone_dir": "/tmp/pr-review-...",
+  "started_at": "ISO-8601",
+  "last_updated": "ISO-8601",
+  "completed_phase": 2,
+  "next_phase": 2.5,
+  "phase_status": {
+    "0": "complete", "1": "complete", "1.5": "complete",
+    "2": "complete", "2.5": "pending", "3": "pending",
+    "4": "pending", "4.5": "pending", "4.6": "pending", "5": "pending"
+  },
+  "subagent_status": {
+    "explore": "pending", "oracle": "pending",
+    "librarian": "pending", "general": "pending"
+  }
+}
+```
+
+## Phase 3 Special Handling
+
+Phase 3 runs 4 parallel subagents. After **EACH** subagent completes:
+1. Update `phase-3-subagents.json` with that subagent's findings and status
+2. Update `manifest.json` subagent_status to `"complete"` for that subagent
+3. On resume: only run subagents with status != `"complete"`
+
+This allows resuming mid-Phase-3 if only some subagents completed before a crash.