@nano-step/skill-manager 5.6.2 → 5.7.0

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.

package/skills/pr-code-reviewer/references/confidence-scoring.md

@@ -0,0 +1,98 @@
+# Confidence Scoring (Phase 4.6)
+
+Re-review the final findings to score how confident we are in the review's **results** — are the findings correct and complete?
+
+**Always run this phase**, even if no critical/warning findings remain. The confidence score reflects the entire review quality, not just individual findings.
+
+## Per-Finding Confidence
+
+For each surviving finding (post Phase 4.5), assign a confidence level:
+
+| Level | Criteria |
+|-------|----------|
+| 🟢 High | Verified with concrete file:line evidence AND 2+ agents independently flagged it |
+| 🟡 Medium | Verified but single agent, OR 2+ agents agreed but evidence is indirect |
+| 🔴 Low | Unverifiable, pattern-based reasoning, no agent consensus |
+
+## Overall Confidence Score (0–100)
+
+Compute from three measurable rates:
+
+```
+# Inputs (from Phase 4 + 4.5)
+raw_findings        = total findings from all 4 subagents (before dedup)
+false_positives     = findings dropped in Phase 4.5 as verified:false
+verified            = findings confirmed real in Phase 4.5 (verified:true)
+unverifiable        = findings marked unverifiable in Phase 4.5
+final_findings      = all findings in the final report (critical + warning + improvement + suggestion)
+consensus_findings  = final findings that were flagged by 2+ agents independently
+evidence_findings   = final findings that cite concrete file:line proof
+
+# Rates
+accuracy_rate   = verified / max(verified + false_positives, 1)        # How often we're right (0.0–1.0)
+consensus_rate  = consensus_findings / max(final_findings, 1)          # Agreement level (0.0–1.0)
+evidence_rate   = evidence_findings / max(final_findings, 1)           # Proof quality (0.0–1.0)
+
+# Weighted score
+overall = round((accuracy_rate * 40) + (consensus_rate * 30) + (evidence_rate * 30))
+```
+
+## Special Cases
+
+- If Phase 4.5 was skipped (no critical/warning to verify): `accuracy_rate = 1.0` (no false positives possible)
+- If `final_findings == 0` (clean review, no issues found): `overall = 100` (nothing to be wrong about)
+- If all subagents returned empty findings: `overall = 100` with note "No issues found by any agent"
+
+## Confidence Thresholds & Gate Behavior
+
+| Score | Label | Gate Action |
+|-------|-------|-------------|
+| 80–100 | 🟢 High | Proceed normally — findings are reliable |
+| 60–79 | 🟡 Medium | Add ⚠️ in report: "Some findings may be inaccurate — verify manually" |
+| < 60 | 🔴 Low | Add 🔴 in report: "Low confidence review — significant uncertainty in findings. Manual review recommended." |
+
+## Display Format (included in Phase 5 TL;DR)
+
+```
+📊 Result Confidence: 🟢 92/100
+   Accuracy: 85% (3 false positives caught and removed)
+   Consensus: 100% (all findings had 2+ agent agreement)
+   Evidence: 100% (all findings cite file:line proof)
+```
+
+For low confidence:
+```
+📊 Result Confidence: 🔴 45/100
+   Accuracy: 50% (4 of 8 findings were false positives)
+   Consensus: 30% (most findings from single agent only)
+   Evidence: 60% (some findings lack concrete proof)
+   ⚠️ Low confidence — manual review recommended for: [list specific uncertain findings]
+```
+
+## Checkpoint Schema
+
+Save results to `.checkpoints/phase-4.6-confidence.json`:
+
+```json
+{
+  "raw_findings": 16,
+  "false_positives": 3,
+  "verified": 5,
+  "unverifiable": 0,
+  "final_findings": 6,
+  "consensus_findings": 4,
+  "evidence_findings": 6,
+  "accuracy_rate": 0.625,
+  "consensus_rate": 0.667,
+  "evidence_rate": 1.0,
+  "overall_score": 75,
+  "label": "medium",
+  "per_finding_confidence": [
+    { "file": "src/service.js", "line": 42, "severity": "warning", "confidence": "high" },
+    { "file": "src/utils.js", "line": 10, "severity": "improvement", "confidence": "medium" }
+  ],
+  "gate_action": "Add warning to report"
+}
+```
+
+Update `manifest.json` (`completed_phase: 4.6`, `next_phase: 5`).

package/skills/pr-code-reviewer/references/framework-rules/nextjs.md

