fix: move prepare lifecycle hook to explicit setup-hooks script (#334)

* fix: move prepare lifecycle hook to explicit setup-hooks script

npm's prepare hook runs on every `npm install` in any environment,
causing the package to silently install git hooks into any consumer's
repository without their explicit consent. This is unexpected behavior
for a plugin package consumed by end users.

Rename prepare to setup-hooks so contributors can opt in explicitly by
running `npm run setup-hooks` after cloning, as now documented in
CONTRIBUTING.md.

Co-Authored-By: Claude Code <noreply@anthropic.com>

* fix(hooks): remove pre-commit placeholder + address bot review

- Remove pre-commit hook installation - it was just a no-op placeholder
  ('lib/ sync now handled by agent-core'), so installing it was pure
  redundancy. Only the pre-push hook (preflight + /enhance reminder +
  release tag validation) actually does anything.
- CONTRIBUTING.md: replace em-dash with single dash per workspace rule;
  update text to reflect that only pre-push is installed now.
- docs/ARCHITECTURE.md: update setup-hooks.js comment - was 'npm prepare'
  before xiaolai's PR; now correctly noted as manual.

---------

Co-authored-by: claude[bot] <claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
Co-authored-by: Avi Fenesh <aviarchi1994@gmail.com>

Author: 4 people

CONTRIBUTING.md

@@ -31,6 +31,17 @@ PRs may receive AI-assisted reviews (Copilot, Claude, Gemini, Codex) at the owne
 
 ## Before You Start
 
+### First-Time Setup
+
+After cloning the repo, install git hooks manually:
+
+```bash
+npm install
+npm run setup-hooks
+```
+
+The `setup-hooks` script installs the pre-push hook into your local `.git/hooks/` (it runs preflight checks, an `/enhance` reminder, and release-tag validation). It does **not** run automatically on `npm install` - you must opt in.
+
 ### Multi-File Changes
 
 For changes touching multiple files, **read the relevant checklist first**:

docs/ARCHITECTURE.md

@@ -63,7 +63,7 @@ agentsys/
 │       └── maintain-cross-platform/  # Cross-platform compatibility skill
 │           └── SKILL.md
 ├── scripts/
-│   ├── setup-hooks.js            # Git hooks installer (npm prepare)
+│   ├── setup-hooks.js            # Git hooks installer (manual: npm run setup-hooks)
 │   └── graduate-plugin.js        # Extract a plugin to a new standalone repo
 ├── docs/                         # User documentation
 │   ├── CROSS_PLATFORM.md

package.json

@@ -38,7 +38,7 @@
     "detect": "node bin/dev-cli.js detect",
     "verify": "node bin/dev-cli.js verify",
     "version": "node scripts/stamp-version.js && git add -A",
-    "prepare": "node bin/dev-cli.js setup-hooks"
+    "setup-hooks": "node bin/dev-cli.js setup-hooks"
   },
   "repository": {
     "type": "git",

scripts/setup-hooks.js

@@ -1,21 +1,15 @@
 #!/usr/bin/env node
 /**
  * Setup git hooks for development
- * - pre-commit: Placeholder (lib/ sync handled by agent-core CI)
  * - pre-push: Runs preflight checks, /enhance reminder, release validation
  */
 
 const fs = require('fs');
 const path = require('path');
 
 const hookDir = path.join(__dirname, '..', '.git', 'hooks');
-const preCommitPath = path.join(hookDir, 'pre-commit');
 const prePushPath = path.join(hookDir, 'pre-push');
 
-const preCommitHook = `#!/bin/sh
-# Pre-commit hook (lib/ sync now handled by agent-core)
-`;
-
 const prePushHook = `#!/bin/sh
 # Pre-push validations:
 # 1. Run preflight checks (validators + gap checks)
@@ -135,14 +129,6 @@ function main() {
     return 0;
   }
 
-  try {
-    fs.writeFileSync(preCommitPath, preCommitHook, { mode: 0o755 });
-    console.log('Git pre-commit hook installed');
-  } catch (err) {
-    // Non-fatal - might not have write permissions
-    console.warn('Could not install pre-commit hook:', err.message);
-  }
-
   try {
     fs.writeFileSync(prePushPath, prePushHook, { mode: 0o755 });
     console.log('Git pre-push hook installed (release tag validation)');