fix: harden hook portability and plugin docs

.opencode/MIGRATION.md

@@ -297,6 +297,15 @@ Then in your `opencode.json`:
 }
 ```
 
+This only loads the published ECC OpenCode plugin module (hooks/events and exported plugin tools).
+It does **not** automatically inject ECC's full `agent`, `command`, or `instructions` config into your project.
+
+If you want the full ECC OpenCode workflow surface, use the repository's bundled `.opencode/opencode.json` as your base config or copy these pieces into your project:
+- `.opencode/commands/`
+- `.opencode/prompts/`
+- `.opencode/instructions/INSTRUCTIONS.md`
+- the `agent` and `command` sections from `.opencode/opencode.json`
+
 ## Troubleshooting
 
 ### Configuration Not Loading
@@ -322,6 +331,7 @@ Then in your `opencode.json`:
 1. Verify the command is defined in `opencode.json` or as `.md` file in `.opencode/commands/`
 2. Check the referenced agent exists
 3. Ensure the template uses `$ARGUMENTS` for user input
+4. If you installed only `plugin: ["ecc-universal"]`, note that npm plugin install does not auto-add ECC commands or agents to your project config
 
 ## Best Practices
 

.opencode/README.md

@@ -32,7 +32,16 @@ Add to your `opencode.json`:
   "plugin": ["ecc-universal"]
 }
 ```
-After installation, the `ecc-install` CLI becomes available:
+
+This loads the ECC OpenCode plugin module from npm:
+- hook/event integrations
+- bundled custom tools exported by the plugin
+
+It does **not** auto-register the full ECC command/agent/instruction catalog in your project config. For the full OpenCode setup, either:
+- run OpenCode inside this repository, or
+- copy the relevant `.opencode/commands/`, `.opencode/prompts/`, `.opencode/instructions/`, and the `instructions`, `agent`, and `command` config entries into your own project
+
+After installation, the `ecc-install` CLI is also available:
 
 ```bash
 npx ecc-install typescript

.opencode/index.ts

@@ -1,12 +1,10 @@
 /**
  * Everything Claude Code (ECC) Plugin for OpenCode
  *
- * This package provides a complete OpenCode plugin with:
- * - 13 specialized agents (planner, architect, code-reviewer, etc.)
- * - 31 commands (/plan, /tdd, /code-review, etc.)
+ * This package provides the published ECC OpenCode plugin module:
  * - Plugin hooks (auto-format, TypeScript check, console.log warning, env injection, etc.)
  * - Custom tools (run-tests, check-coverage, security-audit, format-code, lint-check, git-summary)
- * - 37 skills (coding-standards, security-review, tdd-workflow, etc.)
+ * - Bundled reference config/assets for the wider ECC OpenCode setup
  *
  * Usage:
  *
@@ -22,6 +20,10 @@
  * }
  * ```
  *
+ * That enables the published plugin module only. For ECC commands, agents,
+ * prompts, and instructions, use this repository's `.opencode/opencode.json`
+ * as a base or copy the bundled `.opencode/` assets into your project.
+ *
  * Option 2: Clone and use directly
  * ```bash
  * git clone https://github.com/affaan-m/everything-claude-code
@@ -51,6 +53,7 @@ export const metadata = {
     agents: 13,
     commands: 31,
     skills: 37,
+    configAssets: true,
     hookEvents: [
       "file.edited",
       "tool.execute.before",

README.md

@@ -1050,6 +1050,13 @@ Then add to your `opencode.json`:
 }
 ```
 
+That npm plugin entry enables ECC's published OpenCode plugin module (hooks/events and plugin tools).
+It does **not** automatically add ECC's full command/agent/instruction catalog to your project config.
+
+For the full ECC OpenCode setup, either:
+- run OpenCode inside this repository, or
+- copy the bundled `.opencode/` config assets into your project and wire the `instructions`, `agent`, and `command` entries in `opencode.json`
+
 ### Documentation
 
 - **Migration Guide**: `.opencode/MIGRATION.md`