@@ -0,0 +1,58 @@
+# Next.js Code Review Rules
+
+## Critical Rules
+
+### Data Fetching
+- `getServerSideProps` fetching data that doesn't change per-request → use `getStaticProps` + ISR
+- Missing `revalidate` in `getStaticProps` for dynamic content → stale data
+- Calling internal API routes from `getServerSideProps` → call the handler function directly
+- `fetch` in Server Components without `{ cache: 'no-store' }` when fresh data required → unexpected caching
+
+### Routing & Navigation
+- `useRouter().push()` for external URLs → use `window.location.href`
+- Missing `loading.tsx` for slow data fetches → no loading state shown
+- Dynamic route params accessed before null check → crash on direct URL access
+
+### App Router (Next.js 13+)
+- `'use client'` on a component that has no client-side interactivity → unnecessary client bundle
+- `useState` / `useEffect` in Server Component → runtime error
+- Passing non-serializable props from Server → Client component → crash
+
+### Server Actions
+- No input validation in Server Actions → security hole
+- Missing `revalidatePath` / `revalidateTag` after mutations → stale cache
+
+## Warning Rules
+
+### Performance
+- Large `node_modules` imports in `'use client'` components → bundle bloat (use dynamic imports)
+- Missing `next/image` for `<img>` tags → no lazy loading / optimization
+- Missing `next/font` for Google Fonts → layout shift (CLS)
+- `useEffect` for data fetching → waterfall; prefer Server Components
+
+### Auth & Security
+- Middleware not protecting `/api` routes that require auth
+- `cookies()` / `headers()` in cached Server Components → dynamic rendering forced silently
+- Sensitive env vars without `NEXT_PUBLIC_` prefix check — public prefix exposes to client
+
+## Suggestions
+- Use `next/dynamic` for heavy components with `ssr: false` when not needed server-side
+- Use `unstable_cache` for expensive DB queries in Server Components
+- Wrap `<Suspense>` around async Server Components for streaming
+
+## Detection Patterns
+
+```tsx
+// CRITICAL: useState in Server Component
+// app/page.tsx (no 'use client')
+const [count, setCount] = useState(0)  // Error: hooks in Server Component
+
+// CRITICAL: internal API fetch in getServerSideProps
+export async function getServerSideProps() {
+  const res = await fetch('http://localhost:3000/api/data')  // Wrong
+  // Should: import and call the handler directly
+}
+
+// WARNING: img instead of next/image
+<img src={user.avatar} />  // Use <Image> from 'next/image'
+```

package/skills/pr-code-reviewer/references/framework-rules/prisma.md

@@ -0,0 +1,54 @@
+# Prisma Code Review Rules
+
+## Critical Rules
+
+### Data Safety
+- `prisma.user.deleteMany({})` with empty where → deletes all rows
+- Raw queries with string interpolation → SQL injection (`prisma.$queryRaw` must use tagged template literal `Prisma.sql`)
+- Missing `select` / `omit` on queries that return sensitive fields (e.g., `password`, `token`) → data leak
+- `prisma.$transaction` with non-atomic operations that should be atomic → partial write on failure
+
+### Migrations
+- Renaming a column by adding new + deleting old in one migration → data loss if deployed without backfill
+- `@default(now())` added to existing non-nullable column → migration fails on non-empty table
+- Missing `migrate deploy` step noted in release process for schema changes
+
+## Warning Rules
+
+### Performance
+- `findMany` without `take` (limit) → unbounded query, potential OOM
+- N+1: loop calling `findUnique` per item → use `findMany` with `in` filter or `include`
+- Missing `index` on columns used in `where`, `orderBy`, or `join` → full table scan
+- `include` nesting 3+ levels deep → over-fetching
+
+### Patterns
+- Using `upsert` when only create or only update is semantically correct → confusing intent
+- `update` without checking record exists → silent no-op if not found (use `update` which throws, not `upsert`)
+- Accessing `prisma` directly in route handlers → should go through a repository/service layer
+
+## Suggestions
+- Use `select` to fetch only needed columns (reduces payload size)
+- Use `prisma.$transaction([...])` for related writes that must succeed together
+- Add `@@index` directives for common query patterns in schema
+
+## Detection Patterns
+
+```typescript
+// CRITICAL: SQL injection via raw query
+const user = await prisma.$queryRaw(`SELECT * FROM users WHERE id = ${userId}`)
+// SAFE:
+const user = await prisma.$queryRaw(Prisma.sql`SELECT * FROM users WHERE id = ${userId}`)
+
+// CRITICAL: missing field exclusion
+const user = await prisma.user.findUnique({ where: { id } })
+// user.password is returned — should use select or omit
+
+// WARNING: N+1
+for (const order of orders) {
+  const user = await prisma.user.findUnique({ where: { id: order.userId } })
+}
+// FIX: findMany with where: { id: { in: orders.map(o => o.userId) } }
+
+// WARNING: unbounded query
+const all = await prisma.product.findMany()  // missing take:
+```

