Merge pull request #334 from affaan-m/codex/release-1.8.0-core

feat: v1.8.0 harness release (core reliability + parity + new commands)

.claude-plugin/marketplace.json

@@ -14,7 +14,7 @@
       "name": "everything-claude-code",
       "source": "./",
       "description": "The most comprehensive Claude Code plugin — 14+ agents, 56+ skills, 33+ commands, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
-      "version": "1.7.0",
+      "version": "1.8.0",
       "author": {
         "name": "Affaan Mustafa",
         "email": "me@affaanmustafa.com"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-claude-code",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Complete collection of battle-tested Claude Code configs from an Anthropic hackathon winner - agents, skills, hooks, and rules evolved over 10+ months of intensive daily use",
   "author": {
     "name": "Affaan Mustafa",

.cursor/hooks/adapter.js

@@ -29,13 +29,14 @@ function transformToClaude(cursorInput, overrides = {}) {
   return {
     tool_input: {
       command: cursorInput.command || cursorInput.args?.command || '',
-      file_path: cursorInput.path || cursorInput.file || '',
+      file_path: cursorInput.path || cursorInput.file || cursorInput.args?.filePath || '',
       ...overrides.tool_input,
     },
     tool_output: {
       output: cursorInput.output || cursorInput.result || '',
       ...overrides.tool_output,
     },
+    transcript_path: cursorInput.transcript_path || cursorInput.transcriptPath || cursorInput.session?.transcript_path || '',
     _cursor: {
       conversation_id: cursorInput.conversation_id,
       hook_event_name: cursorInput.hook_event_name,
@@ -59,4 +60,22 @@ function runExistingHook(scriptName, stdinData) {
   }
 }
 
-module.exports = { readStdin, getPluginRoot, transformToClaude, runExistingHook };
+function hookEnabled(hookId, allowedProfiles = ['standard', 'strict']) {
+  const rawProfile = String(process.env.ECC_HOOK_PROFILE || 'standard').toLowerCase();
+  const profile = ['minimal', 'standard', 'strict'].includes(rawProfile) ? rawProfile : 'standard';
+
+  const disabled = new Set(
+    String(process.env.ECC_DISABLED_HOOKS || '')
+      .split(',')
+      .map(v => v.trim().toLowerCase())
+      .filter(Boolean)
+  );
+
+  if (disabled.has(String(hookId || '').toLowerCase())) {
+    return false;
+  }
+
+  return allowedProfiles.includes(profile);
+}
+
+module.exports = { readStdin, getPluginRoot, transformToClaude, runExistingHook, hookEnabled };

.cursor/hooks/after-shell-execution.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-const { readStdin } = require('./adapter');
+const { readStdin, hookEnabled } = require('./adapter');
+
 readStdin().then(raw => {
   try {
-    const input = JSON.parse(raw);
-    const cmd = input.command || '';
-    const output = input.output || input.result || '';
+    const input = JSON.parse(raw || '{}');
+    const cmd = String(input.command || input.args?.command || '');
+    const output = String(input.output || input.result || '');
 
-    // PR creation logging
-    if (/gh pr create/.test(cmd)) {
+    if (hookEnabled('post:bash:pr-created', ['standard', 'strict']) && /\bgh\s+pr\s+create\b/.test(cmd)) {
       const m = output.match(/https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/);
       if (m) {
         console.error('[ECC] PR created: ' + m[0]);
@@ -17,10 +17,12 @@ readStdin().then(raw => {
       }
     }
 
-    // Build completion notice
-    if (/(npm run build|pnpm build|yarn build)/.test(cmd)) {
+    if (hookEnabled('post:bash:build-complete', ['standard', 'strict']) && /(npm run build|pnpm build|yarn build)/.test(cmd)) {
       console.error('[ECC] Build completed');
     }
-  } catch {}
+  } catch {
+    // noop
+  }
+
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

.cursor/hooks/before-shell-execution.js

@@ -1,27 +1,72 @@
 #!/usr/bin/env node
-const { readStdin } = require('./adapter');
-readStdin().then(raw => {
-  try {
-    const input = JSON.parse(raw);
-    const cmd = input.command || '';
+const { readStdin, hookEnabled } = require('./adapter');
 
-    // 1. Block dev server outside tmux
-    if (process.platform !== 'win32' && /(npm run dev\b|pnpm( run)? dev\b|yarn dev\b|bun run dev\b)/.test(cmd)) {
-      console.error('[ECC] BLOCKED: Dev server must run in tmux for log access');
-      console.error('[ECC] Use: tmux new-session -d -s dev "npm run dev"');
-      process.exit(2);
+function splitShellSegments(command) {
+  const segments = [];
+  let current = '';
+  let quote = null;
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      current += ch;
+      continue;
     }
 
-    // 2. Tmux reminder for long-running commands
-    if (process.platform !== 'win32' && !process.env.TMUX &&
-        /(npm (install|test)|pnpm (install|test)|yarn (install|test)?|bun (install|test)|cargo build|make\b|docker\b|pytest|vitest|playwright)/.test(cmd)) {
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+
+    const next = command[i + 1] || '';
+    if (ch === ';' || (ch === '&' && next === '&') || (ch === '|' && next === '|') || (ch === '&' && next !== '&')) {
+      if (current.trim()) segments.push(current.trim());
+      current = '';
+      if ((ch === '&' && next === '&') || (ch === '|' && next === '|')) i++;
+      continue;
+    }
+
+    current += ch;
+  }
+
+  if (current.trim()) segments.push(current.trim());
+  return segments;
+}
+
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw || '{}');
+    const cmd = String(input.command || input.args?.command || '');
+
+    if (hookEnabled('pre:bash:dev-server-block', ['standard', 'strict']) && process.platform !== 'win32') {
+      const segments = splitShellSegments(cmd);
+      const tmuxLauncher = /^\s*tmux\s+(new|new-session|new-window|split-window)\b/;
+      const devPattern = /\b(npm\s+run\s+dev|pnpm(?:\s+run)?\s+dev|yarn\s+dev|bun\s+run\s+dev)\b/;
+      const hasBlockedDev = segments.some(segment => devPattern.test(segment) && !tmuxLauncher.test(segment));
+      if (hasBlockedDev) {
+        console.error('[ECC] BLOCKED: Dev server must run in tmux for log access');
+        console.error('[ECC] Use: tmux new-session -d -s dev "npm run dev"');
+        process.exit(2);
+      }
+    }
+
+    if (
+      hookEnabled('pre:bash:tmux-reminder', ['strict']) &&
+      process.platform !== 'win32' &&
+      !process.env.TMUX &&
+      /(npm (install|test)|pnpm (install|test)|yarn (install|test)?|bun (install|test)|cargo build|make\b|docker\b|pytest|vitest|playwright)/.test(cmd)
+    ) {
       console.error('[ECC] Consider running in tmux for session persistence');
     }
 
-    // 3. Git push review reminder
-    if (/git push/.test(cmd)) {
+    if (hookEnabled('pre:bash:git-push-reminder', ['strict']) && /\bgit\s+push\b/.test(cmd)) {
       console.error('[ECC] Review changes before push: git diff origin/main...HEAD');
     }
-  } catch {}
+  } catch {
+    // noop
+  }
+
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

.cursor/hooks/session-end.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
 readStdin().then(raw => {
-  const input = JSON.parse(raw);
+  const input = JSON.parse(raw || '{}');
   const claudeInput = transformToClaude(input);
-  runExistingHook('session-end.js', claudeInput);
-  runExistingHook('evaluate-session.js', claudeInput);
+  if (hookEnabled('session:end:marker', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-end-marker.js', claudeInput);
+  }
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

.cursor/hooks/session-start.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
 readStdin().then(raw => {
-  const input = JSON.parse(raw);
+  const input = JSON.parse(raw || '{}');
   const claudeInput = transformToClaude(input);
-  runExistingHook('session-start.js', claudeInput);
+  if (hookEnabled('session:start', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-start.js', claudeInput);
+  }
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

.cursor/hooks/stop.js

@@ -1,7 +1,21 @@
 #!/usr/bin/env node
-const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
 readStdin().then(raw => {
-  const claudeInput = JSON.parse(raw || '{}');
-  runExistingHook('check-console-log.js', transformToClaude(claudeInput));
+  const input = JSON.parse(raw || '{}');
+  const claudeInput = transformToClaude(input);
+
+  if (hookEnabled('stop:check-console-log', ['standard', 'strict'])) {
+    runExistingHook('check-console-log.js', claudeInput);
+  }
+  if (hookEnabled('stop:session-end', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-end.js', claudeInput);
+  }
+  if (hookEnabled('stop:evaluate-session', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('evaluate-session.js', claudeInput);
+  }
+  if (hookEnabled('stop:cost-tracker', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('cost-tracker.js', claudeInput);
+  }
+
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

.github/FUNDING.yml

@@ -1,15 +1,2 @@
-# These are supported funding model platforms
-
-github: [affaan-m]
-# patreon: # Replace with a single Patreon username
-# open_collective: # Replace with a single Open Collective username
-# ko_fi: # Replace with a single Ko-fi username
-# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-hierarchical-namespace-controller
-# liberapay: # Replace with a single Liberapay username
-# issuehunt: # Replace with a single IssueHunt username
-# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-hierarchical-namespace-controller
-# polar: # Replace with a single Polar username
-# buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
-# thanks_dev: # Replace with a single thanks.dev username
+github: affaan-m
 custom: ['https://ecc.tools']

.github/release.yml

@@ -0,0 +1,20 @@
+changelog:
+  categories:
+    - title: Core Harness
+      labels:
+        - enhancement
+        - feature
+    - title: Reliability & Bug Fixes
+      labels:
+        - bug
+        - fix
+    - title: Docs & Guides
+      labels:
+        - docs
+    - title: Tooling & CI
+      labels:
+        - ci
+        - chore
+  exclude:
+    labels:
+      - skip-changelog

.github/workflows/copilot-setup-steps.yml

@@ -1,18 +0,0 @@
-steps:
-  - name: Setup Go environment
-    uses: actions/setup-go@v6.2.0
-    with:
-      # The Go version to download (if necessary) and use. Supports semver spec and ranges. Be sure to enclose this option in single quotation marks.
-      go-version: # optional
-      # Path to the go.mod, go.work, .go-version, or .tool-versions file.
-      go-version-file: # optional
-      # Set this option to true if you want the action to always check for the latest available version that satisfies the version spec
-      check-latest: # optional
-      # Used to pull Go distributions from go-versions. Since there's a default, this is typically not supplied by the user. When running this action on github.com, the default value is sufficient. When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.
-      token: # optional, default is ${{ github.server_url == 'https://github.com' && github.token || '' }}
-      # Used to specify whether caching is needed. Set to true, if you'd like to enable caching.
-      cache: # optional, default is true
-      # Used to specify the path to a dependency file - go.sum
-      cache-dependency-path: # optional
-      # Target architecture for Go to use. Examples: x86, x64. Will use system architecture by default.
-      architecture: # optional

.github/workflows/monthly-metrics.yml

@@ -0,0 +1,185 @@
+name: Monthly Metrics Snapshot
+
+on:
+  schedule:
+    - cron: '0 14 1 * *' # Monthly on the 1st at 14:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  snapshot:
+    name: Update metrics issue
+    runs-on: ubuntu-latest
+    steps:
+      - name: Update monthly metrics issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const title = "Monthly Metrics Snapshot";
+            const label = "metrics-snapshot";
+            const monthKey = new Date().toISOString().slice(0, 7);
+
+            function parseLastPage(linkHeader) {
+              if (!linkHeader) return null;
+              const match = linkHeader.match(/&page=(\d+)>; rel="last"/);
+              return match ? Number(match[1]) : null;
+            }
+
+            function fmt(value) {
+              if (value === null || value === undefined) return "n/a";
+              return Number(value).toLocaleString("en-US");
+            }
+
+            async function getNpmDownloads(range, pkg) {
+              try {
+                const res = await fetch(`https://api.npmjs.org/downloads/point/${range}/${pkg}`);
+                if (!res.ok) return null;
+                const data = await res.json();
+                return data.downloads ?? null;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getContributorsCount() {
+              try {
+                const resp = await github.rest.repos.listContributors({
+                  owner,
+                  repo,
+                  per_page: 1,
+                  anon: "false"
+                });
+                return parseLastPage(resp.headers.link) ?? resp.data.length;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getReleasesCount() {
+              try {
+                const resp = await github.rest.repos.listReleases({
+                  owner,
+                  repo,
+                  per_page: 1
+                });
+                return parseLastPage(resp.headers.link) ?? resp.data.length;
+              } catch {
+                return null;
+              }
+            }
+
+            async function getTraffic(metric) {
+              try {
+                const route = metric === "clones"
+                  ? "GET /repos/{owner}/{repo}/traffic/clones"
+                  : "GET /repos/{owner}/{repo}/traffic/views";
+                const resp = await github.request(route, { owner, repo });
+                return resp.data?.count ?? null;
+              } catch {
+                return null;
+              }
+            }
+
+            const [
+              mainWeek,
+              shieldWeek,
+              mainMonth,
+              shieldMonth,
+              repoData,
+              contributors,
+              releases,
+              views14d,
+              clones14d
+            ] = await Promise.all([
+              getNpmDownloads("last-week", "ecc-universal"),
+              getNpmDownloads("last-week", "ecc-agentshield"),
+              getNpmDownloads("last-month", "ecc-universal"),
+              getNpmDownloads("last-month", "ecc-agentshield"),
+              github.rest.repos.get({ owner, repo }),
+              getContributorsCount(),
+              getReleasesCount(),
+              getTraffic("views"),
+              getTraffic("clones")
+            ]);
+
+            const stars = repoData.data.stargazers_count;
+            const forks = repoData.data.forks_count;
+
+            const tableHeader = [
+              "| Month (UTC) | ecc-universal (week) | ecc-agentshield (week) | ecc-universal (30d) | ecc-agentshield (30d) | Stars | Forks | Contributors | GitHub App installs (manual) | Views (14d) | Clones (14d) | Releases |",
+              "|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|"
+            ].join("\n");
+
+            const row = `| ${monthKey} | ${fmt(mainWeek)} | ${fmt(shieldWeek)} | ${fmt(mainMonth)} | ${fmt(shieldMonth)} | ${fmt(stars)} | ${fmt(forks)} | ${fmt(contributors)} | n/a | ${fmt(views14d)} | ${fmt(clones14d)} | ${fmt(releases)} |`;
+
+            const intro = [
+              "# Monthly Metrics Snapshot",
+              "",
+              "Automated monthly snapshot for sponsor/partner reporting.",
+              "",
+              "- `GitHub App installs (manual)` is intentionally manual until a stable public API path is available.",
+              "- Traffic metrics are 14-day rolling windows from the GitHub traffic API and can show `n/a` if unavailable.",
+              "",
+              tableHeader
+            ].join("\n");
+
+            try {
+              await github.rest.issues.getLabel({ owner, repo, name: label });
+            } catch (error) {
+              if (error.status === 404) {
+                await github.rest.issues.createLabel({
+                  owner,
+                  repo,
+                  name: label,
+                  color: "0e8a16",
+                  description: "Automated monthly project metrics snapshots"
+                });
+              } else {
+                throw error;
+              }
+            }
+
+            const issuesResp = await github.rest.issues.listForRepo({
+              owner,
+              repo,
+              state: "open",
+              labels: label,
+              per_page: 100
+            });
+
+            let issue = issuesResp.data.find((item) => item.title === title);
+
+            if (!issue) {
+              const created = await github.rest.issues.create({
+                owner,
+                repo,
+                title,
+                labels: [label],
+                body: `${intro}\n${row}\n`
+              });
+              console.log(`Created issue #${created.data.number}`);
+              return;
+            }
+
+            const currentBody = issue.body || "";
+            if (currentBody.includes(`| ${monthKey} |`)) {
+              console.log(`Issue #${issue.number} already has snapshot row for ${monthKey}`);
+              return;
+            }
+
+            const body = currentBody.includes("| Month (UTC) |")
+              ? `${currentBody.trimEnd()}\n${row}\n`
+              : `${intro}\n${row}\n`;
+
+            await github.rest.issues.update({
+              owner,
+              repo,
+              issue_number: issue.number,
+              body
+            });
+            console.log(`Updated issue #${issue.number}`);

.github/workflows/release.yml

@@ -37,23 +37,31 @@ jobs:
             exit 1
           fi
 
-      - name: Generate changelog
-        id: changelog
+      - name: Generate release highlights
+        id: highlights
+        env:
+          TAG_NAME: ${{ github.ref_name }}
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-          if [ -z "$PREV_TAG" ]; then
-            COMMITS=$(git log --pretty=format:"- %s" HEAD)
-          else
-            COMMITS=$(git log --pretty=format:"- %s" ${PREV_TAG}..HEAD)
-          fi
-          echo "commits<<EOF" >> $GITHUB_OUTPUT
-          echo "$COMMITS" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
+          TAG_VERSION="${TAG_NAME#v}"
+          cat > release_body.md <<EOF
+          ## ECC ${TAG_VERSION}
+
+          ### What This Release Focuses On
+          - Harness reliability and hook stability across Claude Code, Cursor, OpenCode, and Codex
+          - Stronger eval-driven workflows and quality gates
+          - Better operator UX for autonomous loop execution
+
+          ### Notable Changes
+          - Session persistence and hook lifecycle fixes
+          - Expanded skills and command coverage for harness performance work
+          - Improved release-note generation and changelog hygiene
+
+          ### Notes
+          - For migration tips and compatibility notes, see README and CHANGELOG.
+          EOF
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          body: |
-            ## Changes
-            ${{ steps.changelog.outputs.commits }}
-          generate_release_notes: false
+          body_path: release_body.md
+          generate_release_notes: true

.github/workflows/reusable-release.yml

@@ -34,26 +34,23 @@ jobs:
             exit 1
           fi
 
-      - name: Generate changelog
-        id: changelog
+      - name: Generate release highlights
+        env:
+          TAG_NAME: ${{ inputs.tag }}
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-          if [ -z "$PREV_TAG" ]; then
-            COMMITS=$(git log --pretty=format:"- %s" HEAD)
-          else
-            COMMITS=$(git log --pretty=format:"- %s" ${PREV_TAG}..HEAD)
-          fi
-          # Use unique delimiter to prevent truncation if commit messages contain EOF
-          DELIMITER="COMMITS_END_$(date +%s)"
-          echo "commits<<${DELIMITER}" >> $GITHUB_OUTPUT
-          echo "$COMMITS" >> $GITHUB_OUTPUT
-          echo "${DELIMITER}" >> $GITHUB_OUTPUT
+          TAG_VERSION="${TAG_NAME#v}"
+          cat > release_body.md <<EOF
+          ## ECC ${TAG_VERSION}
+
+          ### What This Release Focuses On
+          - Harness reliability and cross-platform compatibility
+          - Eval-driven quality improvements
+          - Better workflow and operator ergonomics
+          EOF
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ inputs.tag }}
-          body: |
-            ## Changes
-            ${{ steps.changelog.outputs.commits }}
+          body_path: release_body.md
           generate_release_notes: ${{ inputs.generate-notes }}

.opencode/MIGRATION.md

@@ -258,6 +258,8 @@ After migration, ALL 23 commands are available:
 | `/instinct-import` | Import instincts |
 | `/instinct-export` | Export instincts |
 | `/evolve` | Cluster instincts into skills |
+| `/promote` | Promote project instincts to global scope |
+| `/projects` | List known projects and instinct stats |
 
 ## Available Agents
 

.opencode/README.md

@@ -67,7 +67,7 @@ opencode
 | go-build-resolver | Go build errors |
 | database-reviewer | Database optimization |
 
-### Commands (24)
+### Commands (31)
 
 | Command | Description |
 |---------|-------------|
@@ -95,6 +95,13 @@ opencode
 | `/instinct-import` | Import instincts |
 | `/instinct-export` | Export instincts |
 | `/evolve` | Cluster instincts |
+| `/promote` | Promote project instincts |
+| `/projects` | List known projects |
+| `/harness-audit` | Audit harness reliability and eval readiness |
+| `/loop-start` | Start controlled agentic loops |
+| `/loop-status` | Check loop state and checkpoints |
+| `/quality-gate` | Run quality gates on file/repo scope |
+| `/model-route` | Route tasks by model and budget |
 
 ### Plugin Hooks
 
@@ -128,6 +135,18 @@ OpenCode's plugin system maps to Claude Code hooks:
 
 OpenCode has 20+ additional events not available in Claude Code.
 
+### Hook Runtime Controls
+
+OpenCode plugin hooks honor the same runtime controls used by Claude Code/Cursor:
+
+```bash
+export ECC_HOOK_PROFILE=standard
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+```
+
+- `ECC_HOOK_PROFILE`: `minimal`, `standard` (default), `strict`
+- `ECC_DISABLED_HOOKS`: comma-separated hook IDs to disable
+
 ## Skills
 
 The default OpenCode config loads 11 curated ECC skills via the `instructions` array:

.opencode/commands/evolve.md

@@ -1,112 +1,36 @@
 ---
-description: Cluster instincts into skills
+description: Analyze instincts and suggest or generate evolved structures
 agent: build
 ---
 
 # Evolve Command
 
-Cluster related instincts into structured skills: $ARGUMENTS
+Analyze and evolve instincts in continuous-learning-v2: $ARGUMENTS
 
 ## Your Task
 
-Analyze instincts and promote clusters to skills.
+Run:
 
-## Evolution Process
-
-### Step 1: Analyze Instincts
-
-Group instincts by:
-- Trigger similarity
-- Action patterns
-- Category tags
-- Confidence levels
-
-### Step 2: Identify Clusters
-
-```
-Cluster: Error Handling
-├── Instinct: Catch specific errors (0.85)
-├── Instinct: Wrap errors with context (0.82)
-├── Instinct: Log errors with stack trace (0.78)
-└── Instinct: Return meaningful error messages (0.80)
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" evolve $ARGUMENTS
 ```
 
-### Step 3: Generate Skill
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
 
-When cluster has:
-- 3+ instincts
-- Average confidence > 0.75
-- Cohesive theme
-
-Generate SKILL.md:
-
-```markdown
-# Error Handling Skill
-
-## Overview
-Patterns for robust error handling learned from session observations.
-
-## Patterns
-
-### 1. Catch Specific Errors
-**Trigger**: When catching errors with generic catch
-**Action**: Use specific error types
-
-### 2. Wrap Errors with Context
-**Trigger**: When re-throwing errors
-**Action**: Add context with fmt.Errorf or Error.cause
-
-### 3. Log with Stack Trace
-**Trigger**: When logging errors
-**Action**: Include stack trace for debugging
-
-### 4. Meaningful Messages
-**Trigger**: When returning errors to users
-**Action**: Provide actionable error messages
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve $ARGUMENTS
 ```
 
-### Step 4: Archive Instincts
+## Supported Args (v2.1)
 
-Move evolved instincts to `archived/` with reference to skill.
+- no args: analysis only
+- `--generate`: also generate files under `evolved/{skills,commands,agents}`
 
-## Evolution Report
+## Behavior Notes
 
-```
-Evolution Summary
-=================
-
-Clusters Found: X
-
-Cluster 1: Error Handling
-- Instincts: 5
-- Avg Confidence: 0.82
-- Status: ✅ Promoted to skill
-
-Cluster 2: Testing Patterns
-- Instincts: 3
-- Avg Confidence: 0.71
-- Status: ⏳ Needs more confidence
-
-Cluster 3: Git Workflow
-- Instincts: 2
-- Avg Confidence: 0.88
-- Status: ⏳ Needs more instincts
-
-Skills Created:
-- skills/error-handling/SKILL.md
-
-Instincts Archived: 5
-Remaining Instincts: 12
-```
-
-## Thresholds
-
-| Metric | Threshold |
-|--------|-----------|
-| Min instincts per cluster | 3 |
-| Min average confidence | 0.75 |
-| Min cluster cohesion | 0.6 |
-
----
-
-**TIP**: Run `/evolve` periodically to graduate instincts to skills as confidence grows.
+- Uses project + global instincts for analysis.
+- Shows skill/command/agent candidates from trigger and domain clustering.
+- Shows project -> global promotion candidates.
+- With `--generate`, output path is:
+  - project context: `~/.claude/homunculus/projects/<project-id>/evolved/`
+  - global fallback: `~/.claude/homunculus/evolved/`

.opencode/commands/harness-audit.md

@@ -0,0 +1,58 @@
+# Harness Audit Command
+
+Audit the current repository's agent harness setup and return a prioritized scorecard.
+
+## Usage
+
+`/harness-audit [scope] [--format text|json]`
+
+- `scope` (optional): `repo` (default), `hooks`, `skills`, `commands`, `agents`
+- `--format`: output style (`text` default, `json` for automation)
+
+## What to Evaluate
+
+Score each category from `0` to `10`:
+
+1. Tool Coverage
+2. Context Efficiency
+3. Quality Gates
+4. Memory Persistence
+5. Eval Coverage
+6. Security Guardrails
+7. Cost Efficiency
+
+## Output Contract
+
+Return:
+
+1. `overall_score` out of 70
+2. Category scores and concrete findings
+3. Top 3 actions with exact file paths
+4. Suggested ECC skills to apply next
+
+## Checklist
+
+- Inspect `hooks/hooks.json`, `scripts/hooks/`, and hook tests.
+- Inspect `skills/`, command coverage, and agent coverage.
+- Verify cross-harness parity for `.cursor/`, `.opencode/`, `.codex/`.
+- Flag broken or stale references.
+
+## Example Result
+
+```text
+Harness Audit (repo): 52/70
+- Quality Gates: 9/10
+- Eval Coverage: 6/10
+- Cost Efficiency: 4/10
+
+Top 3 Actions:
+1) Add cost tracking hook in scripts/hooks/cost-tracker.js
+2) Add pass@k docs and templates in skills/eval-harness/SKILL.md
+3) Add command parity for /harness-audit in .opencode/commands/
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `repo|hooks|skills|commands|agents` (optional scope)
+- `--format text|json` (optional output format)

.opencode/commands/instinct-status.md

@@ -1,75 +1,29 @@
 ---
-description: View learned instincts with confidence scores
+description: Show learned instincts (project + global) with confidence
 agent: build
 ---
 
 # Instinct Status Command
 
-Display learned instincts and their confidence scores: $ARGUMENTS
+Show instinct status from continuous-learning-v2: $ARGUMENTS
 
 ## Your Task
 
-Read and display instincts from the continuous-learning-v2 system.
+Run:
 
-## Instinct Location
-
-Global: `~/.claude/instincts/`
-Project: `.claude/instincts/`
-
-## Status Display
-
-### Instinct Summary
-
-| Category | Count | Avg Confidence |
-|----------|-------|----------------|
-| Coding | X | 0.XX |
-| Testing | X | 0.XX |
-| Security | X | 0.XX |
-| Git | X | 0.XX |
-
-### High Confidence Instincts (>0.8)
-
-```
-[trigger] → [action] (confidence: 0.XX)
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" status
 ```
 
-### Learning Progress
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
 
-- Total instincts: X
-- This session: X
-- Promoted to skills: X
-
-### Recent Instincts
-
-Last 5 instincts learned:
-
-1. **[timestamp]** - [trigger] → [action]
-2. **[timestamp]** - [trigger] → [action]
-...
-
-## Instinct Structure
-
-```json
-{
-  "id": "instinct-123",
-  "trigger": "When I see a try-catch without specific error type",
-  "action": "Suggest using specific error types for better handling",
-  "confidence": 0.75,
-  "applications": 5,
-  "successes": 4,
-  "source": "session-observation",
-  "timestamp": "2025-01-15T10:30:00Z"
-}
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
 ```
 
-## Confidence Calculation
+## Behavior Notes
 
-```
-confidence = (successes + 1) / (applications + 2)
-```
-
-Bayesian smoothing ensures new instincts don't have extreme confidence.
-
----
-
-**TIP**: Use `/evolve` to cluster related instincts into skills when confidence is high.
+- Output includes both project-scoped and global instincts.
+- Project instincts override global instincts when IDs conflict.
+- Output is grouped by domain with confidence bars.
+- This command does not support extra filters in v2.1.

.opencode/commands/loop-start.md

@@ -0,0 +1,32 @@
+# Loop Start Command
+
+Start a managed autonomous loop pattern with safety defaults.
+
+## Usage
+
+`/loop-start [pattern] [--mode safe|fast]`
+
+- `pattern`: `sequential`, `continuous-pr`, `rfc-dag`, `infinite`
+- `--mode`:
+  - `safe` (default): strict quality gates and checkpoints
+  - `fast`: reduced gates for speed
+
+## Flow
+
+1. Confirm repository state and branch strategy.
+2. Select loop pattern and model tier strategy.
+3. Enable required hooks/profile for the chosen mode.
+4. Create loop plan and write runbook under `.claude/plans/`.
+5. Print commands to start and monitor the loop.
+
+## Required Safety Checks
+
+- Verify tests pass before first loop iteration.
+- Ensure `ECC_HOOK_PROFILE` is not disabled globally.
+- Ensure loop has explicit stop condition.
+
+## Arguments
+
+$ARGUMENTS:
+- `<pattern>` optional (`sequential|continuous-pr|rfc-dag|infinite`)
+- `--mode safe|fast` optional

.opencode/commands/loop-status.md

@@ -0,0 +1,24 @@
+# Loop Status Command
+
+Inspect active loop state, progress, and failure signals.
+
+## Usage
+
+`/loop-status [--watch]`
+
+## What to Report
+
+- active loop pattern
+- current phase and last successful checkpoint
+- failing checks (if any)
+- estimated time/cost drift
+- recommended intervention (continue/pause/stop)
+
+## Watch Mode
+
+When `--watch` is present, refresh status periodically and surface state changes.
+
+## Arguments
+
+$ARGUMENTS:
+- `--watch` optional

.opencode/commands/model-route.md

@@ -0,0 +1,26 @@
+# Model Route Command
+
+Recommend the best model tier for the current task by complexity and budget.
+
+## Usage
+
+`/model-route [task-description] [--budget low|med|high]`
+
+## Routing Heuristic
+
+- `haiku`: deterministic, low-risk mechanical changes
+- `sonnet`: default for implementation and refactors
+- `opus`: architecture, deep review, ambiguous requirements
+
+## Required Output
+
+- recommended model
+- confidence level
+- why this model fits
+- fallback model if first attempt fails
+
+## Arguments
+
+$ARGUMENTS:
+- `[task-description]` optional free-text
+- `--budget low|med|high` optional

.opencode/commands/projects.md

@@ -0,0 +1,23 @@
+---
+description: List registered projects and instinct counts
+agent: build
+---
+
+# Projects Command
+
+Show continuous-learning-v2 project registry and stats: $ARGUMENTS
+
+## Your Task
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
+```
+

.opencode/commands/promote.md

@@ -0,0 +1,23 @@
+---
+description: Promote project instincts to global scope
+agent: build
+---
+
+# Promote Command
+
+Promote instincts in continuous-learning-v2: $ARGUMENTS
+
+## Your Task
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" promote $ARGUMENTS
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote $ARGUMENTS
+```
+

.opencode/commands/quality-gate.md

@@ -0,0 +1,29 @@
+# Quality Gate Command
+
+Run the ECC quality pipeline on demand for a file or project scope.
+
+## Usage
+
+`/quality-gate [path|.] [--fix] [--strict]`
+
+- default target: current directory (`.`)
+- `--fix`: allow auto-format/fix where configured
+- `--strict`: fail on warnings where supported
+
+## Pipeline
+
+1. Detect language/tooling for target.
+2. Run formatter checks.
+3. Run lint/type checks when available.
+4. Produce a concise remediation list.
+
+## Notes
+
+This command mirrors hook behavior but is operator-invoked.
+
+## Arguments
+
+$ARGUMENTS:
+- `[path|.]` optional target path
+- `--fix` optional
+- `--strict` optional

.opencode/opencode.json

@@ -303,6 +303,14 @@
     "evolve": {
       "description": "Cluster instincts into skills",
       "template": "{file:.opencode/commands/evolve.md}\n\n$ARGUMENTS"
+    },
+    "promote": {
+      "description": "Promote project instincts to global scope",
+      "template": "{file:.opencode/commands/promote.md}\n\n$ARGUMENTS"
+    },
+    "projects": {
+      "description": "List known projects and instinct stats",
+      "template": "{file:.opencode/commands/projects.md}\n\n$ARGUMENTS"
     }
   },
   "permission": {

.opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecc-universal",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Everything Claude Code (ECC) plugin for OpenCode - agents, commands, hooks, and skills",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

.opencode/plugins/ecc-hooks.ts

@@ -21,6 +21,8 @@ export const ECCHooksPlugin = async ({
   directory,
   worktree,
 }: PluginInput) => {
+  type HookProfile = "minimal" | "standard" | "strict"
+
   // Track files edited in current session for console.log audit
   const editedFiles = new Set<string>()
 
@@ -28,6 +30,40 @@ export const ECCHooksPlugin = async ({
   const log = (level: "debug" | "info" | "warn" | "error", message: string) =>
     client.app.log({ body: { service: "ecc", level, message } })
 
+  const normalizeProfile = (value: string | undefined): HookProfile => {
+    if (value === "minimal" || value === "strict") return value
+    return "standard"
+  }
+
+  const currentProfile = normalizeProfile(process.env.ECC_HOOK_PROFILE)
+  const disabledHooks = new Set(
+    (process.env.ECC_DISABLED_HOOKS || "")
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean)
+  )
+
+  const profileOrder: Record<HookProfile, number> = {
+    minimal: 0,
+    standard: 1,
+    strict: 2,
+  }
+
+  const profileAllowed = (required: HookProfile | HookProfile[]): boolean => {
+    if (Array.isArray(required)) {
+      return required.some((entry) => profileOrder[currentProfile] >= profileOrder[entry])
+    }
+    return profileOrder[currentProfile] >= profileOrder[required]
+  }
+
+  const hookEnabled = (
+    hookId: string,
+    requiredProfile: HookProfile | HookProfile[] = "standard"
+  ): boolean => {
+    if (disabledHooks.has(hookId)) return false
+    return profileAllowed(requiredProfile)
+  }
+
   return {
     /**
      * Prettier Auto-Format Hook
@@ -41,7 +77,7 @@ export const ECCHooksPlugin = async ({
       editedFiles.add(event.path)
 
       // Auto-format JS/TS files
-      if (event.path.match(/\.(ts|tsx|js|jsx)$/)) {
+      if (hookEnabled("post:edit:format", ["standard", "strict"]) && event.path.match(/\.(ts|tsx|js|jsx)$/)) {
         try {
           await $`prettier --write ${event.path} 2>/dev/null`
           log("info", `[ECC] Formatted: ${event.path}`)
@@ -51,7 +87,7 @@ export const ECCHooksPlugin = async ({
       }
 
       // Console.log warning check
-      if (event.path.match(/\.(ts|tsx|js|jsx)$/)) {
+      if (hookEnabled("post:edit:console-warn", ["standard", "strict"]) && event.path.match(/\.(ts|tsx|js|jsx)$/)) {
         try {
           const result = await $`grep -n "console\\.log" ${event.path} 2>/dev/null`.text()
           if (result.trim()) {
@@ -80,6 +116,7 @@ export const ECCHooksPlugin = async ({
     ) => {
       // Check if a TypeScript file was edited
       if (
+        hookEnabled("post:edit:typecheck", ["standard", "strict"]) &&
         input.tool === "edit" &&
         input.args?.filePath?.match(/\.tsx?$/)
       ) {
@@ -98,7 +135,11 @@ export const ECCHooksPlugin = async ({
       }
 
       // PR creation logging
-      if (input.tool === "bash" && input.args?.toString().includes("gh pr create")) {
+      if (
+        hookEnabled("post:bash:pr-created", ["standard", "strict"]) &&
+        input.tool === "bash" &&
+        input.args?.toString().includes("gh pr create")
+      ) {
         log("info", "[ECC] PR created - check GitHub Actions status")
       }
     },
@@ -115,6 +156,7 @@ export const ECCHooksPlugin = async ({
     ) => {
       // Git push review reminder
       if (
+        hookEnabled("pre:bash:git-push-reminder", "strict") &&
         input.tool === "bash" &&
         input.args?.toString().includes("git push")
       ) {
@@ -126,6 +168,7 @@ export const ECCHooksPlugin = async ({
 
       // Block creation of unnecessary documentation files
       if (
+        hookEnabled("pre:write:doc-file-warning", ["standard", "strict"]) &&
         input.tool === "write" &&
         input.args?.filePath &&
         typeof input.args.filePath === "string"
@@ -146,7 +189,7 @@ export const ECCHooksPlugin = async ({
       }
 
       // Long-running command reminder
-      if (input.tool === "bash") {
+      if (hookEnabled("pre:bash:tmux-reminder", "strict") && input.tool === "bash") {
         const cmd = String(input.args?.command || input.args || "")
         if (
           cmd.match(/^(npm|pnpm|yarn|bun)\s+(install|build|test|run)/) ||
@@ -169,7 +212,9 @@ export const ECCHooksPlugin = async ({
      * Action: Loads context and displays welcome message
      */
     "session.created": async () => {
-      log("info", "[ECC] Session started - Everything Claude Code hooks active")
+      if (!hookEnabled("session:start", ["minimal", "standard", "strict"])) return
+
+      log("info", `[ECC] Session started - profile=${currentProfile}`)
 
       // Check for project-specific context files
       try {
@@ -190,6 +235,7 @@ export const ECCHooksPlugin = async ({
      * Action: Runs console.log audit on all edited files
      */
     "session.idle": async () => {
+      if (!hookEnabled("stop:check-console-log", ["minimal", "standard", "strict"])) return
       if (editedFiles.size === 0) return
 
       log("info", "[ECC] Session idle - running console.log audit")
@@ -244,6 +290,7 @@ export const ECCHooksPlugin = async ({
      * Action: Final cleanup and state saving
      */
     "session.deleted": async () => {
+      if (!hookEnabled("session:end-marker", ["minimal", "standard", "strict"])) return
       log("info", "[ECC] Session ended - cleaning up")
       editedFiles.clear()
     },
@@ -285,8 +332,10 @@ export const ECCHooksPlugin = async ({
      */
     "shell.env": async () => {
       const env: Record<string, string> = {
-        ECC_VERSION: "1.6.0",
+        ECC_VERSION: "1.8.0",
         ECC_PLUGIN: "true",
+        ECC_HOOK_PROFILE: currentProfile,
+        ECC_DISABLED_HOOKS: process.env.ECC_DISABLED_HOOKS || "",
         PROJECT_ROOT: worktree || directory,
       }
 
@@ -343,7 +392,7 @@ export const ECCHooksPlugin = async ({
       const contextBlock = [
         "# ECC Context (preserve across compaction)",
         "",
-        "## Active Plugin: Everything Claude Code v1.6.0",
+        "## Active Plugin: Everything Claude Code v1.8.0",
         "- Hooks: file.edited, tool.execute.before/after, session.created/idle/deleted, shell.env, compacting, permission.ask",
         "- Tools: run-tests, check-coverage, security-audit, format-code, lint-check, git-summary",
         "- Agents: 13 specialized (planner, architect, tdd-guide, code-reviewer, security-reviewer, build-error-resolver, e2e-runner, refactor-cleaner, doc-updater, go-reviewer, go-build-resolver, database-reviewer, python-reviewer)",

.opencode/tools/format-code.ts

@@ -1,66 +1,68 @@
 /**
  * ECC Custom Tool: Format Code
  *
- * Language-aware code formatter that auto-detects the project's formatter.
- * Supports: Biome/Prettier (JS/TS), Black (Python), gofmt (Go), rustfmt (Rust)
+ * Returns the formatter command that should be run for a given file.
+ * This avoids shell execution assumptions while still giving precise guidance.
  */
 
-import { tool } from "@opencode-ai/plugin"
-import { z } from "zod"
+import { tool } from "@opencode-ai/plugin/tool"
+import * as path from "path"
+import * as fs from "fs"
+
+type Formatter = "biome" | "prettier" | "black" | "gofmt" | "rustfmt"
 
 export default tool({
-  name: "format-code",
-  description: "Format a file using the project's configured formatter. Auto-detects Biome, Prettier, Black, gofmt, or rustfmt.",
-  parameters: z.object({
-    filePath: z.string().describe("Path to the file to format"),
-    formatter: z.string().optional().describe("Override formatter: biome, prettier, black, gofmt, rustfmt (default: auto-detect)"),
-  }),
-  execute: async ({ filePath, formatter }, { $ }) => {
-    const ext = filePath.split(".").pop()?.toLowerCase() || ""
-
-    // Auto-detect formatter based on file extension and config files
-    let detected = formatter
-    if (!detected) {
-      if (["ts", "tsx", "js", "jsx", "json", "css", "scss"].includes(ext)) {
-        // Check for Biome first, then Prettier
-        try {
-          await $`test -f biome.json || test -f biome.jsonc`
-          detected = "biome"
-        } catch {
-          detected = "prettier"
-        }
-      } else if (["py", "pyi"].includes(ext)) {
-        detected = "black"
-      } else if (ext === "go") {
-        detected = "gofmt"
-      } else if (ext === "rs") {
-        detected = "rustfmt"
-      }
-    }
+  description:
+    "Detect formatter for a file and return the exact command to run (Biome, Prettier, Black, gofmt, rustfmt).",
+  args: {
+    filePath: tool.schema.string().describe("Path to the file to format"),
+    formatter: tool.schema
+      .enum(["biome", "prettier", "black", "gofmt", "rustfmt"])
+      .optional()
+      .describe("Optional formatter override"),
+  },
+  async execute(args, context) {
+    const cwd = context.worktree || context.directory
+    const ext = args.filePath.split(".").pop()?.toLowerCase() || ""
+    const detected = args.formatter || detectFormatter(cwd, ext)
 
     if (!detected) {
-      return { formatted: false, message: `No formatter detected for .${ext} files` }
+      return JSON.stringify({
+        success: false,
+        message: `No formatter detected for .${ext} files`,
+      })
     }
 
-    const commands: Record<string, string> = {
-      biome: `npx @biomejs/biome format --write ${filePath}`,
-      prettier: `npx prettier --write ${filePath}`,
-      black: `black ${filePath}`,
-      gofmt: `gofmt -w ${filePath}`,
-      rustfmt: `rustfmt ${filePath}`,
-    }
-
-    const cmd = commands[detected]
-    if (!cmd) {
-      return { formatted: false, message: `Unknown formatter: ${detected}` }
-    }
-
-    try {
-      const result = await $`${cmd}`.text()
-      return { formatted: true, formatter: detected, output: result }
-    } catch (error: unknown) {
-      const err = error as { stderr?: string }
-      return { formatted: false, formatter: detected, error: err.stderr || "Format failed" }
-    }
+    const command = buildFormatterCommand(detected, args.filePath)
+    return JSON.stringify({
+      success: true,
+      formatter: detected,
+      command,
+      instructions: `Run this command:\n\n${command}`,
+    })
   },
 })
+
+function detectFormatter(cwd: string, ext: string): Formatter | null {
+  if (["ts", "tsx", "js", "jsx", "json", "css", "scss", "md", "yaml", "yml"].includes(ext)) {
+    if (fs.existsSync(path.join(cwd, "biome.json")) || fs.existsSync(path.join(cwd, "biome.jsonc"))) {
+      return "biome"
+    }
+    return "prettier"
+  }
+  if (["py", "pyi"].includes(ext)) return "black"
+  if (ext === "go") return "gofmt"
+  if (ext === "rs") return "rustfmt"
+  return null
+}
+
+function buildFormatterCommand(formatter: Formatter, filePath: string): string {
+  const commands: Record<Formatter, string> = {
+    biome: `npx @biomejs/biome format --write ${filePath}`,
+    prettier: `npx prettier --write ${filePath}`,
+    black: `black ${filePath}`,
+    gofmt: `gofmt -w ${filePath}`,
+    rustfmt: `rustfmt ${filePath}`,
+  }
+  return commands[formatter]
+}

.opencode/tools/git-summary.ts

@@ -1,56 +1,54 @@
 /**
  * ECC Custom Tool: Git Summary
  *
- * Provides a comprehensive git status including branch info, status,
- * recent log, and diff against base branch.
+ * Returns branch/status/log/diff details for the active repository.
  */
 
-import { tool } from "@opencode-ai/plugin"
-import { z } from "zod"
+import { tool } from "@opencode-ai/plugin/tool"
+import { execSync } from "child_process"
 
 export default tool({
-  name: "git-summary",
-  description: "Get comprehensive git summary: branch, status, recent log, and diff against base branch.",
-  parameters: z.object({
-    depth: z.number().optional().describe("Number of recent commits to show (default: 5)"),
-    includeDiff: z.boolean().optional().describe("Include diff against base branch (default: true)"),
-    baseBranch: z.string().optional().describe("Base branch for comparison (default: main)"),
-  }),
-  execute: async ({ depth = 5, includeDiff = true, baseBranch = "main" }, { $ }) => {
-    const results: Record<string, string> = {}
+  description:
+    "Generate git summary with branch, status, recent commits, and optional diff stats.",
+  args: {
+    depth: tool.schema
+      .number()
+      .optional()
+      .describe("Number of recent commits to include (default: 5)"),
+    includeDiff: tool.schema
+      .boolean()
+      .optional()
+      .describe("Include diff stats against base branch (default: true)"),
+    baseBranch: tool.schema
+      .string()
+      .optional()
+      .describe("Base branch for diff comparison (default: main)"),
+  },
+  async execute(args, context) {
+    const cwd = context.worktree || context.directory
+    const depth = args.depth ?? 5
+    const includeDiff = args.includeDiff ?? true
+    const baseBranch = args.baseBranch ?? "main"
 
-    try {
-      results.branch = (await $`git branch --show-current`.text()).trim()
-    } catch {
-      results.branch = "unknown"
-    }
-
-    try {
-      results.status = (await $`git status --short`.text()).trim()
-    } catch {
-      results.status = "unable to get status"
-    }
-
-    try {
-      results.log = (await $`git log --oneline -${depth}`.text()).trim()
-    } catch {
-      results.log = "unable to get log"
+    const result: Record<string, string> = {
+      branch: run("git branch --show-current", cwd) || "unknown",
+      status: run("git status --short", cwd) || "clean",
+      log: run(`git log --oneline -${depth}`, cwd) || "no commits found",
     }
 
     if (includeDiff) {
-      try {
-        results.stagedDiff = (await $`git diff --cached --stat`.text()).trim()
-      } catch {
-        results.stagedDiff = ""
-      }
-
-      try {
-        results.branchDiff = (await $`git diff ${baseBranch}...HEAD --stat`.text()).trim()
-      } catch {
-        results.branchDiff = `unable to diff against ${baseBranch}`
-      }
+      result.stagedDiff = run("git diff --cached --stat", cwd) || ""
+      result.branchDiff = run(`git diff ${baseBranch}...HEAD --stat`, cwd) || `unable to diff against ${baseBranch}`
     }
 
-    return results
+    return JSON.stringify(result)
   },
 })
+
+function run(command: string, cwd: string): string {
+  try {
+    return execSync(command, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+  } catch {
+    return ""
+  }
+}

.opencode/tools/lint-check.ts

@@ -1,74 +1,85 @@
 /**
  * ECC Custom Tool: Lint Check
  *
- * Multi-language linter that auto-detects the project's linting tool.
- * Supports: ESLint/Biome (JS/TS), Pylint/Ruff (Python), golangci-lint (Go)
+ * Detects the appropriate linter and returns a runnable lint command.
  */
 
-import { tool } from "@opencode-ai/plugin"
-import { z } from "zod"
+import { tool } from "@opencode-ai/plugin/tool"
+import * as path from "path"
+import * as fs from "fs"
+
+type Linter = "biome" | "eslint" | "ruff" | "pylint" | "golangci-lint"
 
 export default tool({
-  name: "lint-check",
-  description: "Run linter on files or directories. Auto-detects ESLint, Biome, Ruff, Pylint, or golangci-lint.",
-  parameters: z.object({
-    target: z.string().optional().describe("File or directory to lint (default: current directory)"),
-    fix: z.boolean().optional().describe("Auto-fix issues if supported (default: false)"),
-    linter: z.string().optional().describe("Override linter: eslint, biome, ruff, pylint, golangci-lint (default: auto-detect)"),
-  }),
-  execute: async ({ target = ".", fix = false, linter }, { $ }) => {
-    // Auto-detect linter
-    let detected = linter
-    if (!detected) {
-      try {
-        await $`test -f biome.json || test -f biome.jsonc`
-        detected = "biome"
-      } catch {
-        try {
-          await $`test -f .eslintrc.json || test -f .eslintrc.js || test -f .eslintrc.cjs || test -f eslint.config.js || test -f eslint.config.mjs`
-          detected = "eslint"
-        } catch {
-          try {
-            await $`test -f pyproject.toml && grep -q "ruff" pyproject.toml`
-            detected = "ruff"
-          } catch {
-            try {
-              await $`test -f .golangci.yml || test -f .golangci.yaml`
-              detected = "golangci-lint"
-            } catch {
-              // Fall back based on file extensions in target
-              detected = "eslint"
-            }
-          }
-        }
-      }
-    }
+  description:
+    "Detect linter for a target path and return command for check/fix runs.",
+  args: {
+    target: tool.schema
+      .string()
+      .optional()
+      .describe("File or directory to lint (default: current directory)"),
+    fix: tool.schema
+      .boolean()
+      .optional()
+      .describe("Enable auto-fix mode"),
+    linter: tool.schema
+      .enum(["biome", "eslint", "ruff", "pylint", "golangci-lint"])
+      .optional()
+      .describe("Optional linter override"),
+  },
+  async execute(args, context) {
+    const cwd = context.worktree || context.directory
+    const target = args.target || "."
+    const fix = args.fix ?? false
+    const detected = args.linter || detectLinter(cwd)
 
-    const fixFlag = fix ? " --fix" : ""
-    const commands: Record<string, string> = {
-      biome: `npx @biomejs/biome lint${fix ? " --write" : ""} ${target}`,
-      eslint: `npx eslint${fixFlag} ${target}`,
-      ruff: `ruff check${fixFlag} ${target}`,
-      pylint: `pylint ${target}`,
-      "golangci-lint": `golangci-lint run${fixFlag} ${target}`,
-    }
-
-    const cmd = commands[detected]
-    if (!cmd) {
-      return { success: false, message: `Unknown linter: ${detected}` }
-    }
-
-    try {
-      const result = await $`${cmd}`.text()
-      return { success: true, linter: detected, output: result, issues: 0 }
-    } catch (error: unknown) {
-      const err = error as { stdout?: string; stderr?: string }
-      return {
-        success: false,
-        linter: detected,
-        output: err.stdout || "",
-        errors: err.stderr || "",
-      }
-    }
+    const command = buildLintCommand(detected, target, fix)
+    return JSON.stringify({
+      success: true,
+      linter: detected,
+      command,
+      instructions: `Run this command:\n\n${command}`,
+    })
   },
 })
+
+function detectLinter(cwd: string): Linter {
+  if (fs.existsSync(path.join(cwd, "biome.json")) || fs.existsSync(path.join(cwd, "biome.jsonc"))) {
+    return "biome"
+  }
+
+  const eslintConfigs = [
+    ".eslintrc.json",
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    "eslint.config.js",
+    "eslint.config.mjs",
+  ]
+  if (eslintConfigs.some((name) => fs.existsSync(path.join(cwd, name)))) {
+    return "eslint"
+  }
+
+  const pyprojectPath = path.join(cwd, "pyproject.toml")
+  if (fs.existsSync(pyprojectPath)) {
+    try {
+      const content = fs.readFileSync(pyprojectPath, "utf-8")
+      if (content.includes("ruff")) return "ruff"
+    } catch {
+      // ignore read errors and keep fallback logic
+    }
+  }
+
+  if (fs.existsSync(path.join(cwd, ".golangci.yml")) || fs.existsSync(path.join(cwd, ".golangci.yaml"))) {
+    return "golangci-lint"
+  }
+
+  return "eslint"
+}
+
+function buildLintCommand(linter: Linter, target: string, fix: boolean): string {
+  if (linter === "biome") return `npx @biomejs/biome lint${fix ? " --write" : ""} ${target}`
+  if (linter === "eslint") return `npx eslint${fix ? " --fix" : ""} ${target}`
+  if (linter === "ruff") return `ruff check${fix ? " --fix" : ""} ${target}`
+  if (linter === "pylint") return `pylint ${target}`
+  return `golangci-lint run ${target}`
+}

.prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "trailingComma": "none",
+  "semi": true,
+  "tabWidth": 2,
+  "printWidth": 200,
+  "arrowParens": "avoid"
+}

CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 1.8.0 - 2026-03-04
+
+### Highlights
+
+- Harness-first release focused on reliability, eval discipline, and autonomous loop operations.
+- Hook runtime now supports profile-based control and targeted hook disabling.
+- NanoClaw v2 adds model routing, skill hot-load, branching, search, compaction, export, and metrics.
+
+### Core
+
+- Added new commands: `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`.
+- Added new skills:
+  - `agent-harness-construction`
+  - `agentic-engineering`
+  - `ralphinho-rfc-pipeline`
+  - `ai-first-engineering`
+  - `enterprise-agent-ops`
+  - `nanoclaw-repl`
+  - `continuous-agent-loop`
+- Added new agents:
+  - `harness-optimizer`
+  - `loop-operator`
+
+### Hook Reliability
+
+- Fixed SessionStart root resolution with robust fallback search.
+- Moved session summary persistence to `Stop` where transcript payload is available.
+- Added quality-gate and cost-tracker hooks.
+- Replaced fragile inline hook one-liners with dedicated script files.
+- Added `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` controls.
+
+### Cross-Platform
+
+- Improved Windows-safe path handling in doc warning logic.
+- Hardened observer loop behavior to avoid non-interactive hangs.
+
+### Notes
+
+- `autonomous-loops` is kept as a compatibility alias for one release; `continuous-agent-loop` is the canonical name.
+
+### Credits
+
+- inspired by [zarazhangrui](https://github.com/zarazhangrui)
+- homunculus-inspired by [humanplane](https://github.com/humanplane)

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -62,7 +62,7 @@ cp -r skills/my-skill ~/.claude/skills/  # for skills
 # Then test with Claude Code
 
 # 5. Submit PR
-git add . && git commit -m "feat: add my-skill" && git push
+git add . && git commit -m "feat: add my-skill" && git push -u origin feat/my-contribution
 ```
 
 ---

README.md

@@ -5,6 +5,9 @@
 [![Stars](https://img.shields.io/github/stars/affaan-m/everything-claude-code?style=flat)](https://github.com/affaan-m/everything-claude-code/stargazers)
 [![Forks](https://img.shields.io/github/forks/affaan-m/everything-claude-code?style=flat)](https://github.com/affaan-m/everything-claude-code/network/members)
 [![Contributors](https://img.shields.io/github/contributors/affaan-m/everything-claude-code?style=flat)](https://github.com/affaan-m/everything-claude-code/graphs/contributors)
+[![npm ecc-universal](https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-universal)
+[![npm ecc-agentshield](https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-agentshield)
+[![GitHub App Install](https://img.shields.io/badge/GitHub%20App-150%20installs-2ea44f?logo=github)](https://github.com/marketplace/ecc-tools)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
@@ -27,9 +30,29 @@
 
 ---
 
-**The complete collection of Claude Code configs from an Anthropic hackathon winner.**
+**The performance optimization system for AI agent harnesses. From an Anthropic hackathon winner.**
 
-Production-ready agents, skills, hooks, commands, rules, and MCP configurations evolved over 10+ months of intensive daily use building real products.
+Not just configs. A complete system: skills, instincts, memory optimization, continuous learning, security scanning, and research-first development. Production-ready agents, hooks, commands, rules, and MCP configurations evolved over 10+ months of intensive daily use building real products.
+
+Works across **Claude Code**, **Codex**, **Cowork**, and other AI agent harnesses.
+
+---
+
+## Traction & Distribution
+
+Use these live signals when presenting ECC to sponsors, platforms, or ecosystem partners:
+
+- **Main package installs:** [`ecc-universal` on npm](https://www.npmjs.com/package/ecc-universal)
+- **Security companion installs:** [`ecc-agentshield` on npm](https://www.npmjs.com/package/ecc-agentshield)
+- **GitHub App distribution:** [ECC Tools marketplace listing](https://github.com/marketplace/ecc-tools)
+- **Automated monthly metrics issue:** powered by `.github/workflows/monthly-metrics.yml`
+- **Repo adoption signal:** stars/forks/contributors badges at the top of this README
+
+Download counts for Claude Code plugin installs are not currently exposed as a public API. For partner reporting, combine npm metrics with GitHub App installs and repository traffic/fork growth.
+
+For a sponsor-call metrics checklist and command snippets, see [`docs/business/metrics-and-sponsorship.md`](docs/business/metrics-and-sponsorship.md).
+
+[**Sponsor ECC**](https://github.com/sponsors/affaan-m) | [Sponsor Tiers](SPONSORS.md) | [Sponsorship Program](SPONSORING.md)
 
 ---
 
@@ -69,6 +92,16 @@ This repo is the raw code only. The guides explain everything.
 
 ## What's New
 
+### v1.8.0 — Harness Performance System (Mar 2026)
+
+- **Harness-first release** — ECC is now explicitly framed as an agent harness performance system, not just a config pack.
+- **Hook reliability overhaul** — SessionStart root fallback, Stop-phase session summaries, and script-based hooks replacing fragile inline one-liners.
+- **Hook runtime controls** — `ECC_HOOK_PROFILE=minimal|standard|strict` and `ECC_DISABLED_HOOKS=...` for runtime gating without editing hook files.
+- **New harness commands** — `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`.
+- **NanoClaw v2** — model routing, skill hot-load, session branch/search/export/compact/metrics.
+- **Cross-harness parity** — behavior tightened across Claude Code, Cursor, OpenCode, and Codex app/CLI.
+- **997 internal tests passing** — full suite green after hook/runtime refactor and compatibility updates.
+
 ### v1.7.0 — Cross-Platform Expansion & Presentation Builder (Feb 2026)
 
 - **Codex app + CLI support** — Direct `AGENTS.md`-based Codex support, installer targeting, and Codex docs
@@ -145,6 +178,8 @@ cd everything-claude-code
 # ./install.sh typescript python golang
 # or target cursor:
 # ./install.sh --target cursor typescript
+# or target antigravity:
+# ./install.sh --target antigravity typescript
 ```
 
 For manual install instructions see the README in the `rules/` folder.
@@ -162,13 +197,13 @@ For manual install instructions see the README in the `rules/` folder.
 /plugin list everything-claude-code@everything-claude-code
 ```
 
-✨ **That's it!** You now have access to 13 agents, 56 skills, and 32 commands.
+✨ **That's it!** You now have access to 16 agents, 65 skills, and 40 commands.
 
 ---
 
 ## 🌐 Cross-Platform Support
 
-This plugin now fully supports **Windows, macOS, and Linux**. All hooks and scripts have been rewritten in Node.js for maximum compatibility.
+This plugin now fully supports **Windows, macOS, and Linux**, alongside tight integration across major IDEs (Cursor, OpenCode, Antigravity) and CLI harnesses. All hooks and scripts have been rewritten in Node.js for maximum compatibility.
 
 ### Package Manager Detection
 
@@ -199,6 +234,18 @@ node scripts/setup-package-manager.js --detect
 
 Or use the `/setup-pm` command in Claude Code.
 
+### Hook Runtime Controls
+
+Use runtime flags to tune strictness or disable specific hooks temporarily:
+
+```bash
+# Hook strictness profile (default: standard)
+export ECC_HOOK_PROFILE=standard
+
+# Comma-separated hook IDs to disable
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+```
+
 ---
 
 ## 📦 What's Inside
@@ -281,6 +328,8 @@ everything-claude-code/
 |   |-- liquid-glass-design/         # iOS 26 Liquid Glass design system (NEW)
 |   |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels (NEW)
 |   |-- swift-concurrency-6-2/       # Swift 6.2 Approachable Concurrency (NEW)
+|   |-- autonomous-loops/           # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration (NEW)
+|   |-- plankton-code-quality/      # Write-time code quality enforcement with Plankton hooks (NEW)
 |
 |-- commands/         # Slash commands for quick execution
 |   |-- tdd.md              # /tdd - Test-driven development
@@ -440,6 +489,10 @@ Use `/security-scan` in Claude Code to run it, or add to CI with the [GitHub Act
 
 [GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield)
 
+### 🔬 Plankton — Write-Time Code Quality Enforcement
+
+Plankton (credit: @alxfazio) is a recommended companion for write-time code quality enforcement. It runs formatters and 20+ linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses (routed to Haiku/Sonnet/Opus by violation complexity) to fix issues the main agent missed. Three-phase architecture: auto-format silently (40-50% of issues), collect remaining violations as structured JSON, delegate fixes to a subprocess. Includes config protection hooks that prevent agents from modifying linter configs to pass instead of fixing code. Supports Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, and Dockerfile. Use alongside AgentShield for security + quality coverage. See `skills/plankton-code-quality/` for full integration guide.
+
 ### 🧠 Continuous Learning v2
 
 The instinct-based learning system automatically learns your patterns:
@@ -557,8 +610,15 @@ cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
 # Copy commands
 cp everything-claude-code/commands/*.md ~/.claude/commands/
 
-# Copy skills
-cp -r everything-claude-code/skills/* ~/.claude/skills/
+# Copy skills (core vs niche)
+# Recommended (new users): core/general skills only
+cp -r everything-claude-code/.agents/skills/* ~/.claude/skills/
+cp -r everything-claude-code/skills/search-first ~/.claude/skills/
+
+# Optional: add niche/framework-specific skills only when needed
+# for s in django-patterns django-tdd springboot-patterns; do
+#   cp -r everything-claude-code/skills/$s ~/.claude/skills/
+# done
 ```
 
 #### Add hooks to settings.json
@@ -730,12 +790,13 @@ Each component is fully independent.
 </details>
 
 <details>
-<summary><b>Does this work with Cursor / OpenCode / Codex?</b></summary>
+<summary><b>Does this work with Cursor / OpenCode / Codex / Antigravity?</b></summary>
 
 Yes. ECC is cross-platform:
 - **Cursor**: Pre-translated configs in `.cursor/`. See [Cursor IDE Support](#cursor-ide-support).
 - **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#-opencode-support).
-- **Codex**: First-class support with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257).
+- **Codex**: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257).
+- **Antigravity**: Tightly integrated setup for workflows, skills, and flatten rules in `.agent/`.
 - **Claude Code**: Native — this is the primary target.
 </details>
 
@@ -843,20 +904,25 @@ alwaysApply: false
 
 ---
 
-## Codex CLI Support
+## Codex macOS App + CLI Support
 
-ECC provides **first-class Codex CLI support** with a reference configuration, Codex-specific AGENTS.md supplement, and 16 ported skills.
+ECC provides **first-class Codex support** for both the macOS app and CLI, with a reference configuration, Codex-specific AGENTS.md supplement, and shared skills.
 
-### Quick Start (Codex)
+### Quick Start (Codex App + CLI)
 
 ```bash
 # Copy the reference config to your home directory
 cp .codex/config.toml ~/.codex/config.toml
 
-# Run Codex in the repo — AGENTS.md is auto-detected
+# Run Codex CLI in the repo — AGENTS.md is auto-detected
 codex
 ```
 
+Codex macOS app:
+- Open this repository as your workspace.
+- The root `AGENTS.md` is auto-detected.
+- Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for CLI/app behavior consistency.
+
 ### What's Included
 
 | Component | Count | Details |
@@ -892,7 +958,7 @@ Skills at `.agents/skills/` are auto-loaded by Codex:
 
 ### Key Limitation
 
-Codex CLI does **not yet support hooks** ([GitHub Issue #2109](https://github.com/openai/codex/issues/2109), 430+ upvotes). Security enforcement is instruction-based via `persistent_instructions` in config.toml and the sandbox permission system.
+Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md` and `persistent_instructions`, plus sandbox permissions.
 
 ---
 
@@ -916,9 +982,9 @@ The configuration is automatically detected from `.opencode/opencode.json`.
 
 | Feature | Claude Code | OpenCode | Status |
 |---------|-------------|----------|--------|
-| Agents | ✅ 13 agents | ✅ 12 agents | **Claude Code leads** |
-| Commands | ✅ 33 commands | ✅ 24 commands | **Claude Code leads** |
-| Skills | ✅ 50+ skills | ✅ 37 skills | **Claude Code leads** |
+| Agents | ✅ 16 agents | ✅ 12 agents | **Claude Code leads** |
+| Commands | ✅ 40 commands | ✅ 31 commands | **Claude Code leads** |
+| Skills | ✅ 65 skills | ✅ 37 skills | **Claude Code leads** |
 | Hooks | ✅ 8 event types | ✅ 11 events | **OpenCode has more!** |
 | Rules | ✅ 29 rules | ✅ 13 instructions | **Claude Code leads** |
 | MCP Servers | ✅ 14 servers | ✅ Full | **Full parity** |
@@ -938,7 +1004,7 @@ OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event t
 
 **Additional OpenCode events**: `file.edited`, `file.watcher.updated`, `message.updated`, `lsp.client.diagnostics`, `tui.toast.show`, and more.
 
-### Available Commands (32)
+### Available Commands (31+)
 
 | Command | Description |
 |---------|-------------|
@@ -972,8 +1038,15 @@ OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event t
 | `/instinct-import` | Import instincts |
 | `/instinct-export` | Export instincts |
 | `/evolve` | Cluster instincts into skills |
+| `/promote` | Promote project instincts to global scope |
+| `/projects` | List known projects and instinct stats |
 | `/learn-eval` | Extract and evaluate patterns before saving |
 | `/setup-pm` | Configure package manager |
+| `/harness-audit` | Audit harness reliability, eval readiness, and risk posture |
+| `/loop-start` | Start controlled agentic loop execution pattern |
+| `/loop-status` | Inspect active loop status and checkpoints |
+| `/quality-gate` | Run quality gate checks for paths or entire repo |
+| `/model-route` | Route tasks to models by complexity and budget |
 
 ### Plugin Installation
 
@@ -1010,11 +1083,11 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 
 | Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode |
 |---------|------------|------------|-----------|----------|
-| **Agents** | 13 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
-| **Commands** | 33 | Shared | Instruction-based | 24 |
-| **Skills** | 50+ | Shared | 10 (native format) | 37 |
+| **Agents** | 16 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
+| **Commands** | 40 | Shared | Instruction-based | 31 |
+| **Skills** | 65 | Shared | 10 (native format) | 37 |
 | **Hook Events** | 8 types | 15 types | None yet | 11 types |
-| **Hook Scripts** | 9 scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |
+| **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |
 | **Rules** | 29 (common + lang) | 29 (YAML frontmatter) | Instruction-based | 13 instructions |
 | **Custom Tools** | Via hooks | Via hooks | N/A | 6 native tools |
 | **MCP Servers** | 14 | Shared (mcp.json) | 4 (command-based) | Full |
@@ -1022,7 +1095,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 | **Context File** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md |
 | **Secret Detection** | Hook-based | beforeSubmitPrompt hook | Sandbox-based | Hook-based |
 | **Auto-Format** | PostToolUse hook | afterFileEdit hook | N/A | file.edited hook |
-| **Version** | Plugin | Plugin | Reference config | 1.6.0 |
+| **Version** | Plugin | Plugin | Reference config | 1.8.0 |
 
 **Key architectural decisions:**
 - **AGENTS.md** at root is the universal cross-tool file (read by all 4 tools)
@@ -1038,6 +1111,11 @@ I've been using Claude Code since the experimental rollout. Won the Anthropic x
 
 These configs are battle-tested across multiple production applications.
 
+## Inspiration Credits
+
+- inspired by [zarazhangrui](https://github.com/zarazhangrui)
+- homunculus-inspired by [humanplane](https://github.com/humanplane)
+
 ---
 
 ## Token Optimization
@@ -1142,7 +1220,7 @@ These configs work for my workflow. You should:
 
 This project is free and open source. Sponsors help keep it maintained and growing.
 
-[**Become a Sponsor**](https://github.com/sponsors/affaan-m) | [Sponsor Tiers](SPONSORS.md)
+[**Become a Sponsor**](https://github.com/sponsors/affaan-m) | [Sponsor Tiers](SPONSORS.md) | [Sponsorship Program](SPONSORING.md)
 
 ---
 

README.zh-CN.md

@@ -287,6 +287,8 @@ everything-claude-code/
 /instinct-import <file> # 从他人导入直觉
 /instinct-export        # 导出你的直觉以供分享
 /evolve                 # 将相关直觉聚类到技能中
+/promote                # 将项目级直觉提升为全局直觉
+/projects               # 查看已识别项目与直觉统计
 ```
 
 完整文档见 `skills/continuous-learning-v2/`。

SPONSORING.md

@@ -0,0 +1,43 @@
+# Sponsoring ECC
+
+ECC is maintained as an open-source agent harness performance system across Claude Code, Cursor, OpenCode, and Codex app/CLI.
+
+## Why Sponsor
+
+Sponsorship directly funds:
+
+- Faster bug-fix and release cycles
+- Cross-platform parity work across harnesses
+- Public docs, skills, and reliability tooling that remain free for the community
+
+## Sponsorship Tiers
+
+These are practical starting points and can be adjusted for partnership scope.
+
+| Tier | Price | Best For | Includes |
+|------|-------|----------|----------|
+| Pilot Partner | $200/mo | First sponsor engagement | Monthly metrics update, roadmap preview, prioritized maintainer feedback |
+| Growth Partner | $500/mo | Teams actively adopting ECC | Pilot benefits + monthly office-hours sync + workflow integration guidance |
+| Strategic Partner | $1,000+/mo | Platform/ecosystem partnerships | Growth benefits + coordinated launch support + deeper maintainer collaboration |
+
+## Sponsor Reporting
+
+Metrics shared monthly can include:
+
+- npm downloads (`ecc-universal`, `ecc-agentshield`)
+- Repository adoption (stars, forks, contributors)
+- GitHub App install trend
+- Release cadence and reliability milestones
+
+For exact command snippets and a repeatable pull process, see [`docs/business/metrics-and-sponsorship.md`](docs/business/metrics-and-sponsorship.md).
+
+## Expectations and Scope
+
+- Sponsorship supports maintenance and acceleration; it does not transfer project ownership.
+- Feature requests are prioritized based on sponsor tier, ecosystem impact, and maintenance risk.
+- Security and reliability fixes take precedence over net-new features.
+
+## Sponsor Here
+
+- GitHub Sponsors: [https://github.com/sponsors/affaan-m](https://github.com/sponsors/affaan-m)
+- Project site: [https://ecc.tools](https://ecc.tools)

SPONSORS.md

@@ -29,6 +29,17 @@ Your sponsorship helps:
 - **Better support** — Sponsors get priority responses
 - **Shape the roadmap** — Pro+ sponsors vote on features
 
+## Sponsor Readiness Signals
+
+Use these proof points in sponsor conversations:
+
+- Live npm install/download metrics for `ecc-universal` and `ecc-agentshield`
+- GitHub App distribution via Marketplace installs
+- Public adoption signals: stars, forks, contributors, release cadence
+- Cross-harness support: Claude Code, Cursor, OpenCode, Codex app/CLI
+
+See [`docs/business/metrics-and-sponsorship.md`](docs/business/metrics-and-sponsorship.md) for a copy/paste metrics pull workflow.
+
 ## Sponsor Tiers
 
 | Tier | Price | Benefits |
@@ -37,6 +48,7 @@ Your sponsorship helps:
 | Builder | $10/mo | Premium tools access |
 | Pro | $25/mo | Priority support, office hours |
 | Team | $100/mo | 5 seats, team configs |
+| Harness Partner | $200/mo | Monthly roadmap sync, prioritized maintainer feedback, release-note mention |
 | Business | $500/mo | 25 seats, consulting credit |
 | Enterprise | $2K/mo | Unlimited seats, custom tools |
 

agents/chief-of-staff.md

@@ -146,6 +146,6 @@ claude /schedule-reply "Reply to Sarah about the board meeting"
 ## Prerequisites
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- Gmail CLI (e.g., [gog](https://github.com/pterm/gog))
+- Gmail CLI (e.g., gog by @pterm)
 - Node.js 18+ (for calendar-suggest.js)
 - Optional: Slack MCP server, Matrix bridge (LINE), Chrome + Playwright (Messenger)

agents/code-reviewer.md

@@ -222,3 +222,16 @@ When available, also check project-specific conventions from `CLAUDE.md` or proj
 - State management conventions (Zustand, Redux, Context)
 
 Adapt your review to the project's established patterns. When in doubt, match what the rest of the codebase does.
+
+## v1.8 AI-Generated Code Review Addendum
+
+When reviewing AI-generated changes, prioritize:
+
+1. Behavioral regressions and edge-case handling
+2. Security assumptions and trust boundaries
+3. Hidden coupling or accidental architecture drift
+4. Unnecessary model-cost-inducing complexity
+
+Cost-awareness check:
+- Flag workflows that escalate to higher-cost models without clear reasoning need.
+- Recommend defaulting to lower-cost tiers for deterministic refactors.

agents/database-reviewer.md

@@ -7,7 +7,7 @@ model: sonnet
 
 # Database Reviewer
 
-You are an expert PostgreSQL database specialist focused on query optimization, schema design, security, and performance. Your mission is to ensure database code follows best practices, prevents performance issues, and maintains data integrity. Incorporates patterns from [Supabase's postgres-best-practices](https://github.com/supabase/agent-skills).
+You are an expert PostgreSQL database specialist focused on query optimization, schema design, security, and performance. Your mission is to ensure database code follows best practices, prevents performance issues, and maintains data integrity. Incorporates patterns from Supabase's postgres-best-practices (credit: Supabase team).
 
 ## Core Responsibilities
 
@@ -88,4 +88,4 @@ For detailed index patterns, schema design examples, connection management, conc
 
 **Remember**: Database issues are often the root cause of application performance problems. Optimize queries and schema design early. Use EXPLAIN ANALYZE to verify assumptions. Always index foreign keys and RLS policy columns.
 
-*Patterns adapted from [Supabase Agent Skills](https://github.com/supabase/agent-skills) under MIT license.*
+*Patterns adapted from Supabase Agent Skills (credit: Supabase team) under MIT license.*

agents/harness-optimizer.md

@@ -0,0 +1,35 @@
+---
+name: harness-optimizer
+description: Analyze and improve the local agent harness configuration for reliability, cost, and throughput.
+tools: ["Read", "Grep", "Glob", "Bash", "Edit"]
+model: sonnet
+color: teal
+---
+
+You are the harness optimizer.
+
+## Mission
+
+Raise agent completion quality by improving harness configuration, not by rewriting product code.
+
+## Workflow
+
+1. Run `/harness-audit` and collect baseline score.
+2. Identify top 3 leverage areas (hooks, evals, routing, context, safety).
+3. Propose minimal, reversible configuration changes.
+4. Apply changes and run validation.
+5. Report before/after deltas.
+
+## Constraints
+
+- Prefer small changes with measurable effect.
+- Preserve cross-platform behavior.
+- Avoid introducing fragile shell quoting.
+- Keep compatibility across Claude Code, Cursor, OpenCode, and Codex.
+
+## Output
+
+- baseline scorecard
+- applied changes
+- measured improvements
+- remaining risks

agents/loop-operator.md

@@ -0,0 +1,36 @@
+---
+name: loop-operator
+description: Operate autonomous agent loops, monitor progress, and intervene safely when loops stall.
+tools: ["Read", "Grep", "Glob", "Bash", "Edit"]
+model: sonnet
+color: orange
+---
+
+You are the loop operator.
+
+## Mission
+
+Run autonomous loops safely with clear stop conditions, observability, and recovery actions.
+
+## Workflow
+
+1. Start loop from explicit pattern and mode.
+2. Track progress checkpoints.
+3. Detect stalls and retry storms.
+4. Pause and reduce scope when failure repeats.
+5. Resume only after verification passes.
+
+## Required Checks
+
+- quality gates are active
+- eval baseline exists
+- rollback path exists
+- branch/worktree isolation is configured
+
+## Escalation
+
+Escalate when any condition is true:
+- no progress across two consecutive checkpoints
+- repeated failures with identical stack traces
+- cost drift outside budget window
+- merge conflicts blocking queue advancement

agents/tdd-guide.md

@@ -78,3 +78,14 @@ npm run test:coverage
 - [ ] Coverage is 80%+
 
 For detailed mocking patterns and framework-specific examples, see `skill: tdd-workflow`.
+
+## v1.8 Eval-Driven TDD Addendum
+
+Integrate eval-driven development into TDD flow:
+
+1. Define capability + regression evals before implementation.
+2. Run baseline and capture failure signatures.
+3. Implement minimum passing change.
+4. Re-run tests and evals; report pass@1 and pass@3.
+
+Release-critical paths should target pass^3 stability before merge.

commands/claw.md

@@ -1,10 +1,10 @@
 ---
-description: Start the NanoClaw agent REPL — a persistent, session-aware AI assistant powered by the claude CLI.
+description: Start NanoClaw v2 — ECC's persistent, zero-dependency REPL with model routing, skill hot-load, branching, compaction, export, and metrics.
 ---
 
 # Claw Command
 
-Start an interactive AI agent session that persists conversation history to disk and optionally loads ECC skill context.
+Start an interactive AI agent session with persistent markdown history and operational controls.
 
 ## Usage
 
@@ -23,57 +23,29 @@ npm run claw
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CLAW_SESSION` | `default` | Session name (alphanumeric + hyphens) |
-| `CLAW_SKILLS` | *(empty)* | Comma-separated skill names to load as system context |
+| `CLAW_SKILLS` | *(empty)* | Comma-separated skills loaded at startup |
+| `CLAW_MODEL` | `sonnet` | Default model for the session |
 
 ## REPL Commands
 
-Inside the REPL, type these commands directly at the prompt:
-
-```
-/clear      Clear current session history
-/history    Print full conversation history
-/sessions   List all saved sessions
-/help       Show available commands
-exit        Quit the REPL
+```text
+/help                          Show help
+/clear                         Clear current session history
+/history                       Print full conversation history
+/sessions                      List saved sessions
+/model [name]                  Show/set model
+/load <skill-name>             Hot-load a skill into context
+/branch <session-name>         Branch current session
+/search <query>                Search query across sessions
+/compact                       Compact old turns, keep recent context
+/export <md|json|txt> [path]   Export session
+/metrics                       Show session metrics
+exit                           Quit
 ```
 
-## How It Works
+## Notes
 
-1. Reads `CLAW_SESSION` env var to select a named session (default: `default`)
-2. Loads conversation history from `~/.claude/claw/{session}.md`
-3. Optionally loads ECC skill context from `CLAW_SKILLS` env var
-4. Enters a blocking prompt loop — each user message is sent to `claude -p` with full history
-5. Responses are appended to the session file for persistence across restarts
-
-## Session Storage
-
-Sessions are stored as Markdown files in `~/.claude/claw/`:
-
-```
-~/.claude/claw/default.md
-~/.claude/claw/my-project.md
-```
-
-Each turn is formatted as:
-
-```markdown
-### [2025-01-15T10:30:00.000Z] User
-What does this function do?
----
-### [2025-01-15T10:30:05.000Z] Assistant
-This function calculates...
----
-```
-
-## Examples
-
-```bash
-# Start default session
-node scripts/claw.js
-
-# Named session
-CLAW_SESSION=my-project node scripts/claw.js
-
-# With skill context
-CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
-```
+- NanoClaw remains zero-dependency.
+- Sessions are stored at `~/.claude/claw/<session>.md`.
+- Compaction keeps the most recent turns and writes a compaction header.
+- Export supports markdown, JSON turns, and plain text.

commands/evolve.md

@@ -1,6 +1,6 @@
 ---
 name: evolve
-description: Cluster related instincts into skills, commands, or agents
+description: Analyze instincts and suggest or generate evolved structures
 command: true
 ---
 
@@ -29,9 +29,7 @@ Analyzes instincts and clusters related ones into higher-level structures:
 
 ```
 /evolve                    # Analyze all instincts and suggest evolutions
-/evolve --domain testing   # Only evolve instincts in testing domain
-/evolve --dry-run          # Show what would be created without creating
-/evolve --threshold 5      # Require 5+ related instincts to cluster
+/evolve --generate         # Also generate files under evolved/{skills,commands,agents}
 ```
 
 ## Evolution Rules
@@ -78,63 +76,50 @@ Example:
 
 ## What to Do
 
-1. Read all instincts from `~/.claude/homunculus/instincts/`
-2. Group instincts by:
-   - Domain similarity
-   - Trigger pattern overlap
-   - Action sequence relationship
-3. For each cluster of 3+ related instincts:
-   - Determine evolution type (command/skill/agent)
-   - Generate the appropriate file
-   - Save to `~/.claude/homunculus/evolved/{commands,skills,agents}/`
-4. Link evolved structure back to source instincts
+1. Detect current project context
+2. Read project + global instincts (project takes precedence on ID conflicts)
+3. Group instincts by trigger/domain patterns
+4. Identify:
+   - Skill candidates (trigger clusters with 2+ instincts)
+   - Command candidates (high-confidence workflow instincts)
+   - Agent candidates (larger, high-confidence clusters)
+5. Show promotion candidates (project -> global) when applicable
+6. If `--generate` is passed, write files to:
+   - Project scope: `~/.claude/homunculus/projects/<project-id>/evolved/`
+   - Global fallback: `~/.claude/homunculus/evolved/`
 
 ## Output Format
 
 ```
-🧬 Evolve Analysis
-==================
+============================================================
+  EVOLVE ANALYSIS - 12 instincts
+  Project: my-app (a1b2c3d4e5f6)
+  Project-scoped: 8 | Global: 4
+============================================================
 
-Found 3 clusters ready for evolution:
+High confidence instincts (>=80%): 5
 
-## Cluster 1: Database Migration Workflow
-Instincts: new-table-migration, update-schema, regenerate-types
-Type: Command
-Confidence: 85% (based on 12 observations)
+## SKILL CANDIDATES
+1. Cluster: "adding tests"
+   Instincts: 3
+   Avg confidence: 82%
+   Domains: testing
+   Scopes: project
 
-Would create: /new-table command
-Files:
-  - ~/.claude/homunculus/evolved/commands/new-table.md
+## COMMAND CANDIDATES (2)
+  /adding-tests
+    From: test-first-workflow [project]
+    Confidence: 84%
 
-## Cluster 2: Functional Code Style
-Instincts: prefer-functional, use-immutable, avoid-classes, pure-functions
-Type: Skill
-Confidence: 78% (based on 8 observations)
-
-Would create: functional-patterns skill
-Files:
-  - ~/.claude/homunculus/evolved/skills/functional-patterns.md
-
-## Cluster 3: Debugging Process
-Instincts: debug-check-logs, debug-isolate, debug-reproduce, debug-verify
-Type: Agent
-Confidence: 72% (based on 6 observations)
-
-Would create: debugger agent
-Files:
-  - ~/.claude/homunculus/evolved/agents/debugger.md
-
----
-Run `/evolve --execute` to create these files.
+## AGENT CANDIDATES (1)
+  adding-tests-agent
+    Covers 3 instincts
+    Avg confidence: 82%
 ```
 
 ## Flags
 
-- `--execute`: Actually create the evolved structures (default is preview)
-- `--dry-run`: Preview without creating
-- `--domain <name>`: Only evolve instincts in specified domain
-- `--threshold <n>`: Minimum instincts required to form cluster (default: 3)
-- `--type <command|skill|agent>`: Only create specified type
+- `--generate`: Generate evolved files in addition to analysis output
 
 ## Generated File Format
 

commands/harness-audit.md

@@ -0,0 +1,58 @@
+# Harness Audit Command
+
+Audit the current repository's agent harness setup and return a prioritized scorecard.
+
+## Usage
+
+`/harness-audit [scope] [--format text|json]`
+
+- `scope` (optional): `repo` (default), `hooks`, `skills`, `commands`, `agents`
+- `--format`: output style (`text` default, `json` for automation)
+
+## What to Evaluate
+
+Score each category from `0` to `10`:
+
+1. Tool Coverage
+2. Context Efficiency
+3. Quality Gates
+4. Memory Persistence
+5. Eval Coverage
+6. Security Guardrails
+7. Cost Efficiency
+
+## Output Contract
+
+Return:
+
+1. `overall_score` out of 70
+2. Category scores and concrete findings
+3. Top 3 actions with exact file paths
+4. Suggested ECC skills to apply next
+
+## Checklist
+
+- Inspect `hooks/hooks.json`, `scripts/hooks/`, and hook tests.
+- Inspect `skills/`, command coverage, and agent coverage.
+- Verify cross-harness parity for `.cursor/`, `.opencode/`, `.codex/`.
+- Flag broken or stale references.
+
+## Example Result
+
+```text
+Harness Audit (repo): 52/70
+- Quality Gates: 9/10
+- Eval Coverage: 6/10
+- Cost Efficiency: 4/10
+
+Top 3 Actions:
+1) Add cost tracking hook in scripts/hooks/cost-tracker.js
+2) Add pass@k docs and templates in skills/eval-harness/SKILL.md
+3) Add command parity for /harness-audit in .opencode/commands/
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `repo|hooks|skills|commands|agents` (optional scope)
+- `--format text|json` (optional output format)

commands/instinct-export.md

@@ -1,6 +1,6 @@
 ---
 name: instinct-export
-description: Export instincts for sharing with teammates or other projects
+description: Export instincts from project/global scope to a file
 command: /instinct-export
 ---
 
@@ -18,17 +18,18 @@ Exports instincts to a shareable format. Perfect for:
 /instinct-export --domain testing          # Export only testing instincts
 /instinct-export --min-confidence 0.7      # Only export high-confidence instincts
 /instinct-export --output team-instincts.yaml
+/instinct-export --scope project --output project-instincts.yaml
 ```
 
 ## What to Do
 
-1. Read instincts from `~/.claude/homunculus/instincts/personal/`
-2. Filter based on flags
-3. Strip sensitive information:
-   - Remove session IDs
-   - Remove file paths (keep only patterns)
-   - Remove timestamps older than "last week"
-4. Generate export file
+1. Detect current project context
+2. Load instincts by selected scope:
+   - `project`: current project only
+   - `global`: global only
+   - `all`: project + global merged (default)
+3. Apply filters (`--domain`, `--min-confidence`)
+4. Write YAML-style export to file (or stdout if no output path provided)
 
 ## Output Format
 
@@ -40,52 +41,26 @@ Creates a YAML file:
 # Source: personal
 # Count: 12 instincts
 
-version: "2.0"
-exported_by: "continuous-learning-v2"
-export_date: "2025-01-22T10:30:00Z"
+---
+id: prefer-functional-style
+trigger: "when writing new functions"
+confidence: 0.8
+domain: code-style
+source: session-observation
+scope: project
+project_id: a1b2c3d4e5f6
+project_name: my-app
+---
 
-instincts:
-  - id: prefer-functional-style
-    trigger: "when writing new functions"
-    action: "Use functional patterns over classes"
-    confidence: 0.8
-    domain: code-style
-    observations: 8
+# Prefer Functional Style
 
-  - id: test-first-workflow
-    trigger: "when adding new functionality"
-    action: "Write test first, then implementation"
-    confidence: 0.9
-    domain: testing
-    observations: 12
-
-  - id: grep-before-edit
-    trigger: "when modifying code"
-    action: "Search with Grep, confirm with Read, then Edit"
-    confidence: 0.7
-    domain: workflow
-    observations: 6
+## Action
+Use functional patterns over classes.
 ```
 
-## Privacy Considerations
-
-Exports include:
-- ✅ Trigger patterns
-- ✅ Actions
-- ✅ Confidence scores
-- ✅ Domains
-- ✅ Observation counts
-
-Exports do NOT include:
-- ❌ Actual code snippets
-- ❌ File paths
-- ❌ Session transcripts
-- ❌ Personal identifiers
-
 ## Flags
 
 - `--domain <name>`: Export only specified domain
-- `--min-confidence <n>`: Minimum confidence threshold (default: 0.3)
-- `--output <file>`: Output file path (default: instincts-export-YYYYMMDD.yaml)
-- `--format <yaml|json|md>`: Output format (default: yaml)
-- `--include-evidence`: Include evidence text (default: excluded)
+- `--min-confidence <n>`: Minimum confidence threshold
+- `--output <file>`: Output file path (prints to stdout when omitted)
+- `--scope <project|global|all>`: Export scope (default: `all`)

commands/instinct-import.md

@@ -1,6 +1,6 @@
 ---
 name: instinct-import
-description: Import instincts from teammates, Skill Creator, or other sources
+description: Import instincts from file or URL into project/global scope
 command: true
 ---
 
@@ -11,7 +11,7 @@ command: true
 Run the instinct CLI using the plugin root path:
 
 ```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" import <file-or-url> [--dry-run] [--force] [--min-confidence 0.7]
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" import <file-or-url> [--dry-run] [--force] [--min-confidence 0.7] [--scope project|global]
 ```
 
 Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
@@ -20,18 +20,15 @@ Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
 python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py import <file-or-url>
 ```
 
-Import instincts from:
-- Teammates' exports
-- Skill Creator (repo analysis)
-- Community collections
-- Previous machine backups
+Import instincts from local file paths or HTTP(S) URLs.
 
 ## Usage
 
 ```
 /instinct-import team-instincts.yaml
 /instinct-import https://github.com/org/repo/instincts.yaml
-/instinct-import --from-skill-creator acme/webapp
+/instinct-import team-instincts.yaml --dry-run
+/instinct-import team-instincts.yaml --scope global --force
 ```
 
 ## What to Do
@@ -40,7 +37,9 @@ Import instincts from:
 2. Parse and validate the format
 3. Check for duplicates with existing instincts
 4. Merge or add new instincts
-5. Save to `~/.claude/homunculus/instincts/inherited/`
+5. Save to inherited instincts directory:
+   - Project scope: `~/.claude/homunculus/projects/<project-id>/instincts/inherited/`
+   - Global scope: `~/.claude/homunculus/instincts/inherited/`
 
 ## Import Process
 
@@ -71,60 +70,33 @@ Already have similar instincts:
      Import: 0.9 confidence
      → Update to import (higher confidence)
 
-## Conflicting Instincts (1)
-These contradict local instincts:
-  ❌ use-classes-for-services
-     Conflicts with: avoid-classes
-     → Skip (requires manual resolution)
-
----
-Import 8 new, update 1, skip 3?
+Import 8 new, update 1?
 ```
 
-## Merge Strategies
+## Merge Behavior
 
-### For Duplicates
-When importing an instinct that matches an existing one:
-- **Higher confidence wins**: Keep the one with higher confidence
-- **Merge evidence**: Combine observation counts
-- **Update timestamp**: Mark as recently validated
-
-### For Conflicts
-When importing an instinct that contradicts an existing one:
-- **Skip by default**: Don't import conflicting instincts
-- **Flag for review**: Mark both as needing attention
-- **Manual resolution**: User decides which to keep
+When importing an instinct with an existing ID:
+- Higher-confidence import becomes an update candidate
+- Equal/lower-confidence import is skipped
+- User confirms unless `--force` is used
 
 ## Source Tracking
 
 Imported instincts are marked with:
 ```yaml
-source: "inherited"
+source: inherited
+scope: project
 imported_from: "team-instincts.yaml"
-imported_at: "2025-01-22T10:30:00Z"
-original_source: "session-observation"  # or "repo-analysis"
+project_id: "a1b2c3d4e5f6"
+project_name: "my-project"
 ```
 
-## Skill Creator Integration
-
-When importing from Skill Creator:
-
-```
-/instinct-import --from-skill-creator acme/webapp
-```
-
-This fetches instincts generated from repo analysis:
-- Source: `repo-analysis`
-- Higher initial confidence (0.7+)
-- Linked to source repository
-
 ## Flags
 
 - `--dry-run`: Preview without importing
-- `--force`: Import even if conflicts exist
-- `--merge-strategy <higher|local|import>`: How to handle duplicates
-- `--from-skill-creator <owner/repo>`: Import from Skill Creator analysis
+- `--force`: Skip confirmation prompt
 - `--min-confidence <n>`: Only import instincts above threshold
+- `--scope <project|global>`: Select target scope (default: `project`)
 
 ## Output
 
@@ -134,7 +106,7 @@ After import:
 
 Added: 8 instincts
 Updated: 1 instinct
-Skipped: 3 instincts (2 duplicates, 1 conflict)
+Skipped: 3 instincts (equal/higher confidence already exists)
 
 New instincts saved to: ~/.claude/homunculus/instincts/inherited/
 

commands/instinct-status.md

@@ -1,12 +1,12 @@
 ---
 name: instinct-status
-description: Show all learned instincts with their confidence levels
+description: Show learned instincts (project + global) with confidence
 command: true
 ---
 
 # Instinct Status Command
 
-Shows all learned instincts with their confidence scores, grouped by domain.
+Shows learned instincts for the current project plus global instincts, grouped by domain.
 
 ## Implementation
 
@@ -26,61 +26,34 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
 
 ```
 /instinct-status
-/instinct-status --domain code-style
-/instinct-status --low-confidence
 ```
 
 ## What to Do
 
-1. Read all instinct files from `~/.claude/homunculus/instincts/personal/`
-2. Read inherited instincts from `~/.claude/homunculus/instincts/inherited/`
-3. Display them grouped by domain with confidence bars
+1. Detect current project context (git remote/path hash)
+2. Read project instincts from `~/.claude/homunculus/projects/<project-id>/instincts/`
+3. Read global instincts from `~/.claude/homunculus/instincts/`
+4. Merge with precedence rules (project overrides global when IDs collide)
+5. Display grouped by domain with confidence bars and observation stats
 
 ## Output Format
 
 ```
-📊 Instinct Status
-==================
+============================================================
+  INSTINCT STATUS - 12 total
+============================================================
 
-## Code Style (4 instincts)
+  Project: my-app (a1b2c3d4e5f6)
+  Project instincts: 8
+  Global instincts:  4
 
-### prefer-functional-style
-Trigger: when writing new functions
-Action: Use functional patterns over classes
-Confidence: ████████░░ 80%
-Source: session-observation | Last updated: 2025-01-22
+## PROJECT-SCOPED (my-app)
+  ### WORKFLOW (3)
+    ███████░░░  70%  grep-before-edit [project]
+              trigger: when modifying code
 
-### use-path-aliases
-Trigger: when importing modules
-Action: Use @/ path aliases instead of relative imports
-Confidence: ██████░░░░ 60%
-Source: repo-analysis (github.com/acme/webapp)
-
-## Testing (2 instincts)
-
-### test-first-workflow
-Trigger: when adding new functionality
-Action: Write test first, then implementation
-Confidence: █████████░ 90%
-Source: session-observation
-
-## Workflow (3 instincts)
-
-### grep-before-edit
-Trigger: when modifying code
-Action: Search with Grep, confirm with Read, then Edit
-Confidence: ███████░░░ 70%
-Source: session-observation
-
----
-Total: 9 instincts (4 personal, 5 inherited)
-Observer: Running (last analysis: 5 min ago)
+## GLOBAL (apply to all projects)
+  ### SECURITY (2)
+    █████████░  85%  validate-user-input [global]
+              trigger: when handling user input
 ```
-
-## Flags
-
-- `--domain <name>`: Filter by domain (code-style, testing, git, etc.)
-- `--low-confidence`: Show only instincts with confidence < 0.5
-- `--high-confidence`: Show only instincts with confidence >= 0.7
-- `--source <type>`: Filter by source (session-observation, repo-analysis, inherited)
-- `--json`: Output as JSON for programmatic use

commands/loop-start.md

@@ -0,0 +1,32 @@
+# Loop Start Command
+
+Start a managed autonomous loop pattern with safety defaults.
+
+## Usage
+
+`/loop-start [pattern] [--mode safe|fast]`
+
+- `pattern`: `sequential`, `continuous-pr`, `rfc-dag`, `infinite`
+- `--mode`:
+  - `safe` (default): strict quality gates and checkpoints
+  - `fast`: reduced gates for speed
+
+## Flow
+
+1. Confirm repository state and branch strategy.
+2. Select loop pattern and model tier strategy.
+3. Enable required hooks/profile for the chosen mode.
+4. Create loop plan and write runbook under `.claude/plans/`.
+5. Print commands to start and monitor the loop.
+
+## Required Safety Checks
+
+- Verify tests pass before first loop iteration.
+- Ensure `ECC_HOOK_PROFILE` is not disabled globally.
+- Ensure loop has explicit stop condition.
+
+## Arguments
+
+$ARGUMENTS:
+- `<pattern>` optional (`sequential|continuous-pr|rfc-dag|infinite`)
+- `--mode safe|fast` optional

commands/loop-status.md

@@ -0,0 +1,24 @@
+# Loop Status Command
+
+Inspect active loop state, progress, and failure signals.
+
+## Usage
+
+`/loop-status [--watch]`
+
+## What to Report
+
+- active loop pattern
+- current phase and last successful checkpoint
+- failing checks (if any)
+- estimated time/cost drift
+- recommended intervention (continue/pause/stop)
+
+## Watch Mode
+
+When `--watch` is present, refresh status periodically and surface state changes.
+
+## Arguments
+
+$ARGUMENTS:
+- `--watch` optional

commands/model-route.md

@@ -0,0 +1,26 @@
+# Model Route Command
+
+Recommend the best model tier for the current task by complexity and budget.
+
+## Usage
+
+`/model-route [task-description] [--budget low|med|high]`
+
+## Routing Heuristic
+
+- `haiku`: deterministic, low-risk mechanical changes
+- `sonnet`: default for implementation and refactors
+- `opus`: architecture, deep review, ambiguous requirements
+
+## Required Output
+
+- recommended model
+- confidence level
+- why this model fits
+- fallback model if first attempt fails
+
+## Arguments
+
+$ARGUMENTS:
+- `[task-description]` optional free-text
+- `--budget low|med|high` optional

commands/multi-backend.md

@@ -85,13 +85,13 @@ EOF",
 
 ### Phase 0: Prompt Enhancement (Optional)
 
-`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Codex calls**
+`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Codex calls**. If unavailable, use `$ARGUMENTS` as-is.
 
 ### Phase 1: Research
 
 `[Mode: Research]` - Understand requirements and gather context
 
-1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing APIs, data models, service architecture
+1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing APIs, data models, service architecture. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for symbol/API search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
 2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement
 
 ### Phase 2: Ideation

commands/multi-execute.md

@@ -136,7 +136,7 @@ TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
 
 `[Mode: Retrieval]`
 
-**Must use MCP tool for quick context retrieval, do NOT manually read files one by one**
+**If ace-tool MCP is available**, use it for quick context retrieval:
 
 Based on "Key Files" list in plan, call `mcp__ace-tool__search_context`:
 
@@ -151,7 +151,12 @@ mcp__ace-tool__search_context({
 - Extract target paths from plan's "Key Files" table
 - Build semantic query covering: entry files, dependency modules, related type definitions
 - If results insufficient, add 1-2 recursive retrievals
-- **NEVER** use Bash + find/ls to manually explore project structure
+
+**If ace-tool MCP is NOT available**, use Claude Code built-in tools as fallback:
+1. **Glob**: Find target files from plan's "Key Files" table (e.g., `Glob("src/components/**/*.tsx")`)
+2. **Grep**: Search for key symbols, function names, type definitions across the codebase
+3. **Read**: Read the discovered files to gather complete context
+4. **Task (Explore agent)**: For broader exploration, use `Task` with `subagent_type: "Explore"`
 
 **After Retrieval**:
 - Organize retrieved code snippets

commands/multi-frontend.md

@@ -85,13 +85,13 @@ EOF",
 
 ### Phase 0: Prompt Enhancement (Optional)
 
-`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Gemini calls**
+`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Gemini calls**. If unavailable, use `$ARGUMENTS` as-is.
 
 ### Phase 1: Research
 
 `[Mode: Research]` - Understand requirements and gather context
 
-1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing components, styles, design system
+1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing components, styles, design system. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for component/style search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
 2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement
 
 ### Phase 2: Ideation

commands/multi-plan.md

@@ -71,7 +71,7 @@ TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
 
 #### 1.1 Prompt Enhancement (MUST execute first)
 
-**MUST call `mcp__ace-tool__enhance_prompt` tool**:
+**If ace-tool MCP is available**, call `mcp__ace-tool__enhance_prompt` tool:
 
 ```
 mcp__ace-tool__enhance_prompt({
@@ -83,9 +83,11 @@ mcp__ace-tool__enhance_prompt({
 
 Wait for enhanced prompt, **replace original $ARGUMENTS with enhanced result** for all subsequent phases.
 
+**If ace-tool MCP is NOT available**: Skip this step and use the original `$ARGUMENTS` as-is for all subsequent phases.
+
 #### 1.2 Context Retrieval
 
-**Call `mcp__ace-tool__search_context` tool**:
+**If ace-tool MCP is available**, call `mcp__ace-tool__search_context` tool:
 
 ```
 mcp__ace-tool__search_context({
@@ -96,7 +98,12 @@ mcp__ace-tool__search_context({
 
 - Build semantic query using natural language (Where/What/How)
 - **NEVER answer based on assumptions**
-- If MCP unavailable: fallback to Glob + Grep for file discovery and key symbol location
+
+**If ace-tool MCP is NOT available**, use Claude Code built-in tools as fallback:
+1. **Glob**: Find relevant files by pattern (e.g., `Glob("**/*.ts")`, `Glob("src/**/*.py")`)
+2. **Grep**: Search for key symbols, function names, class definitions (e.g., `Grep("className|functionName")`)
+3. **Read**: Read the discovered files to gather complete context
+4. **Task (Explore agent)**: For deeper exploration, use `Task` with `subagent_type: "Explore"` to search across the codebase
 
 #### 1.3 Completeness Check
 

commands/multi-workflow.md

@@ -15,14 +15,14 @@ Structured development workflow with quality gates, MCP services, and multi-mode
 - Task to develop: $ARGUMENTS
 - Structured 6-phase workflow with quality gates
 - Multi-model collaboration: Codex (backend) + Gemini (frontend) + Claude (orchestration)
-- MCP service integration (ace-tool) for enhanced capabilities
+- MCP service integration (ace-tool, optional) for enhanced capabilities
 
 ## Your Role
 
 You are the **Orchestrator**, coordinating a multi-model collaborative system (Research → Ideation → Plan → Execute → Optimize → Review). Communicate concisely and professionally for experienced developers.
 
 **Collaborative Models**:
-- **ace-tool MCP** – Code retrieval + Prompt enhancement
+- **ace-tool MCP** (optional) – Code retrieval + Prompt enhancement
 - **Codex** – Backend logic, algorithms, debugging (**Backend authority, trustworthy**)
 - **Gemini** – Frontend UI/UX, visual design (**Frontend expert, backend opinions for reference only**)
 - **Claude (self)** – Orchestration, planning, execution, delivery
@@ -111,8 +111,8 @@ TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
 
 `[Mode: Research]` - Understand requirements and gather context:
 
-1. **Prompt Enhancement**: Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls**
-2. **Context Retrieval**: Call `mcp__ace-tool__search_context`
+1. **Prompt Enhancement** (if ace-tool MCP available): Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls**. If unavailable, use `$ARGUMENTS` as-is.
+2. **Context Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context`. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for symbol search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
 3. **Requirement Completeness Score** (0-10):
    - Goal clarity (0-3), Expected outcome (0-3), Scope boundaries (0-2), Constraints (0-2)
    - ≥7: Continue | <7: Stop, ask clarifying questions

commands/projects.md

@@ -0,0 +1,39 @@
+---
+name: projects
+description: List known projects and their instinct statistics
+command: true
+---
+
+# Projects Command
+
+List project registry entries and per-project instinct/observation counts for continuous-learning-v2.
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
+```
+
+## Usage
+
+```bash
+/projects
+```
+
+## What to Do
+
+1. Read `~/.claude/homunculus/projects.json`
+2. For each project, display:
+   - Project name, id, root, remote
+   - Personal and inherited instinct counts
+   - Observation event count
+   - Last seen timestamp
+3. Also display global instinct totals

commands/promote.md

@@ -0,0 +1,41 @@
+---
+name: promote
+description: Promote project-scoped instincts to global scope
+command: true
+---
+
+# Promote Command
+
+Promote instincts from project scope to global scope in continuous-learning-v2.
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" promote [instinct-id] [--force] [--dry-run]
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote [instinct-id] [--force] [--dry-run]
+```
+
+## Usage
+
+```bash
+/promote                      # Auto-detect promotion candidates
+/promote --dry-run            # Preview auto-promotion candidates
+/promote --force              # Promote all qualified candidates without prompt
+/promote grep-before-edit     # Promote one specific instinct from current project
+```
+
+## What to Do
+
+1. Detect current project
+2. If `instinct-id` is provided, promote only that instinct (if present in current project)
+3. Otherwise, find cross-project candidates that:
+   - Appear in at least 2 projects
+   - Meet confidence threshold
+4. Write promoted instincts to `~/.claude/homunculus/instincts/personal/` with `scope: global`

commands/quality-gate.md

@@ -0,0 +1,29 @@
+# Quality Gate Command
+
+Run the ECC quality pipeline on demand for a file or project scope.
+
+## Usage
+
+`/quality-gate [path|.] [--fix] [--strict]`
+
+- default target: current directory (`.`)
+- `--fix`: allow auto-format/fix where configured
+- `--strict`: fail on warnings where supported
+
+## Pipeline
+
+1. Detect language/tooling for target.
+2. Run formatter checks.
+3. Run lint/type checks when available.
+4. Produce a concise remediation list.
+
+## Notes
+
+This command mirrors hook behavior but is operator-invoked.
+
+## Arguments
+
+$ARGUMENTS:
+- `[path|.]` optional target path
+- `--fix` optional
+- `--strict` optional

docs/business/metrics-and-sponsorship.md

@@ -0,0 +1,74 @@
+# Metrics and Sponsorship Playbook
+
+This file is a practical script for sponsor calls and ecosystem partner reviews.
+
+## What to Track
+
+Use four categories in every update:
+
+1. **Distribution** — npm packages and GitHub App installs
+2. **Adoption** — stars, forks, contributors, release cadence
+3. **Product surface** — commands/skills/agents and cross-platform support
+4. **Reliability** — test pass counts and production bug turnaround
+
+## Pull Live Metrics
+
+### npm downloads
+
+```bash
+# Weekly downloads
+curl -s https://api.npmjs.org/downloads/point/last-week/ecc-universal
+curl -s https://api.npmjs.org/downloads/point/last-week/ecc-agentshield
+
+# Last 30 days
+curl -s https://api.npmjs.org/downloads/point/last-month/ecc-universal
+curl -s https://api.npmjs.org/downloads/point/last-month/ecc-agentshield
+```
+
+### GitHub repository adoption
+
+```bash
+gh api repos/affaan-m/everything-claude-code \
+  --jq '{stars:.stargazers_count,forks:.forks_count,contributors_url:.contributors_url,open_issues:.open_issues_count}'
+```
+
+### GitHub traffic (maintainer access required)
+
+```bash
+gh api repos/affaan-m/everything-claude-code/traffic/views
+gh api repos/affaan-m/everything-claude-code/traffic/clones
+```
+
+### GitHub App installs
+
+GitHub App install count is currently most reliable in the Marketplace/App dashboard.
+Use the latest value from:
+
+- [ECC Tools Marketplace](https://github.com/marketplace/ecc-tools)
+
+## What Cannot Be Measured Publicly (Yet)
+
+- Claude plugin install/download counts are not currently exposed via a public API.
+- For partner conversations, use npm metrics + GitHub App installs + repo traffic as the proxy bundle.
+
+## Suggested Sponsor Packaging
+
+Use these as starting points in negotiation:
+
+- **Pilot Partner:** `$200/month`
+  - Best for first partnership validation and simple monthly sponsor updates.
+- **Growth Partner:** `$500/month`
+  - Includes roadmap check-ins and implementation feedback loop.
+- **Strategic Partner:** `$1,000+/month`
+  - Multi-touch collaboration, launch support, and deeper operational alignment.
+
+## 60-Second Talking Track
+
+Use this on calls:
+
+> ECC is now positioned as an agent harness performance system, not a config repo.  
+> We track adoption through npm distribution, GitHub App installs, and repository growth.  
+> Claude plugin installs are structurally undercounted publicly, so we use a blended metrics model.  
+> The project supports Claude Code, Cursor, OpenCode, and Codex app/CLI with production-grade hook reliability and a large passing test suite.
+
+For launch-ready social copy snippets, see [`social-launch-copy.md`](./social-launch-copy.md).

docs/business/social-launch-copy.md

@@ -0,0 +1,62 @@
+# Social Launch Copy (X + LinkedIn)
+
+Use these templates as launch-ready starting points. Replace placeholders before posting.
+
+## X Post: Release Announcement
+
+```text
+ECC v1.8.0 is live.
+
+We moved from “config pack” to an agent harness performance system:
+- hook reliability fixes
+- new harness commands
+- cross-tool parity (Claude Code, Cursor, OpenCode, Codex)
+
+Start here: <repo-link>
+```
+
+## X Post: Proof + Metrics
+
+```text
+If you evaluate agent tooling, use blended distribution metrics:
+- npm installs (`ecc-universal`, `ecc-agentshield`)
+- GitHub App installs
+- repo adoption (stars/forks/contributors)
+
+We now track this monthly in-repo for sponsor transparency.
+```
+
+## X Quote Tweet: Eval Skills Article
+
+```text
+Strong point on eval discipline.
+
+In ECC we turned this into production checks via:
+- /harness-audit
+- /quality-gate
+- Stop-phase session summaries
+
+This is where harness performance compounds over time.
+```
+
+## X Quote Tweet: Plankton / deslop workflow
+
+```text
+This workflow direction is right: optimize the harness, not just prompts.
+
+Our v1.8.0 focus was reliability + parity + measurable quality gates across toolchains.
+```
+
+## LinkedIn Post: Partner-Friendly Summary
+
+```text
+We shipped ECC v1.8.0 with one objective: improve agent harness performance in production.
+
+Highlights:
+- more reliable hook lifecycle behavior
+- new harness-level quality commands
+- parity across Claude Code, Cursor, OpenCode, and Codex
+- stronger sponsor-facing metrics tracking
+
+If your team runs AI coding agents daily, this is designed for operational use.
+```

docs/continuous-learning-v2-spec.md

@@ -0,0 +1,14 @@
+# Continuous Learning v2 Spec
+
+This document captures the v2 continuous-learning architecture:
+
+1. Hook-based observation capture
+2. Background observer analysis loop
+3. Instinct scoring and persistence
+4. Evolution of instincts into reusable skills/commands
+
+Primary implementation lives in:
+- `skills/continuous-learning-v2/`
+- `scripts/hooks/`
+
+Use this file as the stable reference path for docs and translations.

docs/ja-JP/agents/database-reviewer.md

@@ -7,7 +7,7 @@ model: opus
 
 # データベースレビューアー
 
-あなたはクエリ最適化、スキーマ設計、セキュリティ、パフォーマンスに焦点を当てたエキスパートPostgreSQLデータベーススペシャリストです。あなたのミッションは、データベースコードがベストプラクティスに従い、パフォーマンス問題を防ぎ、データ整合性を維持することを確実にすることです。このエージェントは[SupabaseのPostgreSQLベストプラクティス](https://github.com/supabase/agent-skills)からのパターンを組み込んでいます。
+あなたはクエリ最適化、スキーマ設計、セキュリティ、パフォーマンスに焦点を当てたエキスパートPostgreSQLデータベーススペシャリストです。あなたのミッションは、データベースコードがベストプラクティスに従い、パフォーマンス問題を防ぎ、データ整合性を維持することを確実にすることです。このエージェントは[SupabaseのPostgreSQLベストプラクティス](Supabase Agent Skills (credit: Supabase team))からのパターンを組み込んでいます。
 
 ## 主な責務
 
@@ -651,4 +651,4 @@ ORDER BY rank DESC;
 
 **覚えておくこと**: データベースの問題は、アプリケーションパフォーマンス問題の根本原因であることが多いです。クエリとスキーマ設計を早期に最適化してください。仮定を検証するためにEXPLAIN ANALYZEを使用してください。常に外部キーとRLSポリシー列にインデックスを作成してください。
 
-*パターンはMITライセンスの下で[Supabase Agent Skills](https://github.com/supabase/agent-skills)から適応されています。*
+*パターンはMITライセンスの下で[Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team))から適応されています。*

docs/ja-JP/commands/multi-backend.md

@@ -85,13 +85,13 @@ EOF",
 
 ### フェーズ 0: プロンプト強化(オプション)
 
-`[Mode: Prepare]` - ace-tool MCPが利用可能な場合、`mcp__ace-tool__enhance_prompt`を呼び出し、**後続のCodex呼び出しのために元の$ARGUMENTSを強化結果で置き換える**
+`[Mode: Prepare]` - ace-tool MCPが利用可能な場合、`mcp__ace-tool__enhance_prompt`を呼び出し、**後続のCodex呼び出しのために元の$ARGUMENTSを強化結果で置き換える**。利用できない場合は`$ARGUMENTS`をそのまま使用。
 
 ### フェーズ 1: 調査
 
 `[Mode: Research]` - 要件の理解とコンテキストの収集
 
-1. **コード取得**(ace-tool MCPが利用可能な場合): `mcp__ace-tool__search_context`を呼び出して既存のAPI、データモデル、サービスアーキテクチャを取得
+1. **コード取得**(ace-tool MCPが利用可能な場合): `mcp__ace-tool__search_context`を呼び出して既存のAPI、データモデル、サービスアーキテクチャを取得。利用できない場合は組み込みツールを使用: `Glob`でファイル検索、`Grep`でシンボル/API検索、`Read`でコンテキスト収集、`Task`(Exploreエージェント)でより深い探索。
 2. 要件の完全性スコア(0-10): >=7で継続、<7で停止して補足
 
 ### フェーズ 2: アイデア創出

docs/ja-JP/commands/multi-execute.md

@@ -136,7 +136,7 @@ TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
 
 `[Mode: Retrieval]`
 
-**MCPツールを使用したクイックコンテキスト取得が必須です。ファイルを1つずつ手動で読まないでください**
+**ace-tool MCPが利用可能な場合**、クイックコンテキスト取得に使用:
 
 計画の「キーファイル」リストに基づいて、`mcp__ace-tool__search_context`を呼び出します:
 
@@ -151,7 +151,12 @@ mcp__ace-tool__search_context({
 - 計画の「キーファイル」テーブルから対象パスを抽出
 - カバー範囲のセマンティッククエリを構築: エントリファイル、依存モジュール、関連する型定義
 - 結果が不十分な場合、1-2回の再帰的取得を追加
-- **決して**Bash + find/lsを使用してプロジェクト構造を手動で探索しない
+
+**ace-tool MCPが利用できない場合**、Claude Code組み込みツールでフォールバック:
+1. **Glob**: 計画の「キーファイル」テーブルから対象ファイルを検索 (例: `Glob("src/components/**/*.tsx")`)
+2. **Grep**: キーシンボル、関数名、型定義をコードベース全体で検索
+3. **Read**: 発見したファイルを読み取り、完全なコンテキストを収集
+4. **Task (Explore エージェント)**: より広範な探索が必要な場合、`Task` を `subagent_type: "Explore"` で使用
 
 **取得後**:
 - 取得したコードスニペットを整理

docs/ja-JP/commands/multi-frontend.md

@@ -85,13 +85,13 @@ EOF",
 
 ### フェーズ 0: プロンプト強化(オプション)
 
-`[Mode: Prepare]` - ace-tool MCPが利用可能な場合、`mcp__ace-tool__enhance_prompt`を呼び出し、**後続のGemini呼び出しのために元の$ARGUMENTSを強化結果で置き換える**
+`[Mode: Prepare]` - ace-tool MCPが利用可能な場合、`mcp__ace-tool__enhance_prompt`を呼び出し、**後続のGemini呼び出しのために元の$ARGUMENTSを強化結果で置き換える**。利用できない場合は`$ARGUMENTS`をそのまま使用。
 
 ### フェーズ 1: 調査
 
 `[Mode: Research]` - 要件の理解とコンテキストの収集
 
-1. **コード取得**(ace-tool MCPが利用可能な場合): `mcp__ace-tool__search_context`を呼び出して既存のコンポーネント、スタイル、デザインシステムを取得
+1. **コード取得**(ace-tool MCPが利用可能な場合): `mcp__ace-tool__search_context`を呼び出して既存のコンポーネント、スタイル、デザインシステムを取得。利用できない場合は組み込みツールを使用: `Glob`でファイル検索、`Grep`でコンポーネント/スタイル検索、`Read`でコンテキスト収集、`Task`(Exploreエージェント)でより深い探索。
 2. 要件の完全性スコア(0-10): >=7で継続、<7で停止して補足
 
 ### フェーズ 2: アイデア創出

docs/ja-JP/commands/multi-plan.md

@@ -71,7 +71,7 @@ TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
 
 #### 1.1 プロンプト強化(最初に実行する必要があります)
 
-**`mcp__ace-tool__enhance_prompt`ツールを呼び出す必要があります**:
+**ace-tool MCPが利用可能な場合**、`mcp__ace-tool__enhance_prompt`ツールを呼び出す:
 
 ```
 mcp__ace-tool__enhance_prompt({
@@ -83,9 +83,11 @@ mcp__ace-tool__enhance_prompt({
 
 強化されたプロンプトを待ち、**後続のすべてのフェーズのために元の$ARGUMENTSを強化結果で置き換える**。
 
+**ace-tool MCPが利用できない場合**: このステップをスキップし、後続のすべてのフェーズで元の`$ARGUMENTS`をそのまま使用する。
+
 #### 1.2 コンテキスト取得
 
-**`mcp__ace-tool__search_context`ツールを呼び出す**:
+**ace-tool MCPが利用可能な場合**、`mcp__ace-tool__search_context`ツールを呼び出す:
 
 ```
 mcp__ace-tool__search_context({
@@ -96,7 +98,12 @@ mcp__ace-tool__search_context({
 
 - 自然言語を使用してセマンティッククエリを構築(Where/What/How)
 - **仮定に基づいて回答しない**
-- MCPが利用できない場合: Glob + Grepにフォールバックしてファイル検出とキーシンボル位置を特定
+
+**ace-tool MCPが利用できない場合**、Claude Code組み込みツールでフォールバック:
+1. **Glob**: パターンで関連ファイルを検索 (例: `Glob("**/*.ts")`, `Glob("src/**/*.py")`)
+2. **Grep**: キーシンボル、関数名、クラス定義を検索 (例: `Grep("className|functionName")`)
+3. **Read**: 発見したファイルを読み取り、完全なコンテキストを収集
+4. **Task (Explore エージェント)**: より深い探索が必要な場合、`Task` を `subagent_type: "Explore"` で使用
 
 #### 1.3 完全性チェック
 

docs/ja-JP/commands/multi-workflow.md

@@ -15,14 +15,14 @@
 - 開発するタスク: $ARGUMENTS
 - 品質ゲートを備えた構造化された6フェーズワークフロー
 - マルチモデル連携: Codex(バックエンド) + Gemini(フロントエンド) + Claude(オーケストレーション)
-- MCPサービス統合(ace-tool)による機能強化
+- MCPサービス統合(ace-tool、オプション)による機能強化
 
 ## 役割
 
 あなたは**オーケストレーター**として、マルチモデル協調システムを調整します(調査 → アイデア創出 → 計画 → 実装 → 最適化 → レビュー)。経験豊富な開発者向けに簡潔かつ専門的にコミュニケーションします。
 
 **連携モデル**:
-- **ace-tool MCP** – コード取得 + プロンプト強化
+- **ace-tool MCP**(オプション) – コード取得 + プロンプト強化
 - **Codex** – バックエンドロジック、アルゴリズム、デバッグ(**バックエンドの権威、信頼できる**)
 - **Gemini** – フロントエンドUI/UX、ビジュアルデザイン(**フロントエンドエキスパート、バックエンドの意見は参考のみ**)
 - **Claude(自身)** – オーケストレーション、計画、実装、配信
@@ -111,8 +111,8 @@ TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
 
 `[Mode: Research]` - 要件の理解とコンテキストの収集:
 
-1. **プロンプト強化**: `mcp__ace-tool__enhance_prompt`を呼び出し、**後続のすべてのCodex/Gemini呼び出しのために元の$ARGUMENTSを強化結果で置き換える**
-2. **コンテキスト取得**: `mcp__ace-tool__search_context`を呼び出す
+1. **プロンプト強化**(ace-tool MCPが利用可能な場合): `mcp__ace-tool__enhance_prompt`を呼び出し、**後続のすべてのCodex/Gemini呼び出しのために元の$ARGUMENTSを強化結果で置き換える**。利用できない場合は`$ARGUMENTS`をそのまま使用。
+2. **コンテキスト取得**(ace-tool MCPが利用可能な場合): `mcp__ace-tool__search_context`を呼び出す。利用できない場合は組み込みツールを使用: `Glob`でファイル検索、`Grep`でシンボル検索、`Read`でコンテキスト収集、`Task`(Exploreエージェント)でより深い探索。
 3. **要件完全性スコア**(0-10):
    - 目標の明確性(0-3)、期待される結果(0-3)、スコープの境界(0-2)、制約(0-2)
    - ≥7: 継続 | <7: 停止、明確化の質問を尋ねる

docs/ja-JP/plugins/README.md

@@ -15,7 +15,8 @@
 claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
 
 # コミュニティマーケットプレイスを追加
-claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
+# mgrep plugin by @mixedbread-ai
+claud plugin marketplace add https://github.com/mixedbread-ai/mgrep
 ```
 
 ### 推奨マーケットプレイス
@@ -67,7 +68,8 @@ claude plugin install typescript-lsp@claude-plugins-official
 ```bash
 # マーケットプレイスを追加
 claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
-claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
+# mgrep plugin by @mixedbread-ai
+claud plugin marketplace add https://github.com/mixedbread-ai/mgrep
 
 # /pluginsを開き、必要なものをインストール
 ```

docs/ja-JP/skills/continuous-learning/SKILL.md

@@ -107,4 +107,4 @@ Homunculus v2はより洗練されたアプローチを採用:
 4. **ドメインタグ付け** - コードスタイル、テスト、git、デバッグなど
 5. **進化パス** - 関連する本能をスキル/コマンドにクラスタ化
 
-詳細: `/Users/affoon/Documents/tasks/12-continuous-learning-v2.md`を参照。
+詳細: `docs/continuous-learning-v2-spec.md`を参照。

docs/ja-JP/skills/cpp-testing/SKILL.md

@@ -160,7 +160,7 @@ include(FetchContent)
 set(GTEST_VERSION v1.17.0) # プロジェクトポリシーに合わせて調整します。
 FetchContent_Declare(
   googletest
-  URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
+  URL Google Test framework (official repository) https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
 )
 FetchContent_MakeAvailable(googletest)
 

docs/ja-JP/skills/postgres-patterns/SKILL.md

@@ -143,4 +143,4 @@ SELECT pg_reload_conf();
 
 ---
 
-*[Supabase Agent Skills](https://github.com/supabase/agent-skills)（MITライセンス）に基づく*
+*[Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team))（MITライセンス）に基づく*

docs/releases/1.8.0/linkedin-post.md

@@ -0,0 +1,13 @@
+# LinkedIn Draft - ECC v1.8.0
+
+ECC v1.8.0 is now focused on harness performance at the system level.
+
+This release improves:
+- hook reliability and lifecycle behavior
+- eval-driven engineering workflows
+- operator tooling for autonomous loops
+- cross-platform support for Claude Code, Cursor, OpenCode, and Codex
+
+We also shipped NanoClaw v2 with stronger session operations for real workflow usage.
+
+If your AI coding workflow feels inconsistent, start by treating the harness as a first-class engineering system.

docs/releases/1.8.0/reference-attribution.md

@@ -0,0 +1,16 @@
+# Reference Attribution and Licensing Notes
+
+ECC v1.8.0 references research and workflow inspiration from:
+
+- `plankton`
+- `ralphinho`
+- `infinite-agentic-loop`
+- `continuous-claude`
+- public profiles: [zarazhangrui](https://github.com/zarazhangrui), [humanplane](https://github.com/humanplane)
+
+## Policy
+
+1. No direct code copying from unlicensed or incompatible sources.
+2. ECC implementations are re-authored for this repository’s architecture and licensing model.
+3. Referenced material is used for ideas, patterns, and conceptual framing only unless licensing explicitly permits reuse.
+4. Any future direct reuse requires explicit license verification and source attribution in-file and in release notes.

docs/releases/1.8.0/release-notes.md

@@ -0,0 +1,20 @@
+# ECC v1.8.0 Release Notes
+
+## Positioning
+
+ECC v1.8.0 positions the project as an agent harness performance system, not just a config bundle.
+
+## Key Improvements
+
+- Stabilized hooks and lifecycle behavior.
+- Expanded eval and loop operations surface.
+- Upgraded NanoClaw for operational use.
+- Improved cross-harness parity (Claude Code, Cursor, OpenCode, Codex).
+
+## Upgrade Focus
+
+1. Validate hook profile defaults in your environment.
+2. Run `/harness-audit` to baseline your project.
+3. Use `/quality-gate` and updated eval workflows to enforce consistency.
+4. Review attribution and licensing notes for referenced ecosystems: [reference-attribution.md](./reference-attribution.md).
+5. For partner/sponsor optics, use live distribution metrics and talking points: [../business/metrics-and-sponsorship.md](../../business/metrics-and-sponsorship.md).

docs/releases/1.8.0/x-quote-eval-skills.md

@@ -0,0 +1,5 @@
+# X Quote Draft - Eval Skills Post
+
+Strong eval skills are now built deeper into ECC.
+
+v1.8.0 expands eval-harness patterns, pass@k guidance, and release-level verification loops so teams can measure reliability, not guess it.

docs/releases/1.8.0/x-quote-plankton-deslop.md

@@ -0,0 +1,5 @@
+# X Quote Draft - Plankton / De-slop Workflow
+
+The quality gate model matters.
+
+In v1.8.0 we pushed harder on write-time quality enforcement, deterministic checks, and cleaner loop recovery so agents converge faster with less noise.

docs/releases/1.8.0/x-thread.md

@@ -0,0 +1,11 @@
+# X Thread Draft - ECC v1.8.0
+
+1/ ECC v1.8.0 is live. This release is about one thing: better agent harness performance.
+
+2/ We shipped hook reliability fixes, loop operations commands, and stronger eval workflows.
+
+3/ NanoClaw v2 now supports model routing, skill hot-load, branching, search, compaction, export, and metrics.
+
+4/ If your agents are underperforming, start with `/harness-audit` and tighten quality gates.
+
+5/ Cross-harness parity remains a priority: Claude Code, Cursor, OpenCode, Codex.

docs/zh-CN/CONTRIBUTING.md

@@ -89,10 +89,11 @@ skills/
 
 ### SKILL.md 模板
 
-```markdown
+````markdown
 ---
 name: your-skill-name
 description: Brief description shown in skill list
+origin: ECC
 ---
 
 # 你的技能标题
@@ -101,30 +102,16 @@ description: Brief description shown in skill list
 
 ## 核心概念
 
-解释关键模式和准则。
+解释关键模式和指导原则。
 
 ## 代码示例
 
-`​`​`typescript
-
+```typescript
 // 包含实用、经过测试的示例
 function example() {
   // 注释良好的代码
 }
-`​`​`
-
-
-## 最佳实践
-
-- 可操作的指导原则
-- 该做与不该做的事项
-- 需要避免的常见陷阱
-
-## 适用场景
-
-描述此技能适用的场景。
-
-```
+````
 
 ### 技能清单
 

docs/zh-CN/README.md

@@ -1,4 +1,4 @@
-**语言:** English | [繁體中文](../zh-TW/README.md) | [简体中文](README.md)
+**语言：** 英语 | [繁體中文](../zh-TW/README.md) | [简体中文](../../README.md)
 
 # Everything Claude Code
 
@@ -13,7 +13,7 @@
 ![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk\&logoColor=white)
 ![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown\&logoColor=white)
 
-> **42K+ 星标** | **5K+ 分支** | **24 位贡献者** | **支持 6 种语言**
+> **5万+ stars** | **6千+ forks** | **30位贡献者** | **支持6种语言** | **Anthropic黑客马拉松获胜者**
 
 ***
 
@@ -21,7 +21,7 @@
 
 **🌐 语言 / 语言 / 語言**
 
-[**English**](../../README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../../docs/zh-TW/README.md)
+[**English**](../../README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md)
 
 </div>
 
@@ -69,6 +69,23 @@
 
 ## 最新动态
 
+### v1.7.0 — 跨平台扩展与演示文稿生成器（2026年2月）
+
+* **Codex 应用 + CLI 支持** — 基于 `AGENTS.md` 的直接 Codex 支持、安装器目标定位以及 Codex 文档
+* **`frontend-slides` 技能** — 零依赖的 HTML 演示文稿生成器，附带 PPTX 转换指导和严格的视口适配规则
+* **5个新的通用业务/内容技能** — `article-writing`、`content-engine`、`market-research`、`investor-materials`、`investor-outreach`
+* **更广泛的工具覆盖** — 加强了对 Cursor、Codex 和 OpenCode 的支持，使得同一代码仓库可以在所有主要平台上干净地部署
+* **992项内部测试** — 在插件、钩子、技能和打包方面扩展了验证和回归测试覆盖
+
+### v1.6.0 — Codex CLI、AgentShield 与市场（2026年2月）
+
+* **Codex CLI 支持** — 新的 `/codex-setup` 命令生成 `codex.md` 以实现 OpenAI Codex CLI 兼容性
+* **7个新技能** — `search-first`、`swift-actor-persistence`、`swift-protocol-di-testing`、`regex-vs-llm-structured-text`、`content-hash-cache-pattern`、`cost-aware-llm-pipeline`、`skill-stocktake`
+* **AgentShield 集成** — `/security-scan` 技能直接从 Claude Code 运行 AgentShield；1282 项测试，102 条规则
+* **GitHub 市场** — ECC Tools GitHub 应用已在 [github.com/marketplace/ecc-tools](https://github.com/marketplace/ecc-tools) 上线，提供免费/专业/企业版
+* **合并了 30+ 个社区 PR** — 来自 6 种语言的 30 位贡献者的贡献
+* **978项内部测试** — 在代理、技能、命令、钩子和规则方面扩展了验证套件
+
 ### v1.4.1 — 错误修复 (2026年2月)
 
 * **修复了直觉导入内容丢失问题** — `parse_instinct_file()` 在 `/instinct-import` 期间会静默丢弃 frontmatter 之后的所有内容（Action, Evidence, Examples 部分）。已由社区贡献者 @ericcai0814 修复 ([#148](https://github.com/affaan-m/everything-claude-code/issues/148), [#161](https://github.com/affaan-m/everything-claude-code/pull/161))
@@ -120,27 +137,32 @@
 ```bash
 # Clone the repo first
 git clone https://github.com/affaan-m/everything-claude-code.git
+cd everything-claude-code
 
-# Install common rules (required)
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-
-# Install language-specific rules (pick your stack)
-cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/
-cp -r everything-claude-code/rules/python/* ~/.claude/rules/
-cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+# Recommended: use the installer (handles common + language rules safely)
+./install.sh typescript    # or python or golang
+# You can pass multiple languages:
+# ./install.sh typescript python golang
+# or target cursor:
+# ./install.sh --target cursor typescript
 ```
 
+手动安装说明请参阅 `rules/` 文件夹中的 README。
+
 ### 步骤 3：开始使用
 
 ```bash
-# Try a command
-/plan "Add user authentication"
+# Try a command (plugin install uses namespaced form)
+/everything-claude-code:plan "Add user authentication"
+
+# Manual install (Option 2) uses the shorter form:
+# /plan "Add user authentication"
 
 # Check available commands
 /plugin list everything-claude-code@everything-claude-code
 ```
 
-✨ **就是这样！** 您现在可以访问 15+ 个智能体，30+ 个技能，以及 30+ 个命令。
+✨ **就是这样！** 你现在可以访问 13 个代理、56 个技能和 32 个命令。
 
 ***
 
@@ -185,11 +207,11 @@ node scripts/setup-package-manager.js --detect
 
 ```
 everything-claude-code/
-|-- .claude-plugin/   # 插件和插件市场清单
+|-- .claude-plugin/   # 插件和市场清单
 |   |-- plugin.json         # 插件元数据和组件路径
 |   |-- marketplace.json    # 用于 /plugin marketplace add 的市场目录
 |
-|-- agents/           # 用于任务委派的专用子代理
+|-- agents/           # 用于委派的专用子代理
 |   |-- planner.md           # 功能实现规划
 |   |-- architect.md         # 系统设计决策
 |   |-- tdd-guide.md         # 测试驱动开发
@@ -205,20 +227,28 @@ everything-claude-code/
 |   |-- database-reviewer.md # 数据库/Supabase 审查（新增）
 |
 |-- skills/           # 工作流定义与领域知识
-|   |-- coding-standards/           # 各语言最佳实践
+|   |-- coding-standards/           # 语言最佳实践
+|   |-- clickhouse-io/              # ClickHouse 分析、查询与数据工程
 |   |-- backend-patterns/           # API、数据库、缓存模式
 |   |-- frontend-patterns/          # React、Next.js 模式
-|   |-- continuous-learning/        # 从会话中自动提取模式（长文档指南）
+|   |-- frontend-slides/            # HTML 幻灯片与 PPTX 转 Web 演示流程（新增）
+|   |-- article-writing/            # 使用指定风格进行长文写作（避免通用 AI 语气）（新增）
+|   |-- content-engine/             # 多平台内容创作与再利用工作流（新增）
+|   |-- market-research/            # 带来源标注的市场、竞品与投资人研究（新增）
+|   |-- investor-materials/         # 融资路演材料、单页纸、备忘录与财务模型（新增）
+|   |-- investor-outreach/          # 个性化融资外联与跟进（新增）
+|   |-- continuous-learning/        # 从会话中自动提取模式（长文指南）
 |   |-- continuous-learning-v2/     # 基于直觉的学习与置信度评分
-|   |-- iterative-retrieval/        # 子代理的渐进式上下文精炼
-|   |-- strategic-compact/          # 手动压缩建议（长文档指南）
+|   |-- iterative-retrieval/        # 子代理渐进式上下文优化
+|   |-- strategic-compact/          # 手动压缩建议（长文指南）
 |   |-- tdd-workflow/               # TDD 方法论
 |   |-- security-review/            # 安全检查清单
-|   |-- eval-harness/               # 验证循环评估（长文档指南）
-|   |-- verification-loop/          # 持续验证（长文档指南）
-|   |-- golang-patterns/            # Go 语言惯用法与最佳实践
+|   |-- eval-harness/               # 验证循环评估（长文指南）
+|   |-- verification-loop/          # 持续验证（长文指南）
+|   |-- golang-patterns/            # Go 惯用法与最佳实践
 |   |-- golang-testing/             # Go 测试模式、TDD 与基准测试
-|   |-- cpp-testing/                # 使用 GoogleTest、CMake/CTest 的 C++ 测试（新增）
+|   |-- cpp-coding-standards/         # 来自 C++ Core Guidelines 的 C++ 编码规范（新增）
+|   |-- cpp-testing/                # 使用 GoogleTest 与 CMake/CTest 的 C++ 测试（新增）
 |   |-- django-patterns/            # Django 模式、模型与视图（新增）
 |   |-- django-security/            # Django 安全最佳实践（新增）
 |   |-- django-tdd/                 # Django TDD 工作流（新增）
@@ -228,25 +258,46 @@ everything-claude-code/
 |   |-- springboot-patterns/        # Java Spring Boot 模式（新增）
 |   |-- springboot-security/        # Spring Boot 安全（新增）
 |   |-- springboot-tdd/             # Spring Boot TDD（新增）
-|   |-- springboot-verification/    # Spring Boot 验证流程（新增）
+|   |-- springboot-verification/    # Spring Boot 验证（新增）
 |   |-- configure-ecc/              # 交互式安装向导（新增）
 |   |-- security-scan/              # AgentShield 安全审计集成（新增）
+|   |-- java-coding-standards/     # Java 编码规范（新增）
+|   |-- jpa-patterns/              # JPA/Hibernate 模式（新增）
+|   |-- postgres-patterns/         # PostgreSQL 优化模式（新增）
+|   |-- nutrient-document-processing/ # 使用 Nutrient API 的文档处理（新增）
+|   |-- project-guidelines-example/   # 项目专用技能模板
+|   |-- database-migrations/         # 迁移模式（Prisma、Drizzle、Django、Go）（新增）
+|   |-- api-design/                  # REST API 设计、分页与错误响应（新增）
+|   |-- deployment-patterns/         # CI/CD、Docker、健康检查与回滚（新增）
+|   |-- docker-patterns/            # Docker Compose、网络、卷与容器安全（新增）
+|   |-- e2e-testing/                 # Playwright 端到端模式与页面对象模型（新增）
+|   |-- content-hash-cache-pattern/  # 基于 SHA-256 内容哈希的文件处理缓存（新增）
+|   |-- cost-aware-llm-pipeline/     # LLM 成本优化、模型路由与预算跟踪（新增）
+|   |-- regex-vs-llm-structured-text/ # 决策框架：文本解析使用正则还是 LLM（新增）
+|   |-- swift-actor-persistence/     # 使用 Actor 实现线程安全的 Swift 数据持久化（新增）
+|   |-- swift-protocol-di-testing/   # 基于协议的依赖注入，实现可测试的 Swift 代码（新增）
+|   |-- search-first/               # 先研究后编码的工作流（新增）
+|   |-- skill-stocktake/            # 技能与命令质量审计（新增）
+|   |-- liquid-glass-design/         # iOS 26 Liquid Glass 设计系统（新增）
+|   |-- foundation-models-on-device/ # Apple 设备端 LLM 与 FoundationModels（新增）
+|   |-- swift-concurrency-6-2/       # Swift 6.2 易用并发（新增）
 |
-|-- commands/         # 快捷执行的 Slash 命令
+|-- commands/         # 快速执行的斜杠命令
 |   |-- tdd.md              # /tdd - 测试驱动开发
 |   |-- plan.md             # /plan - 实现规划
 |   |-- e2e.md              # /e2e - 端到端测试生成
 |   |-- code-review.md      # /code-review - 质量审查
 |   |-- build-fix.md        # /build-fix - 修复构建错误
-|   |-- refactor-clean.md   # /refactor-clean - 清理无用代码
-|   |-- learn.md            # /learn - 会话中提取模式（长文档指南）
-|   |-- checkpoint.md       # /checkpoint - 保存验证状态（长文档指南）
-|   |-- verify.md           # /verify - 运行验证循环（长文档指南）
+|   |-- refactor-clean.md   # /refactor-clean - 无用代码清理
+|   |-- learn.md            # /learn - 会话中提取模式（长文指南）
+|   |-- learn-eval.md       # /learn-eval - 提取、评估并保存模式（新增）
+|   |-- checkpoint.md       # /checkpoint - 保存验证状态（长文指南）
+|   |-- verify.md           # /verify - 执行验证循环（长文指南）
 |   |-- setup-pm.md         # /setup-pm - 配置包管理器
 |   |-- go-review.md        # /go-review - Go 代码审查（新增）
-|   |-- go-test.md          # /go-test - Go 的 TDD 工作流（新增）
+|   |-- go-test.md          # /go-test - Go TDD 工作流（新增）
 |   |-- go-build.md         # /go-build - 修复 Go 构建错误（新增）
-|   |-- skill-create.md     # /skill-create - 从 Git 历史生成技能（新增）
+|   |-- skill-create.md     # /skill-create - 从 git 历史生成技能（新增）
 |   |-- instinct-status.md  # /instinct-status - 查看已学习的直觉（新增）
 |   |-- instinct-import.md  # /instinct-import - 导入直觉（新增）
 |   |-- instinct-export.md  # /instinct-export - 导出直觉（新增）
@@ -257,26 +308,34 @@ everything-claude-code/
 |   |-- multi-backend.md    # /multi-backend - 后端多服务编排（新增）
 |   |-- multi-frontend.md   # /multi-frontend - 前端多服务编排（新增）
 |   |-- multi-workflow.md   # /multi-workflow - 通用多服务工作流（新增）
+|   |-- orchestrate.md      # /orchestrate - 多代理协调
+|   |-- sessions.md         # /sessions - 会话历史管理
+|   |-- eval.md             # /eval - 按标准评估
+|   |-- test-coverage.md    # /test-coverage - 测试覆盖率分析
+|   |-- update-docs.md      # /update-docs - 更新文档
+|   |-- update-codemaps.md  # /update-codemaps - 更新代码映射
+|   |-- python-review.md    # /python-review - Python 代码审查（新增）
 |
 |-- rules/            # 必须遵循的规则（复制到 ~/.claude/rules/）
-|   |-- README.md            # 结构概览与安装指南
-|   |-- common/              # 与语言无关的通用原则
+|   |-- README.md            # 结构说明与安装指南
+|   |-- common/              # 与语言无关的原则
 |   |   |-- coding-style.md    # 不可变性与文件组织
 |   |   |-- git-workflow.md    # 提交格式与 PR 流程
-|   |   |-- testing.md         # TDD，80% 覆盖率要求
+|   |   |-- testing.md         # TDD 与 80% 覆盖率要求
 |   |   |-- performance.md     # 模型选择与上下文管理
-|   |   |-- patterns.md        # 设计模式与项目骨架
+|   |   |-- patterns.md        # 设计模式与骨架项目
 |   |   |-- hooks.md           # Hook 架构与 TodoWrite
 |   |   |-- agents.md          # 何时委派给子代理
 |   |   |-- security.md        # 强制安全检查
-|   |-- typescript/          # TypeScript / JavaScript 专用
+|   |-- typescript/          # TypeScript/JavaScript 专用
 |   |-- python/              # Python 专用
 |   |-- golang/              # Go 专用
 |
 |-- hooks/            # 基于触发器的自动化
+|   |-- README.md                 # Hook 文档、示例与自定义指南
 |   |-- hooks.json                # 所有 Hook 配置（PreToolUse、PostToolUse、Stop 等）
-|   |-- memory-persistence/       # 会话生命周期 Hook（长文档指南）
-|   |-- strategic-compact/        # 压缩建议（长文档指南）
+|   |-- memory-persistence/       # 会话生命周期 Hook（长文指南）
+|   |-- strategic-compact/        # 压缩建议（长文指南）
 |
 |-- scripts/          # 跨平台 Node.js 脚本（新增）
 |   |-- lib/                     # 共享工具
@@ -286,7 +345,7 @@ everything-claude-code/
 |   |   |-- session-start.js     # 会话开始时加载上下文
 |   |   |-- session-end.js       # 会话结束时保存状态
 |   |   |-- pre-compact.js       # 压缩前状态保存
-|   |   |-- suggest-compact.js   # 战略性压缩建议
+|   |   |-- suggest-compact.js   # 战略压缩建议
 |   |   |-- evaluate-session.js  # 从会话中提取模式
 |   |-- setup-package-manager.js # 交互式包管理器设置
 |
@@ -295,19 +354,23 @@ everything-claude-code/
 |   |-- hooks/                   # Hook 测试
 |   |-- run-all.js               # 运行所有测试
 |
-|-- contexts/         # 动态系统提示注入上下文（长文档指南）
+|-- contexts/         # 动态系统提示注入上下文（长文指南）
 |   |-- dev.md              # 开发模式上下文
 |   |-- review.md           # 代码审查模式上下文
 |   |-- research.md         # 研究/探索模式上下文
 |
 |-- examples/         # 示例配置与会话
-|   |-- CLAUDE.md           # 项目级配置示例
-|   |-- user-CLAUDE.md      # 用户级配置示例
+|   |-- CLAUDE.md             # 项目级配置示例
+|   |-- user-CLAUDE.md        # 用户级配置示例
+|   |-- saas-nextjs-CLAUDE.md   # 实际 SaaS 示例（Next.js + Supabase + Stripe）
+|   |-- go-microservice-CLAUDE.md # 实际 Go 微服务示例（gRPC + PostgreSQL）
+|   |-- django-api-CLAUDE.md      # 实际 Django REST API 示例（DRF + Celery）
+|   |-- rust-api-CLAUDE.md        # 实际 Rust API 示例（Axum + SQLx + PostgreSQL）（新增）
 |
 |-- mcp-configs/      # MCP 服务器配置
 |   |-- mcp-servers.json    # GitHub、Supabase、Vercel、Railway 等
 |
-|-- marketplace.json  # 自托管插件市场配置（用于 /plugin marketplace add）
+|-- marketplace.json  # 自托管市场配置（用于 /plugin marketplace add）
 ```
 
 ***
@@ -350,6 +413,8 @@ everything-claude-code/
 
 ### AgentShield — 安全审计器
 
+> 在 Claude Code 黑客马拉松（Cerebral Valley x Anthropic，2026年2月）上构建。1282 项测试，98% 覆盖率，102 条静态分析规则。
+
 扫描您的 Claude Code 配置，查找漏洞、错误配置和注入风险。
 
 ```bash
@@ -359,14 +424,18 @@ npx ecc-agentshield scan
 # Auto-fix safe issues
 npx ecc-agentshield scan --fix
 
-# Deep analysis with Opus 4.6
+# Deep analysis with three Opus 4.6 agents
 npx ecc-agentshield scan --opus --stream
 
 # Generate secure config from scratch
 npx ecc-agentshield init
 ```
 
-检查 CLAUDE.md、settings.json、MCP 服务器、钩子和智能体定义。生成带有可操作发现的安全等级 (A-F)。
+**它扫描什么：** CLAUDE.md、settings.json、MCP 配置、钩子、代理定义以及 5 个类别的技能 —— 密钥检测（14 种模式）、权限审计、钩子注入分析、MCP 服务器风险剖析和代理配置审查。
+
+**`--opus` 标志** 在红队/蓝队/审计员管道中运行三个 Claude Opus 4.6 代理。攻击者寻找利用链，防御者评估保护措施，审计员将两者综合成优先风险评估。对抗性推理，而不仅仅是模式匹配。
+
+**输出格式：** 终端（按颜色分级的 A-F）、JSON（CI 管道）、Markdown、HTML。在关键发现时退出代码 2，用于构建门控。
 
 在 Claude Code 中使用 `/security-scan` 来运行它，或者通过 [GitHub Action](https://github.com/affaan-m/agentshield) 添加到 CI。
 
@@ -449,23 +518,23 @@ Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded fil
 
 这将使您能够立即访问所有命令、代理、技能和钩子。
 
-> **注意：** Claude Code 插件系统不支持通过插件分发 `rules`（[上游限制](https://code.claude.com/docs/en/plugins-reference)）。您需要手动安装规则：
+> **注意：** Claude Code 插件系统不支持通过插件分发 `rules`（[上游限制](https://code.claude.com/docs/en/plugins-reference)）。你需要手动安装规则：
 >
 > ```bash
 > # 首先克隆仓库
 > git clone https://github.com/affaan-m/everything-claude-code.git
 >
-> # 选项 A：用户级规则（适用于所有项目）
+> # 选项 A：用户级规则（应用于所有项目）
 > mkdir -p ~/.claude/rules
 > cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # 选择您的技术栈
+> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/   # 选择你的技术栈
 > cp -r everything-claude-code/rules/python/* ~/.claude/rules/
 > cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
 >
-> # 选项 B：项目级规则（仅适用于当前项目）
+> # 选项 B：项目级规则（仅应用于当前项目）
 > mkdir -p .claude/rules
 > cp -r everything-claude-code/rules/common/* .claude/rules/
-> cp -r everything-claude-code/rules/typescript/* .claude/rules/     # 选择您的技术栈
+> cp -r everything-claude-code/rules/typescript/* .claude/rules/     # 选择你的技术栈
 > ```
 
 ***
@@ -564,7 +633,136 @@ rules/
   golang/          # Go specific patterns and tools
 ```
 
-有关安装和结构详情，请参阅 [`rules/README.md`](rules/README.md)。
+有关安装和结构详情，请参阅 [`rules/README.md`](../../rules/README.md)。
+
+***
+
+## 🗺️ 我应该使用哪个代理？
+
+不确定从哪里开始？使用这个快速参考：
+
+| 我想要... | 使用此命令 | 使用的代理 |
+|--------------|-----------------|------------|
+| 规划新功能 | `/everything-claude-code:plan "Add auth"` | planner |
+| 设计系统架构 | `/everything-claude-code:plan` + architect agent | architect |
+| 先写带测试的代码 | `/tdd` | tdd-guide |
+| 审查我刚写的代码 | `/code-review` | code-reviewer |
+| 修复失败的构建 | `/build-fix` | build-error-resolver |
+| 运行端到端测试 | `/e2e` | e2e-runner |
+| 查找安全漏洞 | `/security-scan` | security-reviewer |
+| 移除死代码 | `/refactor-clean` | refactor-cleaner |
+| 更新文档 | `/update-docs` | doc-updater |
+| 审查 Go 代码 | `/go-review` | go-reviewer |
+| 审查 Python 代码 | `/python-review` | python-reviewer |
+| 审计数据库查询 | *(自动委派)* | database-reviewer |
+
+### 常见工作流
+
+**开始新功能：**
+
+```
+/everything-claude-code:plan "Add user authentication with OAuth"
+                                              → planner creates implementation blueprint
+/tdd                                          → tdd-guide enforces write-tests-first
+/code-review                                  → code-reviewer checks your work
+```
+
+**修复错误：**
+
+```
+/tdd                                          → tdd-guide: write a failing test that reproduces it
+                                              → implement the fix, verify test passes
+/code-review                                  → code-reviewer: catch regressions
+```
+
+**准备生产环境：**
+
+```
+/security-scan                                → security-reviewer: OWASP Top 10 audit
+/e2e                                          → e2e-runner: critical user flow tests
+/test-coverage                                → verify 80%+ coverage
+```
+
+***
+
+## ❓ 常见问题
+
+<details>
+<summary><b>How do I check which agents/commands are installed?</b></summary>
+
+```bash
+/plugin list everything-claude-code@everything-claude-code
+```
+
+这会显示插件中所有可用的代理、命令和技能。
+
+</details>
+
+<details>
+<summary><b>My hooks aren't working / I see "Duplicate hooks file" errors</b></summary>
+
+这是最常见的问题。**不要在 `.claude-plugin/plugin.json` 中添加 `"hooks"` 字段。** Claude Code v2.1+ 会自动从已安装的插件加载 `hooks/hooks.json`。显式声明它会导致重复检测错误。参见 [#29](https://github.com/affaan-m/everything-claude-code/issues/29), [#52](https://github.com/affaan-m/everything-claude-code/issues/52), [#103](https://github.com/affaan-m/everything-claude-code/issues/103)。
+
+</details>
+
+<details>
+<summary><b>My context window is shrinking / Claude is running out of context</b></summary>
+
+太多的 MCP 服务器会消耗你的上下文。每个 MCP 工具描述都会消耗你 200k 窗口的令牌，可能将其减少到约 70k。
+
+**修复：** 按项目禁用未使用的 MCP：
+
+```json
+// In your project's .claude/settings.json
+{
+  "disabledMcpServers": ["supabase", "railway", "vercel"]
+}
+```
+
+保持启用的 MCP 少于 10 个，活动工具少于 80 个。
+
+</details>
+
+<details>
+<summary><b>Can I use only some components (e.g., just agents)?</b></summary>
+
+是的。使用选项 2（手动安装）并仅复制你需要的部分：
+
+```bash
+# Just agents
+cp everything-claude-code/agents/*.md ~/.claude/agents/
+
+# Just rules
+cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+```
+
+每个组件都是完全独立的。
+
+</details>
+
+<details>
+<summary><b>Does this work with Cursor / OpenCode / Codex?</b></summary>
+
+是的。ECC 是跨平台的：
+
+* **Cursor**：`.cursor/` 中的预翻译配置。参见 [Cursor IDE 支持](#cursor-ide-支持)。
+* **OpenCode**：`.opencode/` 中的完整插件支持。参见 [OpenCode 支持](#-opencode-支持)。
+* **Codex**：提供适配器漂移保护和 SessionStart 回退的一流支持。参见 PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257)。
+* **Claude Code**：原生支持 — 这是主要目标。
+
+</details>
+
+<details>
+<summary><b>How do I contribute a new skill or agent?</b></summary>
+
+参见 [CONTRIBUTING.md](CONTRIBUTING.md)。简短版本：
+
+1. Fork 仓库
+2. 在 `skills/your-skill-name/SKILL.md` 中创建你的技能（带有 YAML 前言）
+3. 或在 `agents/your-agent.md` 中创建代理
+4. 提交 PR，清晰描述其功能和使用时机
+
+</details>
 
 ***
 
@@ -609,31 +807,109 @@ node tests/hooks/hooks.test.js
 
 ## Cursor IDE 支持
 
-ecc-universal 包含为 [Cursor IDE](https://cursor.com) 预翻译的配置。`.cursor/` 目录包含适用于 Cursor 格式的规则、智能体、技能、命令和 MCP 配置。
+ECC 提供**完整的 Cursor IDE 支持**，包括为 Cursor 原生格式适配的钩子、规则、代理、技能、命令和 MCP 配置。
 
 ### 快速开始 (Cursor)
 
 ```bash
-# Install the package
-npm install ecc-universal
-
 # Install for your language(s)
 ./install.sh --target cursor typescript
-./install.sh --target cursor python golang
+./install.sh --target cursor python golang swift
 ```
 
-### 已翻译内容
+### 包含内容
 
-| 组件 | Claude Code → Cursor | 对等性 |
-|-----------|---------------------|--------|
-| 规则 | 添加了 YAML frontmatter，路径扁平化 | 完全 |
-| 智能体 | 模型 ID 已扩展，工具 → 只读标志 | 完全 |
-| 技能 | 无需更改 (标准相同) | 相同 |
-| 命令 | 路径引用已更新，多-\* 已存根 | 部分 |
-| MCP 配置 | 环境变量插值语法已更新 | 完全 |
-| 钩子 | Cursor 中无等效项 | 参见替代方案 |
+| 组件 | 数量 | 详情 |
+|-----------|-------|---------|
+| 钩子事件 | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, 以及另外 10 个 |
+| 钩子脚本 | 16 | 通过共享适配器委托给 `scripts/hooks/` 的轻量 Node.js 脚本 |
+| 规则 | 29 | 9 条通用规则 (alwaysApply) + 20 条语言特定规则 (TypeScript, Python, Go, Swift) |
+| 代理 | 共享 | 通过根目录下的 AGENTS.md（被 Cursor 原生读取） |
+| 技能 | 共享 + 捆绑 | 通过根目录下的 AGENTS.md 和用于翻译补充的 `.cursor/skills/` |
+| 命令 | 共享 | `.cursor/commands/`（如果已安装） |
+| MCP 配置 | 共享 | `.cursor/mcp.json`（如果已安装） |
 
-详情请参阅 [.cursor/README.md](.cursor/README.md)，完整迁移指南请参阅 [.cursor/MIGRATION.md](.cursor/MIGRATION.md)。
+### 钩子架构（DRY 适配器模式）
+
+Cursor 的**钩子事件比 Claude Code 多**（20 对 8）。`.cursor/hooks/adapter.js` 模块将 Cursor 的 stdin JSON 转换为 Claude Code 的格式，允许重用现有的 `scripts/hooks/*.js` 而无需重复。
+
+```
+Cursor stdin JSON → adapter.js → transforms → scripts/hooks/*.js
+                                              (shared with Claude Code)
+```
+
+关键钩子：
+
+* **beforeShellExecution** — 阻止在 tmux 外启动开发服务器（退出码 2），git push 审查
+* **afterFileEdit** — 自动格式化 + TypeScript 检查 + console.log 警告
+* **beforeSubmitPrompt** — 检测提示中的密钥（sk-、ghp\_、AKIA 模式）
+* **beforeTabFileRead** — 阻止 Tab 读取 .env、.key、.pem 文件（退出码 2）
+* **beforeMCPExecution / afterMCPExecution** — MCP 审计日志记录
+
+### 规则格式
+
+Cursor 规则使用带有 `description`、`globs` 和 `alwaysApply` 的 YAML 前言：
+
+```yaml
+---
+description: "TypeScript coding style extending common rules"
+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
+alwaysApply: false
+---
+```
+
+***
+
+## Codex CLI 支持
+
+ECC 提供**一流的 Codex CLI 支持**，包含参考配置、Codex 特定的 AGENTS.md 补充和 16 个移植的技能。
+
+### 快速开始（Codex）
+
+```bash
+# Copy the reference config to your home directory
+cp .codex/config.toml ~/.codex/config.toml
+
+# Run Codex in the repo — AGENTS.md is auto-detected
+codex
+```
+
+### 包含内容
+
+| 组件 | 数量 | 详情 |
+|-----------|-------|---------|
+| 配置 | 1 | `.codex/config.toml` — 模型、权限、MCP 服务器、持久指令 |
+| AGENTS.md | 2 | 根目录（通用）+ `.codex/AGENTS.md`（Codex 特定补充） |
+| 技能 | 16 | `.agents/skills/` — 每个技能包含 SKILL.md + agents/openai.yaml |
+| MCP 服务器 | 4 | GitHub、Context7、Memory、Sequential Thinking（基于命令） |
+| 配置文件 | 2 | `strict`（只读沙箱）和 `yolo`（完全自动批准） |
+
+### 技能
+
+位于 `.agents/skills/` 的技能会被 Codex 自动加载：
+
+| 技能 | 描述 |
+|-------|-------------|
+| tdd-workflow | 测试驱动开发，覆盖率 80%+ |
+| security-review | 全面的安全检查清单 |
+| coding-standards | 通用编码标准 |
+| frontend-patterns | React/Next.js 模式 |
+| frontend-slides | HTML 演示文稿、PPTX 转换、视觉风格探索 |
+| article-writing | 根据笔记和语音参考进行长文写作 |
+| content-engine | 平台原生的社交内容和再利用 |
+| market-research | 带来源归属的市场和竞争对手研究 |
+| investor-materials | 幻灯片、备忘录、模型和一页纸文档 |
+| investor-outreach | 个性化外联、跟进和介绍摘要 |
+| backend-patterns | API 设计、数据库、缓存 |
+| e2e-testing | Playwright 端到端测试 |
+| eval-harness | 评估驱动的开发 |
+| strategic-compact | 上下文管理 |
+| api-design | REST API 设计模式 |
+| verification-loop | 构建、测试、代码检查、类型检查、安全 |
+
+### 关键限制
+
+Codex CLI **尚不支持钩子**（[GitHub Issue #2109](https://github.com/openai/codex/issues/2109)，430+ 点赞）。安全强制执行是通过 `persistent_instructions` 中的指令和沙箱权限系统实现的。
 
 ***
 
@@ -655,15 +931,15 @@ opencode
 
 ### 功能对等
 
-| 特性 | Claude Code | OpenCode | 状态 |
+| 功能 | Claude Code | OpenCode | 状态 |
 |---------|-------------|----------|--------|
-| 智能体 | ✅ 14 agents | ✅ 12 agents | **Claude Code 领先** |
-| 命令 | ✅ 30 commands | ✅ 24 commands | **Claude Code 领先** |
-| 技能 | ✅ 28 skills | ✅ 16 skills | **Claude Code 领先** |
-| 钩子 | ✅ 3 phases | ✅ 20+ events | **OpenCode 更多！** |
-| 规则 | ✅ 8 rules | ✅ 8 rules | **完全一致** |
-| MCP Servers | ✅ Full | ✅ Full | **完全一致** |
-| 自定义工具 | ✅ Via hooks | ✅ Native support | **OpenCode 更好** |
+| 代理 | ✅ 13 个代理 | ✅ 12 个代理 | **Claude Code 领先** |
+| 命令 | ✅ 33 个命令 | ✅ 24 个命令 | **Claude Code 领先** |
+| 技能 | ✅ 50+ 个技能 | ✅ 37 个技能 | **Claude Code 领先** |
+| 钩子 | ✅ 8 种事件类型 | ✅ 11 种事件 | **OpenCode 更多！** |
+| 规则 | ✅ 29 条规则 | ✅ 13 条指令 | **Claude Code 领先** |
+| MCP 服务器 | ✅ 14 个服务器 | ✅ 完整支持 | **完全对等** |
+| 自定义工具 | ✅ 通过钩子 | ✅ 6 个原生工具 | **OpenCode 更好** |
 
 ### 通过插件实现的钩子支持
 
@@ -679,14 +955,13 @@ OpenCode 的插件系统比 Claude Code 更复杂，有 20 多种事件类型：
 
 **额外的 OpenCode 事件**：`file.edited`、`file.watcher.updated`、`message.updated`、`lsp.client.diagnostics`、`tui.toast.show` 等等。
 
-### 可用命令 (24)
+### 可用命令（32个）
 
 | 命令 | 描述 |
 |---------|-------------|
 | `/plan` | 创建实施计划 |
 | `/tdd` | 强制执行 TDD 工作流 |
 | `/code-review` | 审查代码变更 |
-| `/security` | 运行安全审查 |
 | `/build-fix` | 修复构建错误 |
 | `/e2e` | 生成端到端测试 |
 | `/refactor-clean` | 移除死代码 |
@@ -701,11 +976,20 @@ OpenCode 的插件系统比 Claude Code 更复杂，有 20 多种事件类型：
 | `/go-review` | Go 代码审查 |
 | `/go-test` | Go TDD 工作流 |
 | `/go-build` | 修复 Go 构建错误 |
+| `/python-review` | Python 代码审查（PEP 8、类型提示、安全） |
+| `/multi-plan` | 多模型协作规划 |
+| `/multi-execute` | 多模型协作执行 |
+| `/multi-backend` | 后端聚焦的多模型工作流 |
+| `/multi-frontend` | 前端聚焦的多模型工作流 |
+| `/multi-workflow` | 完整的多模型开发工作流 |
+| `/pm2` | 自动生成 PM2 服务命令 |
+| `/sessions` | 管理会话历史 |
 | `/skill-create` | 从 git 生成技能 |
-| `/instinct-status` | 查看习得的本能 |
+| `/instinct-status` | 查看已学习的本能 |
 | `/instinct-import` | 导入本能 |
 | `/instinct-export` | 导出本能 |
 | `/evolve` | 将本能聚类为技能 |
+| `/learn-eval` | 在保存前提取和评估模式 |
 | `/setup-pm` | 配置包管理器 |
 
 ### 插件安装
@@ -740,6 +1024,35 @@ npm install ecc-universal
 
 ***
 
+## 跨工具功能对等
+
+ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以下是每个平台的比较：
+
+| 功能 | Claude Code | Cursor IDE | Codex CLI | OpenCode |
+|---------|------------|------------|-----------|----------|
+| **代理** | 13 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
+| **命令** | 33 | 共享 | 基于指令 | 24 |
+| **技能** | 50+ | 共享 | 10 (原生格式) | 37 |
+| **钩子事件** | 8 种类型 | 15 种类型 | 尚无 | 11 种类型 |
+| **钩子脚本** | 9 个脚本 | 16 个脚本 (DRY 适配器) | 不适用 | 插件钩子 |
+| **规则** | 29 (通用 + 语言) | 29 (YAML 前言) | 基于指令 | 13 条指令 |
+| **自定义工具** | 通过钩子 | 通过钩子 | 不适用 | 6 个原生工具 |
+| **MCP 服务器** | 14 | 共享 (mcp.json) | 4 (基于命令) | 完整 |
+| **配置格式** | settings.json | hooks.json + rules/ | config.toml | opencode.json |
+| **上下文文件** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md |
+| **密钥检测** | 基于钩子 | beforeSubmitPrompt 钩子 | 基于沙箱 | 基于钩子 |
+| **自动格式化** | PostToolUse 钩子 | afterFileEdit 钩子 | 不适用 | file.edited 钩子 |
+| **版本** | 插件 | 插件 | 参考配置 | 1.6.0 |
+
+**关键架构决策：**
+
+* 根目录下的 **AGENTS.md** 是通用的跨工具文件（被所有 4 个工具读取）
+* **DRY 适配器模式** 让 Cursor 可以重用 Claude Code 的钩子脚本而无需重复
+* **技能格式**（带有 YAML 前言的 SKILL.md）在 Claude Code、Codex 和 OpenCode 上都能工作
+* Codex 缺乏钩子的问题通过 `persistent_instructions` 和沙箱权限来弥补
+
+***
+
 ## 📖 背景
 
 我从实验性推出以来就一直在使用 Claude Code。在 2025 年 9 月，与 [@DRodriguezFX](https://x.com/DRodriguezFX) 一起使用 Claude Code 构建 [zenith.chat](https://zenith.chat)，赢得了 Anthropic x Forum Ventures 黑客马拉松。
@@ -748,19 +1061,96 @@ npm install ecc-universal
 
 ***
 
-## ⚠️ 重要说明
+## 令牌优化
+
+如果不管理令牌消耗，使用 Claude Code 可能会很昂贵。这些设置能在不牺牲质量的情况下显著降低成本。
+
+### 推荐设置
+
+添加到 `~/.claude/settings.json`：
+
+```json
+{
+  "model": "sonnet",
+  "env": {
+    "MAX_THINKING_TOKENS": "10000",
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
+  }
+}
+```
+
+| 设置 | 默认值 | 推荐值 | 影响 |
+|---------|---------|-------------|--------|
+| `model` | opus | **sonnet** | 约 60% 的成本降低；处理 80%+ 的编码任务 |
+| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | 每个请求的隐藏思考成本降低约 70% |
+| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | 更早压缩 —— 在长会话中质量更好 |
+
+仅在需要深度架构推理时切换到 Opus：
+
+```
+/model opus
+```
+
+### 日常工作流命令
+
+| 命令 | 何时使用 |
+|---------|-------------|
+| `/model sonnet` | 大多数任务的默认选择 |
+| `/model opus` | 复杂架构、调试、深度推理 |
+| `/clear` | 在不相关的任务之间（免费，即时重置） |
+| `/compact` | 在逻辑任务断点处（研究完成，里程碑达成） |
+| `/cost` | 在会话期间监控令牌花费 |
+
+### 策略性压缩
+
+`strategic-compact` 技能（包含在此插件中）建议在逻辑断点处进行 `/compact`，而不是依赖在 95% 上下文时的自动压缩。完整决策指南请参见 `skills/strategic-compact/SKILL.md`。
+
+**何时压缩：**
+
+* 研究/探索之后，实施之前
+* 完成一个里程碑之后，开始下一个之前
+* 调试之后，继续功能工作之前
+* 失败的方法之后，尝试新方法之前
+
+**何时不压缩：**
+
+* 实施过程中（你会丢失变量名、文件路径、部分状态）
 
 ### 上下文窗口管理
 
-**关键：** 不要一次性启用所有 MCP。启用过多工具后，你的 200k 上下文窗口可能会缩小到 70k。
+**关键：** 不要一次性启用所有 MCP。每个 MCP 工具描述都会消耗你 200k 窗口的令牌，可能将其减少到约 70k。
 
-经验法则：
+* 每个项目保持启用的 MCP 少于 10 个
+* 保持活动工具少于 80 个
+* 在项目配置中使用 `disabledMcpServers` 来禁用未使用的 MCP
 
-* 配置 20-30 个 MCP
-* 每个项目保持启用少于 10 个
-* 活动工具少于 80 个
+### 代理团队成本警告
 
-在项目配置中使用 `disabledMcpServers` 来禁用未使用的工具。
+代理团队会生成多个上下文窗口。每个团队成员独立消耗令牌。仅用于并行性能提供明显价值的任务（多模块工作、并行审查）。对于简单的顺序任务，子代理更节省令牌。
+
+***
+
+## ⚠️ 重要说明
+
+### 令牌优化
+
+达到每日限制？参见 **[令牌优化指南](../token-optimization.md)** 获取推荐设置和工作流提示。
+
+快速见效的方法：
+
+```json
+// ~/.claude/settings.json
+{
+  "model": "sonnet",
+  "env": {
+    "MAX_THINKING_TOKENS": "10000",
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
+    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
+  }
+}
+```
+
+在不相关的任务之间使用 `/clear`，在逻辑断点处使用 `/compact`，并使用 `/cost` 来监控花费。
 
 ### 定制化
 
@@ -773,6 +1163,14 @@ npm install ecc-universal
 
 ***
 
+## 💜 赞助商
+
+这个项目是免费和开源的。赞助商帮助保持其维护和发展。
+
+[**成为赞助商**](https://github.com/sponsors/affaan-m) | [赞助商等级](SPONSORS.md)
+
+***
+
 ## 🌟 Star 历史
 
 [![Star History Chart](https://api.star-history.com/svg?repos=affaan-m/everything-claude-code\&type=Date)](https://star-history.com/#affaan-m/everything-claude-code\&Date)
@@ -781,11 +1179,11 @@ npm install ecc-universal
 
 ## 🔗 链接
 
-* **速查指南 (从此开始):** [Claude Code 万事速查指南](https://x.com/affaanmustafa/status/2012378465664745795)
-* **详细指南 (进阶):** [Claude Code 万事详细指南](https://x.com/affaanmustafa/status/2014040193557471352)
-* **关注:** [@affaanmustafa](https://x.com/affaanmustafa)
-* **zenith.chat:** [zenith.chat](https://zenith.chat)
-* **技能目录:** awesome-agent-skills（社区维护的智能体技能目录）
+* **速查指南（从这里开始）：** [Claude Code 速查指南](https://x.com/affaanmustafa/status/2012378465664745795)
+* **详细指南（进阶）：** [Claude Code 详细指南](https://x.com/affaanmustafa/status/2014040193557471352)
+* **关注：** [@affaanmustafa](https://x.com/affaanmustafa)
+* **zenith.chat：** [zenith.chat](https://zenith.chat)
+* **技能目录：** awesome-agent-skills（社区维护的智能体技能目录）
 
 ***
 

docs/zh-CN/agents/build-error-resolver.md

@@ -1,556 +1,119 @@
 ---
 name: build-error-resolver
-description: 构建与TypeScript错误解决专家。在构建失败或类型错误发生时主动使用。仅通过最小差异修复构建/类型错误，不进行架构编辑。专注于快速使构建变绿。
+description: 构建和TypeScript错误解决专家。在构建失败或类型错误发生时主动使用。仅以最小差异修复构建/类型错误，不进行架构编辑。专注于快速使构建通过。
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
-model: opus
+model: sonnet
 ---
 
 # 构建错误解决器
 
-你是一位专注于快速高效修复 TypeScript、编译和构建错误的构建错误解决专家。你的任务是让构建通过，且改动最小，不进行架构修改。
+你是一名专业的构建错误解决专家。你的任务是以最小的改动让构建通过——不重构、不改变架构、不进行改进。
 
 ## 核心职责
 
-1. **TypeScript 错误解决** - 修复类型错误、推断问题、泛型约束
-2. **构建错误修复** - 解决编译失败、模块解析问题
-3. **依赖项问题** - 修复导入错误、缺失的包、版本冲突
-4. **配置错误** - 解决 tsconfig.json、webpack、Next.js 配置问题
-5. **最小化差异** - 做出尽可能小的更改来修复错误
-6. **无架构更改** - 只修复错误，不重构或重新设计
+1. **TypeScript 错误解决** — 修复类型错误、推断问题、泛型约束
+2. **构建错误修复** — 解决编译失败、模块解析问题
+3. **依赖问题** — 修复导入错误、缺失包、版本冲突
+4. **配置错误** — 解决 tsconfig、webpack、Next.js 配置问题
+5. **最小差异** — 做尽可能小的改动来修复错误
+6. **不改变架构** — 只修复错误，不重新设计
 
-## 可用的工具
-
-### 构建和类型检查工具
-
-* **tsc** - TypeScript 编译器，用于类型检查
-* **npm/yarn** - 包管理
-* **eslint** - 代码检查（可能导致构建失败）
-* **next build** - Next.js 生产构建
-
-### 诊断命令
+## 诊断命令
 
 ```bash
-# TypeScript type check (no emit)
-npx tsc --noEmit
-
-# TypeScript with pretty output
 npx tsc --noEmit --pretty
-
-# Show all errors (don't stop at first)
-npx tsc --noEmit --pretty --incremental false
-
-# Check specific file
-npx tsc --noEmit path/to/file.ts
-
-# ESLint check
-npx eslint . --ext .ts,.tsx,.js,.jsx
-
-# Next.js build (production)
+npx tsc --noEmit --pretty --incremental false   # Show all errors
 npm run build
-
-# Next.js build with debug
-npm run build -- --debug
+npx eslint . --ext .ts,.tsx,.js,.jsx
 ```
 
-## 错误解决工作流程
+## 工作流程
 
 ### 1. 收集所有错误
 
-```
-a) Run full type check
-   - npx tsc --noEmit --pretty
-   - Capture ALL errors, not just first
+* 运行 `npx tsc --noEmit --pretty` 获取所有类型错误
+* 分类：类型推断、缺失类型、导入、配置、依赖
+* 优先级：首先处理阻塞构建的错误，然后是类型错误，最后是警告
 
-b) Categorize errors by type
-   - Type inference failures
-   - Missing type definitions
-   - Import/export errors
-   - Configuration errors
-   - Dependency issues
+### 2. 修复策略（最小改动）
 
-c) Prioritize by impact
-   - Blocking build: Fix first
-   - Type errors: Fix in order
-   - Warnings: Fix if time permits
-```
+对于每个错误：
 
-### 2. 修复策略（最小化更改）
+1. 仔细阅读错误信息——理解预期与实际结果
+2. 找到最小的修复方案（类型注解、空值检查、导入修复）
+3. 验证修复不会破坏其他代码——重新运行 tsc
+4. 迭代直到构建通过
 
-```
-For each error:
+### 3. 常见修复
 
-1. Understand the error
-   - Read error message carefully
-   - Check file and line number
-   - Understand expected vs actual type
+| 错误 | 修复 |
+|-------|-----|
+| `implicitly has 'any' type` | 添加类型注解 |
+| `Object is possibly 'undefined'` | 可选链 `?.` 或空值检查 |
+| `Property does not exist` | 添加到接口或使用可选 `?` |
+| `Cannot find module` | 检查 tsconfig 路径、安装包或修复导入路径 |
+| `Type 'X' not assignable to 'Y'` | 解析/转换类型或修复类型 |
+| `Generic constraint` | 添加 `extends { ... }` |
+| `Hook called conditionally` | 将钩子移到顶层 |
+| `'await' outside async` | 添加 `async` 关键字 |
 
-2. Find minimal fix
-   - Add missing type annotation
-   - Fix import statement
-   - Add null check
-   - Use type assertion (last resort)
+## 做与不做
 
-3. Verify fix doesn't break other code
-   - Run tsc again after each fix
-   - Check related files
-   - Ensure no new errors introduced
+**做：**
 
-4. Iterate until build passes
-   - Fix one error at a time
-   - Recompile after each fix
-   - Track progress (X/Y errors fixed)
-```
+* 在缺失的地方添加类型注解
+* 在需要的地方添加空值检查
+* 修复导入/导出
+* 添加缺失的依赖项
+* 更新类型定义
+* 修复配置文件
 
-### 3. 常见错误模式及修复方法
+**不做：**
 
-**模式 1：类型推断失败**
+* 重构无关代码
+* 改变架构
+* 重命名变量（除非导致错误）
+* 添加新功能
+* 改变逻辑流程（除非为了修复错误）
+* 优化性能或样式
 
-```typescript
-// ❌ ERROR: Parameter 'x' implicitly has an 'any' type
-function add(x, y) {
-  return x + y
-}
+## 优先级等级
 
-// ✅ FIX: Add type annotations
-function add(x: number, y: number): number {
-  return x + y
-}
-```
+| 等级 | 症状 | 行动 |
+|-------|----------|--------|
+| 严重 | 构建完全中断，开发服务器无法启动 | 立即修复 |
+| 高 | 单个文件失败，新代码类型错误 | 尽快修复 |
+| 中 | 代码检查警告、已弃用的 API | 在可能时修复 |
 
-**模式 2：Null/Undefined 错误**
-
-```typescript
-// ❌ ERROR: Object is possibly 'undefined'
-const name = user.name.toUpperCase()
-
-// ✅ FIX: Optional chaining
-const name = user?.name?.toUpperCase()
-
-// ✅ OR: Null check
-const name = user && user.name ? user.name.toUpperCase() : ''
-```
-
-**模式 3：缺少属性**
-
-```typescript
-// ❌ ERROR: Property 'age' does not exist on type 'User'
-interface User {
-  name: string
-}
-const user: User = { name: 'John', age: 30 }
-
-// ✅ FIX: Add property to interface
-interface User {
-  name: string
-  age?: number // Optional if not always present
-}
-```
-
-**模式 4：导入错误**
-
-```typescript
-// ❌ ERROR: Cannot find module '@/lib/utils'
-import { formatDate } from '@/lib/utils'
-
-// ✅ FIX 1: Check tsconfig paths are correct
-{
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}
-
-// ✅ FIX 2: Use relative import
-import { formatDate } from '../lib/utils'
-
-// ✅ FIX 3: Install missing package
-npm install @/lib/utils
-```
-
-**模式 5：类型不匹配**
-
-```typescript
-// ❌ ERROR: Type 'string' is not assignable to type 'number'
-const age: number = "30"
-
-// ✅ FIX: Parse string to number
-const age: number = parseInt("30", 10)
-
-// ✅ OR: Change type
-const age: string = "30"
-```
-
-**模式 6：泛型约束**
-
-```typescript
-// ❌ ERROR: Type 'T' is not assignable to type 'string'
-function getLength<T>(item: T): number {
-  return item.length
-}
-
-// ✅ FIX: Add constraint
-function getLength<T extends { length: number }>(item: T): number {
-  return item.length
-}
-
-// ✅ OR: More specific constraint
-function getLength<T extends string | any[]>(item: T): number {
-  return item.length
-}
-```
-
-**模式 7：React Hook 错误**
-
-```typescript
-// ❌ ERROR: React Hook "useState" cannot be called in a function
-function MyComponent() {
-  if (condition) {
-    const [state, setState] = useState(0) // ERROR!
-  }
-}
-
-// ✅ FIX: Move hooks to top level
-function MyComponent() {
-  const [state, setState] = useState(0)
-
-  if (!condition) {
-    return null
-  }
-
-  // Use state here
-}
-```
-
-**模式 8：Async/Await 错误**
-
-```typescript
-// ❌ ERROR: 'await' expressions are only allowed within async functions
-function fetchData() {
-  const data = await fetch('/api/data')
-}
-
-// ✅ FIX: Add async keyword
-async function fetchData() {
-  const data = await fetch('/api/data')
-}
-```
-
-**模式 9：模块未找到**
-
-```typescript
-// ❌ ERROR: Cannot find module 'react' or its corresponding type declarations
-import React from 'react'
-
-// ✅ FIX: Install dependencies
-npm install react
-npm install --save-dev @types/react
-
-// ✅ CHECK: Verify package.json has dependency
-{
-  "dependencies": {
-    "react": "^19.0.0"
-  },
-  "devDependencies": {
-    "@types/react": "^19.0.0"
-  }
-}
-```
-
-**模式 10：Next.js 特定错误**
-
-```typescript
-// ❌ ERROR: Fast Refresh had to perform a full reload
-// Usually caused by exporting non-component
-
-// ✅ FIX: Separate exports
-// ❌ WRONG: file.tsx
-export const MyComponent = () => <div />
-export const someConstant = 42 // Causes full reload
-
-// ✅ CORRECT: component.tsx
-export const MyComponent = () => <div />
-
-// ✅ CORRECT: constants.ts
-export const someConstant = 42
-```
-
-## 项目特定的构建问题示例
-
-### Next.js 15 + React 19 兼容性
-
-```typescript
-// ❌ ERROR: React 19 type changes
-import { FC } from 'react'
-
-interface Props {
-  children: React.ReactNode
-}
-
-const Component: FC<Props> = ({ children }) => {
-  return <div>{children}</div>
-}
-
-// ✅ FIX: React 19 doesn't need FC
-interface Props {
-  children: React.ReactNode
-}
-
-const Component = ({ children }: Props) => {
-  return <div>{children}</div>
-}
-```
-
-### Supabase 客户端类型
-
-```typescript
-// ❌ ERROR: Type 'any' not assignable
-const { data } = await supabase
-  .from('markets')
-  .select('*')
-
-// ✅ FIX: Add type annotation
-interface Market {
-  id: string
-  name: string
-  slug: string
-  // ... other fields
-}
-
-const { data } = await supabase
-  .from('markets')
-  .select('*') as { data: Market[] | null, error: any }
-```
-
-### Redis Stack 类型
-
-```typescript
-// ❌ ERROR: Property 'ft' does not exist on type 'RedisClientType'
-const results = await client.ft.search('idx:markets', query)
-
-// ✅ FIX: Use proper Redis Stack types
-import { createClient } from 'redis'
-
-const client = createClient({
-  url: process.env.REDIS_URL
-})
-
-await client.connect()
-
-// Type is inferred correctly now
-const results = await client.ft.search('idx:markets', query)
-```
-
-### Solana Web3.js 类型
-
-```typescript
-// ❌ ERROR: Argument of type 'string' not assignable to 'PublicKey'
-const publicKey = wallet.address
-
-// ✅ FIX: Use PublicKey constructor
-import { PublicKey } from '@solana/web3.js'
-const publicKey = new PublicKey(wallet.address)
-```
-
-## 最小化差异策略
-
-**关键：做出尽可能小的更改**
-
-### 应该做：
-
-✅ 在缺少的地方添加类型注解
-✅ 在需要的地方添加空值检查
-✅ 修复导入/导出
-✅ 添加缺失的依赖项
-✅ 更新类型定义
-✅ 修复配置文件
-
-### 不应该做：
-
-❌ 重构无关的代码
-❌ 更改架构
-❌ 重命名变量/函数（除非导致错误）
-❌ 添加新功能
-❌ 更改逻辑流程（除非为了修复错误）
-❌ 优化性能
-❌ 改进代码风格
-
-**最小化差异示例：**
-
-```typescript
-// File has 200 lines, error on line 45
-
-// ❌ WRONG: Refactor entire file
-// - Rename variables
-// - Extract functions
-// - Change patterns
-// Result: 50 lines changed
-
-// ✅ CORRECT: Fix only the error
-// - Add type annotation on line 45
-// Result: 1 line changed
-
-function processData(data) { // Line 45 - ERROR: 'data' implicitly has 'any' type
-  return data.map(item => item.value)
-}
-
-// ✅ MINIMAL FIX:
-function processData(data: any[]) { // Only change this line
-  return data.map(item => item.value)
-}
-
-// ✅ BETTER MINIMAL FIX (if type known):
-function processData(data: Array<{ value: number }>) {
-  return data.map(item => item.value)
-}
-```
-
-## 构建错误报告格式
-
-```markdown
-# 构建错误解决报告
-
-**日期:** YYYY-MM-DD
-**构建目标:** Next.js 生产环境 / TypeScript 检查 / ESLint
-**初始错误数:** X
-**已修复错误数:** Y
-**构建状态:** ✅ 通过 / ❌ 失败
-
-## 已修复的错误
-
-### 1. [错误类别 - 例如：类型推断]
-**位置:** `src/components/MarketCard.tsx:45`
-**错误信息:**
-```
-
-参数 'market' 隐式具有 'any' 类型。
-
-````
-
-**Root Cause:** Missing type annotation for function parameter
-
-**Fix Applied:**
-```diff
-- function formatMarket(market) {
-+ function formatMarket(market: Market) {
-    return market.name
-  }
-````
-
-**更改的行数：** 1
-**影响：** 无 - 仅类型安全性改进
-
-***
-
-### 2. \[下一个错误类别]
-
-\[相同格式]
-
-***
-
-## 验证步骤
-
-1. ✅ TypeScript 检查通过：`npx tsc --noEmit`
-2. ✅ Next.js 构建成功：`npm run build`
-3. ✅ ESLint 检查通过：`npx eslint .`
-4. ✅ 没有引入新的错误
-5. ✅ 开发服务器运行：`npm run dev`
-
-## 总结
-
-* 已解决错误总数：X
-* 总更改行数：Y
-* 构建状态：✅ 通过
-* 修复时间：Z 分钟
-* 阻塞问题：剩余 0 个
-
-## 后续步骤
-
-* \[ ] 运行完整的测试套件
-* \[ ] 在生产构建中验证
-* \[ ] 部署到暂存环境进行 QA
-
-````
-
-## When to Use This Agent
-
-**USE when:**
-- `npm run build` fails
-- `npx tsc --noEmit` shows errors
-- Type errors blocking development
-- Import/module resolution errors
-- Configuration errors
-- Dependency version conflicts
-
-**DON'T USE when:**
-- Code needs refactoring (use refactor-cleaner)
-- Architectural changes needed (use architect)
-- New features required (use planner)
-- Tests failing (use tdd-guide)
-- Security issues found (use security-reviewer)
-
-## Build Error Priority Levels
-
-### 🔴 CRITICAL (Fix Immediately)
-- Build completely broken
-- No development server
-- Production deployment blocked
-- Multiple files failing
-
-### 🟡 HIGH (Fix Soon)
-- Single file failing
-- Type errors in new code
-- Import errors
-- Non-critical build warnings
-
-### 🟢 MEDIUM (Fix When Possible)
-- Linter warnings
-- Deprecated API usage
-- Non-strict type issues
-- Minor configuration warnings
-
-## Quick Reference Commands
+## 快速恢复
 
 ```bash
-# Check for errors
-npx tsc --noEmit
+# Nuclear option: clear all caches
+rm -rf .next node_modules/.cache && npm run build
 
-# Build Next.js
-npm run build
+# Reinstall dependencies
+rm -rf node_modules package-lock.json && npm install
 
-# Clear cache and rebuild
-rm -rf .next node_modules/.cache
-npm run build
-
-# Check specific file
-npx tsc --noEmit src/path/to/file.ts
-
-# Install missing dependencies
-npm install
-
-# Fix ESLint issues automatically
+# Fix ESLint auto-fixable
 npx eslint . --fix
-
-# Update TypeScript
-npm install --save-dev typescript@latest
-
-# Verify node_modules
-rm -rf node_modules package-lock.json
-npm install
-````
+```
 
 ## 成功指标
 
-构建错误解决后：
+* `npx tsc --noEmit` 以代码 0 退出
+* `npm run build` 成功完成
+* 没有引入新的错误
+* 更改的行数最少（< 受影响文件的 5%）
+* 测试仍然通过
 
-* ✅ `npx tsc --noEmit` 以代码 0 退出
-* ✅ `npm run build` 成功完成
-* ✅ 没有引入新的错误
-* ✅ 更改的行数最少（< 受影响文件的 5%）
-* ✅ 构建时间没有显著增加
-* ✅ 开发服务器运行无错误
-* ✅ 测试仍然通过
+## 何时不应使用
+
+* 代码需要重构 → 使用 `refactor-cleaner`
+* 需要架构变更 → 使用 `architect`
+* 需要新功能 → 使用 `planner`
+* 测试失败 → 使用 `tdd-guide`
+* 安全问题 → 使用 `security-reviewer`
 
 ***
 
-**记住**：目标是快速修复错误，且改动最小。不要重构，不要优化，不要重新设计。修复错误，验证构建通过，然后继续。速度和精确性胜过完美。
+**记住**：修复错误，验证构建通过，然后继续。速度和精确度胜过完美。

docs/zh-CN/agents/chief-of-staff.md

@@ -0,0 +1,155 @@
+---
+name: chief-of-staff
+description: 个人通讯首席参谋，负责筛选电子邮件、Slack、LINE和Messenger中的消息。将消息分为4个等级（跳过/仅信息/会议信息/需要行动），生成草稿回复，并通过钩子强制执行发送后的跟进。适用于管理多渠道通讯工作流程时。
+tools: ["Read", "Grep", "Glob", "Bash", "Edit", "Write"]
+model: opus
+---
+
+你是一位个人幕僚长，通过一个统一的分类处理管道管理所有通信渠道——电子邮件、Slack、LINE、Messenger 和日历。
+
+## 你的角色
+
+* 并行处理所有 5 个渠道的传入消息
+* 使用下面的 4 级系统对每条消息进行分类
+* 生成与用户语气和签名相匹配的回复草稿
+* 强制执行发送后的跟进（日历、待办事项、关系记录）
+* 根据日历数据计算日程安排可用性
+* 检测陈旧的待处理回复和逾期任务
+
+## 4 级分类系统
+
+每条消息都按优先级顺序被精确分类到以下一个级别：
+
+### 1. skip (自动归档)
+
+* 来自 `noreply`、`no-reply`、`notification`、`alert`
+* 来自 `@github.com`、`@slack.com`、`@jira`、`@notion.so`
+* 机器人消息、频道加入/离开、自动警报
+* 官方 LINE 账户、Messenger 页面通知
+
+### 2. info\_only (仅摘要)
+
+* 抄送邮件、收据、群聊闲聊
+* `@channel` / `@here` 公告
+* 没有提问的文件分享
+
+### 3. meeting\_info (日历交叉引用)
+
+* 包含 Zoom/Teams/Meet/WebEx 链接
+* 包含日期 + 会议上下文
+* 位置或房间分享、`.ics` 附件
+* **行动**：与日历交叉引用，自动填充缺失的链接
+
+### 4. action\_required (草稿回复)
+
+* 包含未答复问题的直接消息
+* 等待回复的 `@user` 提及
+* 日程安排请求、明确的询问
+* **行动**：使用 SOUL.md 的语气和关系上下文生成回复草稿
+
+## 分类处理流程
+
+### 步骤 1：并行获取
+
+同时获取所有渠道的消息：
+
+```bash
+# Email (via Gmail CLI)
+gog gmail search "is:unread -category:promotions -category:social" --max 20 --json
+
+# Calendar
+gog calendar events --today --all --max 30
+
+# LINE/Messenger via channel-specific scripts
+```
+
+```text
+# Slack (via MCP)
+conversations_search_messages(search_query: "YOUR_NAME", filter_date_during: "Today")
+channels_list(channel_types: "im,mpim") → conversations_history(limit: "4h")
+```
+
+### 步骤 2：分类
+
+对每条消息应用 4 级系统。优先级顺序：skip → info\_only → meeting\_info → action\_required。
+
+### 步骤 3：执行
+
+| 级别 | 行动 |
+|------|--------|
+| skip | 立即归档，仅显示数量 |
+| info\_only | 显示单行摘要 |
+| meeting\_info | 交叉引用日历，更新缺失信息 |
+| action\_required | 加载关系上下文，生成回复草稿 |
+
+### 步骤 4：草稿回复
+
+对于每条 action\_required 消息：
+
+1. 读取 `private/relationships.md` 以获取发件人上下文
+2. 读取 `SOUL.md` 以获取语气规则
+3. 检测日程安排关键词 → 通过 `calendar-suggest.js` 计算空闲时段
+4. 生成与关系语气（正式/随意/友好）相匹配的草稿
+5. 提供 `[Send] [Edit] [Skip]` 选项进行展示
+
+### 步骤 5：发送后跟进
+
+**每次发送后，在继续之前完成以下所有步骤：**
+
+1. **日历** — 为提议的日期创建 `[Tentative]` 事件，更新会议链接
+2. **关系** — 将互动记录追加到 `relationships.md` 中发件人的部分
+3. **待办事项** — 更新即将到来的事件表，标记已完成项目
+4. **待处理回复** — 设置跟进截止日期，移除已解决项目
+5. **归档** — 从收件箱中移除已处理的消息
+6. **分类文件** — 更新 LINE/Messenger 草稿状态
+7. **Git 提交与推送** — 对知识文件的所有更改进行版本控制
+
+此清单由 `PostToolUse` 钩子强制执行，该钩子会阻止完成，直到所有步骤都完成。该钩子拦截 `gmail send` / `conversations_add_message` 并将清单作为系统提醒注入。
+
+## 简报输出格式
+
+```
+# Today's Briefing — [Date]
+
+## Schedule (N)
+| Time | Event | Location | Prep? |
+|------|-------|----------|-------|
+
+## Email — Skipped (N) → auto-archived
+## Email — Action Required (N)
+### 1. Sender <email>
+**Subject**: ...
+**Summary**: ...
+**Draft reply**: ...
+→ [Send] [Edit] [Skip]
+
+## Slack — Action Required (N)
+## LINE — Action Required (N)
+
+## Triage Queue
+- Stale pending responses: N
+- Overdue tasks: N
+```
+
+## 关键设计原则
+
+* **可靠性优先选择钩子而非提示**：LLM 大约有 20% 的时间会忘记指令。`PostToolUse` 钩子在工具级别强制执行清单——LLM 在物理上无法跳过它们。
+* **确定性逻辑使用脚本**：日历计算、时区处理、空闲时段计算——使用 `calendar-suggest.js`，而不是 LLM。
+* **知识文件即记忆**：`relationships.md`、`preferences.md`、`todo.md` 通过 git 在无状态会话之间持久化。
+* **规则由系统注入**：`.claude/rules/*.md` 文件在每个会话中自动加载。与提示指令不同，LLM 无法选择忽略它们。
+
+## 调用示例
+
+```bash
+claude /mail                    # Email-only triage
+claude /slack                   # Slack-only triage
+claude /today                   # All channels + calendar + todo
+claude /schedule-reply "Reply to Sarah about the board meeting"
+```
+
+## 先决条件
+
+* [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+* Gmail CLI (例如 [gog](https://gog by @pterm))
+* Node.js 18+ (用于 calendar-suggest.js)
+* 可选：Slack MCP 服务器、Matrix 桥接 (LINE)、Chrome + Playwright (Messenger)

docs/zh-CN/agents/code-reviewer.md

@@ -1,109 +1,224 @@
 ---
 name: code-reviewer
-description: 专家代码审查专家。主动审查代码质量、安全性和可维护性。编写或修改代码后立即使用。所有代码变更必须使用。
+description: 专业代码审查专家。主动审查代码的质量、安全性和可维护性。在编写或修改代码后立即使用。所有代码变更必须使用。
 tools: ["Read", "Grep", "Glob", "Bash"]
-model: opus
+model: sonnet
 ---
 
 您是一位资深代码审查员，确保代码质量和安全的高标准。
 
+## 审查流程
+
 当被调用时：
 
-1. 运行 git diff 查看最近的更改
-2. 关注修改过的文件
-3. 立即开始审查
+1. **收集上下文** — 运行 `git diff --staged` 和 `git diff` 查看所有更改。如果没有差异，使用 `git log --oneline -5` 检查最近的提交。
+2. **理解范围** — 识别哪些文件发生了更改，这些更改与什么功能/修复相关，以及它们之间如何联系。
+3. **阅读周边代码** — 不要孤立地审查更改。阅读整个文件，理解导入、依赖项和调用位置。
+4. **应用审查清单** — 按顺序处理下面的每个类别，从 CRITICAL 到 LOW。
+5. **报告发现** — 使用下面的输出格式。只报告你确信的问题（>80% 确定是真实问题）。
 
-审查清单：
+## 基于置信度的筛选
 
-* 代码简洁且可读性强
-* 函数和变量命名良好
-* 没有重复代码
-* 适当的错误处理
-* 没有暴露的秘密或 API 密钥
-* 已实施输入验证
-* 良好的测试覆盖率
-* 已解决性能考虑
-* 已分析算法的时间复杂度
-* 已检查集成库的许可证
+**重要**：不要用噪音淹没审查。应用这些过滤器：
 
-按优先级提供反馈：
+* **报告** 如果你有 >80% 的把握认为这是一个真实问题
+* **跳过** 风格偏好，除非它们违反了项目约定
+* **跳过** 未更改代码中的问题，除非它们是 CRITICAL 安全漏洞
+* **合并** 类似问题（例如，“5 个函数缺少错误处理”，而不是 5 个独立的发现）
+* **优先处理** 可能导致错误、安全漏洞或数据丢失的问题
 
-* 关键问题（必须修复）
-* 警告（应该修复）
-* 建议（考虑改进）
+## 审查清单
 
-包括如何修复问题的具体示例。
+### 安全性 (CRITICAL)
 
-## 安全检查（关键）
+这些**必须**标记出来——它们可能造成实际损害：
 
-* 硬编码的凭据（API 密钥、密码、令牌）
-* SQL 注入风险（查询中的字符串拼接）
-* XSS 漏洞（未转义的用户输入）
-* 缺少输入验证
-* 不安全的依赖项（过时、易受攻击）
-* 路径遍历风险（用户控制的文件路径）
-* CSRF 漏洞
-* 身份验证绕过
+* **硬编码凭据** — 源代码中的 API 密钥、密码、令牌、连接字符串
+* **SQL 注入** — 查询中使用字符串拼接而非参数化查询
+* **XSS 漏洞** — 在 HTML/JSX 中渲染未转义的用户输入
+* **路径遍历** — 未经净化的用户控制文件路径
+* **CSRF 漏洞** — 更改状态的端点没有 CSRF 保护
+* **认证绕过** — 受保护路由缺少认证检查
+* **不安全的依赖项** — 已知存在漏洞的包
+* **日志中暴露的秘密** — 记录敏感数据（令牌、密码、PII）
 
-## 代码质量（高）
+```typescript
+// BAD: SQL injection via string concatenation
+const query = `SELECT * FROM users WHERE id = ${userId}`;
 
-* 大型函数（>50 行）
-* 大型文件（>800 行）
-* 深层嵌套（>4 级）
-* 缺少错误处理（try/catch）
-* console.log 语句
-* 可变模式
-* 新代码缺少测试
+// GOOD: Parameterized query
+const query = `SELECT * FROM users WHERE id = $1`;
+const result = await db.query(query, [userId]);
+```
 
-## 性能（中）
+```typescript
+// BAD: Rendering raw user HTML without sanitization
+// Always sanitize user content with DOMPurify.sanitize() or equivalent
 
-* 低效算法（在可能 O(n log n) 时使用 O(n²)）
-* React 中不必要的重新渲染
-* 缺少记忆化
-* 包体积过大
-* 未优化的图像
-* 缺少缓存
-* N+1 查询
+// GOOD: Use text content or sanitize
+<div>{userComment}</div>
+```
 
-## 最佳实践（中）
+### 代码质量 (HIGH)
 
-* 在代码/注释中使用表情符号
-* TODO/FIXME 没有关联工单
-* 公共 API 缺少 JSDoc
-* 可访问性问题（缺少 ARIA 标签，对比度差）
-* 变量命名不佳（x, tmp, data）
-* 没有解释的魔数
-* 格式不一致
+* **大型函数** (>50 行) — 拆分为更小、专注的函数
+* **大型文件** (>800 行) — 按职责提取模块
+* **深度嵌套** (>4 层) — 使用提前返回、提取辅助函数
+* **缺少错误处理** — 未处理的 Promise 拒绝、空的 catch 块
+* **变异模式** — 优先使用不可变操作（展开运算符、map、filter）
+* **console.log 语句** — 合并前移除调试日志
+* **缺少测试** — 没有测试覆盖的新代码路径
+* **死代码** — 注释掉的代码、未使用的导入、无法到达的分支
+
+```typescript
+// BAD: Deep nesting + mutation
+function processUsers(users) {
+  if (users) {
+    for (const user of users) {
+      if (user.active) {
+        if (user.email) {
+          user.verified = true;  // mutation!
+          results.push(user);
+        }
+      }
+    }
+  }
+  return results;
+}
+
+// GOOD: Early returns + immutability + flat
+function processUsers(users) {
+  if (!users) return [];
+  return users
+    .filter(user => user.active && user.email)
+    .map(user => ({ ...user, verified: true }));
+}
+```
+
+### React/Next.js 模式 (HIGH)
+
+审查 React/Next.js 代码时，还需检查：
+
+* **缺少依赖数组** — `useEffect`/`useMemo`/`useCallback` 依赖项不完整
+* **渲染中的状态更新** — 在渲染期间调用 setState 会导致无限循环
+* **列表中缺少 key** — 当项目可能重新排序时，使用数组索引作为 key
+* **属性透传** — 属性传递超过 3 层（应使用上下文或组合）
+* **不必要的重新渲染** — 昂贵的计算缺少记忆化
+* **客户端/服务器边界** — 在服务器组件中使用 `useState`/`useEffect`
+* **缺少加载/错误状态** — 数据获取没有备用 UI
+* **过时的闭包** — 事件处理程序捕获了过时的状态值
+
+```tsx
+// BAD: Missing dependency, stale closure
+useEffect(() => {
+  fetchData(userId);
+}, []); // userId missing from deps
+
+// GOOD: Complete dependencies
+useEffect(() => {
+  fetchData(userId);
+}, [userId]);
+```
+
+```tsx
+// BAD: Using index as key with reorderable list
+{items.map((item, i) => <ListItem key={i} item={item} />)}
+
+// GOOD: Stable unique key
+{items.map(item => <ListItem key={item.id} item={item} />)}
+```
+
+### Node.js/后端模式 (HIGH)
+
+审查后端代码时：
+
+* **未验证的输入** — 使用未经模式验证的请求体/参数
+* **缺少速率限制** — 公共端点没有限流
+* **无限制查询** — 面向用户的端点上使用 `SELECT *` 或没有 LIMIT 的查询
+* **N+1 查询** — 在循环中获取相关数据，而不是使用连接/批量查询
+* **缺少超时设置** — 外部 HTTP 调用没有配置超时
+* **错误信息泄露** — 向客户端发送内部错误详情
+* **缺少 CORS 配置** — API 可从非预期的来源访问
+
+```typescript
+// BAD: N+1 query pattern
+const users = await db.query('SELECT * FROM users');
+for (const user of users) {
+  user.posts = await db.query('SELECT * FROM posts WHERE user_id = $1', [user.id]);
+}
+
+// GOOD: Single query with JOIN or batch
+const usersWithPosts = await db.query(`
+  SELECT u.*, json_agg(p.*) as posts
+  FROM users u
+  LEFT JOIN posts p ON p.user_id = u.id
+  GROUP BY u.id
+`);
+```
+
+### 性能 (MEDIUM)
+
+* **低效算法** — 在可能使用 O(n log n) 或 O(n) 时使用了 O(n^2)
+* **不必要的重新渲染** — 缺少 React.memo、useMemo、useCallback
+* **打包体积过大** — 导入整个库，而存在可摇树优化的替代方案
+* **缺少缓存** — 重复的昂贵计算没有记忆化
+* **未优化的图片** — 大图片没有压缩或懒加载
+* **同步 I/O** — 在异步上下文中使用阻塞操作
+
+### 最佳实践 (LOW)
+
+* **没有关联工单的 TODO/FIXME** — TODO 应引用问题编号
+* **公共 API 缺少 JSDoc** — 导出的函数没有文档
+* **命名不佳** — 在非平凡上下文中使用单字母变量（x、tmp、data）
+* **魔法数字** — 未解释的数字常量
+* **格式不一致** — 混合使用分号、引号风格、缩进
 
 ## 审查输出格式
 
-对于每个问题：
+按严重程度组织发现的问题。对于每个问题：
 
 ```
-[CRITICAL] Hardcoded API key
+[CRITICAL] Hardcoded API key in source
 File: src/api/client.ts:42
-Issue: API key exposed in source code
-Fix: Move to environment variable
+Issue: API key "sk-abc..." exposed in source code. This will be committed to git history.
+Fix: Move to environment variable and add to .gitignore/.env.example
 
-const apiKey = "sk-abc123";  // ❌ Bad
-const apiKey = process.env.API_KEY;  // ✓ Good
+  const apiKey = "sk-abc123";           // BAD
+  const apiKey = process.env.API_KEY;   // GOOD
+```
+
+### 摘要格式
+
+每次审查结束时使用：
+
+```
+## Review Summary
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| CRITICAL | 0     | pass   |
+| HIGH     | 2     | warn   |
+| MEDIUM   | 3     | info   |
+| LOW      | 1     | note   |
+
+Verdict: WARNING — 2 HIGH issues should be resolved before merge.
 ```
 
 ## 批准标准
 
-* ✅ 批准：没有关键或高优先级问题
-* ⚠️ 警告：只有中优先级问题（可以谨慎合并）
-* ❌ 阻止：发现关键或高优先级问题
+* **批准**：没有 CRITICAL 或 HIGH 问题
+* **警告**：只有 HIGH 问题（可以谨慎合并）
+* **阻止**：发现 CRITICAL 问题 — 必须在合并前修复
 
-## 项目特定指南（示例）
+## 项目特定指南
 
-在此处添加您的项目特定检查项。例如：
+如果可用，还应检查来自 `CLAUDE.md` 或项目规则的项目特定约定：
 
-* 遵循 MANY SMALL FILES 原则（典型 200-400 行）
-* 代码库中不使用表情符号
-* 使用不可变模式（扩展运算符）
-* 验证数据库 RLS 策略
-* 检查 AI 集成错误处理
-* 验证缓存回退行为
+* 文件大小限制（例如，典型 200-400 行，最大 800 行）
+* Emoji 策略（许多项目禁止在代码中使用 emoji）
+* 不可变性要求（优先使用展开运算符而非变异）
+* 数据库策略（RLS、迁移模式）
+* 错误处理模式（自定义错误类、错误边界）
+* 状态管理约定（Zustand、Redux、Context）
 
-根据您的项目的 `CLAUDE.md` 或技能文件进行自定义。
+根据项目已建立的模式调整你的审查。如有疑问，与代码库的其余部分保持一致。

docs/zh-CN/agents/database-reviewer.md

@@ -1,662 +1,94 @@
 ---
 name: database-reviewer
-description: PostgreSQL数据库专家，专注于查询优化、架构设计、安全性和性能。在编写SQL、创建迁移、设计架构或排查数据库性能问题时，请主动使用。融合了Supabase最佳实践。
+description: PostgreSQL 数据库专家，专注于查询优化、模式设计、安全性和性能。在编写 SQL、创建迁移、设计模式或排查数据库性能问题时，请主动使用。融合了 Supabase 最佳实践。
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
-model: opus
+model: sonnet
 ---
 
 # 数据库审查员
 
-你是一位专注于查询优化、模式设计、安全和性能的 PostgreSQL 数据库专家。你的使命是确保数据库代码遵循最佳实践，防止性能问题并保持数据完整性。此代理融合了 [Supabase 的 postgres-best-practices](https://github.com/supabase/agent-skills) 中的模式。
+您是一位专注于查询优化、模式设计、安全性和性能的 PostgreSQL 数据库专家。您的任务是确保数据库代码遵循最佳实践、防止性能问题并保持数据完整性。融合了 [Supabase 的 postgres-best-practices](Supabase Agent Skills (credit: Supabase team)) 中的模式。
 
 ## 核心职责
 
-1. **查询性能** - 优化查询，添加适当的索引，防止表扫描
-2. **模式设计** - 设计具有适当数据类型和约束的高效模式
-3. **安全与 RLS** - 实现行级安全、最小权限访问
-4. **连接管理** - 配置连接池、超时、限制
-5. **并发性** - 防止死锁，优化锁定策略
-6. **监控** - 设置查询分析和性能跟踪
+1. **查询性能** — 优化查询，添加适当的索引，防止表扫描
+2. **模式设计** — 使用适当的数据类型和约束设计高效模式
+3. **安全性与 RLS** — 实现行级安全，最小权限访问
+4. **连接管理** — 配置连接池、超时、限制
+5. **并发性** — 防止死锁，优化锁定策略
+6. **监控** — 设置查询分析和性能跟踪
 
-## 可用的工具
-
-### 数据库分析命令
+## 诊断命令
 
 ```bash
-# Connect to database
 psql $DATABASE_URL
-
-# Check for slow queries (requires pg_stat_statements)
 psql -c "SELECT query, mean_exec_time, calls FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
-
-# Check table sizes
 psql -c "SELECT relname, pg_size_pretty(pg_total_relation_size(relid)) FROM pg_stat_user_tables ORDER BY pg_total_relation_size(relid) DESC;"
-
-# Check index usage
 psql -c "SELECT indexrelname, idx_scan, idx_tup_read FROM pg_stat_user_indexes ORDER BY idx_scan DESC;"
-
-# Find missing indexes on foreign keys
-psql -c "SELECT conrelid::regclass, a.attname FROM pg_constraint c JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey) WHERE c.contype = 'f' AND NOT EXISTS (SELECT 1 FROM pg_index i WHERE i.indrelid = c.conrelid AND a.attnum = ANY(i.indkey));"
-
-# Check for table bloat
-psql -c "SELECT relname, n_dead_tup, last_vacuum, last_autovacuum FROM pg_stat_user_tables WHERE n_dead_tup > 1000 ORDER BY n_dead_tup DESC;"
 ```
 
-## 数据库审查工作流
+## 审查工作流
 
-### 1. 查询性能审查（关键）
+### 1. 查询性能（关键）
 
-对于每个 SQL 查询，验证：
+* WHERE/JOIN 列是否已建立索引？
+* 在复杂查询上运行 `EXPLAIN ANALYZE` — 检查大表上的顺序扫描
+* 注意 N+1 查询模式
+* 验证复合索引列顺序（等值列在前，范围列在后）
 
-```
-a) Index Usage
-   - Are WHERE columns indexed?
-   - Are JOIN columns indexed?
-   - Is the index type appropriate (B-tree, GIN, BRIN)?
+### 2. 模式设计（高）
 
-b) Query Plan Analysis
-   - Run EXPLAIN ANALYZE on complex queries
-   - Check for Seq Scans on large tables
-   - Verify row estimates match actuals
+* 使用正确的类型：`bigint` 用于 ID，`text` 用于字符串，`timestamptz` 用于时间戳，`numeric` 用于货币，`boolean` 用于标志
+* 定义约束：主键，带有 `ON DELETE`、`NOT NULL`、`CHECK` 的外键
+* 使用 `lowercase_snake_case` 标识符（不使用引号包裹的大小写混合名称）
 
-c) Common Issues
-   - N+1 query patterns
-   - Missing composite indexes
-   - Wrong column order in indexes
-```
+### 3. 安全性（关键）
 
-### 2. 模式设计审查（高）
+* 在具有 `(SELECT auth.uid())` 模式的多租户表上启用 RLS
+* RLS 策略使用的列已建立索引
+* 最小权限访问 — 不要向应用程序用户授予 `GRANT ALL`
+* 撤销 public 模式的权限
 
-```
-a) Data Types
-   - bigint for IDs (not int)
-   - text for strings (not varchar(n) unless constraint needed)
-   - timestamptz for timestamps (not timestamp)
-   - numeric for money (not float)
-   - boolean for flags (not varchar)
+## 关键原则
 
-b) Constraints
-   - Primary keys defined
-   - Foreign keys with proper ON DELETE
-   - NOT NULL where appropriate
-   - CHECK constraints for validation
-
-c) Naming
-   - lowercase_snake_case (avoid quoted identifiers)
-   - Consistent naming patterns
-```
-
-### 3. 安全审查（关键）
-
-```
-a) Row Level Security
-   - RLS enabled on multi-tenant tables?
-   - Policies use (select auth.uid()) pattern?
-   - RLS columns indexed?
-
-b) Permissions
-   - Least privilege principle followed?
-   - No GRANT ALL to application users?
-   - Public schema permissions revoked?
-
-c) Data Protection
-   - Sensitive data encrypted?
-   - PII access logged?
-```
-
-***
-
-## 索引模式
-
-### 1. 在 WHERE 和 JOIN 列上添加索引
-
-**影响：** 在大表上查询速度提升 100-1000 倍
-
-```sql
--- ❌ BAD: No index on foreign key
-CREATE TABLE orders (
-  id bigint PRIMARY KEY,
-  customer_id bigint REFERENCES customers(id)
-  -- Missing index!
-);
-
--- ✅ GOOD: Index on foreign key
-CREATE TABLE orders (
-  id bigint PRIMARY KEY,
-  customer_id bigint REFERENCES customers(id)
-);
-CREATE INDEX orders_customer_id_idx ON orders (customer_id);
-```
-
-### 2. 选择正确的索引类型
-
-| 索引类型 | 使用场景 | 操作符 |
-|------------|----------|-----------|
-| **B-tree** (默认) | 等值、范围 | `=`, `<`, `>`, `BETWEEN`, `IN` |
-| **GIN** | 数组、JSONB、全文 | `@>`, `?`, `?&`, `?\|`, `@@` |
-| **BRIN** | 大型时间序列表 | 在排序数据上进行范围查询 |
-| **Hash** | 仅等值查询 | `=` (比 B-tree 略快) |
-
-```sql
--- ❌ BAD: B-tree for JSONB containment
-CREATE INDEX products_attrs_idx ON products (attributes);
-SELECT * FROM products WHERE attributes @> '{"color": "red"}';
-
--- ✅ GOOD: GIN for JSONB
-CREATE INDEX products_attrs_idx ON products USING gin (attributes);
-```
-
-### 3. 多列查询的复合索引
-
-**影响：** 多列查询速度提升 5-10 倍
-
-```sql
--- ❌ BAD: Separate indexes
-CREATE INDEX orders_status_idx ON orders (status);
-CREATE INDEX orders_created_idx ON orders (created_at);
-
--- ✅ GOOD: Composite index (equality columns first, then range)
-CREATE INDEX orders_status_created_idx ON orders (status, created_at);
-```
-
-**最左前缀规则：**
-
-* 索引 `(status, created_at)` 适用于：
-  * `WHERE status = 'pending'`
-  * `WHERE status = 'pending' AND created_at > '2024-01-01'`
-* **不**适用于：
-  * 单独的 `WHERE created_at > '2024-01-01'`
-
-### 4. 覆盖索引（仅索引扫描）
-
-**影响：** 通过避免表查找，查询速度提升 2-5 倍
-
-```sql
--- ❌ BAD: Must fetch name from table
-CREATE INDEX users_email_idx ON users (email);
-SELECT email, name FROM users WHERE email = 'user@example.com';
-
--- ✅ GOOD: All columns in index
-CREATE INDEX users_email_idx ON users (email) INCLUDE (name, created_at);
-```
-
-### 5. 用于筛选查询的部分索引
-
-**影响：** 索引大小减少 5-20 倍，写入和查询更快
-
-```sql
--- ❌ BAD: Full index includes deleted rows
-CREATE INDEX users_email_idx ON users (email);
-
--- ✅ GOOD: Partial index excludes deleted rows
-CREATE INDEX users_active_email_idx ON users (email) WHERE deleted_at IS NULL;
-```
-
-**常见模式：**
-
-* 软删除：`WHERE deleted_at IS NULL`
-* 状态筛选：`WHERE status = 'pending'`
-* 非空值：`WHERE sku IS NOT NULL`
-
-***
-
-## 模式设计模式
-
-### 1. 数据类型选择
-
-```sql
--- ❌ BAD: Poor type choices
-CREATE TABLE users (
-  id int,                           -- Overflows at 2.1B
-  email varchar(255),               -- Artificial limit
-  created_at timestamp,             -- No timezone
-  is_active varchar(5),             -- Should be boolean
-  balance float                     -- Precision loss
-);
-
--- ✅ GOOD: Proper types
-CREATE TABLE users (
-  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  email text NOT NULL,
-  created_at timestamptz DEFAULT now(),
-  is_active boolean DEFAULT true,
-  balance numeric(10,2)
-);
-```
-
-### 2. 主键策略
-
-```sql
--- ✅ Single database: IDENTITY (default, recommended)
-CREATE TABLE users (
-  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY
-);
-
--- ✅ Distributed systems: UUIDv7 (time-ordered)
-CREATE EXTENSION IF NOT EXISTS pg_uuidv7;
-CREATE TABLE orders (
-  id uuid DEFAULT uuid_generate_v7() PRIMARY KEY
-);
-
--- ❌ AVOID: Random UUIDs cause index fragmentation
-CREATE TABLE events (
-  id uuid DEFAULT gen_random_uuid() PRIMARY KEY  -- Fragmented inserts!
-);
-```
-
-### 3. 表分区
-
-**使用时机：** 表 > 1 亿行、时间序列数据、需要删除旧数据时
-
-```sql
--- ✅ GOOD: Partitioned by month
-CREATE TABLE events (
-  id bigint GENERATED ALWAYS AS IDENTITY,
-  created_at timestamptz NOT NULL,
-  data jsonb
-) PARTITION BY RANGE (created_at);
-
-CREATE TABLE events_2024_01 PARTITION OF events
-  FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
-
-CREATE TABLE events_2024_02 PARTITION OF events
-  FOR VALUES FROM ('2024-02-01') TO ('2024-03-01');
-
--- Drop old data instantly
-DROP TABLE events_2023_01;  -- Instant vs DELETE taking hours
-```
-
-### 4. 使用小写标识符
-
-```sql
--- ❌ BAD: Quoted mixed-case requires quotes everywhere
-CREATE TABLE "Users" ("userId" bigint, "firstName" text);
-SELECT "firstName" FROM "Users";  -- Must quote!
-
--- ✅ GOOD: Lowercase works without quotes
-CREATE TABLE users (user_id bigint, first_name text);
-SELECT first_name FROM users;
-```
-
-***
-
-## 安全与行级安全 (RLS)
-
-### 1. 为多租户数据启用 RLS
-
-**影响：** 关键 - 数据库强制执行的租户隔离
-
-```sql
--- ❌ BAD: Application-only filtering
-SELECT * FROM orders WHERE user_id = $current_user_id;
--- Bug means all orders exposed!
-
--- ✅ GOOD: Database-enforced RLS
-ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
-ALTER TABLE orders FORCE ROW LEVEL SECURITY;
-
-CREATE POLICY orders_user_policy ON orders
-  FOR ALL
-  USING (user_id = current_setting('app.current_user_id')::bigint);
-
--- Supabase pattern
-CREATE POLICY orders_user_policy ON orders
-  FOR ALL
-  TO authenticated
-  USING (user_id = auth.uid());
-```
-
-### 2. 优化 RLS 策略
-
-**影响：** RLS 查询速度提升 5-10 倍
-
-```sql
--- ❌ BAD: Function called per row
-CREATE POLICY orders_policy ON orders
-  USING (auth.uid() = user_id);  -- Called 1M times for 1M rows!
-
--- ✅ GOOD: Wrap in SELECT (cached, called once)
-CREATE POLICY orders_policy ON orders
-  USING ((SELECT auth.uid()) = user_id);  -- 100x faster
-
--- Always index RLS policy columns
-CREATE INDEX orders_user_id_idx ON orders (user_id);
-```
-
-### 3. 最小权限访问
-
-```sql
--- ❌ BAD: Overly permissive
-GRANT ALL PRIVILEGES ON ALL TABLES TO app_user;
-
--- ✅ GOOD: Minimal permissions
-CREATE ROLE app_readonly NOLOGIN;
-GRANT USAGE ON SCHEMA public TO app_readonly;
-GRANT SELECT ON public.products, public.categories TO app_readonly;
-
-CREATE ROLE app_writer NOLOGIN;
-GRANT USAGE ON SCHEMA public TO app_writer;
-GRANT SELECT, INSERT, UPDATE ON public.orders TO app_writer;
--- No DELETE permission
-
-REVOKE ALL ON SCHEMA public FROM public;
-```
-
-***
-
-## 连接管理
-
-### 1. 连接限制
-
-**公式：** `(RAM_in_MB / 5MB_per_connection) - reserved`
-
-```sql
--- 4GB RAM example
-ALTER SYSTEM SET max_connections = 100;
-ALTER SYSTEM SET work_mem = '8MB';  -- 8MB * 100 = 800MB max
-SELECT pg_reload_conf();
-
--- Monitor connections
-SELECT count(*), state FROM pg_stat_activity GROUP BY state;
-```
-
-### 2. 空闲超时
-
-```sql
-ALTER SYSTEM SET idle_in_transaction_session_timeout = '30s';
-ALTER SYSTEM SET idle_session_timeout = '10min';
-SELECT pg_reload_conf();
-```
-
-### 3. 使用连接池
-
-* **事务模式**：最适合大多数应用（每次事务后归还连接）
-* **会话模式**：用于预处理语句、临时表
-* **连接池大小**：`(CPU_cores * 2) + spindle_count`
-
-***
-
-## 并发与锁定
-
-### 1. 保持事务简短
-
-```sql
--- ❌ BAD: Lock held during external API call
-BEGIN;
-SELECT * FROM orders WHERE id = 1 FOR UPDATE;
--- HTTP call takes 5 seconds...
-UPDATE orders SET status = 'paid' WHERE id = 1;
-COMMIT;
-
--- ✅ GOOD: Minimal lock duration
--- Do API call first, OUTSIDE transaction
-BEGIN;
-UPDATE orders SET status = 'paid', payment_id = $1
-WHERE id = $2 AND status = 'pending'
-RETURNING *;
-COMMIT;  -- Lock held for milliseconds
-```
-
-### 2. 防止死锁
-
-```sql
--- ❌ BAD: Inconsistent lock order causes deadlock
--- Transaction A: locks row 1, then row 2
--- Transaction B: locks row 2, then row 1
--- DEADLOCK!
-
--- ✅ GOOD: Consistent lock order
-BEGIN;
-SELECT * FROM accounts WHERE id IN (1, 2) ORDER BY id FOR UPDATE;
--- Now both rows locked, update in any order
-UPDATE accounts SET balance = balance - 100 WHERE id = 1;
-UPDATE accounts SET balance = balance + 100 WHERE id = 2;
-COMMIT;
-```
-
-### 3. 对队列使用 SKIP LOCKED
-
-**影响：** 工作队列吞吐量提升 10 倍
-
-```sql
--- ❌ BAD: Workers wait for each other
-SELECT * FROM jobs WHERE status = 'pending' LIMIT 1 FOR UPDATE;
-
--- ✅ GOOD: Workers skip locked rows
-UPDATE jobs
-SET status = 'processing', worker_id = $1, started_at = now()
-WHERE id = (
-  SELECT id FROM jobs
-  WHERE status = 'pending'
-  ORDER BY created_at
-  LIMIT 1
-  FOR UPDATE SKIP LOCKED
-)
-RETURNING *;
-```
-
-***
-
-## 数据访问模式
-
-### 1. 批量插入
-
-**影响：** 批量插入速度提升 10-50 倍
-
-```sql
--- ❌ BAD: Individual inserts
-INSERT INTO events (user_id, action) VALUES (1, 'click');
-INSERT INTO events (user_id, action) VALUES (2, 'view');
--- 1000 round trips
-
--- ✅ GOOD: Batch insert
-INSERT INTO events (user_id, action) VALUES
-  (1, 'click'),
-  (2, 'view'),
-  (3, 'click');
--- 1 round trip
-
--- ✅ BEST: COPY for large datasets
-COPY events (user_id, action) FROM '/path/to/data.csv' WITH (FORMAT csv);
-```
-
-### 2. 消除 N+1 查询
-
-```sql
--- ❌ BAD: N+1 pattern
-SELECT id FROM users WHERE active = true;  -- Returns 100 IDs
--- Then 100 queries:
-SELECT * FROM orders WHERE user_id = 1;
-SELECT * FROM orders WHERE user_id = 2;
--- ... 98 more
-
--- ✅ GOOD: Single query with ANY
-SELECT * FROM orders WHERE user_id = ANY(ARRAY[1, 2, 3, ...]);
-
--- ✅ GOOD: JOIN
-SELECT u.id, u.name, o.*
-FROM users u
-LEFT JOIN orders o ON o.user_id = u.id
-WHERE u.active = true;
-```
-
-### 3. 基于游标的分页
-
-**影响：** 无论页面深度如何，都能保持 O(1) 的稳定性能
-
-```sql
--- ❌ BAD: OFFSET gets slower with depth
-SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 199980;
--- Scans 200,000 rows!
-
--- ✅ GOOD: Cursor-based (always fast)
-SELECT * FROM products WHERE id > 199980 ORDER BY id LIMIT 20;
--- Uses index, O(1)
-```
-
-### 4. 用于插入或更新的 UPSERT
-
-```sql
--- ❌ BAD: Race condition
-SELECT * FROM settings WHERE user_id = 123 AND key = 'theme';
--- Both threads find nothing, both insert, one fails
-
--- ✅ GOOD: Atomic UPSERT
-INSERT INTO settings (user_id, key, value)
-VALUES (123, 'theme', 'dark')
-ON CONFLICT (user_id, key)
-DO UPDATE SET value = EXCLUDED.value, updated_at = now()
-RETURNING *;
-```
-
-***
-
-## 监控与诊断
-
-### 1. 启用 pg\_stat\_statements
-
-```sql
-CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-
--- Find slowest queries
-SELECT calls, round(mean_exec_time::numeric, 2) as mean_ms, query
-FROM pg_stat_statements
-ORDER BY mean_exec_time DESC
-LIMIT 10;
-
--- Find most frequent queries
-SELECT calls, query
-FROM pg_stat_statements
-ORDER BY calls DESC
-LIMIT 10;
-```
-
-### 2. EXPLAIN ANALYZE
-
-```sql
-EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
-SELECT * FROM orders WHERE customer_id = 123;
-```
-
-| 指标 | 问题 | 解决方案 |
-|-----------|---------|----------|
-| 在大表上出现 `Seq Scan` | 缺少索引 | 在筛选列上添加索引 |
-| `Rows Removed by Filter` 过高 | 选择性差 | 检查 WHERE 子句 |
-| `Buffers: read >> hit` | 数据未缓存 | 增加 `shared_buffers` |
-| `Sort Method: external merge` | `work_mem` 过低 | 增加 `work_mem` |
-
-### 3. 维护统计信息
-
-```sql
--- Analyze specific table
-ANALYZE orders;
-
--- Check when last analyzed
-SELECT relname, last_analyze, last_autoanalyze
-FROM pg_stat_user_tables
-ORDER BY last_analyze NULLS FIRST;
-
--- Tune autovacuum for high-churn tables
-ALTER TABLE orders SET (
-  autovacuum_vacuum_scale_factor = 0.05,
-  autovacuum_analyze_scale_factor = 0.02
-);
-```
-
-***
-
-## JSONB 模式
-
-### 1. 索引 JSONB 列
-
-```sql
--- GIN index for containment operators
-CREATE INDEX products_attrs_gin ON products USING gin (attributes);
-SELECT * FROM products WHERE attributes @> '{"color": "red"}';
-
--- Expression index for specific keys
-CREATE INDEX products_brand_idx ON products ((attributes->>'brand'));
-SELECT * FROM products WHERE attributes->>'brand' = 'Nike';
-
--- jsonb_path_ops: 2-3x smaller, only supports @>
-CREATE INDEX idx ON products USING gin (attributes jsonb_path_ops);
-```
-
-### 2. 使用 tsvector 进行全文搜索
-
-```sql
--- Add generated tsvector column
-ALTER TABLE articles ADD COLUMN search_vector tsvector
-  GENERATED ALWAYS AS (
-    to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))
-  ) STORED;
-
-CREATE INDEX articles_search_idx ON articles USING gin (search_vector);
-
--- Fast full-text search
-SELECT * FROM articles
-WHERE search_vector @@ to_tsquery('english', 'postgresql & performance');
-
--- With ranking
-SELECT *, ts_rank(search_vector, query) as rank
-FROM articles, to_tsquery('english', 'postgresql') query
-WHERE search_vector @@ query
-ORDER BY rank DESC;
-```
-
-***
+* **索引外键** — 总是，没有例外
+* **使用部分索引** — `WHERE deleted_at IS NULL` 用于软删除
+* **覆盖索引** — `INCLUDE (col)` 以避免表查找
+* **队列使用 SKIP LOCKED** — 对于工作模式，吞吐量提升 10 倍
+* **游标分页** — `WHERE id > $last` 而不是 `OFFSET`
+* **批量插入** — 多行 `INSERT` 或 `COPY`，切勿在循环中进行单行插入
+* **短事务** — 在进行外部 API 调用期间绝不持有锁
+* **一致的锁顺序** — `ORDER BY id FOR UPDATE` 以防止死锁
 
 ## 需要标记的反模式
 
-### ❌ 查询反模式
-
-* 在生产代码中使用 `SELECT *`
-* WHERE/JOIN 列上缺少索引
-* 在大表上使用 OFFSET 分页
-* N+1 查询模式
-* 未参数化的查询（SQL 注入风险）
-
-### ❌ 模式反模式
-
-* 对 ID 使用 `int`（应使用 `bigint`）
-* 无理由使用 `varchar(255)`（应使用 `text`）
+* `SELECT *` 出现在生产代码中
+* `int` 用于 ID（应使用 `bigint`），无理由使用 `varchar(255)`（应使用 `text`）
 * 使用不带时区的 `timestamp`（应使用 `timestamptz`）
 * 使用随机 UUID 作为主键（应使用 UUIDv7 或 IDENTITY）
-* 需要引号的大小写混合标识符
-
-### ❌ 安全反模式
-
+* 在大表上使用 OFFSET 分页
+* 未参数化的查询（SQL 注入风险）
 * 向应用程序用户授予 `GRANT ALL`
-* 多租户表上缺少 RLS
-* RLS 策略每行调用函数（未包装在 SELECT 中）
-* 未索引的 RLS 策略列
-
-### ❌ 连接反模式
-
-* 没有连接池
-* 没有空闲超时
-* 在事务模式连接池中使用预处理语句
-* 在外部 API 调用期间持有锁
-
-***
+* RLS 策略每行调用函数（未包装在 `SELECT` 中）
 
 ## 审查清单
 
-### 批准数据库更改前：
-
-* \[ ] 所有 WHERE/JOIN 列都已建立索引
-* \[ ] 复合索引的列顺序正确
-* \[ ] 使用了适当的数据类型（bigint、text、timestamptz、numeric）
-* \[ ] 在多租户表上启用了 RLS
-* \[ ] RLS 策略使用了 `(SELECT auth.uid())` 模式
-* \[ ] 外键已建立索引
+* \[ ] 所有 WHERE/JOIN 列已建立索引
+* \[ ] 复合索引列顺序正确
+* \[ ] 使用正确的数据类型（bigint, text, timestamptz, numeric）
+* \[ ] 在多租户表上启用 RLS
+* \[ ] RLS 策略使用 `(SELECT auth.uid())` 模式
+* \[ ] 外键有索引
 * \[ ] 没有 N+1 查询模式
-* \[ ] 对复杂查询运行了 EXPLAIN ANALYZE
-* \[ ] 使用了小写标识符
+* \[ ] 在复杂查询上运行了 EXPLAIN ANALYZE
 * \[ ] 事务保持简短
 
+## 参考
+
+有关详细的索引模式、模式设计示例、连接管理、并发策略、JSONB 模式和全文搜索，请参阅技能：`postgres-patterns` 和 `database-migrations`。
+
 ***
 
 **请记住**：数据库问题通常是应用程序性能问题的根本原因。尽早优化查询和模式设计。使用 EXPLAIN ANALYZE 来验证假设。始终对外键和 RLS 策略列建立索引。
 
-*模式改编自 [Supabase Agent Skills](https://github.com/supabase/agent-skills)，遵循 MIT 许可证。*
+*模式改编自 [Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team))，遵循 MIT 许可证。*

docs/zh-CN/agents/doc-updater.md

@@ -2,7 +2,7 @@
 name: doc-updater
 description: 文档和代码映射专家。主动用于更新代码映射和文档。运行 /update-codemaps 和 /update-docs，生成 docs/CODEMAPS/*，更新 README 和指南。
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
-model: opus
+model: haiku
 ---
 
 # 文档与代码映射专家
@@ -11,67 +11,45 @@ model: opus
 
 ## 核心职责
 
-1. **代码映射生成** - 根据代码库结构创建架构图
-2. **文档更新** - 根据代码刷新 README 和指南
-3. **AST 分析** - 使用 TypeScript 编译器 API 来理解结构
-4. **依赖映射** - 跟踪模块间的导入/导出关系
-5. **文档质量** - 确保文档与现实匹配
+1. **代码地图生成** — 从代码库结构创建架构地图
+2. **文档更新** — 根据代码刷新 README 和指南
+3. **AST 分析** — 使用 TypeScript 编译器 API 来理解结构
+4. **依赖映射** — 跟踪模块间的导入/导出
+5. **文档质量** — 确保文档与现实匹配
 
-## 可用的工具
-
-### 分析工具
-
-* **ts-morph** - TypeScript AST 分析和操作
-* **TypeScript 编译器 API** - 深度代码结构分析
-* **madge** - 依赖关系图可视化
-* **jsdoc-to-markdown** - 从 JSDoc 注释生成文档
-
-### 分析命令
+## 分析命令
 
 ```bash
-# Analyze TypeScript project structure (run custom script using ts-morph library)
-npx tsx scripts/codemaps/generate.ts
-
-# Generate dependency graph
-npx madge --image graph.svg src/
-
-# Extract JSDoc comments
-npx jsdoc2md src/**/*.ts
+npx tsx scripts/codemaps/generate.ts    # Generate codemaps
+npx madge --image graph.svg src/        # Dependency graph
+npx jsdoc2md src/**/*.ts                # Extract JSDoc
 ```
 
-## 代码映射生成工作流
+## 代码地图工作流
 
-### 1. 仓库结构分析
+### 1. 分析仓库
 
-```
-a) Identify all workspaces/packages
-b) Map directory structure
-c) Find entry points (apps/*, packages/*, services/*)
-d) Detect framework patterns (Next.js, Node.js, etc.)
-```
+* 识别工作区/包
+* 映射目录结构
+* 查找入口点 (apps/*, packages/*, services/\*)
+* 检测框架模式
 
-### 2. 模块分析
+### 2. 分析模块
 
-```
-For each module:
-- Extract exports (public API)
-- Map imports (dependencies)
-- Identify routes (API routes, pages)
-- Find database models (Supabase, Prisma)
-- Locate queue/worker modules
-```
+对于每个模块：提取导出项、映射导入项、识别路由、查找数据库模型、定位工作进程
 
 ### 3. 生成代码映射
 
+输出结构：
+
 ```
-Structure:
 docs/CODEMAPS/
-├── INDEX.md              # Overview of all areas
-├── frontend.md           # Frontend structure
-├── backend.md            # Backend/API structure
-├── database.md           # Database schema
-├── integrations.md       # External services
-└── workers.md            # Background jobs
+├── INDEX.md          # Overview of all areas
+├── frontend.md       # Frontend structure
+├── backend.md        # Backend/API structure
+├── database.md       # Database schema
+├── integrations.md   # External services
+└── workers.md        # Background jobs
 ```
 
 ### 4. 代码映射格式
@@ -80,395 +58,53 @@ docs/CODEMAPS/
 # [区域] 代码地图
 
 **最后更新：** YYYY-MM-DD
-**入口点：** 主要文件列表
+**入口点：** 主文件列表
 
 ## 架构
-
 [组件关系的 ASCII 图]
 
 ## 关键模块
-
 | 模块 | 用途 | 导出 | 依赖项 |
-|--------|---------|---------|--------------|
-| ... | ... | ... | ... |
 
 ## 数据流
+[数据如何在此区域中流动]
 
-[描述数据如何流经此区域]
-
-## 外部依赖项
-
+## 外部依赖
 - package-name - 用途，版本
-- ...
 
 ## 相关区域
-
-链接到与此区域交互的其他代码地图
+指向其他代码地图的链接
 ```
 
 ## 文档更新工作流
 
-### 1. 从代码中提取文档
+1. **提取** — 读取 JSDoc/TSDoc、README 部分、环境变量、API 端点
+2. **更新** — README.md、docs/GUIDES/\*.md、package.json、API 文档
+3. **验证** — 验证文件存在、链接有效、示例可运行、代码片段可编译
 
-```
-- Read JSDoc/TSDoc comments
-- Extract README sections from package.json
-- Parse environment variables from .env.example
-- Collect API endpoint definitions
-```
+## 关键原则
 
-### 2. 更新文档文件
-
-```
-Files to update:
-- README.md - Project overview, setup instructions
-- docs/GUIDES/*.md - Feature guides, tutorials
-- package.json - Descriptions, scripts docs
-- API documentation - Endpoint specs
-```
-
-### 3. 文档验证
-
-```
-- Verify all mentioned files exist
-- Check all links work
-- Ensure examples are runnable
-- Validate code snippets compile
-```
-
-## 项目特定代码映射示例
-
-### 前端代码映射 (docs/CODEMAPS/frontend.md)
-
-```markdown
-# 前端架构
-
-**最后更新：** YYYY-MM-DD
-**框架：** Next.js 15.1.4 (App Router)
-**入口点：** website/src/app/layout.tsx
-
-## 结构
-
-website/src/
-├── app/                # Next.js App Router
-│   ├── api/           # API 路由
-│   ├── markets/       # 市场页面
-│   ├── bot/           # 机器人交互
-│   └── creator-dashboard/
-├── components/        # React 组件
-├── hooks/             # 自定义钩子
-└── lib/               # 工具函数
-
-## 关键组件
-
-| 组件 | 用途 | 位置 |
-|-----------|---------|----------|
-| HeaderWallet | 钱包连接 | components/HeaderWallet.tsx |
-| MarketsClient | 市场列表 | app/markets/MarketsClient.js |
-| SemanticSearchBar | 搜索界面 | components/SemanticSearchBar.js |
-
-## 数据流
-
-用户 → 市场页面 → API 路由 → Supabase → Redis (可选) → 响应
-
-## 外部依赖
-
-- Next.js 15.1.4 - 框架
-- React 19.0.0 - UI 库
-- Privy - 身份验证
-- Tailwind CSS 3.4.1 - 样式
-```
-
-### 后端代码映射 (docs/CODEMAPS/backend.md)
-
-```markdown
-# 后端架构
-
-**最后更新:** YYYY-MM-DD
-**运行时:** Next.js API 路由
-**入口点:** website/src/app/api/
-
-## API 路由
-
-| 路由 | 方法 | 用途 |
-|-------|--------|---------|
-| /api/markets | GET | 列出所有市场 |
-| /api/markets/search | GET | 语义搜索 |
-| /api/market/[slug] | GET | 单个市场 |
-| /api/market-price | GET | 实时定价 |
-
-## 数据流
-
-API 路由 → Supabase 查询 → Redis (缓存) → 响应
-
-## 外部服务
-
-- Supabase - PostgreSQL 数据库
-- Redis Stack - 向量搜索
-- OpenAI - 嵌入
-```
-
-### 集成代码映射 (docs/CODEMAPS/integrations.md)
-
-```markdown
-# 外部集成
-
-**最后更新：** YYYY-MM-DD
-
-## 认证 (Privy)
-- 钱包连接 (Solana, Ethereum)
-- 邮箱认证
-- 会话管理
-
-## 数据库 (Supabase)
-- PostgreSQL 表
-- 实时订阅
-- 行级安全
-
-## 搜索 (Redis + OpenAI)
-- 向量嵌入 (text-embedding-ada-002)
-- 语义搜索 (KNN)
-- 回退到子字符串搜索
-
-## 区块链 (Solana)
-- 钱包集成
-- 交易处理
-- Meteora CP-AMM SDK
-```
-
-## README 更新模板
-
-更新 README.md 时：
-
-```markdown
-# 项目名称
-
-简要描述
-
-## 设置
-
-`​`​`bash
-
-# 安装
-npm install
-
-# 环境变量
-cp .env.example .env.local
-# 填写：OPENAI_API_KEY, REDIS_URL 等
-
-# 开发
-npm run dev
-
-# 构建
-npm run build
-`​`​`
-
-
-## 架构
-
-详细架构请参阅 [docs/CODEMAPS/INDEX.md](docs/CODEMAPS/INDEX.md)。
-
-### 关键目录
-
-- `src/app` - Next.js App Router 页面和 API 路由
-- `src/components` - 可复用的 React 组件
-- `src/lib` - 工具库和客户端
-
-## 功能
-
-- [功能 1] - 描述
-- [功能 2] - 描述
-
-## 文档
-
-- [设置指南](docs/GUIDES/setup.md)
-- [API 参考](docs/GUIDES/api.md)
-- [架构](docs/CODEMAPS/INDEX.md)
-
-## 贡献
-
-请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)
-```
-
-## 支持文档的脚本
-
-### scripts/codemaps/generate.ts
-
-```typescript
-/**
- * Generate codemaps from repository structure
- * Usage: tsx scripts/codemaps/generate.ts
- */
-
-import { Project } from 'ts-morph'
-import * as fs from 'fs'
-import * as path from 'path'
-
-async function generateCodemaps() {
-  const project = new Project({
-    tsConfigFilePath: 'tsconfig.json',
-  })
-
-  // 1. Discover all source files
-  const sourceFiles = project.getSourceFiles('src/**/*.{ts,tsx}')
-
-  // 2. Build import/export graph
-  const graph = buildDependencyGraph(sourceFiles)
-
-  // 3. Detect entrypoints (pages, API routes)
-  const entrypoints = findEntrypoints(sourceFiles)
-
-  // 4. Generate codemaps
-  await generateFrontendMap(graph, entrypoints)
-  await generateBackendMap(graph, entrypoints)
-  await generateIntegrationsMap(graph)
-
-  // 5. Generate index
-  await generateIndex()
-}
-
-function buildDependencyGraph(files: SourceFile[]) {
-  // Map imports/exports between files
-  // Return graph structure
-}
-
-function findEntrypoints(files: SourceFile[]) {
-  // Identify pages, API routes, entry files
-  // Return list of entrypoints
-}
-```
-
-### scripts/docs/update.ts
-
-```typescript
-/**
- * Update documentation from code
- * Usage: tsx scripts/docs/update.ts
- */
-
-import * as fs from 'fs'
-import { execSync } from 'child_process'
-
-async function updateDocs() {
-  // 1. Read codemaps
-  const codemaps = readCodemaps()
-
-  // 2. Extract JSDoc/TSDoc
-  const apiDocs = extractJSDoc('src/**/*.ts')
-
-  // 3. Update README.md
-  await updateReadme(codemaps, apiDocs)
-
-  // 4. Update guides
-  await updateGuides(codemaps)
-
-  // 5. Generate API reference
-  await generateAPIReference(apiDocs)
-}
-
-function extractJSDoc(pattern: string) {
-  // Use jsdoc-to-markdown or similar
-  // Extract documentation from source
-}
-```
-
-## 拉取请求模板
-
-提交包含文档更新的拉取请求时：
-
-```markdown
-## 文档：更新代码映射和文档
-
-### 摘要
-重新生成了代码映射并更新了文档，以反映当前代码库状态。
-
-### 变更
-- 根据当前代码结构更新了 docs/CODEMAPS/*
-- 使用最新的设置说明刷新了 README.md
-- 使用当前 API 端点更新了 docs/GUIDES/*
-- 向代码映射添加了 X 个新模块
-- 移除了 Y 个过时的文档章节
-
-### 生成的文件
-- docs/CODEMAPS/INDEX.md
-- docs/CODEMAPS/frontend.md
-- docs/CODEMAPS/backend.md
-- docs/CODEMAPS/integrations.md
-
-### 验证
-- [x] 文档中的所有链接有效
-- [x] 代码示例是最新的
-- [x] 架构图与现实匹配
-- [x] 没有过时的引用
-
-### 影响
-🟢 低 - 仅文档更新，无代码变更
-
-有关完整的架构概述，请参阅 docs/CODEMAPS/INDEX.md。
-```
-
-## 维护计划
-
-**每周：**
-
-* 检查 `src/` 中是否出现未在代码映射中记录的新文件
-* 验证 README.md 中的说明是否有效
-* 更新 package.json 描述
-
-**主要功能完成后：**
-
-* 重新生成所有代码映射
-* 更新架构文档
-* 刷新 API 参考
-* 更新设置指南
-
-**发布前：**
-
-* 全面的文档审计
-* 验证所有示例是否有效
-* 检查所有外部链接
-* 更新版本引用
+1. **单一事实来源** — 从代码生成，而非手动编写
+2. **新鲜度时间戳** — 始终包含最后更新日期
+3. **令牌效率** — 保持每个代码地图不超过 500 行
+4. **可操作** — 包含实际有效的设置命令
+5. **交叉引用** — 链接相关文档
 
 ## 质量检查清单
 
-提交文档前：
-
-* \[ ] 代码映射从实际代码生成
+* \[ ] 代码地图从实际代码生成
 * \[ ] 所有文件路径已验证存在
 * \[ ] 代码示例可编译/运行
-* \[ ] 链接已测试（内部和外部）
+* \[ ] 链接已测试
 * \[ ] 新鲜度时间戳已更新
-* \[ ] ASCII 图表清晰
-* \[ ] 没有过时的引用
-* \[ ] 拼写/语法已检查
+* \[ ] 无过时引用
 
-## 最佳实践
+## 何时更新
 
-1. **单一事实来源** - 从代码生成，不要手动编写
-2. **新鲜度时间戳** - 始终包含最后更新日期
-3. **令牌效率** - 保持每个代码映射在 500 行以内
-4. **结构清晰** - 使用一致的 Markdown 格式
-5. **可操作** - 包含实际可用的设置命令
-6. **链接化** - 交叉引用相关文档
-7. **示例** - 展示真实可运行的代码片段
-8. **版本控制** - 在 git 中跟踪文档变更
+**始终：** 新增主要功能、API 路由变更、添加/移除依赖项、架构变更、设置流程修改。
 
-## 何时更新文档
-
-**在以下情况必须更新文档：**
-
-* 添加新主要功能时
-* API 路由变更时
-* 添加/移除依赖项时
-* 架构发生重大变更时
-* 设置流程修改时
-
-**在以下情况可选择性地更新：**
-
-* 小的错误修复
-* 外观变更
-* 不涉及 API 变更的重构
+**可选：** 次要错误修复、外观更改、内部重构。
 
 ***
 
-**记住**：与现实不符的文档比没有文档更糟。始终从事实来源（实际代码）生成。
+**记住：** 与现实不符的文档比没有文档更糟糕。始终从事实来源生成。

docs/zh-CN/agents/e2e-runner.md

@@ -1,822 +1,110 @@
 ---
 name: e2e-runner
-description: 端到端测试专家，首选使用 Vercel Agent Browser，备选使用 Playwright。主动用于生成、维护和运行 E2E 测试。管理测试旅程，隔离不稳定测试，上传工件（截图、视频、跟踪），并确保关键用户流程正常工作。
+description: 使用Vercel Agent Browser（首选）和Playwright备选方案进行端到端测试的专家。主动用于生成、维护和运行E2E测试。管理测试流程，隔离不稳定的测试，上传工件（截图、视频、跟踪），并确保关键用户流程正常运行。
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
-model: opus
+model: sonnet
 ---
 
 # E2E 测试运行器
 
 您是一位专业的端到端测试专家。您的使命是通过创建、维护和执行全面的 E2E 测试，并配合适当的工件管理和不稳定测试处理，确保关键用户旅程正常工作。
 
-## 主要工具：Vercel Agent Browser
-
-**优先使用 Agent Browser 而非原始 Playwright** - 它针对 AI 代理进行了优化，具有语义选择器并能更好地处理动态内容。
-
-### 为什么选择 Agent Browser？
-
-* **语义选择器** - 通过含义查找元素，而非脆弱的 CSS/XPath
-* **AI 优化** - 专为 LLM 驱动的浏览器自动化设计
-* **自动等待** - 智能等待动态内容
-* **基于 Playwright 构建** - 完全兼容 Playwright 作为备用方案
-
-### Agent Browser 设置
-
-```bash
-# Install agent-browser globally
-npm install -g agent-browser
-
-# Install Chromium (required)
-agent-browser install
-```
-
-### Agent Browser CLI 用法（主要）
-
-Agent Browser 使用针对 AI 代理优化的快照 + refs 系统：
-
-```bash
-# Open a page and get a snapshot with interactive elements
-agent-browser open https://example.com
-agent-browser snapshot -i  # Returns elements with refs like [ref=e1]
-
-# Interact using element references from snapshot
-agent-browser click @e1                      # Click element by ref
-agent-browser fill @e2 "user@example.com"   # Fill input by ref
-agent-browser fill @e3 "password123"        # Fill password field
-agent-browser click @e4                      # Click submit button
-
-# Wait for conditions
-agent-browser wait visible @e5               # Wait for element
-agent-browser wait navigation                # Wait for page load
-
-# Take screenshots
-agent-browser screenshot after-login.png
-
-# Get text content
-agent-browser get text @e1
-```
-
-### 脚本中的 Agent Browser
-
-对于程序化控制，通过 shell 命令使用 CLI：
-
-```typescript
-import { execSync } from 'child_process'
-
-// Execute agent-browser commands
-const snapshot = execSync('agent-browser snapshot -i --json').toString()
-const elements = JSON.parse(snapshot)
-
-// Find element ref and interact
-execSync('agent-browser click @e1')
-execSync('agent-browser fill @e2 "test@example.com"')
-```
-
-### 程序化 API（高级）
-
-用于直接浏览器控制（屏幕录制、低级事件）：
-
-```typescript
-import { BrowserManager } from 'agent-browser'
-
-const browser = new BrowserManager()
-await browser.launch({ headless: true })
-await browser.navigate('https://example.com')
-
-// Low-level event injection
-await browser.injectMouseEvent({ type: 'mousePressed', x: 100, y: 200, button: 'left' })
-await browser.injectKeyboardEvent({ type: 'keyDown', key: 'Enter', code: 'Enter' })
-
-// Screencast for AI vision
-await browser.startScreencast()  // Stream viewport frames
-```
-
-### Agent Browser 与 Claude Code
-
-如果您安装了 `agent-browser` 技能，请使用 `/agent-browser` 进行交互式浏览器自动化任务。
-
-***
-
-## 备用工具：Playwright
-
-当 Agent Browser 不可用或用于复杂的测试套件时，回退到 Playwright。
-
 ## 核心职责
 
-1. **测试旅程创建** - 为用户流程编写测试（优先使用 Agent Browser，回退到 Playwright）
-2. **测试维护** - 保持测试与 UI 更改同步
-3. **不稳定测试管理** - 识别并隔离不稳定的测试
-4. **工件管理** - 捕获截图、视频、跟踪记录
-5. **CI/CD 集成** - 确保测试在流水线中可靠运行
-6. **测试报告** - 生成 HTML 报告和 JUnit XML
+1. **测试旅程创建** — 为用户流程编写测试（首选 Agent Browser，备选 Playwright）
+2. **测试维护** — 保持测试与 UI 更改同步更新
+3. **不稳定测试管理** — 识别并隔离不稳定的测试
+4. **产物管理** — 捕获截图、视频、追踪记录
+5. **CI/CD 集成** — 确保测试在流水线中可靠运行
+6. **测试报告** — 生成 HTML 报告和 JUnit XML
 
-## Playwright 测试框架（备用）
+## 主要工具：Agent Browser
 
-### 工具
-
-* **@playwright/test** - 核心测试框架
-* **Playwright Inspector** - 交互式调试测试
-* **Playwright Trace Viewer** - 分析测试执行情况
-* **Playwright Codegen** - 根据浏览器操作生成测试代码
-
-### 测试命令
+**首选 Agent Browser 而非原始 Playwright** — 语义化选择器、AI 优化、自动等待，基于 Playwright 构建。
 
 ```bash
-# Run all E2E tests
-npx playwright test
+# Setup
+npm install -g agent-browser && agent-browser install
 
-# Run specific test file
-npx playwright test tests/markets.spec.ts
-
-# Run tests in headed mode (see browser)
-npx playwright test --headed
-
-# Debug test with inspector
-npx playwright test --debug
-
-# Generate test code from actions
-npx playwright codegen http://localhost:3000
-
-# Run tests with trace
-npx playwright test --trace on
-
-# Show HTML report
-npx playwright show-report
-
-# Update snapshots
-npx playwright test --update-snapshots
-
-# Run tests in specific browser
-npx playwright test --project=chromium
-npx playwright test --project=firefox
-npx playwright test --project=webkit
+# Core workflow
+agent-browser open https://example.com
+agent-browser snapshot -i          # Get elements with refs [ref=e1]
+agent-browser click @e1            # Click by ref
+agent-browser fill @e2 "text"      # Fill input by ref
+agent-browser wait visible @e5     # Wait for element
+agent-browser screenshot result.png
 ```
 
-## E2E 测试工作流
+## 备选方案：Playwright
 
-### 1. 测试规划阶段
-
-```
-a) Identify critical user journeys
-   - Authentication flows (login, logout, registration)
-   - Core features (market creation, trading, searching)
-   - Payment flows (deposits, withdrawals)
-   - Data integrity (CRUD operations)
-
-b) Define test scenarios
-   - Happy path (everything works)
-   - Edge cases (empty states, limits)
-   - Error cases (network failures, validation)
-
-c) Prioritize by risk
-   - HIGH: Financial transactions, authentication
-   - MEDIUM: Search, filtering, navigation
-   - LOW: UI polish, animations, styling
-```
-
-### 2. 测试创建阶段
-
-```
-For each user journey:
-
-1. Write test in Playwright
-   - Use Page Object Model (POM) pattern
-   - Add meaningful test descriptions
-   - Include assertions at key steps
-   - Add screenshots at critical points
-
-2. Make tests resilient
-   - Use proper locators (data-testid preferred)
-   - Add waits for dynamic content
-   - Handle race conditions
-   - Implement retry logic
-
-3. Add artifact capture
-   - Screenshot on failure
-   - Video recording
-   - Trace for debugging
-   - Network logs if needed
-```
-
-### 3. 测试执行阶段
-
-```
-a) Run tests locally
-   - Verify all tests pass
-   - Check for flakiness (run 3-5 times)
-   - Review generated artifacts
-
-b) Quarantine flaky tests
-   - Mark unstable tests as @flaky
-   - Create issue to fix
-   - Remove from CI temporarily
-
-c) Run in CI/CD
-   - Execute on pull requests
-   - Upload artifacts to CI
-   - Report results in PR comments
-```
-
-## Playwright 测试结构
-
-### 测试文件组织
-
-```
-tests/
-├── e2e/                       # End-to-end user journeys
-│   ├── auth/                  # Authentication flows
-│   │   ├── login.spec.ts
-│   │   ├── logout.spec.ts
-│   │   └── register.spec.ts
-│   ├── markets/               # Market features
-│   │   ├── browse.spec.ts
-│   │   ├── search.spec.ts
-│   │   ├── create.spec.ts
-│   │   └── trade.spec.ts
-│   ├── wallet/                # Wallet operations
-│   │   ├── connect.spec.ts
-│   │   └── transactions.spec.ts
-│   └── api/                   # API endpoint tests
-│       ├── markets-api.spec.ts
-│       └── search-api.spec.ts
-├── fixtures/                  # Test data and helpers
-│   ├── auth.ts                # Auth fixtures
-│   ├── markets.ts             # Market test data
-│   └── wallets.ts             # Wallet fixtures
-└── playwright.config.ts       # Playwright configuration
-```
-
-### 页面对象模型模式
-
-```typescript
-// pages/MarketsPage.ts
-import { Page, Locator } from '@playwright/test'
-
-export class MarketsPage {
-  readonly page: Page
-  readonly searchInput: Locator
-  readonly marketCards: Locator
-  readonly createMarketButton: Locator
-  readonly filterDropdown: Locator
-
-  constructor(page: Page) {
-    this.page = page
-    this.searchInput = page.locator('[data-testid="search-input"]')
-    this.marketCards = page.locator('[data-testid="market-card"]')
-    this.createMarketButton = page.locator('[data-testid="create-market-btn"]')
-    this.filterDropdown = page.locator('[data-testid="filter-dropdown"]')
-  }
-
-  async goto() {
-    await this.page.goto('/markets')
-    await this.page.waitForLoadState('networkidle')
-  }
-
-  async searchMarkets(query: string) {
-    await this.searchInput.fill(query)
-    await this.page.waitForResponse(resp => resp.url().includes('/api/markets/search'))
-    await this.page.waitForLoadState('networkidle')
-  }
-
-  async getMarketCount() {
-    return await this.marketCards.count()
-  }
-
-  async clickMarket(index: number) {
-    await this.marketCards.nth(index).click()
-  }
-
-  async filterByStatus(status: string) {
-    await this.filterDropdown.selectOption(status)
-    await this.page.waitForLoadState('networkidle')
-  }
-}
-```
-
-### 包含最佳实践的示例测试
-
-```typescript
-// tests/e2e/markets/search.spec.ts
-import { test, expect } from '@playwright/test'
-import { MarketsPage } from '../../pages/MarketsPage'
-
-test.describe('Market Search', () => {
-  let marketsPage: MarketsPage
-
-  test.beforeEach(async ({ page }) => {
-    marketsPage = new MarketsPage(page)
-    await marketsPage.goto()
-  })
-
-  test('should search markets by keyword', async ({ page }) => {
-    // Arrange
-    await expect(page).toHaveTitle(/Markets/)
-
-    // Act
-    await marketsPage.searchMarkets('trump')
-
-    // Assert
-    const marketCount = await marketsPage.getMarketCount()
-    expect(marketCount).toBeGreaterThan(0)
-
-    // Verify first result contains search term
-    const firstMarket = marketsPage.marketCards.first()
-    await expect(firstMarket).toContainText(/trump/i)
-
-    // Take screenshot for verification
-    await page.screenshot({ path: 'artifacts/search-results.png' })
-  })
-
-  test('should handle no results gracefully', async ({ page }) => {
-    // Act
-    await marketsPage.searchMarkets('xyznonexistentmarket123')
-
-    // Assert
-    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
-    const marketCount = await marketsPage.getMarketCount()
-    expect(marketCount).toBe(0)
-  })
-
-  test('should clear search results', async ({ page }) => {
-    // Arrange - perform search first
-    await marketsPage.searchMarkets('trump')
-    await expect(marketsPage.marketCards.first()).toBeVisible()
-
-    // Act - clear search
-    await marketsPage.searchInput.clear()
-    await page.waitForLoadState('networkidle')
-
-    // Assert - all markets shown again
-    const marketCount = await marketsPage.getMarketCount()
-    expect(marketCount).toBeGreaterThan(10) // Should show all markets
-  })
-})
-```
-
-## 示例项目特定的测试场景
-
-### 示例项目的关键用户旅程
-
-**1. 市场浏览流程**
-
-```typescript
-test('user can browse and view markets', async ({ page }) => {
-  // 1. Navigate to markets page
-  await page.goto('/markets')
-  await expect(page.locator('h1')).toContainText('Markets')
-
-  // 2. Verify markets are loaded
-  const marketCards = page.locator('[data-testid="market-card"]')
-  await expect(marketCards.first()).toBeVisible()
-
-  // 3. Click on a market
-  await marketCards.first().click()
-
-  // 4. Verify market details page
-  await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
-  await expect(page.locator('[data-testid="market-name"]')).toBeVisible()
-
-  // 5. Verify chart loads
-  await expect(page.locator('[data-testid="price-chart"]')).toBeVisible()
-})
-```
-
-**2. 语义搜索流程**
-
-```typescript
-test('semantic search returns relevant results', async ({ page }) => {
-  // 1. Navigate to markets
-  await page.goto('/markets')
-
-  // 2. Enter search query
-  const searchInput = page.locator('[data-testid="search-input"]')
-  await searchInput.fill('election')
-
-  // 3. Wait for API call
-  await page.waitForResponse(resp =>
-    resp.url().includes('/api/markets/search') && resp.status() === 200
-  )
-
-  // 4. Verify results contain relevant markets
-  const results = page.locator('[data-testid="market-card"]')
-  await expect(results).not.toHaveCount(0)
-
-  // 5. Verify semantic relevance (not just substring match)
-  const firstResult = results.first()
-  const text = await firstResult.textContent()
-  expect(text?.toLowerCase()).toMatch(/election|trump|biden|president|vote/)
-})
-```
-
-**3. 钱包连接流程**
-
-```typescript
-test('user can connect wallet', async ({ page, context }) => {
-  // Setup: Mock Privy wallet extension
-  await context.addInitScript(() => {
-    // @ts-ignore
-    window.ethereum = {
-      isMetaMask: true,
-      request: async ({ method }) => {
-        if (method === 'eth_requestAccounts') {
-          return ['0x1234567890123456789012345678901234567890']
-        }
-        if (method === 'eth_chainId') {
-          return '0x1'
-        }
-      }
-    }
-  })
-
-  // 1. Navigate to site
-  await page.goto('/')
-
-  // 2. Click connect wallet
-  await page.locator('[data-testid="connect-wallet"]').click()
-
-  // 3. Verify wallet modal appears
-  await expect(page.locator('[data-testid="wallet-modal"]')).toBeVisible()
-
-  // 4. Select wallet provider
-  await page.locator('[data-testid="wallet-provider-metamask"]').click()
-
-  // 5. Verify connection successful
-  await expect(page.locator('[data-testid="wallet-address"]')).toBeVisible()
-  await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')
-})
-```
-
-**4. 市场创建流程（已验证身份）**
-
-```typescript
-test('authenticated user can create market', async ({ page }) => {
-  // Prerequisites: User must be authenticated
-  await page.goto('/creator-dashboard')
-
-  // Verify auth (or skip test if not authenticated)
-  const isAuthenticated = await page.locator('[data-testid="user-menu"]').isVisible()
-  test.skip(!isAuthenticated, 'User not authenticated')
-
-  // 1. Click create market button
-  await page.locator('[data-testid="create-market"]').click()
-
-  // 2. Fill market form
-  await page.locator('[data-testid="market-name"]').fill('Test Market')
-  await page.locator('[data-testid="market-description"]').fill('This is a test market')
-  await page.locator('[data-testid="market-end-date"]').fill('2025-12-31')
-
-  // 3. Submit form
-  await page.locator('[data-testid="submit-market"]').click()
-
-  // 4. Verify success
-  await expect(page.locator('[data-testid="success-message"]')).toBeVisible()
-
-  // 5. Verify redirect to new market
-  await expect(page).toHaveURL(/\/markets\/test-market/)
-})
-```
-
-**5. 交易流程（关键 - 真实资金）**
-
-```typescript
-test('user can place trade with sufficient balance', async ({ page }) => {
-  // WARNING: This test involves real money - use testnet/staging only!
-  test.skip(process.env.NODE_ENV === 'production', 'Skip on production')
-
-  // 1. Navigate to market
-  await page.goto('/markets/test-market')
-
-  // 2. Connect wallet (with test funds)
-  await page.locator('[data-testid="connect-wallet"]').click()
-  // ... wallet connection flow
-
-  // 3. Select position (Yes/No)
-  await page.locator('[data-testid="position-yes"]').click()
-
-  // 4. Enter trade amount
-  await page.locator('[data-testid="trade-amount"]').fill('1.0')
-
-  // 5. Verify trade preview
-  const preview = page.locator('[data-testid="trade-preview"]')
-  await expect(preview).toContainText('1.0 SOL')
-  await expect(preview).toContainText('Est. shares:')
-
-  // 6. Confirm trade
-  await page.locator('[data-testid="confirm-trade"]').click()
-
-  // 7. Wait for blockchain transaction
-  await page.waitForResponse(resp =>
-    resp.url().includes('/api/trade') && resp.status() === 200,
-    { timeout: 30000 } // Blockchain can be slow
-  )
-
-  // 8. Verify success
-  await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()
-
-  // 9. Verify balance updated
-  const balance = page.locator('[data-testid="wallet-balance"]')
-  await expect(balance).not.toContainText('--')
-})
-```
-
-## Playwright 配置
-
-```typescript
-// playwright.config.ts
-import { defineConfig, devices } from '@playwright/test'
-
-export default defineConfig({
-  testDir: './tests/e2e',
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: [
-    ['html', { outputFolder: 'playwright-report' }],
-    ['junit', { outputFile: 'playwright-results.xml' }],
-    ['json', { outputFile: 'playwright-results.json' }]
-  ],
-  use: {
-    baseURL: process.env.BASE_URL || 'http://localhost:3000',
-    trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
-    video: 'retain-on-failure',
-    actionTimeout: 10000,
-    navigationTimeout: 30000,
-  },
-  projects: [
-    {
-      name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
-    },
-    {
-      name: 'firefox',
-      use: { ...devices['Desktop Firefox'] },
-    },
-    {
-      name: 'webkit',
-      use: { ...devices['Desktop Safari'] },
-    },
-    {
-      name: 'mobile-chrome',
-      use: { ...devices['Pixel 5'] },
-    },
-  ],
-  webServer: {
-    command: 'npm run dev',
-    url: 'http://localhost:3000',
-    reuseExistingServer: !process.env.CI,
-    timeout: 120000,
-  },
-})
-```
-
-## 不稳定测试管理
-
-### 识别不稳定测试
+当 Agent Browser 不可用时，直接使用 Playwright。
 
 ```bash
-# Run test multiple times to check stability
-npx playwright test tests/markets/search.spec.ts --repeat-each=10
-
-# Run specific test with retries
-npx playwright test tests/markets/search.spec.ts --retries=3
+npx playwright test                        # Run all E2E tests
+npx playwright test tests/auth.spec.ts     # Run specific file
+npx playwright test --headed               # See browser
+npx playwright test --debug                # Debug with inspector
+npx playwright test --trace on             # Run with trace
+npx playwright show-report                 # View HTML report
 ```
 
-### 隔离模式
+## 工作流程
+
+### 1. 规划
+
+* 识别关键用户旅程（认证、核心功能、支付、增删改查）
+* 定义场景：成功路径、边界情况、错误情况
+* 按风险确定优先级：高（财务、认证）、中（搜索、导航）、低（UI 优化）
+
+### 2. 创建
+
+* 使用页面对象模型（POM）模式
+* 优先使用 `data-testid` 定位器而非 CSS/XPath
+* 在关键步骤添加断言
+* 在关键点捕获截图
+* 使用适当的等待（绝不使用 `waitForTimeout`）
+
+### 3. 执行
+
+* 本地运行 3-5 次以检查是否存在不稳定性
+* 使用 `test.fixme()` 或 `test.skip()` 隔离不稳定的测试
+* 将产物上传到 CI
+
+## 关键原则
+
+* **使用语义化定位器**：`[data-testid="..."]` > CSS 选择器 > XPath
+* **等待条件，而非时间**：`waitForResponse()` > `waitForTimeout()`
+* **内置自动等待**：`page.locator().click()` 自动等待；原始的 `page.click()` 不会
+* **隔离测试**：每个测试应独立；无共享状态
+* **快速失败**：在每个关键步骤使用 `expect()` 断言
+* **重试时追踪**：配置 `trace: 'on-first-retry'` 以调试失败
+
+## 不稳定测试处理
 
 ```typescript
-// Mark flaky test for quarantine
-test('flaky: market search with complex query', async ({ page }) => {
-  test.fixme(true, 'Test is flaky - Issue #123')
-
-  // Test code here...
+// Quarantine
+test('flaky: market search', async ({ page }) => {
+  test.fixme(true, 'Flaky - Issue #123')
 })
 
-// Or use conditional skip
-test('market search with complex query', async ({ page }) => {
-  test.skip(process.env.CI, 'Test is flaky in CI - Issue #123')
-
-  // Test code here...
-})
+// Identify flakiness
+// npx playwright test --repeat-each=10
 ```
 
-### 常见的不稳定原因及修复方法
-
-**1. 竞态条件**
-
-```typescript
-// ❌ FLAKY: Don't assume element is ready
-await page.click('[data-testid="button"]')
-
-// ✅ STABLE: Wait for element to be ready
-await page.locator('[data-testid="button"]').click() // Built-in auto-wait
-```
-
-**2. 网络时序**
-
-```typescript
-// ❌ FLAKY: Arbitrary timeout
-await page.waitForTimeout(5000)
-
-// ✅ STABLE: Wait for specific condition
-await page.waitForResponse(resp => resp.url().includes('/api/markets'))
-```
-
-**3. 动画时序**
-
-```typescript
-// ❌ FLAKY: Click during animation
-await page.click('[data-testid="menu-item"]')
-
-// ✅ STABLE: Wait for animation to complete
-await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
-await page.waitForLoadState('networkidle')
-await page.click('[data-testid="menu-item"]')
-```
-
-## 产物管理
-
-### 截图策略
-
-```typescript
-// Take screenshot at key points
-await page.screenshot({ path: 'artifacts/after-login.png' })
-
-// Full page screenshot
-await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })
-
-// Element screenshot
-await page.locator('[data-testid="chart"]').screenshot({
-  path: 'artifacts/chart.png'
-})
-```
-
-### 跟踪记录收集
-
-```typescript
-// Start trace
-await browser.startTracing(page, {
-  path: 'artifacts/trace.json',
-  screenshots: true,
-  snapshots: true,
-})
-
-// ... test actions ...
-
-// Stop trace
-await browser.stopTracing()
-```
-
-### 视频录制
-
-```typescript
-// Configured in playwright.config.ts
-use: {
-  video: 'retain-on-failure', // Only save video if test fails
-  videosPath: 'artifacts/videos/'
-}
-```
-
-## CI/CD 集成
-
-### GitHub Actions 工作流
-
-```yaml
-# .github/workflows/e2e.yml
-name: E2E Tests
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Install Playwright browsers
-        run: npx playwright install --with-deps
-
-      - name: Run E2E tests
-        run: npx playwright test
-        env:
-          BASE_URL: https://staging.pmx.trade
-
-      - name: Upload artifacts
-        if: always()
-        uses: actions/upload-artifact@v3
-        with:
-          name: playwright-report
-          path: playwright-report/
-          retention-days: 30
-
-      - name: Upload test results
-        if: always()
-        uses: actions/upload-artifact@v3
-        with:
-          name: playwright-results
-          path: playwright-results.xml
-```
-
-## 测试报告格式
-
-```markdown
-# E2E 测试报告
-
-**日期:** YYYY-MM-DD HH:MM
-**持续时间:** Xm Ys
-**状态:** ✅ 通过 / ❌ 失败
-
-## 概要
-
-- **总测试数:** X
-- **通过:** Y (Z%)
-- **失败:** A
-- **不稳定:** B
-- **跳过:** C
-
-## 按测试套件分类的结果
-
-### 市场 - 浏览与搜索
-- ✅ 用户可以浏览市场 (2.3s)
-- ✅ 语义搜索返回相关结果 (1.8s)
-- ✅ 搜索处理无结果情况 (1.2s)
-- ❌ 搜索包含特殊字符 (0.9s)
-
-### 钱包 - 连接
-- ✅ 用户可以连接 MetaMask (3.1s)
-- ⚠️  用户可以连接 Phantom (2.8s) - 不稳定
-- ✅ 用户可以断开钱包连接 (1.5s)
-
-### 交易 - 核心流程
-- ✅ 用户可以下买单 (5.2s)
-- ❌ 用户可以下卖单 (4.8s)
-- ✅ 余额不足显示错误 (1.9s)
-
-## 失败的测试
-
-### 1. search with special characters
-**文件:** `tests/e2e/markets/search.spec.ts:45`
-**错误:** 期望元素可见，但未找到
-**截图:** artifacts/search-special-chars-failed.png
-**跟踪文件:** artifacts/trace-123.zip
-
-**重现步骤:**
-1. 导航到 /markets
-2. 输入包含特殊字符的搜索查询："trump & biden"
-3. 验证结果
-
-**建议修复:** 对搜索查询中的特殊字符进行转义
-
----
-
-### 2. user can place sell order
-**文件:** `tests/e2e/trading/sell.spec.ts:28`
-**错误:** 等待 API 响应 /api/trade 超时
-**视频:** artifacts/videos/sell-order-failed.webm
-
-**可能原因:**
-- 区块链网络慢
-- Gas 不足
-- 交易被回退
-
-**建议修复:** 增加超时时间或检查区块链日志
-
-## 产物
-
-- HTML 报告: playwright-report/index.html
-- 截图: artifacts/*.png (12 个文件)
-- 视频: artifacts/videos/*.webm (2 个文件)
-- 跟踪文件: artifacts/*.zip (2 个文件)
-- JUnit XML: playwright-results.xml
-
-## 后续步骤
-
-- [ ] 修复 2 个失败的测试
-- [ ] 调查 1 个不稳定的测试
-- [ ] 如果全部通过，则审阅并合并
-
-```
+常见原因：竞态条件（使用自动等待定位器）、网络时序（等待响应）、动画时序（等待 `networkidle`）。
 
 ## 成功指标
 
-E2E 测试运行后：
+* 所有关键旅程通过（100%）
+* 总体通过率 > 95%
+* 不稳定率 < 5%
+* 测试持续时间 < 10 分钟
+* 产物已上传并可访问
 
-* ✅ 所有关键旅程通过 (100%)
-* ✅ 总体通过率 > 95%
-* ✅ 不稳定率 < 5%
-* ✅ 没有失败的测试阻塞部署
-* ✅ 产物已上传并可访问
-* ✅ 测试持续时间 < 10 分钟
-* ✅ HTML 报告已生成
+## 参考
+
+有关详细的 Playwright 模式、页面对象模型示例、配置模板、CI/CD 工作流和产物管理策略，请参阅技能：`e2e-testing`。
 
 ***
 
-**请记住**：E2E 测试是进入生产环境前的最后一道防线。它们能捕捉单元测试遗漏的集成问题。投入时间让它们变得稳定、快速且全面。对于示例项目，请特别关注资金流相关的测试——一个漏洞就可能让用户损失真实资金。
+**记住**：端到端测试是上线前的最后一道防线。它们能捕获单元测试遗漏的集成问题。投资于稳定性、速度和覆盖率。

docs/zh-CN/agents/go-build-resolver.md

@@ -1,8 +1,8 @@
 ---
 name: go-build-resolver
-description: Go 构建、vet 和编译错误解决专家。以最小更改修复构建错误、go vet 问题和 linter 警告。在 Go 构建失败时使用。
+description: Go 构建、vet 和编译错误解决专家。以最小改动修复构建错误、go vet 问题和 linter 警告。在 Go 构建失败时使用。
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
-model: opus
+model: sonnet
 ---
 
 # Go 构建错误解决器
@@ -19,366 +19,77 @@ model: opus
 
 ## 诊断命令
 
-按顺序运行这些命令以理解问题：
+按顺序运行这些命令：
 
 ```bash
-# 1. Basic build check
 go build ./...
-
-# 2. Vet for common mistakes
 go vet ./...
-
-# 3. Static analysis (if available)
 staticcheck ./... 2>/dev/null || echo "staticcheck not installed"
 golangci-lint run 2>/dev/null || echo "golangci-lint not installed"
-
-# 4. Module verification
 go mod verify
 go mod tidy -v
-
-# 5. List dependencies
-go list -m all
 ```
 
-## 常见错误模式及修复方法
-
-### 1. 未定义的标识符
-
-**错误：** `undefined: SomeFunc`
-
-**原因：**
-
-* 缺少导入
-* 函数/变量名拼写错误
-* 未导出的标识符（首字母小写）
-* 函数定义在具有构建约束的不同文件中
-
-**修复：**
-
-```go
-// Add missing import
-import "package/that/defines/SomeFunc"
-
-// Or fix typo
-// somefunc -> SomeFunc
-
-// Or export the identifier
-// func someFunc() -> func SomeFunc()
-```
-
-### 2. 类型不匹配
-
-**错误：** `cannot use x (type A) as type B`
-
-**原因：**
-
-* 错误的类型转换
-* 接口未满足
-* 指针与值不匹配
-
-**修复：**
-
-```go
-// Type conversion
-var x int = 42
-var y int64 = int64(x)
-
-// Pointer to value
-var ptr *int = &x
-var val int = *ptr
-
-// Value to pointer
-var val int = 42
-var ptr *int = &val
-```
-
-### 3. 接口未满足
-
-**错误：** `X does not implement Y (missing method Z)`
-
-**诊断：**
-
-```bash
-# Find what methods are missing
-go doc package.Interface
-```
-
-**修复：**
-
-```go
-// Implement missing method with correct signature
-func (x *X) Z() error {
-    // implementation
-    return nil
-}
-
-// Check receiver type matches (pointer vs value)
-// If interface expects: func (x X) Method()
-// You wrote:           func (x *X) Method()  // Won't satisfy
-```
-
-### 4. 导入循环
-
-**错误：** `import cycle not allowed`
-
-**诊断：**
-
-```bash
-go list -f '{{.ImportPath}} -> {{.Imports}}' ./...
-```
-
-**修复：**
-
-* 将共享类型移动到单独的包中
-* 使用接口来打破循环
-* 重构包依赖关系
-
-```text
-# Before (cycle)
-package/a -> package/b -> package/a
-
-# After (fixed)
-package/types  <- shared types
-package/a -> package/types
-package/b -> package/types
-```
-
-### 5. 找不到包
-
-**错误：** `cannot find package "x"`
-
-**修复：**
-
-```bash
-# Add dependency
-go get package/path@version
-
-# Or update go.mod
-go mod tidy
-
-# Or for local packages, check go.mod module path
-# Module: github.com/user/project
-# Import: github.com/user/project/internal/pkg
-```
-
-### 6. 缺少返回
-
-**错误：** `missing return at end of function`
-
-**修复：**
-
-```go
-func Process() (int, error) {
-    if condition {
-        return 0, errors.New("error")
-    }
-    return 42, nil  // Add missing return
-}
-```
-
-### 7. 未使用的变量/导入
-
-**错误：** `x declared but not used` 或 `imported and not used`
-
-**修复：**
-
-```go
-// Remove unused variable
-x := getValue()  // Remove if x not used
-
-// Use blank identifier if intentionally ignoring
-_ = getValue()
-
-// Remove unused import or use blank import for side effects
-import _ "package/for/init/only"
-```
-
-### 8. 单值上下文中的多值
-
-**错误：** `multiple-value X() in single-value context`
-
-**修复：**
-
-```go
-// Wrong
-result := funcReturningTwo()
-
-// Correct
-result, err := funcReturningTwo()
-if err != nil {
-    return err
-}
-
-// Or ignore second value
-result, _ := funcReturningTwo()
-```
-
-### 9. 无法分配给字段
-
-**错误：** `cannot assign to struct field x.y in map`
-
-**修复：**
-
-```go
-// Cannot modify struct in map directly
-m := map[string]MyStruct{}
-m["key"].Field = "value"  // Error!
-
-// Fix: Use pointer map or copy-modify-reassign
-m := map[string]*MyStruct{}
-m["key"] = &MyStruct{}
-m["key"].Field = "value"  // Works
-
-// Or
-m := map[string]MyStruct{}
-tmp := m["key"]
-tmp.Field = "value"
-m["key"] = tmp
-```
-
-### 10. 无效操作（类型断言）
-
-**错误：** `invalid type assertion: x.(T) (non-interface type)`
-
-**修复：**
-
-```go
-// Can only assert from interface
-var i interface{} = "hello"
-s := i.(string)  // Valid
-
-var s string = "hello"
-// s.(int)  // Invalid - s is not interface
-```
-
-## 模块问题
-
-### Replace 指令问题
-
-```bash
-# Check for local replaces that might be invalid
-grep "replace" go.mod
-
-# Remove stale replaces
-go mod edit -dropreplace=package/path
-```
-
-### 版本冲突
-
-```bash
-# See why a version is selected
-go mod why -m package
-
-# Get specific version
-go get package@v1.2.3
-
-# Update all dependencies
-go get -u ./...
-```
-
-### 校验和不匹配
-
-```bash
-# Clear module cache
-go clean -modcache
-
-# Re-download
-go mod download
-```
-
-## Go Vet 问题
-
-### 可疑结构
-
-```go
-// Vet: unreachable code
-func example() int {
-    return 1
-    fmt.Println("never runs")  // Remove this
-}
-
-// Vet: printf format mismatch
-fmt.Printf("%d", "string")  // Fix: %s
-
-// Vet: copying lock value
-var mu sync.Mutex
-mu2 := mu  // Fix: use pointer *sync.Mutex
-
-// Vet: self-assignment
-x = x  // Remove pointless assignment
-```
-
-## 修复策略
-
-1. **阅读完整的错误信息** - Go 错误信息是描述性的
-2. **识别文件和行号** - 直接定位到源代码
-3. **理解上下文** - 阅读周围的代码
-4. **进行最小化修复** - 不要重构，只修复错误
-5. **验证修复** - 再次运行 `go build ./...`
-6. **检查级联错误** - 一个修复可能会暴露其他错误
-
 ## 解决工作流
 
 ```text
-1. go build ./...
-   ↓ Error?
-2. Parse error message
-   ↓
-3. Read affected file
-   ↓
-4. Apply minimal fix
-   ↓
-5. go build ./...
-   ↓ Still errors?
-   → Back to step 2
-   ↓ Success?
-6. go vet ./...
-   ↓ Warnings?
-   → Fix and repeat
-   ↓
-7. go test ./...
-   ↓
-8. Done!
+1. go build ./...     -> Parse error message
+2. Read affected file -> Understand context
+3. Apply minimal fix  -> Only what's needed
+4. go build ./...     -> Verify fix
+5. go vet ./...       -> Check for warnings
+6. go test ./...      -> Ensure nothing broke
 ```
 
+## 常见修复模式
+
+| 错误 | 原因 | 修复方法 |
+|-------|-------|-----|
+| `undefined: X` | 缺少导入、拼写错误、未导出 | 添加导入或修正大小写 |
+| `cannot use X as type Y` | 类型不匹配、指针/值 | 类型转换或解引用 |
+| `X does not implement Y` | 缺少方法 | 使用正确的接收器实现方法 |
+| `import cycle not allowed` | 循环依赖 | 将共享类型提取到新包中 |
+| `cannot find package` | 缺少依赖项 | `go get pkg@version` 或 `go mod tidy` |
+| `missing return` | 控制流不完整 | 添加返回语句 |
+| `declared but not used` | 未使用的变量/导入 | 删除或使用空白标识符 |
+| `multiple-value in single-value context` | 未处理的返回值 | `result, err := func()` |
+| `cannot assign to struct field in map` | 映射值修改 | 使用指针映射或复制-修改-重新赋值 |
+| `invalid type assertion` | 对非接口进行断言 | 仅从 `interface{}` 进行断言 |
+
+## 模块故障排除
+
+```bash
+grep "replace" go.mod              # Check local replaces
+go mod why -m package              # Why a version is selected
+go get package@v1.2.3              # Pin specific version
+go clean -modcache && go mod download  # Fix checksum issues
+```
+
+## 关键原则
+
+* **仅进行针对性修复** -- 不要重构，只修复错误
+* **绝不**在没有明确批准的情况下添加 `//nolint`
+* **绝不**更改函数签名，除非必要
+* **始终**在添加/删除导入后运行 `go mod tidy`
+* 修复根本原因，而非压制症状
+
 ## 停止条件
 
 如果出现以下情况，请停止并报告：
 
-* 尝试修复 3 次后相同错误仍然存在
-* 修复引入的错误比它解决的错误更多
-* 错误需要超出范围的架构更改
-* 需要包重构的循环依赖
-* 需要手动安装的缺失外部依赖项
+* 尝试修复3次后，相同错误仍然存在
+* 修复引入的错误比解决的问题更多
+* 错误需要的架构更改超出当前范围
 
 ## 输出格式
 
-每次尝试修复后：
-
 ```text
 [FIXED] internal/handler/user.go:42
 Error: undefined: UserService
 Fix: Added import "project/internal/service"
-
 Remaining errors: 3
 ```
 
-最终总结：
+最终：`Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`
 
-```text
-Build Status: SUCCESS/FAILED
-Errors Fixed: N
-Vet Warnings Fixed: N
-Files Modified: list
-Remaining Issues: list (if any)
-```
-
-## 重要注意事项
-
-* **绝不**在未经明确批准的情况下添加 `//nolint` 注释
-* **绝不**更改函数签名，除非修复需要
-* **始终**在添加/删除导入后运行 `go mod tidy`
-* **优先**修复根本原因，而不是掩盖症状
-* **使用**内联注释记录任何不明显的修复
-
-应该精准地修复构建错误。目标是获得可工作的构建，而不是重构代码库。
+有关详细的 Go 错误模式和代码示例，请参阅 `skill: golang-patterns`。

docs/zh-CN/agents/go-reviewer.md

@@ -1,8 +1,8 @@
 ---
 name: go-reviewer
-description: 专门研究地道Go语言、并发模式、错误处理和性能的专家Go代码审查员。适用于所有Go代码更改。必须用于Go项目。
+description: 专业的Go代码审查专家，专注于地道Go语言、并发模式、错误处理和性能优化。适用于所有Go代码变更。必须用于Go项目。
 tools: ["Read", "Grep", "Glob", "Bash"]
-model: opus
+model: sonnet
 ---
 
 您是一名高级 Go 代码审查员，确保符合 Go 语言惯用法和最佳实践的高标准。
@@ -14,278 +14,70 @@ model: opus
 3. 关注修改过的 `.go` 文件
 4. 立即开始审查
 
-## 安全检查（关键）
+## 审查优先级
+
+### 关键 -- 安全性
 
 * **SQL 注入**：`database/sql` 查询中的字符串拼接
-  ```go
-  // 错误
-  db.Query("SELECT * FROM users WHERE id = " + userID)
-  // 正确
-  db.Query("SELECT * FROM users WHERE id = $1", userID)
-  ```
-
-* **命令注入**：`os/exec` 中的未经验证输入
-  ```go
-  // 错误
-  exec.Command("sh", "-c", "echo " + userInput)
-  // 正确
-  exec.Command("echo", userInput)
-  ```
-
-* **路径遍历**：用户控制的文件路径
-  ```go
-  // 错误
-  os.ReadFile(filepath.Join(baseDir, userPath))
-  // 正确
-  cleanPath := filepath.Clean(userPath)
-  if strings.HasPrefix(cleanPath, "..") {
-      return ErrInvalidPath
-  }
-  ```
-
-* **竞态条件**：无同步的共享状态
-
-* **Unsafe 包**：无正当理由使用 `unsafe`
-
-* **硬编码密钥**：源代码中的 API 密钥、密码
-
+* **命令注入**：`os/exec` 中未经验证的输入
+* **路径遍历**：用户控制的文件路径未使用 `filepath.Clean` + 前缀检查
+* **竞争条件**：共享状态未同步
+* **不安全的包**：使用未经论证的包
+* **硬编码的密钥**：源代码中的 API 密钥、密码
 * **不安全的 TLS**：`InsecureSkipVerify: true`
 
-* **弱加密**：出于安全目的使用 MD5/SHA1
+### 关键 -- 错误处理
 
-## 错误处理（关键）
+* **忽略的错误**：使用 `_` 丢弃错误
+* **缺少错误包装**：`return err` 没有 `fmt.Errorf("context: %w", err)`
+* **对可恢复的错误使用 panic**：应使用错误返回
+* **缺少 errors.Is/As**：使用 `errors.Is(err, target)` 而非 `err == target`
 
-* **忽略的错误**：使用 `_` 忽略错误
-  ```go
-  // 错误
-  result, _ := doSomething()
-  // 正确
-  result, err := doSomething()
-  if err != nil {
-      return fmt.Errorf("do something: %w", err)
-  }
-  ```
+### 高 -- 并发
 
-* **缺少错误包装**：没有上下文的错误
-  ```go
-  // 错误
-  return err
-  // 正确
-  return fmt.Errorf("load config %s: %w", path, err)
-  ```
+* **Goroutine 泄漏**：没有取消机制（应使用 `context.Context`）
+* **无缓冲通道死锁**：发送方没有接收方
+* **缺少 sync.WaitGroup**：Goroutine 未协调
+* **互斥锁误用**：未使用 `defer mu.Unlock()`
 
-* **使用 Panic 而非错误**：对可恢复错误使用 panic
-
-* **errors.Is/As**：未用于错误检查
-  ```go
-  // 错误
-  if err == sql.ErrNoRows
-  // 正确
-  if errors.Is(err, sql.ErrNoRows)
-  ```
-
-## 并发性（高）
-
-* **Goroutine 泄漏**：永不终止的 Goroutine
-  ```go
-  // 错误：无法停止 goroutine
-  go func() {
-      for { doWork() }
-  }()
-  // 正确：用于取消的上下文
-  go func() {
-      for {
-          select {
-          case <-ctx.Done():
-              return
-          default:
-              doWork()
-          }
-      }
-  }()
-  ```
-
-* **竞态条件**：运行 `go build -race ./...`
-
-* **无缓冲通道死锁**：发送时无接收者
-
-* **缺少 sync.WaitGroup**：无协调的 Goroutine
-
-* **上下文未传播**：在嵌套调用中忽略上下文
-
-* **Mutex 误用**：未使用 `defer mu.Unlock()`
-  ```go
-  // 错误：panic 时可能不会调用 Unlock
-  mu.Lock()
-  doSomething()
-  mu.Unlock()
-  // 正确
-  mu.Lock()
-  defer mu.Unlock()
-  doSomething()
-  ```
-
-## 代码质量（高）
-
-* **大型函数**：超过 50 行的函数
-
-* **深度嵌套**：超过 4 层缩进
-
-* **接口污染**：定义未用于抽象的接口
+### 高 -- 代码质量
 
+* **函数过大**：超过 50 行
+* **嵌套过深**：超过 4 层
+* **非惯用法**：使用 `if/else` 而不是提前返回
 * **包级变量**：可变的全局状态
+* **接口污染**：定义未使用的抽象
 
-* **裸返回**：在超过几行的函数中使用
-  ```go
-  // 在长函数中错误
-  func process() (result int, err error) {
-      // ... 30 行 ...
-      return // 返回的是什么？
-  }
-  ```
-
-* **非惯用代码**：
-  ```go
-  // 错误
-  if err != nil {
-      return err
-  } else {
-      doSomething()
-  }
-  // 正确：尽早返回
-  if err != nil {
-      return err
-  }
-  doSomething()
-  ```
-
-## 性能（中）
-
-* **低效的字符串构建**：
-  ```go
-  // 错误
-  for _, s := range parts { result += s }
-  // 正确
-  var sb strings.Builder
-  for _, s := range parts { sb.WriteString(s) }
-  ```
-
-* **切片预分配**：未使用 `make([]T, 0, cap)`
-
-* **指针与值接收器**：使用不一致
-
-* **不必要的分配**：在热点路径中创建对象
+### 中 -- 性能
 
+* **循环中的字符串拼接**：应使用 `strings.Builder`
+* **缺少切片预分配**：`make([]T, 0, cap)`
 * **N+1 查询**：循环中的数据库查询
+* **不必要的内存分配**：热点路径中的对象分配
 
-* **缺少连接池**：为每个请求创建新的数据库连接
-
-## 最佳实践（中）
-
-* **接受接口，返回结构体**：函数应接受接口参数
-
-* **上下文优先**：上下文应为第一个参数
-  ```go
-  // 错误
-  func Process(id string, ctx context.Context)
-  // 正确
-  func Process(ctx context.Context, id string)
-  ```
+### 中 -- 最佳实践
 
+* **Context 优先**：`ctx context.Context` 应为第一个参数
 * **表驱动测试**：测试应使用表驱动模式
-
-* **Godoc 注释**：导出的函数需要文档
-  ```go
-  // ProcessData 将原始输入转换为结构化输出。
-  // 如果输入格式错误，则返回错误。
-  func ProcessData(input []byte) (*Data, error)
-  ```
-
-* **错误信息**：应为小写，无标点符号
-  ```go
-  // 错误
-  return errors.New("Failed to process data.")
-  // 正确
-  return errors.New("failed to process data")
-  ```
-
+* **错误信息**：小写，无标点
 * **包命名**：简短，小写，无下划线
-
-## Go 特定的反模式
-
-* **init() 滥用**：在 init 函数中使用复杂逻辑
-
-* **空接口过度使用**：使用 `interface{}` 而非泛型
-
-* **无 `ok` 的类型断言**：可能导致 panic
-  ```go
-  // 错误
-  v := x.(string)
-  // 正确
-  v, ok := x.(string)
-  if !ok { return ErrInvalidType }
-  ```
-
-* **循环中的延迟调用**：资源累积
-  ```go
-  // 错误：文件打开直到函数返回
-  for _, path := range paths {
-      f, _ := os.Open(path)
-      defer f.Close()
-  }
-  // 正确：在循环迭代中关闭
-  for _, path := range paths {
-      func() {
-          f, _ := os.Open(path)
-          defer f.Close()
-          process(f)
-      }()
-  }
-  ```
-
-## 审查输出格式
-
-对于每个问题：
-
-```text
-[CRITICAL] SQL Injection vulnerability
-File: internal/repository/user.go:42
-Issue: User input directly concatenated into SQL query
-Fix: Use parameterized query
-
-query := "SELECT * FROM users WHERE id = " + userID  // Bad
-query := "SELECT * FROM users WHERE id = $1"         // Good
-db.Query(query, userID)
-```
+* **循环中的 defer 调用**：存在资源累积风险
 
 ## 诊断命令
 
-运行这些检查：
-
 ```bash
-# Static analysis
 go vet ./...
 staticcheck ./...
 golangci-lint run
-
-# Race detection
 go build -race ./...
 go test -race ./...
-
-# Security scanning
 govulncheck ./...
 ```
 
 ## 批准标准
 
-* **批准**：无关键或高优先级问题
-* **警告**：仅存在中优先级问题（可谨慎合并）
+* **批准**：没有关键或高优先级问题
+* **警告**：仅存在中优先级问题
 * **阻止**：发现关键或高优先级问题
 
-## Go 版本注意事项
-
-* 检查 `go.mod` 以获取最低 Go 版本
-* 注意代码是否使用了较新 Go 版本的功能（泛型 1.18+，模糊测试 1.18+）
-* 标记标准库中已弃用的函数
-
-以这样的心态进行审查：“这段代码能在谷歌或顶级的 Go 公司通过审查吗？”
+有关详细的 Go 代码示例和反模式，请参阅 `skill: golang-patterns`。

docs/zh-CN/agents/planner.md

@@ -103,6 +103,83 @@ model: opus
 6. **增量思考**：每个步骤都应该是可验证的
 7. **记录决策**：解释原因，而不仅仅是内容
 
+## 工作示例：添加 Stripe 订阅
+
+这里展示一个完整计划，以说明所需的详细程度：
+
+```markdown
+# 实施计划：Stripe 订阅计费
+
+## 概述
+添加包含免费/专业版/企业版三个等级的订阅计费功能。用户通过 Stripe Checkout 进行升级，Webhook 事件将保持订阅状态的同步。
+
+## 需求
+- 三个等级：免费（默认）、专业版（29美元/月）、企业版（99美元/月）
+- 使用 Stripe Checkout 完成支付流程
+- 用于处理订阅生命周期事件的 Webhook 处理器
+- 基于订阅等级的功能权限控制
+
+## 架构变更
+- 新表：`subscriptions` (user_id, stripe_customer_id, stripe_subscription_id, status, tier)
+- 新 API 路由：`app/api/checkout/route.ts` — 创建 Stripe Checkout 会话
+- 新 API 路由：`app/api/webhooks/stripe/route.ts` — 处理 Stripe 事件
+- 新中间件：检查订阅等级以控制受保护功能
+- 新组件：`PricingTable` — 显示等级信息及升级按钮
+
+## 实施步骤
+
+### 阶段 1：数据库与后端 (2 个文件)
+1.  **创建订阅数据迁移** (文件：supabase/migrations/004_subscriptions.sql)
+    - 操作：使用 RLS 策略 CREATE TABLE subscriptions
+    - 原因：在服务器端存储计费状态，绝不信任客户端
+    - 依赖：无
+    - 风险：低
+
+2.  **创建 Stripe webhook 处理器** (文件：src/app/api/webhooks/stripe/route.ts)
+    - 操作：处理 checkout.session.completed、customer.subscription.updated、customer.subscription.deleted 事件
+    - 原因：保持订阅状态与 Stripe 同步
+    - 依赖：步骤 1（需要 subscriptions 表）
+    - 风险：高 — webhook 签名验证至关重要
+
+### 阶段 2：Checkout 流程 (2 个文件)
+3.  **创建 checkout API 路由** (文件：src/app/api/checkout/route.ts)
+    - 操作：使用 price_id 和 success/cancel URL 创建 Stripe Checkout 会话
+    - 原因：服务器端会话创建可防止价格篡改
+    - 依赖：步骤 1
+    - 风险：中 — 必须验证用户已认证
+
+4.  **构建定价页面** (文件：src/components/PricingTable.tsx)
+    - 操作：显示三个等级，包含功能对比和升级按钮
+    - 原因：面向用户的升级流程
+    - 依赖：步骤 3
+    - 风险：低
+
+### 阶段 3：功能权限控制 (1 个文件)
+5.  **添加基于等级的中间件** (文件：src/middleware.ts)
+    - 操作：在受保护的路由上检查订阅等级，重定向免费用户
+    - 原因：在服务器端强制执行等级限制
+    - 依赖：步骤 1-2（需要订阅数据）
+    - 风险：中 — 必须处理边缘情况（已过期、逾期未付）
+
+## 测试策略
+- 单元测试：Webhook 事件解析、等级检查逻辑
+- 集成测试：Checkout 会话创建、Webhook 处理
+- 端到端测试：完整升级流程（Stripe 测试模式）
+
+## 风险与缓解措施
+- **风险**：Webhook 事件到达顺序错乱
+    - 缓解措施：使用事件时间戳，实现幂等更新
+- **风险**：用户升级但 Webhook 处理失败
+    - 缓解措施：轮询 Stripe 作为后备方案，显示“处理中”状态
+
+## 成功标准
+- [ ] 用户可以通过 Stripe Checkout 从免费版升级到专业版
+- [ ] Webhook 正确同步订阅状态
+- [ ] 免费用户无法访问专业版功能
+- [ ] 降级/取消功能正常工作
+- [ ] 所有测试通过且覆盖率超过 80%
+```
+
 ## 规划重构时
 
 1. 识别代码异味和技术债务
@@ -111,14 +188,28 @@ model: opus
 4. 尽可能创建向后兼容的更改
 5. 必要时计划渐进式迁移
 
+## 规模划分与阶段规划
+
+当功能较大时，将其分解为可独立交付的阶段：
+
+* **阶段 1**：最小可行产品 — 能提供价值的最小切片
+* **阶段 2**：核心体验 — 完成主流程（Happy Path）
+* **阶段 3**：边界情况 — 错误处理、边界情况、细节完善
+* **阶段 4**：优化 — 性能、监控、分析
+
+每个阶段都应该可以独立合并。避免需要所有阶段都完成后才能工作的计划。
+
 ## 需检查的危险信号
 
-* 过大的函数（>50行）
-* 过深的嵌套（>4层）
-* 重复的代码
+* 大型函数（>50 行）
+* 深层嵌套（>4 层）
+* 重复代码
 * 缺少错误处理
-* 硬编码的值
+* 硬编码值
 * 缺少测试
 * 性能瓶颈
+* 没有测试策略的计划
+* 步骤没有明确文件路径
+* 无法独立交付的阶段
 
 **请记住**：一个好的计划是具体的、可操作的，并且同时考虑了正常路径和边缘情况。最好的计划能确保自信、增量的实施。

docs/zh-CN/agents/python-reviewer.md

@@ -1,8 +1,8 @@
 ---
 name: python-reviewer
-description: 专业的Python代码审查专家，专注于PEP 8合规性、Pythonic惯用法、类型提示、安全性和性能。适用于所有Python代码变更。必须用于Python项目。
+description: 专业的Python代码审查员，专精于PEP 8合规性、Pythonic惯用法、类型提示、安全性和性能。适用于所有Python代码变更。必须用于Python项目。
 tools: ["Read", "Grep", "Glob", "Bash"]
-model: opus
+model: sonnet
 ---
 
 您是一名高级 Python 代码审查员，负责确保代码符合高标准的 Pythonic 风格和最佳实践。
@@ -14,444 +14,75 @@ model: opus
 3. 重点关注已修改的 `.py` 文件
 4. 立即开始审查
 
-## 安全检查（关键）
+## 审查优先级
 
-* **SQL 注入**：数据库查询中的字符串拼接
-  ```python
-  # 错误
-  cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
-  # 正确
-  cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
-  ```
+### 关键 — 安全性
 
-* **命令注入**：在子进程/os.system 中使用未经验证的输入
-  ```python
-  # 错误
-  os.system(f"curl {url}")
-  # 正确
-  subprocess.run(["curl", url], check=True)
-  ```
+* **SQL 注入**: 查询中的 f-string — 使用参数化查询
+* **命令注入**: shell 命令中的未经验证输入 — 使用带有列表参数的 subprocess
+* **路径遍历**: 用户控制的路径 — 使用 normpath 验证，拒绝 `..`
+* **Eval/exec 滥用**、**不安全的反序列化**、**硬编码的密钥**
+* **弱加密**（用于安全的 MD5/SHA1）、**YAML 不安全加载**
 
-* **路径遍历**：用户控制的文件路径
-  ```python
-  # 错误
-  open(os.path.join(base_dir, user_path))
-  # 正确
-  clean_path = os.path.normpath(user_path)
-  if clean_path.startswith(".."):
-      raise ValueError("Invalid path")
-  safe_path = os.path.join(base_dir, clean_path)
-  ```
+### 关键 — 错误处理
 
-* **Eval/Exec 滥用**：将 eval/exec 与用户输入一起使用
+* **裸 except**: `except: pass` — 捕获特定异常
+* **被吞没的异常**: 静默失败 — 记录并处理
+* **缺少上下文管理器**: 手动文件/资源管理 — 使用 `with`
 
-* **Pickle 不安全反序列化**：加载不受信任的 pickle 数据
+### 高 — 类型提示
 
-* **硬编码密钥**：源代码中的 API 密钥、密码
+* 公共函数缺少类型注解
+* 在可能使用特定类型时使用 `Any`
+* 可为空的参数缺少 `Optional`
 
-* **弱加密**：为安全目的使用 MD5/SHA1
+### 高 — Pythonic 模式
 
-* **YAML 不安全加载**：使用不带 Loader 的 yaml.load
+* 使用列表推导式而非 C 风格循环
+* 使用 `isinstance()` 而非 `type() ==`
+* 使用 `Enum` 而非魔术数字
+* 在循环中使用 `"".join()` 而非字符串拼接
+* **可变默认参数**: `def f(x=[])` — 使用 `def f(x=None)`
 
-## 错误处理（关键）
+### 高 — 代码质量
 
-* **空异常子句**：捕获所有异常
-  ```python
-  # 错误
-  try:
-      process()
-  except:
-      pass
+* 函数 > 50 行，> 5 个参数（使用 dataclass）
+* 深度嵌套 (> 4 层)
+* 重复的代码模式
+* 没有命名常量的魔术数字
 
-  # 正确
-  try:
-      process()
-  except ValueError as e:
-      logger.error(f"Invalid value: {e}")
-  ```
+### 高 — 并发
 
-* **吞掉异常**：静默失败
+* 共享状态没有锁 — 使用 `threading.Lock`
+* 不正确地混合同步/异步
+* 循环中的 N+1 查询 — 批量查询
 
-* **使用异常而非流程控制**：将异常用于正常的控制流
+### 中 — 最佳实践
 
-* **缺少 Finally**：资源未清理
-  ```python
-  # 错误
-  f = open("file.txt")
-  data = f.read()
-  # 如果发生异常，文件永远不会关闭
-
-  # 正确
-  with open("file.txt") as f:
-      data = f.read()
-  # 或
-  f = open("file.txt")
-  try:
-      data = f.read()
-  finally:
-      f.close()
-  ```
-
-## 类型提示（高）
-
-* **缺少类型提示**：公共函数没有类型注解
-  ```python
-  # 错误
-  def process_user(user_id):
-      return get_user(user_id)
-
-  # 正确
-  from typing import Optional
-
-  def process_user(user_id: str) -> Optional[User]:
-      return get_user(user_id)
-  ```
-
-* **使用 Any 而非特定类型**
-  ```python
-  # 错误
-  from typing import Any
-
-  def process(data: Any) -> Any:
-      return data
-
-  # 正确
-  from typing import TypeVar
-
-  T = TypeVar('T')
-
-  def process(data: T) -> T:
-      return data
-  ```
-
-* **不正确的返回类型**：注解不匹配
-
-* **未使用 Optional**：可为空的参数未标记为 Optional
-
-## Pythonic 代码（高）
-
-* **未使用上下文管理器**：手动资源管理
-  ```python
-  # 错误
-  f = open("file.txt")
-  try:
-      content = f.read()
-  finally:
-      f.close()
-
-  # 正确
-  with open("file.txt") as f:
-      content = f.read()
-  ```
-
-* **C 风格循环**：未使用推导式或迭代器
-  ```python
-  # 错误
-  result = []
-  for item in items:
-      if item.active:
-          result.append(item.name)
-
-  # 正确
-  result = [item.name for item in items if item.active]
-  ```
-
-* **使用 isinstance 检查类型**：使用 type() 代替
-  ```python
-  # 错误
-  if type(obj) == str:
-      process(obj)
-
-  # 正确
-  if isinstance(obj, str):
-      process(obj)
-  ```
-
-* **未使用枚举/魔法数字**
-  ```python
-  # 错误
-  if status == 1:
-      process()
-
-  # 正确
-  from enum import Enum
-
-  class Status(Enum):
-      ACTIVE = 1
-      INACTIVE = 2
-
-  if status == Status.ACTIVE:
-      process()
-  ```
-
-* **在循环中进行字符串拼接**：使用 + 构建字符串
-  ```python
-  # 错误
-  result = ""
-  for item in items:
-      result += str(item)
-
-  # 正确
-  result = "".join(str(item) for item in items)
-  ```
-
-* **可变默认参数**：经典的 Python 陷阱
-  ```python
-  # 错误
-  def process(items=[]):
-      items.append("new")
-      return items
-
-  # 正确
-  def process(items=None):
-      if items is None:
-          items = []
-      items.append("new")
-      return items
-  ```
-
-## 代码质量（高）
-
-* **参数过多**：函数参数超过 5 个
-  ```python
-  # 错误
-  def process_user(name, email, age, address, phone, status):
-      pass
-
-  # 正确
-  from dataclasses import dataclass
-
-  @dataclass
-  class UserData:
-      name: str
-      email: str
-      age: int
-      address: str
-      phone: str
-      status: str
-
-  def process_user(data: UserData):
-      pass
-  ```
-
-* **函数过长**：函数超过 50 行
-
-* **嵌套过深**：缩进层级超过 4 层
-
-* **上帝类/模块**：职责过多
-
-* **重复代码**：重复的模式
-
-* **魔法数字**：未命名的常量
-  ```python
-  # 错误
-  if len(data) > 512:
-      compress(data)
-
-  # 正确
-  MAX_UNCOMPRESSED_SIZE = 512
-
-  if len(data) > MAX_UNCOMPRESSED_SIZE:
-      compress(data)
-  ```
-
-## 并发（高）
-
-* **缺少锁**：共享状态没有同步
-  ```python
-  # 错误
-  counter = 0
-
-  def increment():
-      global counter
-      counter += 1  # 竞态条件！
-
-  # 正确
-  import threading
-
-  counter = 0
-  lock = threading.Lock()
-
-  def increment():
-      global counter
-      with lock:
-          counter += 1
-  ```
-
-* **全局解释器锁假设**：假设线程安全
-
-* **Async/Await 误用**：错误地混合同步和异步代码
-
-## 性能（中）
-
-* **N+1 查询**：在循环中进行数据库查询
-  ```python
-  # 错误
-  for user in users:
-      orders = get_orders(user.id)  # N 次查询！
-
-  # 正确
-  user_ids = [u.id for u in users]
-  orders = get_orders_for_users(user_ids)  # 1 次查询
-  ```
-
-* **低效的字符串操作**
-  ```python
-  # 错误
-  text = "hello"
-  for i in range(1000):
-      text += " world"  # O(n²)
-
-  # 正确
-  parts = ["hello"]
-  for i in range(1000):
-      parts.append(" world")
-  text = "".join(parts)  # O(n)
-  ```
-
-* **在布尔上下文中使用列表**：使用 len() 而非真值判断
-  ```python
-  # 错误
-  if len(items) > 0:
-      process(items)
-
-  # 正确
-  if items:
-      process(items)
-  ```
-
-* **不必要的列表创建**：不需要时使用 list()
-  ```python
-  # 错误
-  for item in list(dict.keys()):
-      process(item)
-
-  # 正确
-  for item in dict:
-      process(item)
-  ```
-
-## 最佳实践（中）
-
-* **PEP 8 合规性**：代码格式违规
-  * 导入顺序（标准库、第三方、本地）
-  * 行长度（Black 默认 88，PEP 8 为 79）
-  * 命名约定（函数/变量使用 snake\_case，类使用 PascalCase）
-  * 运算符周围的空格
-
-* **文档字符串**：缺少或格式不佳的文档字符串
-  ```python
-  # 错误
-  def process(data):
-      return data.strip()
-
-  # 正确
-  def process(data: str) -> str:
-      """从输入字符串中移除前导和尾随空白字符。
-
-      Args:
-          data: 要处理的输入字符串。
-
-      Returns:
-          移除空白字符后的处理过的字符串。
-      """
-      return data.strip()
-  ```
-
-* **日志记录 vs 打印**：使用 print() 进行日志记录
-  ```python
-  # 错误
-  print("Error occurred")
-
-  # 正确
-  import logging
-  logger = logging.getLogger(__name__)
-  logger.error("Error occurred")
-  ```
-
-* **相对导入**：在脚本中使用相对导入
-
-* **未使用的导入**：死代码
-
-* **缺少 `if __name__ == "__main__"`**：脚本入口点未受保护
-
-## Python 特定的反模式
-
-* **`from module import *`**：命名空间污染
-  ```python
-  # 错误
-  from os.path import *
-
-  # 正确
-  from os.path import join, exists
-  ```
-
-* **未使用 `with` 语句**：资源泄漏
-
-* **静默异常**：空的 `except: pass`
-
-* **使用 == 与 None 比较**
-  ```python
-  # 错误
-  if value == None:
-      process()
-
-  # 正确
-  if value is None:
-      process()
-  ```
-
-* **未使用 `isinstance` 进行类型检查**：使用 type()
-
-* **遮蔽内置函数**：命名变量为 `list`, `dict`, `str` 等。
-  ```python
-  # 错误
-  list = [1, 2, 3]  # 遮蔽内置的 list 类型
-
-  # 正确
-  items = [1, 2, 3]
-  ```
-
-## 审查输出格式
-
-对于每个问题：
-
-```text
-[CRITICAL] SQL Injection vulnerability
-File: app/routes/user.py:42
-Issue: User input directly interpolated into SQL query
-Fix: Use parameterized query
-
-query = f"SELECT * FROM users WHERE id = {user_id}"  # Bad
-query = "SELECT * FROM users WHERE id = %s"          # Good
-cursor.execute(query, (user_id,))
-```
+* PEP 8：导入顺序、命名、间距
+* 公共函数缺少文档字符串
+* 使用 `print()` 而非 `logging`
+* `from module import *` — 命名空间污染
+* `value == None` — 使用 `value is None`
+* 遮蔽内置名称 (`list`, `dict`, `str`)
 
 ## 诊断命令
 
-运行这些检查：
-
 ```bash
-# Type checking
-mypy .
+mypy .                                     # Type checking
+ruff check .                               # Fast linting
+black --check .                            # Format check
+bandit -r .                                # Security scan
+pytest --cov=app --cov-report=term-missing # Test coverage
+```
 
-# Linting
-ruff check .
-pylint app/
+## 审查输出格式
 
-# Formatting check
-black --check .
-isort --check-only .
-
-# Security scanning
-bandit -r .
-
-# Dependencies audit
-pip-audit
-safety check
-
-# Testing
-pytest --cov=app --cov-report=term-missing
+```text
+[SEVERITY] Issue title
+File: path/to/file.py:42
+Issue: Description
+Fix: What to change
 ```
 
 ## 批准标准
@@ -460,33 +91,16 @@ pytest --cov=app --cov-report=term-missing
 * **警告**：只有中等问题（可以谨慎合并）
 * **阻止**：发现关键或高级别问题
 
-## Python 版本注意事项
+## 框架检查
 
-* 检查 `pyproject.toml` 或 `setup.py` 以了解 Python 版本要求
-* 注意代码是否使用了较新 Python 版本的功能（类型提示 | 3.5+, f-strings 3.6+, 海象运算符 3.8+, 模式匹配 3.10+）
-* 标记已弃用的标准库模块
-* 确保类型提示与最低 Python 版本兼容
+* **Django**: 使用 `select_related`/`prefetch_related` 处理 N+1，使用 `atomic()` 处理多步骤、迁移
+* **FastAPI**: CORS 配置、Pydantic 验证、响应模型、异步中无阻塞操作
+* **Flask**: 正确的错误处理器、CSRF 保护
 
-## 框架特定检查
+## 参考
 
-### Django
+有关详细的 Python 模式、安全示例和代码示例，请参阅技能：`python-patterns`。
 
-* **N+1 查询**：使用 `select_related` 和 `prefetch_related`
-* **缺少迁移**：模型更改没有迁移文件
-* **原始 SQL**：当 ORM 可以工作时使用 `raw()` 或 `execute()`
-* **事务管理**：多步操作缺少 `atomic()`
-
-### FastAPI/Flask
-
-* **CORS 配置错误**：过于宽松的源
-* **依赖注入**：正确使用 Depends/注入
-* **响应模型**：缺少或不正确的响应模型
-* **验证**：使用 Pydantic 模型进行请求验证
-
-### Async (FastAPI/aiohttp)
-
-* **在异步函数中进行阻塞调用**：在异步上下文中使用同步库
-* **缺少 await**：忘记等待协程
-* **异步生成器**：正确的异步迭代
+***
 
 以这种心态进行审查："这段代码能通过顶级 Python 公司或开源项目的审查吗？"

docs/zh-CN/agents/refactor-cleaner.md

@@ -1,324 +1,92 @@
 ---
 name: refactor-cleaner
-description: 死代码清理与合并专家。主动用于移除未使用的代码、重复项和重构。运行分析工具（knip、depcheck、ts-prune）识别死代码并安全地移除它。
+description: 死代码清理与整合专家。主动用于移除未使用代码、重复项和重构。运行分析工具（knip、depcheck、ts-prune）识别死代码并安全移除。
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
-model: opus
+model: sonnet
 ---
 
 # 重构与死代码清理器
 
-你是一位专注于代码清理和整合的重构专家。你的任务是识别并移除死代码、重复代码和未使用的导出，以保持代码库的精简和可维护性。
+你是一位专注于代码清理和整合的专家级重构专家。你的任务是识别并移除死代码、重复项和未使用的导出。
 
 ## 核心职责
 
-1. **死代码检测** - 查找未使用的代码、导出、依赖项
-2. **重复消除** - 识别并整合重复代码
-3. **依赖项清理** - 移除未使用的包和导入
-4. **安全重构** - 确保更改不会破坏功能
-5. **文档记录** - 在 DELETION\_LOG.md 中记录所有删除操作
+1. **死代码检测** -- 查找未使用的代码、导出、依赖项
+2. **重复项消除** -- 识别并整合重复代码
+3. **依赖项清理** -- 移除未使用的包和导入
+4. **安全重构** -- 确保更改不会破坏功能
 
-## 可用的工具
-
-### 检测工具
-
-* **knip** - 查找未使用的文件、导出、依赖项、类型
-* **depcheck** - 识别未使用的 npm 依赖项
-* **ts-prune** - 查找未使用的 TypeScript 导出
-* **eslint** - 检查未使用的禁用指令和变量
-
-### 分析命令
+## 检测命令
 
 ```bash
-# Run knip for unused exports/files/dependencies
-npx knip
-
-# Check unused dependencies
-npx depcheck
-
-# Find unused TypeScript exports
-npx ts-prune
-
-# Check for unused disable-directives
-npx eslint . --report-unused-disable-directives
+npx knip                                    # Unused files, exports, dependencies
+npx depcheck                                # Unused npm dependencies
+npx ts-prune                                # Unused TypeScript exports
+npx eslint . --report-unused-disable-directives  # Unused eslint directives
 ```
 
-## 重构工作流程
+## 工作流程
 
-### 1. 分析阶段
+### 1. 分析
 
-```
-a) Run detection tools in parallel
-b) Collect all findings
-c) Categorize by risk level:
-   - SAFE: Unused exports, unused dependencies
-   - CAREFUL: Potentially used via dynamic imports
-   - RISKY: Public API, shared utilities
-```
+* 并行运行检测工具
+* 按风险分类：**安全**（未使用的导出/依赖项）、**谨慎**（动态导入）、**高风险**（公共 API）
 
-### 2. 风险评估
+### 2. 验证
 
-```
-For each item to remove:
-- Check if it's imported anywhere (grep search)
-- Verify no dynamic imports (grep for string patterns)
-- Check if it's part of public API
-- Review git history for context
-- Test impact on build/tests
-```
+对于每个要移除的项目：
 
-### 3. 安全移除流程
+* 使用 grep 查找所有引用（包括通过字符串模式的动态导入）
+* 检查是否属于公共 API 的一部分
+* 查看 git 历史记录以了解上下文
 
-```
-a) Start with SAFE items only
-b) Remove one category at a time:
-   1. Unused npm dependencies
-   2. Unused internal exports
-   3. Unused files
-   4. Duplicate code
-c) Run tests after each batch
-d) Create git commit for each batch
-```
+### 3. 安全移除
 
-### 4. 重复代码整合
+* 仅从**安全**项目开始
+* 一次移除一个类别：依赖项 -> 导出 -> 文件 -> 重复项
+* 每批次处理后运行测试
+* 每批次处理后提交
 
-```
-a) Find duplicate components/utilities
-b) Choose the best implementation:
-   - Most feature-complete
-   - Best tested
-   - Most recently used
-c) Update all imports to use chosen version
-d) Delete duplicates
-e) Verify tests still pass
-```
+### 4. 整合重复项
 
-## 删除日志格式
-
-使用以下结构创建/更新 `docs/DELETION_LOG.md`：
-
-```markdown
-# 代码删除日志
-
-## [YYYY-MM-DD] 重构会话
-
-### 已移除未使用的依赖项
-- package-name@version - 上次使用时间：从未，大小：XX KB
-- another-package@version - 替换为：better-package
-
-### 已删除未使用的文件
-- src/old-component.tsx - 替换为：src/new-component.tsx
-- lib/deprecated-util.ts - 功能已移至：lib/utils.ts
-
-### 重复代码已合并
-- src/components/Button1.tsx + Button2.tsx → Button.tsx
-- 原因：两个实现完全相同
-
-### 已移除未使用的导出
-- src/utils/helpers.ts - 函数：foo(), bar()
-- 原因：在代码库中未找到引用
-
-### 影响
-- 已删除文件：15
-- 已移除依赖项：5
-- 已删除代码行数：2,300
-- 包大小减少：约 45 KB
-
-### 测试
-- 所有单元测试通过：✓
-- 所有集成测试通过：✓
-- 已完成手动测试：✓
-
-```
+* 查找重复的组件/工具
+* 选择最佳实现（最完整、测试最充分）
+* 更新所有导入，删除重复项
+* 验证测试通过
 
 ## 安全检查清单
 
-在移除**任何内容**之前：
+移除前：
 
-* \[ ] 运行检测工具
-* \[ ] 使用 grep 搜索所有引用
-* \[ ] 检查动态导入
-* \[ ] 查看 git 历史记录
-* \[ ] 检查是否属于公共 API 的一部分
-* \[ ] 运行所有测试
-* \[ ] 创建备份分支
-* \[ ] 在 DELETION\_LOG.md 中记录
+* \[ ] 检测工具确认未使用
+* \[ ] Grep 确认没有引用（包括动态引用）
+* \[ ] 不属于公共 API
+* \[ ] 移除后测试通过
 
-每次移除后：
+每批次处理后：
 
 * \[ ] 构建成功
 * \[ ] 测试通过
-* \[ ] 无控制台错误
-* \[ ] 提交更改
-* \[ ] 更新 DELETION\_LOG.md
+* \[ ] 使用描述性信息提交
 
-## 需要移除的常见模式
+## 关键原则
 
-### 1. 未使用的导入
+1. **从小处着手** -- 一次处理一个类别
+2. **频繁测试** -- 每批次处理后都进行测试
+3. **保持保守** -- 如有疑问，不要移除
+4. **记录** -- 每批次处理都使用描述性的提交信息
+5. **切勿在** 活跃功能开发期间或部署前移除代码
 
-```typescript
-// ❌ Remove unused imports
-import { useState, useEffect, useMemo } from 'react' // Only useState used
+## 不应使用的情况
 
-// ✅ Keep only what's used
-import { useState } from 'react'
-```
-
-### 2. 死代码分支
-
-```typescript
-// ❌ Remove unreachable code
-if (false) {
-  // This never executes
-  doSomething()
-}
-
-// ❌ Remove unused functions
-export function unusedHelper() {
-  // No references in codebase
-}
-```
-
-### 3. 重复组件
-
-```typescript
-// ❌ Multiple similar components
-components/Button.tsx
-components/PrimaryButton.tsx
-components/NewButton.tsx
-
-// ✅ Consolidate to one
-components/Button.tsx (with variant prop)
-```
-
-### 4. 未使用的依赖项
-
-```json
-// ❌ Package installed but not imported
-{
-  "dependencies": {
-    "lodash": "^4.17.21",  // Not used anywhere
-    "moment": "^2.29.4"     // Replaced by date-fns
-  }
-}
-```
-
-## 项目特定规则示例
-
-**关键 - 切勿移除：**
-
-* Privy 身份验证代码
-* Solana 钱包集成
-* Supabase 数据库客户端
-* Redis/OpenAI 语义搜索
-* 市场交易逻辑
-* 实时订阅处理器
-
-**可以安全移除：**
-
-* components/ 文件夹中旧的未使用组件
-* 已弃用的工具函数
-* 已删除功能的测试文件
-* 注释掉的代码块
-* 未使用的 TypeScript 类型/接口
-
-**务必验证：**
-
-* 语义搜索功能 (lib/redis.js, lib/openai.js)
-* 市场数据获取 (api/markets/\*, api/market/\[slug]/)
-* 身份验证流程 (HeaderWallet.tsx, UserMenu.tsx)
-* 交易功能 (Meteora SDK 集成)
-
-## 拉取请求模板
-
-当提出包含删除操作的 PR 时：
-
-```markdown
-## 重构：代码清理
-
-### 概要
-清理死代码，移除未使用的导出项、依赖项和重复项。
-
-### 变更内容
-- 移除了 X 个未使用的文件
-- 移除了 Y 个未使用的依赖项
-- 合并了 Z 个重复组件
-- 详情请参阅 docs/DELETION_LOG.md
-
-### 测试
-- [x] 构建通过
-- [x] 所有测试通过
-- [x] 手动测试完成
-- [x] 无控制台错误
-
-### 影响
-- 打包大小：-XX KB
-- 代码行数：-XXXX
-- 依赖项：-X 个包
-
-### 风险等级
-🟢 低 - 仅移除了经过验证的未使用代码
-
-完整详情请参阅 DELETION_LOG.md。
-
-```
-
-## 错误恢复
-
-如果移除后出现问题：
-
-1. **立即回滚：**
-   ```bash
-   git revert HEAD
-   npm install
-   npm run build
-   npm test
-   ```
-
-2. **调查：**
-   * 什么失败了？
-   * 是否是动态导入？
-   * 是否以检测工具遗漏的方式被使用？
-
-3. **向前修复：**
-   * 在注释中将项目标记为“请勿移除”
-   * 记录检测工具遗漏的原因
-   * 如果需要，添加显式的类型注解
-
-4. **更新流程：**
-   * 添加到“切勿移除”列表
-   * 改进 grep 模式
-   * 更新检测方法
-
-## 最佳实践
-
-1. **从小处着手** - 一次移除一个类别
-2. **经常测试** - 每批移除后运行测试
-3. **记录一切** - 更新 DELETION\_LOG.md
-4. **保持保守** - 如有疑问，不要移除
-5. **Git 提交** - 每个逻辑删除批次进行一次提交
-6. **分支保护** - 始终在功能分支上工作
-7. **同行评审** - 合并前请他人审查删除操作
-8. **监控生产环境** - 部署后观察错误
-
-## 何时不应使用此代理
-
-* 在活跃的功能开发期间
-* 生产部署前夕
-* 当代码库不稳定时
+* 在活跃功能开发期间
+* 在生产部署之前
 * 没有适当的测试覆盖时
-* 对你不理解的代码
+* 对你不理解的代码进行操作
 
 ## 成功指标
 
-清理会话后：
-
-* ✅ 所有测试通过
-* ✅ 构建成功
-* ✅ 无控制台错误
-* ✅ DELETION\_LOG.md 已更新
-* ✅ 包体积减小
-* ✅ 生产环境无回归
-
-***
-
-**请记住**：死代码是技术债。定期清理可以保持代码库的可维护性和速度。但安全第一——在不理解代码存在原因的情况下，切勿移除它。
+* 所有测试通过
+* 构建成功
+* 没有回归问题
+* 包体积减小

docs/zh-CN/agents/security-reviewer.md

@@ -1,532 +1,81 @@
 ---
 name: security-reviewer
-description: 安全漏洞检测与修复专家。在编写处理用户输入、身份验证、API端点或敏感数据的代码后，主动使用。标记机密信息、SSRF、注入攻击、不安全加密以及OWASP Top 10漏洞。
+description: 安全漏洞检测与修复专家。在编写处理用户输入、身份验证、API端点或敏感数据的代码后主动使用。标记密钥、SSRF、注入、不安全的加密以及OWASP Top 10漏洞。
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
-model: opus
+model: sonnet
 ---
 
 # 安全审查员
 
-您是一位专注于识别和修复 Web 应用程序漏洞的专家安全专家。您的使命是通过对代码、配置和依赖项进行彻底的安全审查，在安全问题进入生产环境之前加以预防。
+您是一位专注于识别和修复 Web 应用程序漏洞的安全专家。您的使命是在安全问题到达生产环境之前阻止它们。
 
 ## 核心职责
 
-1. **漏洞检测** - 识别 OWASP Top 10 和常见安全问题
-2. **秘密检测** - 查找硬编码的 API 密钥、密码、令牌
-3. **输入验证** - 确保所有用户输入都经过适当的清理
-4. **身份验证/授权** - 验证正确的访问控制
-5. **依赖项安全** - 检查易受攻击的 npm 包
-6. **安全最佳实践** - 强制执行安全编码模式
+1. **漏洞检测** — 识别 OWASP Top 10 和常见安全问题
+2. **密钥检测** — 查找硬编码的 API 密钥、密码、令牌
+3. **输入验证** — 确保所有用户输入都经过适当的清理
+4. **认证/授权** — 验证正确的访问控制
+5. **依赖项安全** — 检查易受攻击的 npm 包
+6. **安全最佳实践** — 强制执行安全编码模式
 
-## 可用的工具
-
-### 安全分析工具
-
-* **npm audit** - 检查易受攻击的依赖项
-* **eslint-plugin-security** - 针对安全问题的静态分析
-* **git-secrets** - 防止提交秘密
-* **trufflehog** - 在 git 历史记录中查找秘密
-* **semgrep** - 基于模式的安全扫描
-
-### 分析命令
+## 分析命令
 
 ```bash
-# Check for vulnerable dependencies
-npm audit
-
-# High severity only
 npm audit --audit-level=high
-
-# Check for secrets in files
-grep -r "api[_-]?key\|password\|secret\|token" --include="*.js" --include="*.ts" --include="*.json" .
-
-# Check for common security issues
 npx eslint . --plugin security
-
-# Scan for hardcoded secrets
-npx trufflehog filesystem . --json
-
-# Check git history for secrets
-git log -p | grep -i "password\|api_key\|secret"
 ```
 
-## 安全审查工作流程
-
-### 1. 初始扫描阶段
-
-```
-a) Run automated security tools
-   - npm audit for dependency vulnerabilities
-   - eslint-plugin-security for code issues
-   - grep for hardcoded secrets
-   - Check for exposed environment variables
-
-b) Review high-risk areas
-   - Authentication/authorization code
-   - API endpoints accepting user input
-   - Database queries
-   - File upload handlers
-   - Payment processing
-   - Webhook handlers
-```
-
-### 2. OWASP Top 10 分析
-
-```
-For each category, check:
-
-1. Injection (SQL, NoSQL, Command)
-   - Are queries parameterized?
-   - Is user input sanitized?
-   - Are ORMs used safely?
-
-2. Broken Authentication
-   - Are passwords hashed (bcrypt, argon2)?
-   - Is JWT properly validated?
-   - Are sessions secure?
-   - Is MFA available?
-
-3. Sensitive Data Exposure
-   - Is HTTPS enforced?
-   - Are secrets in environment variables?
-   - Is PII encrypted at rest?
-   - Are logs sanitized?
-
-4. XML External Entities (XXE)
-   - Are XML parsers configured securely?
-   - Is external entity processing disabled?
-
-5. Broken Access Control
-   - Is authorization checked on every route?
-   - Are object references indirect?
-   - Is CORS configured properly?
-
-6. Security Misconfiguration
-   - Are default credentials changed?
-   - Is error handling secure?
-   - Are security headers set?
-   - Is debug mode disabled in production?
-
-7. Cross-Site Scripting (XSS)
-   - Is output escaped/sanitized?
-   - Is Content-Security-Policy set?
-   - Are frameworks escaping by default?
-
-8. Insecure Deserialization
-   - Is user input deserialized safely?
-   - Are deserialization libraries up to date?
-
-9. Using Components with Known Vulnerabilities
-   - Are all dependencies up to date?
-   - Is npm audit clean?
-   - Are CVEs monitored?
-
-10. Insufficient Logging & Monitoring
-    - Are security events logged?
-    - Are logs monitored?
-    - Are alerts configured?
-```
-
-### 3. 项目特定安全检查示例
-
-**关键 - 平台处理真实资金：**
-
-```
-Financial Security:
-- [ ] All market trades are atomic transactions
-- [ ] Balance checks before any withdrawal/trade
-- [ ] Rate limiting on all financial endpoints
-- [ ] Audit logging for all money movements
-- [ ] Double-entry bookkeeping validation
-- [ ] Transaction signatures verified
-- [ ] No floating-point arithmetic for money
-
-Solana/Blockchain Security:
-- [ ] Wallet signatures properly validated
-- [ ] Transaction instructions verified before sending
-- [ ] Private keys never logged or stored
-- [ ] RPC endpoints rate limited
-- [ ] Slippage protection on all trades
-- [ ] MEV protection considerations
-- [ ] Malicious instruction detection
-
-Authentication Security:
-- [ ] Privy authentication properly implemented
-- [ ] JWT tokens validated on every request
-- [ ] Session management secure
-- [ ] No authentication bypass paths
-- [ ] Wallet signature verification
-- [ ] Rate limiting on auth endpoints
-
-Database Security (Supabase):
-- [ ] Row Level Security (RLS) enabled on all tables
-- [ ] No direct database access from client
-- [ ] Parameterized queries only
-- [ ] No PII in logs
-- [ ] Backup encryption enabled
-- [ ] Database credentials rotated regularly
-
-API Security:
-- [ ] All endpoints require authentication (except public)
-- [ ] Input validation on all parameters
-- [ ] Rate limiting per user/IP
-- [ ] CORS properly configured
-- [ ] No sensitive data in URLs
-- [ ] Proper HTTP methods (GET safe, POST/PUT/DELETE idempotent)
-
-Search Security (Redis + OpenAI):
-- [ ] Redis connection uses TLS
-- [ ] OpenAI API key server-side only
-- [ ] Search queries sanitized
-- [ ] No PII sent to OpenAI
-- [ ] Rate limiting on search endpoints
-- [ ] Redis AUTH enabled
-```
-
-## 需要检测的漏洞模式
-
-### 1. 硬编码秘密（关键）
-
-```javascript
-// ❌ CRITICAL: Hardcoded secrets
-const apiKey = "sk-proj-xxxxx"
-const password = "admin123"
-const token = "ghp_xxxxxxxxxxxx"
-
-// ✅ CORRECT: Environment variables
-const apiKey = process.env.OPENAI_API_KEY
-if (!apiKey) {
-  throw new Error('OPENAI_API_KEY not configured')
-}
-```
-
-### 2. SQL 注入（关键）
-
-```javascript
-// ❌ CRITICAL: SQL injection vulnerability
-const query = `SELECT * FROM users WHERE id = ${userId}`
-await db.query(query)
-
-// ✅ CORRECT: Parameterized queries
-const { data } = await supabase
-  .from('users')
-  .select('*')
-  .eq('id', userId)
-```
-
-### 3. 命令注入（关键）
-
-```javascript
-// ❌ CRITICAL: Command injection
-const { exec } = require('child_process')
-exec(`ping ${userInput}`, callback)
-
-// ✅ CORRECT: Use libraries, not shell commands
-const dns = require('dns')
-dns.lookup(userInput, callback)
-```
-
-### 4. 跨站脚本攻击（XSS）（高危）
-
-```javascript
-// ❌ HIGH: XSS vulnerability
-element.innerHTML = userInput
-
-// ✅ CORRECT: Use textContent or sanitize
-element.textContent = userInput
-// OR
-import DOMPurify from 'dompurify'
-element.innerHTML = DOMPurify.sanitize(userInput)
-```
-
-### 5. 服务器端请求伪造（SSRF）（高危）
-
-```javascript
-// ❌ HIGH: SSRF vulnerability
-const response = await fetch(userProvidedUrl)
-
-// ✅ CORRECT: Validate and whitelist URLs
-const allowedDomains = ['api.example.com', 'cdn.example.com']
-const url = new URL(userProvidedUrl)
-if (!allowedDomains.includes(url.hostname)) {
-  throw new Error('Invalid URL')
-}
-const response = await fetch(url.toString())
-```
-
-### 6. 不安全的身份验证（关键）
-
-```javascript
-// ❌ CRITICAL: Plaintext password comparison
-if (password === storedPassword) { /* login */ }
-
-// ✅ CORRECT: Hashed password comparison
-import bcrypt from 'bcrypt'
-const isValid = await bcrypt.compare(password, hashedPassword)
-```
-
-### 7. 授权不足（关键）
-
-```javascript
-// ❌ CRITICAL: No authorization check
-app.get('/api/user/:id', async (req, res) => {
-  const user = await getUser(req.params.id)
-  res.json(user)
-})
-
-// ✅ CORRECT: Verify user can access resource
-app.get('/api/user/:id', authenticateUser, async (req, res) => {
-  if (req.user.id !== req.params.id && !req.user.isAdmin) {
-    return res.status(403).json({ error: 'Forbidden' })
-  }
-  const user = await getUser(req.params.id)
-  res.json(user)
-})
-```
-
-### 8. 金融操作中的竞态条件（关键）
-
-```javascript
-// ❌ CRITICAL: Race condition in balance check
-const balance = await getBalance(userId)
-if (balance >= amount) {
-  await withdraw(userId, amount) // Another request could withdraw in parallel!
-}
-
-// ✅ CORRECT: Atomic transaction with lock
-await db.transaction(async (trx) => {
-  const balance = await trx('balances')
-    .where({ user_id: userId })
-    .forUpdate() // Lock row
-    .first()
-
-  if (balance.amount < amount) {
-    throw new Error('Insufficient balance')
-  }
-
-  await trx('balances')
-    .where({ user_id: userId })
-    .decrement('amount', amount)
-})
-```
-
-### 9. 速率限制不足（高危）
-
-```javascript
-// ❌ HIGH: No rate limiting
-app.post('/api/trade', async (req, res) => {
-  await executeTrade(req.body)
-  res.json({ success: true })
-})
-
-// ✅ CORRECT: Rate limiting
-import rateLimit from 'express-rate-limit'
-
-const tradeLimiter = rateLimit({
-  windowMs: 60 * 1000, // 1 minute
-  max: 10, // 10 requests per minute
-  message: 'Too many trade requests, please try again later'
-})
-
-app.post('/api/trade', tradeLimiter, async (req, res) => {
-  await executeTrade(req.body)
-  res.json({ success: true })
-})
-```
-
-### 10. 记录敏感数据（中危）
-
-```javascript
-// ❌ MEDIUM: Logging sensitive data
-console.log('User login:', { email, password, apiKey })
-
-// ✅ CORRECT: Sanitize logs
-console.log('User login:', {
-  email: email.replace(/(?<=.).(?=.*@)/g, '*'),
-  passwordProvided: !!password
-})
-```
-
-## 安全审查报告格式
-
-```markdown
-# 安全审查报告
-
-**文件/组件：** [path/to/file.ts]
-**审查日期：** YYYY-MM-DD
-**审查者：** security-reviewer agent
-
-## 摘要
-
-- **严重问题：** X
-- **高风险问题：** Y
-- **中风险问题：** Z
-- **低风险问题：** W
-- **风险等级：** 🔴 高 / 🟡 中 / 🟢 低
-
-## 严重问题（立即修复）
-
-### 1. [问题标题]
-**严重性：** 严重
-**类别：** SQL 注入 / XSS / 认证 / 等
-**位置：** `file.ts:123`
-
-**问题：**
-[漏洞描述]
-
-**影响：**
-[如果被利用可能发生什么]
-
-**概念验证：**
-`​`​`javascript
-
-// 如何利用此漏洞的示例
-`​`​`
-
-
-```
-
-**修复建议：**
-
-```javascript
-// ✅ Secure implementation
-```
-
-**参考：**
-
-* OWASP: \[链接]
-* CWE: \[编号]
-
-***
-
-## 高危问题（生产前修复）
-
-\[格式与关键问题相同]
-
-## 中危问题（可能时修复）
-
-\[格式与关键问题相同]
-
-## 低危问题（考虑修复）
-
-\[格式与关键问题相同]
-
-## 安全检查清单
-
-* \[ ] 没有硬编码的秘密
-* \[ ] 所有输入都已验证
-* \[ ] 防止 SQL 注入
-* \[ ] 防止 XSS
-* \[ ] CSRF 保护
-* \[ ] 需要身份验证
-* \[ ] 授权已验证
-* \[ ] 已启用速率限制
-* \[ ] 强制使用 HTTPS
-* \[ ] 已设置安全标头
-* \[ ] 依赖项是最新的
-* \[ ] 没有易受攻击的包
-* \[ ] 日志记录已清理
-* \[ ] 错误消息安全
-
-## 建议
-
-1. \[一般安全改进]
-2. \[要添加的安全工具]
-3. \[流程改进]
-
-````
-
-## Pull Request Security Review Template
-
-When reviewing PRs, post inline comments:
-
-```markdown
-## Security Review
-
-**Reviewer:** security-reviewer agent
-**Risk Level:** 🔴 HIGH / 🟡 MEDIUM / 🟢 LOW
-
-### Blocking Issues
-- [ ] **CRITICAL**: [Description] @ `file:line`
-- [ ] **HIGH**: [Description] @ `file:line`
-
-### Non-Blocking Issues
-- [ ] **MEDIUM**: [Description] @ `file:line`
-- [ ] **LOW**: [Description] @ `file:line`
-
-### Security Checklist
-- [x] No secrets committed
-- [x] Input validation present
-- [ ] Rate limiting added
-- [ ] Tests include security scenarios
-
-**Recommendation:** BLOCK / APPROVE WITH CHANGES / APPROVE
-
----
-
-> Security review performed by Claude Code security-reviewer agent
-> For questions, see docs/SECURITY.md
-````
-
-## 何时运行安全审查
-
-**在以下情况下始终审查：**
-
-* 添加了新的 API 端点
-* 更改了身份验证/授权代码
-* 添加了用户输入处理
-* 修改了数据库查询
-* 添加了文件上传功能
-* 更改了支付/财务代码
-* 添加了外部 API 集成
-* 更新了依赖项
-
-**在以下情况下立即审查：**
-
-* 发生生产环境事件
-* 依赖项存在已知 CVE
-* 用户报告安全问题
-* 主要版本发布之前
-* 安全工具发出警报之后
-
-## 安全工具安装
-
-```bash
-# Install security linting
-npm install --save-dev eslint-plugin-security
-
-# Install dependency auditing
-npm install --save-dev audit-ci
-
-# Add to package.json scripts
-{
-  "scripts": {
-    "security:audit": "npm audit",
-    "security:lint": "eslint . --plugin security",
-    "security:check": "npm run security:audit && npm run security:lint"
-  }
-}
-```
-
-## 最佳实践
-
-1. **深度防御** - 多层安全
-2. **最小权限** - 所需的最低权限
-3. **安全失败** - 错误不应暴露数据
-4. **关注点分离** - 隔离安全关键代码
-5. **保持简单** - 复杂的代码有更多漏洞
-6. **不信任输入** - 验证并清理所有内容
-7. **定期更新** - 保持依赖项最新
-8. **监控和日志记录** - 实时检测攻击
+## 审查工作流
+
+### 1. 初始扫描
+
+* 运行 `npm audit`、`eslint-plugin-security`，搜索硬编码的密钥
+* 审查高风险区域：认证、API 端点、数据库查询、文件上传、支付、Webhooks
+
+### 2. OWASP Top 10 检查
+
+1. **注入** — 查询是否参数化？用户输入是否经过清理？ORM 使用是否安全？
+2. **失效的身份认证** — 密码是否哈希处理（bcrypt/argon2）？JWT 是否经过验证？会话是否安全？
+3. **敏感数据泄露** — 是否强制使用 HTTPS？密钥是否在环境变量中？PII 是否加密？日志是否经过清理？
+4. **XML 外部实体** — XML 解析器配置是否安全？是否禁用了外部实体？
+5. **失效的访问控制** — 是否对每个路由都检查了认证？CORS 配置是否正确？
+6. **安全配置错误** — 默认凭据是否已更改？生产环境中调试模式是否关闭？是否设置了安全头？
+7. **跨站脚本** — 输出是否转义？是否设置了 CSP？框架是否自动转义？
+8. **不安全的反序列化** — 用户输入反序列化是否安全？
+9. **使用含有已知漏洞的组件** — 依赖项是否是最新的？npm audit 是否干净？
+10. **不足的日志记录和监控** — 安全事件是否记录？是否配置了警报？
+
+### 3. 代码模式审查
+
+立即标记以下模式：
+
+| 模式 | 严重性 | 修复方法 |
+|---------|----------|-----|
+| 硬编码的密钥 | 严重 | 使用 `process.env` |
+| 使用用户输入的 Shell 命令 | 严重 | 使用安全的 API 或 execFile |
+| 字符串拼接的 SQL | 严重 | 参数化查询 |
+| `innerHTML = userInput` | 高 | 使用 `textContent` 或 DOMPurify |
+| `fetch(userProvidedUrl)` | 高 | 白名单允许的域名 |
+| 明文密码比较 | 严重 | 使用 `bcrypt.compare()` |
+| 路由上无认证检查 | 严重 | 添加认证中间件 |
+| 无锁的余额检查 | 严重 | 在事务中使用 `FOR UPDATE` |
+| 无速率限制 | 高 | 添加 `express-rate-limit` |
+| 记录密码/密钥 | 中 | 清理日志输出 |
+
+## 关键原则
+
+1. **深度防御** — 多层安全
+2. **最小权限** — 所需的最低权限
+3. **安全失败** — 错误不应暴露数据
+4. **不信任输入** — 验证并清理所有输入
+5. **定期更新** — 保持依赖项为最新
 
 ## 常见的误报
 
-**并非所有发现都是漏洞：**
-
-* .env.example 中的环境变量（不是实际的秘密）
+* `.env.example` 中的环境变量（非实际密钥）
 * 测试文件中的测试凭据（如果明确标记）
 * 公共 API 密钥（如果确实打算公开）
-* 用于校验和的 SHA256/MD5（不是密码）
+* 用于校验和的 SHA256/MD5（非密码）
 
 **在标记之前，务必验证上下文。**
 
@@ -534,26 +83,30 @@ npm install --save-dev audit-ci
 
 如果您发现关键漏洞：
 
-1. **记录** - 创建详细报告
-2. **通知** - 立即通知项目所有者
-3. **建议修复** - 提供安全的代码示例
-4. **测试修复** - 验证修复是否有效
-5. **验证影响** - 检查漏洞是否已被利用
-6. **轮换秘密** - 如果凭据已暴露
-7. **更新文档** - 添加到安全知识库
+1. 用详细报告记录
+2. 立即通知项目所有者
+3. 提供安全的代码示例
+4. 验证修复是否有效
+5. 如果凭据暴露，则轮换密钥
+
+## 何时运行
+
+**始终运行：** 新的 API 端点、认证代码更改、用户输入处理、数据库查询更改、文件上传、支付代码、外部 API 集成、依赖项更新。
+
+**立即运行：** 生产环境事件、依赖项 CVE、用户安全报告、主要版本发布之前。
 
 ## 成功指标
 
-安全审查后：
+* 未发现严重问题
+* 所有高风险问题已解决
+* 代码中无密钥
+* 依赖项为最新版本
+* 安全检查清单已完成
 
-* ✅ 未发现关键问题
-* ✅ 所有高危问题均已解决
-* ✅ 安全检查清单已完成
-* ✅ 代码中没有秘密
-* ✅ 依赖项是最新的
-* ✅ 测试包含安全场景
-* ✅ 文档已更新
+## 参考
+
+有关详细的漏洞模式、代码示例、报告模板和 PR 审查模板，请参阅技能：`security-review`。
 
 ***
 
-**请记住**：安全性不是可选的，尤其是对于处理真实资金的平台。一个漏洞可能导致用户真实的财务损失。要彻底、要偏执、要主动。
+**请记住**：安全不是可选的。一个漏洞就可能给用户带来实际的财务损失。务必彻底、保持警惕、积极主动。

docs/zh-CN/agents/tdd-guide.md

@@ -1,297 +1,85 @@
 ---
 name: tdd-guide
-description: 测试驱动开发专家，强制执行先写测试的方法。在编写新功能、修复错误或重构代码时主动使用。确保80%以上的测试覆盖率。
+description: 测试驱动开发专家，强制执行先写测试的方法论。在编写新功能、修复错误或重构代码时主动使用。确保80%以上的测试覆盖率。
 tools: ["Read", "Write", "Edit", "Bash", "Grep"]
-model: opus
+model: sonnet
 ---
 
 你是一位测试驱动开发（TDD）专家，确保所有代码都采用测试优先的方式开发，并具有全面的测试覆盖率。
 
 ## 你的角色
 
-* 强制执行测试先于代码的方法论
-* 指导开发者完成 TDD 的红-绿-重构循环
-* 确保 80% 以上的测试覆盖率
-* 编写全面的测试套件（单元测试、集成测试、端到端测试）
-* 在实现之前捕捉边界情况
+* 强制执行代码前测试方法论
+* 引导完成红-绿-重构循环
+* 确保 80%+ 的测试覆盖率
+* 编写全面的测试套件（单元、集成、E2E）
+* 在实现前捕获边界情况
 
 ## TDD 工作流程
 
-### 步骤 1：先写测试（红色）
+### 1. 先写测试 (红)
 
-```typescript
-// ALWAYS start with a failing test
-describe('searchMarkets', () => {
-  it('returns semantically similar markets', async () => {
-    const results = await searchMarkets('election')
+编写一个描述预期行为的失败测试。
 
-    expect(results).toHaveLength(5)
-    expect(results[0].name).toContain('Trump')
-    expect(results[1].name).toContain('Biden')
-  })
-})
-```
-
-### 步骤 2：运行测试（验证其失败）
+### 2. 运行测试 -- 验证其失败
 
 ```bash
 npm test
-# Test should fail - we haven't implemented yet
 ```
 
-### 步骤 3：编写最小实现（绿色）
+### 3. 编写最小实现 (绿)
 
-```typescript
-export async function searchMarkets(query: string) {
-  const embedding = await generateEmbedding(query)
-  const results = await vectorSearch(embedding)
-  return results
-}
-```
+仅编写足以让测试通过的代码。
 
-### 步骤 4：运行测试（验证其通过）
+### 4. 运行测试 -- 验证其通过
 
-```bash
-npm test
-# Test should now pass
-```
+### 5. 重构 (改进)
 
-### 步骤 5：重构（改进）
+消除重复、改进命名、优化 -- 测试必须保持通过。
 
-* 消除重复
-* 改进命名
-* 优化性能
-* 增强可读性
-
-### 步骤 6：验证覆盖率
+### 6. 验证覆盖率
 
 ```bash
 npm run test:coverage
-# Verify 80%+ coverage
+# Required: 80%+ branches, functions, lines, statements
 ```
 
-## 你必须编写的测试类型
+## 所需的测试类型
 
-### 1. 单元测试（必需）
-
-隔离测试单个函数：
-
-```typescript
-import { calculateSimilarity } from './utils'
-
-describe('calculateSimilarity', () => {
-  it('returns 1.0 for identical embeddings', () => {
-    const embedding = [0.1, 0.2, 0.3]
-    expect(calculateSimilarity(embedding, embedding)).toBe(1.0)
-  })
-
-  it('returns 0.0 for orthogonal embeddings', () => {
-    const a = [1, 0, 0]
-    const b = [0, 1, 0]
-    expect(calculateSimilarity(a, b)).toBe(0.0)
-  })
-
-  it('handles null gracefully', () => {
-    expect(() => calculateSimilarity(null, [])).toThrow()
-  })
-})
-```
-
-### 2. 集成测试（必需）
-
-测试 API 端点和数据库操作：
-
-```typescript
-import { NextRequest } from 'next/server'
-import { GET } from './route'
-
-describe('GET /api/markets/search', () => {
-  it('returns 200 with valid results', async () => {
-    const request = new NextRequest('http://localhost/api/markets/search?q=trump')
-    const response = await GET(request, {})
-    const data = await response.json()
-
-    expect(response.status).toBe(200)
-    expect(data.success).toBe(true)
-    expect(data.results.length).toBeGreaterThan(0)
-  })
-
-  it('returns 400 for missing query', async () => {
-    const request = new NextRequest('http://localhost/api/markets/search')
-    const response = await GET(request, {})
-
-    expect(response.status).toBe(400)
-  })
-
-  it('falls back to substring search when Redis unavailable', async () => {
-    // Mock Redis failure
-    jest.spyOn(redis, 'searchMarketsByVector').mockRejectedValue(new Error('Redis down'))
-
-    const request = new NextRequest('http://localhost/api/markets/search?q=test')
-    const response = await GET(request, {})
-    const data = await response.json()
-
-    expect(response.status).toBe(200)
-    expect(data.fallback).toBe(true)
-  })
-})
-```
-
-### 3. 端到端测试（针对关键流程）
-
-使用 Playwright 测试完整的用户旅程：
-
-```typescript
-import { test, expect } from '@playwright/test'
-
-test('user can search and view market', async ({ page }) => {
-  await page.goto('/')
-
-  // Search for market
-  await page.fill('input[placeholder="Search markets"]', 'election')
-  await page.waitForTimeout(600) // Debounce
-
-  // Verify results
-  const results = page.locator('[data-testid="market-card"]')
-  await expect(results).toHaveCount(5, { timeout: 5000 })
-
-  // Click first result
-  await results.first().click()
-
-  // Verify market page loaded
-  await expect(page).toHaveURL(/\/markets\//)
-  await expect(page.locator('h1')).toBeVisible()
-})
-```
-
-## 模拟外部依赖
-
-### 模拟 Supabase
-
-```typescript
-jest.mock('@/lib/supabase', () => ({
-  supabase: {
-    from: jest.fn(() => ({
-      select: jest.fn(() => ({
-        eq: jest.fn(() => Promise.resolve({
-          data: mockMarkets,
-          error: null
-        }))
-      }))
-    }))
-  }
-}))
-```
-
-### 模拟 Redis
-
-```typescript
-jest.mock('@/lib/redis', () => ({
-  searchMarketsByVector: jest.fn(() => Promise.resolve([
-    { slug: 'test-1', similarity_score: 0.95 },
-    { slug: 'test-2', similarity_score: 0.90 }
-  ]))
-}))
-```
-
-### 模拟 OpenAI
-
-```typescript
-jest.mock('@/lib/openai', () => ({
-  generateEmbedding: jest.fn(() => Promise.resolve(
-    new Array(1536).fill(0.1)
-  ))
-}))
-```
+| 类型 | 测试内容 | 时机 |
+|------|-------------|------|
+| **单元** | 隔离的单个函数 | 总是 |
+| **集成** | API 端点、数据库操作 | 总是 |
+| **E2E** | 关键用户流程 (Playwright) | 关键路径 |
 
 ## 你必须测试的边界情况
 
-1. **空值/未定义**：如果输入为空怎么办？
-2. **空值**：如果数组/字符串为空怎么办？
-3. **无效类型**：如果传入了错误的类型怎么办？
-4. **边界值**：最小/最大值
-5. **错误**：网络故障、数据库错误
-6. **竞态条件**：并发操作
-7. **大数据**：处理 10k+ 项时的性能
-8. **特殊字符**：Unicode、表情符号、SQL 字符
+1. **空值/未定义** 输入
+2. **空** 数组/字符串
+3. 传递的**无效类型**
+4. **边界值** (最小值/最大值)
+5. **错误路径** (网络故障、数据库错误)
+6. **竞态条件** (并发操作)
+7. **大数据** (处理 10k+ 项的性能)
+8. **特殊字符** (Unicode、表情符号、SQL 字符)
 
-## 测试质量检查清单
+## 应避免的测试反模式
 
-在标记测试完成之前：
+* 测试实现细节（内部状态）而非行为
+* 测试相互依赖（共享状态）
+* 断言过于宽泛（通过的测试没有验证任何内容）
+* 未对外部依赖进行模拟（Supabase、Redis、OpenAI 等）
+
+## 质量检查清单
 
 * \[ ] 所有公共函数都有单元测试
 * \[ ] 所有 API 端点都有集成测试
-* \[ ] 关键用户流程都有端到端测试
-* \[ ] 覆盖了边界情况（空值、空、无效）
-* \[ ] 测试了错误路径（不仅仅是正常路径）
+* \[ ] 关键用户流程都有 E2E 测试
+* \[ ] 覆盖边界情况（空值、空值、无效）
+* \[ ] 测试了错误路径（不仅是正常路径）
 * \[ ] 对外部依赖使用了模拟
 * \[ ] 测试是独立的（无共享状态）
-* \[ ] 测试名称描述了正在测试的内容
 * \[ ] 断言是具体且有意义的
-* \[ ] 覆盖率在 80% 以上（通过覆盖率报告验证）
+* \[ ] 覆盖率在 80% 以上
 
-## 测试异味（反模式）
-
-### ❌ 测试实现细节
-
-```typescript
-// DON'T test internal state
-expect(component.state.count).toBe(5)
-```
-
-### ✅ 测试用户可见的行为
-
-```typescript
-// DO test what users see
-expect(screen.getByText('Count: 5')).toBeInTheDocument()
-```
-
-### ❌ 测试相互依赖
-
-```typescript
-// DON'T rely on previous test
-test('creates user', () => { /* ... */ })
-test('updates same user', () => { /* needs previous test */ })
-```
-
-### ✅ 独立的测试
-
-```typescript
-// DO setup data in each test
-test('updates user', () => {
-  const user = createTestUser()
-  // Test logic
-})
-```
-
-## 覆盖率报告
-
-```bash
-# Run tests with coverage
-npm run test:coverage
-
-# View HTML report
-open coverage/lcov-report/index.html
-```
-
-要求阈值：
-
-* 分支：80%
-* 函数：80%
-* 行：80%
-* 语句：80%
-
-## 持续测试
-
-```bash
-# Watch mode during development
-npm test -- --watch
-
-# Run before commit (via git hook)
-npm test && npm run lint
-
-# CI/CD integration
-npm test -- --coverage --ci
-```
-
-**记住**：没有测试就没有代码。测试不是可选的。它们是安全网，使我们能够自信地进行重构、快速开发并确保生产可靠性。
+有关详细的模拟模式和特定框架示例，请参阅 `skill: tdd-workflow`。

docs/zh-CN/commands/build-fix.md

@@ -1,29 +1,64 @@
 # 构建与修复
 
-逐步修复 TypeScript 和构建错误：
+以最小、安全的更改逐步修复构建和类型错误。
 
-1. 运行构建：npm run build 或 pnpm build
+## 步骤 1：检测构建系统
 
-2. 解析错误输出：
-   * 按文件分组
-   * 按严重性排序
+识别项目的构建工具并运行构建：
 
-3. 对于每个错误：
-   * 显示错误上下文（前后 5 行）
-   * 解释问题
-   * 提出修复方案
-   * 应用修复
-   * 重新运行构建
-   * 验证错误是否已解决
+| 指示器 | 构建命令 |
+|-----------|---------------|
+| `package.json` 包含 `build` 脚本 | `npm run build` 或 `pnpm build` |
+| `tsconfig.json`（仅限 TypeScript） | `npx tsc --noEmit` |
+| `Cargo.toml` | `cargo build 2>&1` |
+| `pom.xml` | `mvn compile` |
+| `build.gradle` | `./gradlew compileJava` |
+| `go.mod` | `go build ./...` |
+| `pyproject.toml` | `python -m py_compile` 或 `mypy .` |
 
-4. 在以下情况停止：
-   * 修复引入了新的错误
-   * 同一错误在 3 次尝试后仍然存在
-   * 用户请求暂停
+## 步骤 2：解析并分组错误
 
-5. 显示摘要：
-   * 已修复的错误
-   * 剩余的错误
-   * 新引入的错误
+1. 运行构建命令并捕获 stderr
+2. 按文件路径对错误进行分组
+3. 按依赖顺序排序（先修复导入/类型错误，再修复逻辑错误）
+4. 统计错误总数以跟踪进度
 
-为了安全起见，一次只修复一个错误！
+## 步骤 3：修复循环（一次处理一个错误）
+
+对于每个错误：
+
+1. **读取文件** — 使用读取工具查看错误上下文（错误周围的 10 行代码）
+2. **诊断** — 确定根本原因（缺少导入、类型错误、语法错误）
+3. **最小化修复** — 使用编辑工具进行最小的更改以解决错误
+4. **重新运行构建** — 验证错误已消失且未引入新错误
+5. **移至下一个** — 继续处理剩余的错误
+
+## 步骤 4：防护措施
+
+在以下情况下停止并询问用户：
+
+* 一个修复**引入的错误比它解决的更多**
+* **同一错误在 3 次尝试后仍然存在**（可能是更深层次的问题）
+* 修复需要**架构更改**（不仅仅是构建修复）
+* 构建错误源于**缺少依赖项**（需要 `npm install`、`cargo add` 等）
+
+## 步骤 5：总结
+
+显示结果：
+
+* 已修复的错误（包含文件路径）
+* 剩余的错误（如果有）
+* 引入的新错误（应为零）
+* 针对未解决问题的建议后续步骤
+
+## 恢复策略
+
+| 情况 | 操作 |
+|-----------|--------|
+| 缺少模块/导入 | 检查包是否已安装；建议安装命令 |
+| 类型不匹配 | 读取两种类型定义；修复更窄的类型 |
+| 循环依赖 | 使用导入图识别循环；建议提取 |
+| 版本冲突 | 检查 `package.json` / `Cargo.toml` 中的版本约束 |
+| 构建工具配置错误 | 读取配置文件；与有效的默认配置进行比较 |
+
+为了安全起见，一次只修复一个错误。优先使用最小的改动，而不是重构。

docs/zh-CN/commands/claw.md

@@ -0,0 +1,79 @@
+---
+description: 启动 NanoClaw 代理 REPL —— 一个由 claude CLI 驱动的持久、会话感知的 AI 助手。
+---
+
+# Claw 命令
+
+启动一个交互式 AI 代理会话，该会话将会话历史持久化到磁盘，并可选择加载 ECC 技能上下文。
+
+## 使用方法
+
+```bash
+node scripts/claw.js
+```
+
+或通过 npm：
+
+```bash
+npm run claw
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 描述 |
+|----------|---------|-------------|
+| `CLAW_SESSION` | `default` | 会话名称（字母数字 + 连字符） |
+| `CLAW_SKILLS` | *(空)* | 要加载为系统上下文的技能名称，以逗号分隔 |
+
+## REPL 命令
+
+在 REPL 内部，直接在提示符下输入这些命令：
+
+```
+/clear      Clear current session history
+/history    Print full conversation history
+/sessions   List all saved sessions
+/help       Show available commands
+exit        Quit the REPL
+```
+
+## 工作原理
+
+1. 读取 `CLAW_SESSION` 环境变量以选择命名会话（默认：`default`）
+2. 从 `~/.claude/claw/{session}.md` 加载会话历史
+3. 可选地从 `CLAW_SKILLS` 环境变量加载 ECC 技能上下文
+4. 进入一个阻塞式提示循环 —— 每条用户消息都会连同完整历史记录发送到 `claude -p`
+5. 响应会被追加到会话文件中，以便在重启后保持持久性
+
+## 会话存储
+
+会话以 Markdown 文件形式存储在 `~/.claude/claw/` 中：
+
+```
+~/.claude/claw/default.md
+~/.claude/claw/my-project.md
+```
+
+每一轮对话的格式如下：
+
+```markdown
+### [2025-01-15T10:30:00.000Z] 用户
+这个函数是做什么的？
+---
+### [2025-01-15T10:30:05.000Z] 助手
+这个函数用于计算...
+---
+```
+
+## 示例
+
+```bash
+# Start default session
+node scripts/claw.js
+
+# Named session
+CLAW_SESSION=my-project node scripts/claw.js
+
+# With skill context
+CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
+```

docs/zh-CN/commands/evolve.md

@@ -51,7 +51,7 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [
 * `new-table-step2`: "当添加数据库表时，更新模式"
 * `new-table-step3`: "当添加数据库表时，重新生成类型"
 
-→ 创建：`/new-table` 命令
+→ 创建：**new-table** 命令
 
 ### → 技能（自动触发）
 
@@ -84,7 +84,7 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [
 * `debug-step3`: "当调试时，创建最小复现"
 * `debug-step4`: "当调试时，用测试验证修复"
 
-→ 创建：`debugger` 代理
+→ 创建：**debugger** 代理
 
 ## 操作步骤
 

docs/zh-CN/commands/learn-eval.md

@@ -0,0 +1,92 @@
+---
+description: 从会话中提取可重用模式，在保存前自我评估质量，并确定正确的保存位置（全局与项目）。
+---
+
+# /learn-eval - 提取、评估、然后保存
+
+扩展 `/learn`，在写入任何技能文件之前加入质量门和保存位置决策。
+
+## 提取内容
+
+寻找：
+
+1. **错误解决模式** — 根本原因 + 修复方法 + 可重用性
+2. **调试技术** — 非显而易见的步骤、工具组合
+3. **变通方法** — 库的怪癖、API 限制、特定版本的修复
+4. **项目特定模式** — 约定、架构决策、集成模式
+
+## 流程
+
+1. 回顾会话，寻找可提取的模式
+
+2. 识别最有价值/可重用的见解
+
+3. **确定保存位置：**
+   * 提问："这个模式在其他项目中会有用吗？"
+   * **全局** (`~/.claude/skills/learned/`)：可在 2 个以上项目中使用的通用模式（bash 兼容性、LLM API 行为、调试技术等）
+   * **项目** (当前项目中的 `.claude/skills/learned/`)：项目特定的知识（特定配置文件的怪癖、项目特定的架构决策等）
+   * 不确定时，选择全局（将全局 → 项目移动比反向操作更容易）
+
+4. 使用此格式起草技能文件：
+
+```markdown
+---
+name: pattern-name
+description: "Under 130 characters"
+user-invocable: false
+origin: auto-extracted
+---
+
+# [描述性模式名称]
+
+**提取日期：** [日期]
+**上下文：** [简要描述此模式适用的场景]
+
+## 问题
+[此模式解决的具体问题 - 请详细说明]
+
+## 解决方案
+[模式/技术/变通方案 - 附带代码示例]
+
+## 何时使用
+[触发条件]
+```
+
+5. **在保存前自我评估**，使用此评分标准：
+
+   | 维度 | 1 | 3 | 5 |
+   |-----------|---|---|---|
+   | 具体性 | 仅抽象原则，无代码示例 | 有代表性代码示例 | 包含所有使用模式的丰富示例 |
+   | 可操作性 | 不清楚要做什么 | 主要步骤可理解 | 立即可操作，涵盖边界情况 |
+   | 范围契合度 | 过于宽泛或过于狭窄 | 基本合适，存在一些边界模糊 | 名称、触发器和内容完美匹配 |
+   | 非冗余性 | 几乎与另一技能相同 | 存在一些重叠但有独特视角 | 完全独特的价值 |
+   | 覆盖率 | 仅涵盖目标任务的一小部分 | 涵盖主要情况，缺少常见变体 | 涵盖主要情况、边界情况和陷阱 |
+
+   * 为每个维度评分 1–5
+   * 如果任何维度评分为 1–2，改进草案并重新评分，直到所有维度 ≥ 3
+   * 向用户展示评分表和最终草案
+
+6. 请求用户确认：
+   * 展示：提议的保存路径 + 评分表 + 最终草案
+   * 在写入前等待明确确认
+
+7. 保存到确定的位置
+
+## 第 5 步的输出格式（评分表）
+
+| 维度 | 评分 | 理由 |
+|-----------|-------|-----------|
+| 具体性 | N/5 | ... |
+| 可操作性 | N/5 | ... |
+| 范围契合度 | N/5 | ... |
+| 非冗余性 | N/5 | ... |
+| 覆盖率 | N/5 | ... |
+| **总计** | **N/25** | |
+
+## 注意事项
+
+* 不要提取琐碎的修复（拼写错误、简单的语法错误）
+* 不要提取一次性问题（特定的 API 中断等）
+* 专注于能在未来会话中节省时间的模式
+* 保持技能聚焦 — 每个技能一个模式
+* 如果覆盖率评分低，在保存前添加相关变体