commands/e2e.md

@@ -337,8 +337,10 @@ For PMX, prioritize these E2E tests:
 
 ## Related Agents
 
-This command invokes the `e2e-runner` agent located at:
-`~/.claude/agents/e2e-runner.md`
+This command invokes the `e2e-runner` agent provided by ECC.
+
+For manual installs, the source file lives at:
+`agents/e2e-runner.md`
 
 ## Quick Commands
 

commands/plan.md

@@ -109,5 +109,7 @@ After planning:
 
 ## Related Agents
 
-This command invokes the `planner` agent located at:
-`~/.claude/agents/planner.md`
+This command invokes the `planner` agent provided by ECC.
+
+For manual installs, the source file lives at:
+`agents/planner.md`

commands/tdd.md

@@ -319,8 +319,10 @@ Never skip the RED phase. Never write code before tests.
 
 ## Related Agents
 
-This command invokes the `tdd-guide` agent located at:
-`~/.claude/agents/tdd-guide.md`
+This command invokes the `tdd-guide` agent provided by ECC.
 
-And can reference the `tdd-workflow` skill at:
-`~/.claude/skills/tdd-workflow/`
+The related `tdd-workflow` skill is also bundled with ECC.
+
+For manual installs, the source files live at:
+- `agents/tdd-guide.md`
+- `skills/tdd-workflow/SKILL.md`

schemas/plugin.schema.json

@@ -34,6 +34,25 @@
     "agents": {
       "type": "array",
       "items": { "type": "string" }
+    },
+    "features": {
+      "type": "object",
+      "properties": {
+        "agents": { "type": "integer", "minimum": 0 },
+        "commands": { "type": "integer", "minimum": 0 },
+        "skills": { "type": "integer", "minimum": 0 },
+        "configAssets": { "type": "boolean" },
+        "hookEvents": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "customTools": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
     }
-  }
+  },
+  "additionalProperties": false
 }

scripts/hooks/post-edit-format.js

@@ -10,11 +10,34 @@
  * Fails silently if no formatter is found or installed.
  */
 