package/skills/pr-code-reviewer/references/framework-rules/react.md

@@ -0,0 +1,61 @@
+# React Code Review Rules
+
+## Critical Rules
+
+### Hooks
+- Hooks called conditionally → violates Rules of Hooks, runtime error
+- `useEffect` with missing dependency → stale closure / infinite loop
+- `useEffect` with object/array literal in deps → new reference every render, infinite loop
+- Mutating state directly (`state.items.push(x)`) → no re-render triggered
+
+### State & Props
+- Derived state stored in `useState` when it can be computed inline → sync issues
+- Prop drilling 3+ levels deep without context or state manager → maintenance burden (flag as warning)
+- Reading stale ref value in async callback after unmount → memory leak / crash
+
+### Event Handling
+- Missing cleanup in `useEffect` (subscriptions, timers, event listeners) → memory leak
+- `onClick` on non-interactive element without keyboard equivalent → accessibility gap
+
+## Warning Rules
+
+### Performance
+- Anonymous functions / object literals as props to memoized components → memo is bypassed
+- Missing `useCallback` on functions passed to child components with `React.memo`
+- Large lists rendered without virtualization (`react-window` / `react-virtual`) → slow paint
+- `useContext` on frequently-changing context → unnecessary re-renders
+
+### Patterns
+- `index` as `key` in lists that can reorder/filter → wrong element reconciled
+- Multiple `useState` for related state → use `useReducer`
+- `useEffect` for synchronizing with external system vs for side effects — distinguish them
+
+## Suggestions
+- Use `React.lazy` + `<Suspense>` for code-splitting heavy routes
+- Consider `useMemo` for expensive calculations with stable inputs
+- Use `<ErrorBoundary>` around async components
+
+## Detection Patterns
+
+```tsx
+// CRITICAL: conditional hook
+if (user) {
+  const [name, setName] = useState(user.name)  // Error: conditional hook
+}
+
+// CRITICAL: missing cleanup
+useEffect(() => {
+  const sub = eventBus.subscribe(handler)
+  // Missing: return () => sub.unsubscribe()
+}, [])
+
+// CRITICAL: stale closure
+useEffect(() => {
+  setInterval(() => {
+    console.log(count)  // stale if count not in deps
+  }, 1000)
+}, [])  // Missing: count in deps
+
+// WARNING: object literal breaks memo
+<MyMemo style={{ color: 'red' }} />  // new object every render
+```

package/skills/pr-code-reviewer/references/nano-brain-integration.md

@@ -5,30 +5,26 @@ nano-brain provides persistent memory across sessions. The reviewer uses it for
 - Known issues and tech debt in affected modules
 - Prior discussions about the same code areas
 
-## Access Method: CLI
+## Access Method: HTTP API
 
-All nano-brain operations use the CLI via Bash tool:
+All nano-brain operations use HTTP API (nano-brain runs as Docker service on port 3100):
 
-| Need | CLI Command |
-|------|-------------|
-| Hybrid search (best quality) | `npx nano-brain query "search terms"` |
-| Keyword search (function name, error) | `npx nano-brain query "exact term" -c codebase` |
-| Save review findings | `npx nano-brain write "content" --tags=review` |
-
-## Setup
-
-Run `/nano-brain-init` in the workspace, or `npx nano-brain init --root=/path/to/workspace`.
+| Need | Command |
+|------|---------|
+| Hybrid search (best quality) | `curl -s localhost:3100/api/query -d '{"query":"search terms"}'` |
+| Keyword search (function name, error) | `curl -s localhost:3100/api/search -d '{"query":"exact term"}'` |
+| Save review findings | `curl -s localhost:3100/api/write -d '{"content":"...","tags":"review"}'` |
 
 ## Phase 1 Memory Queries
 
 For each significantly changed file/module:
-- **Hybrid search**: `npx nano-brain query "<module-name>"` (best quality, combines BM25 + vector + reranking)
-- **Scoped search**: `npx nano-brain query "<function-name>" -c codebase` for code-specific results
+- **Hybrid search**: `curl -s localhost:3100/api/query -d '{"query":"<module-name>"}'` (best quality, combines BM25 + vector + reranking)
+- **Scoped search**: `curl -s localhost:3100/api/query -d '{"query":"<function-name>","collection":"codebase"}'` for code-specific results
 
 Specific queries:
-- Past review findings: `npx nano-brain query "review <module-name>"`
-- Architectural decisions: `npx nano-brain query "<module-name> architecture design decision"`
-- Known issues: `npx nano-brain query "<function-name> bug issue regression"`
+- Past review findings: `curl -s localhost:3100/api/query -d '{"query":"review <module-name>"}'`
+- Architectural decisions: `curl -s localhost:3100/api/query -d '{"query":"<module-name> architecture design decision"}'`
+- Known issues: `curl -s localhost:3100/api/query -d '{"query":"<function-name> bug issue regression"}'`
 
 Collect relevant memory hits as `projectMemory` context for subagents.
 
@@ -36,7 +32,7 @@ Collect relevant memory hits as `projectMemory` context for subagents.
 
 Query nano-brain for known issues:
 ```bash
-npx nano-brain query "<function-name> bug issue edge case regression"
+curl -s localhost:3100/api/query -d '{"query":"<function-name> bug issue edge case regression"}'
 ```
 
 ## Phase 5.5: Save Review to nano-brain
@@ -44,18 +40,7 @@ npx nano-brain query "<function-name> bug issue edge case regression"
 After generating the report, save key findings for future sessions:
 
 ```bash
-npx nano-brain write "## Code Review: PR #<number> - <title>
-Date: <date>
-Files: <changed_files>
-
-### Key Findings
-<critical_issues_summary>
-<warnings_summary>
-
-### Decisions
-<architectural_decisions_noted>
-
-### Recommendation: <APPROVE|REQUEST_CHANGES|COMMENT>" --tags=review,pr-<number>
+curl -s localhost:3100/api/write -d '{"content":"## Code Review: PR #<number> - <title>\nDate: <date>\nFiles: <changed_files>\n\n### Key Findings\n<critical_issues_summary>\n<warnings_summary>\n\n### Decisions\n<architectural_decisions_noted>\n\n### Recommendation: <APPROVE|REQUEST_CHANGES|COMMENT>","tags":"review,pr-<number>"}'
 ```
 
 This ensures future reviews can reference past findings on the same codebase areas.

package/skills/pr-code-reviewer/references/report-template.md

@@ -30,6 +30,11 @@ Create `.opencode/reviews/` if it does not exist.
 {If Phase 4.5 verified all findings: "🔍 All findings verified"}
 {If Phase 4.5 was skipped (no critical/warning): omit this line entirely}
 
+📊 **Result Confidence: {emoji} {score}/100**
+   Accuracy: {accuracy_rate}% ({false_positives} false positive(s) caught) | Consensus: {consensus_rate}% | Evidence: {evidence_rate}%
+{If score < 80: "⚠️ {gate_message}"}
+{If score >= 80: omit the warning line}
+
 ## What This PR Does
 
 {1-3 sentences. Start with action verb. Include business impact if clear.}

package/skills/pr-code-reviewer/references/setup-wizard.md