-const { execFileSync } = require('child_process');
+const { execFileSync, spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { getPackageManager } = require('../lib/package-manager');
 
 const MAX_STDIN = 1024 * 1024; // 1MB limit
+const BIOME_CONFIGS = ['biome.json', 'biome.jsonc'];
+const PRETTIER_CONFIGS = [
+  '.prettierrc',
+  '.prettierrc.json',
+  '.prettierrc.json5',
+  '.prettierrc.js',
+  '.prettierrc.cjs',
+  '.prettierrc.mjs',
+  '.prettierrc.ts',
+  '.prettierrc.cts',
+  '.prettierrc.mts',
+  '.prettierrc.yml',
+  '.prettierrc.yaml',
+  '.prettierrc.toml',
+  'prettier.config.js',
+  'prettier.config.cjs',
+  'prettier.config.mjs',
+  'prettier.config.ts',
+  'prettier.config.cts',
+  'prettier.config.mts',
+];
+const PROJECT_ROOT_MARKERS = ['package.json', ...BIOME_CONFIGS, ...PRETTIER_CONFIGS];
 let data = '';
 process.stdin.setEncoding('utf8');
 
@@ -27,50 +50,102 @@ process.stdin.on('data', chunk => {
 
 function findProjectRoot(startDir) {
   let dir = startDir;
-  while (dir !== path.dirname(dir)) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
-    dir = path.dirname(dir);
+  let fallbackDir = null;
+
+  while (true) {
+    if (detectFormatter(dir)) {
+      return dir;
+    }
+
+    if (!fallbackDir && PROJECT_ROOT_MARKERS.some(marker => fs.existsSync(path.join(dir, marker)))) {
+      fallbackDir = dir;
+    }
+
+    const parentDir = path.dirname(dir);
+    if (parentDir === dir) break;
+    dir = parentDir;
   }
-  return startDir;
+
+  return fallbackDir || startDir;
 }
 
 function detectFormatter(projectRoot) {
-  const biomeConfigs = ['biome.json', 'biome.jsonc'];
-  for (const cfg of biomeConfigs) {
+  for (const cfg of BIOME_CONFIGS) {
     if (fs.existsSync(path.join(projectRoot, cfg))) return 'biome';
   }
 
-  const prettierConfigs = [
-    '.prettierrc',
-    '.prettierrc.json',
-    '.prettierrc.js',
-    '.prettierrc.cjs',
-    '.prettierrc.mjs',
-    '.prettierrc.yml',
-    '.prettierrc.yaml',
-    '.prettierrc.toml',
-    'prettier.config.js',
-    'prettier.config.cjs',
-    'prettier.config.mjs',
-  ];
-  for (const cfg of prettierConfigs) {
+  for (const cfg of PRETTIER_CONFIGS) {
     if (fs.existsSync(path.join(projectRoot, cfg))) return 'prettier';
   }
 
   return null;
 }
 
-function getFormatterCommand(formatter, filePath) {
-  const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+function getRunnerBin(bin) {
+  if (process.platform !== 'win32') return bin;
+  if (bin === 'npx') return 'npx.cmd';
+  if (bin === 'pnpm') return 'pnpm.cmd';
+  if (bin === 'yarn') return 'yarn.cmd';
+  if (bin === 'bunx') return 'bunx.cmd';
+  return bin;
+}
+
+function getFormatterRunner(projectRoot) {
+  const pm = getPackageManager({ projectDir: projectRoot });
+  const execCmd = pm?.config?.execCmd || 'npx';
+  const [bin = 'npx', ...prefix] = execCmd.split(/\s+/).filter(Boolean);
+
+  return {
+    bin: getRunnerBin(bin),
+    prefix
+  };
+}
+
+function getFormatterCommand(formatter, filePath, projectRoot) {
+  const runner = getFormatterRunner(projectRoot);
+
   if (formatter === 'biome') {
-    return { bin: npxBin, args: ['@biomejs/biome', 'format', '--write', filePath] };
+    return {
+      bin: runner.bin,
+      args: [...runner.prefix, '@biomejs/biome', 'format', '--write', filePath]
+    };
   }
   if (formatter === 'prettier') {
-    return { bin: npxBin, args: ['prettier', '--write', filePath] };
+    return {
+      bin: runner.bin,
+      args: [...runner.prefix, 'prettier', '--write', filePath]
+    };
   }
   return null;
 }
 
+function runFormatterCommand(cmd, projectRoot) {
+  if (process.platform === 'win32' && cmd.bin.endsWith('.cmd')) {
+    const result = spawnSync(cmd.bin, cmd.args, {
+      cwd: projectRoot,
+      shell: true,
+      stdio: 'pipe',
+      timeout: 15000
+    });
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    if (typeof result.status === 'number' && result.status !== 0) {
+      throw new Error(result.stderr?.toString() || `Formatter exited with status ${result.status}`);
+    }
+
+    return;
+  }
+
+  execFileSync(cmd.bin, cmd.args, {
+    cwd: projectRoot,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 15000
+  });
+}
+
 process.stdin.on('end', () => {
   try {
     const input = JSON.parse(data);
@@ -80,14 +155,10 @@ process.stdin.on('end', () => {
       try {
         const projectRoot = findProjectRoot(path.dirname(path.resolve(filePath)));
         const formatter = detectFormatter(projectRoot);
-        const cmd = getFormatterCommand(formatter, filePath);
+        const cmd = getFormatterCommand(formatter, filePath, projectRoot);
 
         if (cmd) {
-          execFileSync(cmd.bin, cmd.args, {
-            cwd: projectRoot,
-            stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: 15000
-          });
+          runFormatterCommand(cmd, projectRoot);
         }
       } catch {
         // Formatter not installed, file missing, or failed — non-blocking