@@ -0,0 +1,207 @@
+# Setup Wizard (Phase -2)
+
+Runs once when no `.opencode/code-reviewer.json` exists, or when user runs `/review --setup`.
+
+## Wizard Flow
+
+Ask each question conversationally. Accept number or name. If the user says "both" or lists multiple, select all that apply.
+
+---
+
+### Question 1: Frontend framework
+
+```
+What frontend framework does this project use?
+
+  1. Nuxt 3
+  2. Next.js
+  3. Vue 3 (SPA, no SSR)
+  4. React (CRA / Vite)
+  5. None (API-only project)
+```
+
+→ Maps to `stack.frontend`: `"nuxt"` | `"nextjs"` | `"vue"` | `"react"` | `null`
+
+---
+
+### Question 2: Backend framework
+
+```
+What backend framework?
+
+  1. Express
+  2. NestJS
+  3. Fastify
+  4. None (frontend-only project)
+```
+
+→ Maps to `stack.backend`: `"express"` | `"nestjs"` | `"fastify"` | `null`
+
+---
+
+### Question 3: ORM / database access
+
+```
+How does the project access the database?
+
+  1. TypeORM
+  2. Prisma
+  3. Sequelize
+  4. Raw SQL / query builder
+  5. No database
+```
+
+→ Maps to `stack.orm`: `"typeorm"` | `"prisma"` | `"sequelize"` | `"raw"` | `null`
+
+---
+
+### Question 4: Language
+
+```
+TypeScript, JavaScript, or mixed?
+
+  1. TypeScript (strict)
+  2. TypeScript (loose / partial)
+  3. JavaScript
+  4. Mixed
+```
+
+→ Maps to `stack.language`: `"typescript-strict"` | `"typescript"` | `"javascript"` | `"mixed"`
+
+---
+
+### Question 5: State management (skip if backend-only)
+
+```
+Frontend state management?
+
+  1. Pinia
+  2. Vuex
+  3. Redux / Zustand
+  4. React hooks only
+  5. None / not applicable
+```
+
+→ Maps to `stack.state`: `"pinia"` | `"vuex"` | `"redux"` | `"hooks"` | `null`
+
+---
+
+---
+
+### Question 6: Agent knowledge base
+
+```
+Does your workspace have an AGENTS.md or a .agents/ knowledge folder?
+
+  1. Yes — I have AGENTS.md + .agents/ folder at workspace root
+  2. Yes — I have only AGENTS.md (no .agents/ folder)
+  3. No — I don't have any of these
+```
+
+If yes:
+- Ask for the **workspace root path** (the folder that contains all repos).
+  Example: `/Users/tamlh/workspaces/NUSTechnology/Projects/zengamingx`
+- Auto-detect by going one level up from the current repo and checking for `AGENTS.md`.
+- Verify: check if `.agents/_repos/` and `.agents/_domains/` directories exist.
+
+→ Maps to `agents.workspace_root`, `agents.has_repos_dir`, `agents.has_domains_dir`
+
+---
+
+## Saving the Config
+
+After all questions, write `.opencode/code-reviewer.json`:
+
+```json
+{
+  "version": "3.3.0",
+  "stack": {
+    "frontend": "nuxt",
+    "backend": "express",
+    "orm": "typeorm",
+    "language": "typescript",
+    "state": "pinia"
+  },
+  "agents": {
+    "workspace_root": "/Users/tamlh/workspaces/NUSTechnology/Projects/zengamingx",
+    "has_agents_md": true,
+    "has_repos_dir": true,
+    "has_domains_dir": true
+  },
+  "workspace": {
+    "name": "",
+    "github": {
+      "owner": "",
+      "default_base": "main"
+    },
+    "linear": {
+      "enabled": true,
+      "extract_from": ["branch_name", "pr_description", "pr_title"],
+      "fetch_comments": true
+    }
+  },
+  "output": {
+    "directory": ".opencode/reviews",
+    "filename_pattern": "{type}_{identifier}_{date}"
+  },
+  "report": {
+    "verbosity": "compact",
+    "show_suggestions": false,
+    "show_improvements": true
+  }
+}
+```
+
+Then show a confirmation:
+
+```
+✅ Setup complete! Code reviewer configured for:
+   Frontend:  Nuxt 3
+   Backend:   Express
+   ORM:       TypeORM
+   Language:  TypeScript
+   State:     Pinia
+
+Knowledge base:
+   ✅ AGENTS.md found at workspace root
+   ✅ .agents/_repos/ — 37 repo files
+   ✅ .agents/_domains/ — 7 domain files
+
+Framework rules that will be applied:
+   • references/framework-rules/vue-nuxt.md
+   • references/framework-rules/express.md
+   • references/framework-rules/typeorm.md
+   • references/framework-rules/typescript.md
+
+Config saved to: .opencode/code-reviewer.json
+Run /review PR#123 to start your first review.
+```
+
+---
+
+## Framework Rule File Mapping
+
+| Stack value | Rule file | Applies to agent |
+|-------------|-----------|-----------------|
+| `frontend: "nuxt"` or `"vue"` | `framework-rules/vue-nuxt.md` | Quality + Security |
+| `frontend: "nextjs"` | `framework-rules/nextjs.md` | Quality + Security |
+| `frontend: "react"` | `framework-rules/react.md` | Quality + Security |
+| `backend: "express"` | `framework-rules/express.md` | Security + Quality |
+| `backend: "nestjs"` | `framework-rules/nestjs.md` | Security + Quality |
+| `orm: "typeorm"` | `framework-rules/typeorm.md` | Security + Quality |
+| `orm: "prisma"` | `framework-rules/prisma.md` | Security + Quality |
+| `language: "typescript*"` | `framework-rules/typescript.md` | Quality |
+
+Load ONLY the files that match the configured stack. Do not load all framework rules.
+
+---
+
+## Re-running Setup
+
+Users can reset at any time:
+
+```
+/review --setup
+```
+
+This overwrites `.opencode/code-reviewer.json` entirely. Warn the user before overwriting existing config.