@amsterdamdatalabs/enact-extensions 0.1.5 → 0.1.8

package/extensions/plugin-dev/{commands/create-plugin.md → skills/create-plugin/SKILL.md}

@@ -1,12 +1,18 @@
 ---
-description: Create plugins with guided 8-phase workflow
-argument-hint: [plugin-description]
-allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:*), Bash(git init:*), TaskCreate, TaskGet, TaskUpdate, TaskList, AskUserQuestion, Skill, Task
-model: sonnet
+name: create-plugin
+description: >-
+  Guided workflow to create a complete Enact plugin from concept to tested
+  implementation. Use when someone says "create a plugin", "build a plugin",
+  "/create-plugin", or describes plugin functionality they want to scaffold.
 ---
 
 # Plugin Creation Workflow
 
+> **Commands are skills.** Enact plugins have no separate "commands" component.
+> A user-initiated action (e.g. `/create-plugin`) is an *invocable skill* — a
+> skill whose `SKILL.md` carries an invocable frontmatter and `$ARGUMENTS`.
+> Wherever you'd reach for a "command", create a skill instead.
+
 Guide the user through creating a complete, high-quality Claude Code plugin from initial concept to tested implementation. Follow a systematic approach: understand requirements, design components, clarify details, implement following best practices, validate, and test.
 
 ## Core Principles
@@ -55,8 +61,10 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 
 1. Load plugin-structure skill to understand component types
 2. Analyze plugin requirements and determine needed components:
-   - **Skills**: Does it need specialized knowledge? (hooks API, MCP patterns, etc.)
-   - **Commands**: User-initiated actions? (deploy, configure, analyze)
+   - **Skills**: Specialized knowledge AND user-initiated actions. A skill can
+     be passive (auto-triggered by its description) or *invocable* (a slash
+     entry point like `/deploy` carrying `$ARGUMENTS`). There is no separate
+     "command" component — invocable skills replace commands.
    - **Agents**: Autonomous tasks? (validation, generation, analysis)
    - **Hooks**: Event-driven automation? (validation, notifications)
    - **MCP**: External service integration? (databases, APIs)
@@ -68,13 +76,13 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
    - Rough triggering/usage patterns
 4. Present component plan to user as table:
    ```
-   | Component Type | Count | Purpose |
-   |----------------|-------|---------|
-   | Skills         | 2     | Hook patterns, MCP usage |
-   | Commands       | 3     | Deploy, configure, validate |
-   | Agents         | 1     | Autonomous validation |
-   | Hooks          | 0     | Not needed |
-   | MCP            | 1     | Database integration |
+   | Component Type     | Count | Purpose |
+   |--------------------|-------|---------|
+   | Skills (passive)   | 2     | Hook patterns, MCP usage |
+   | Skills (invocable) | 3     | /deploy, /configure, /validate |
+   | Agents             | 1     | Autonomous validation |
+   | Hooks              | 0     | Not needed |
+   | MCP                | 1     | Database integration |
    ```
 5. Get user confirmation or adjustments
 
@@ -91,8 +99,8 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 **Actions**:
 
 1. For each component in the plan, identify underspecified aspects:
-   - **Skills**: What triggers them? What knowledge do they provide? How detailed?
-   - **Commands**: What arguments? What tools? Interactive or automated?
+   - **Skills (passive)**: What triggers them? What knowledge do they provide? How detailed?
+   - **Skills (invocable)**: What slash name? What `$ARGUMENTS`? Interactive or automated?
    - **Agents**: When to trigger (proactive/reactive)? What tools? Output format?
    - **Hooks**: Which events? Prompt or command based? Validation criteria?
    - **MCP**: What server type? Authentication? Which tools?
@@ -135,12 +143,11 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 3. Create directory structure using bash:
    ```bash
    mkdir -p plugin-name/.agents
-   mkdir -p plugin-name/skills     # if needed
-   mkdir -p plugin-name/commands   # if needed
+   mkdir -p plugin-name/skills     # passive + invocable skills (no commands/ dir)
    mkdir -p plugin-name/agents     # if needed
    mkdir -p plugin-name/hooks      # if needed
    ```
-4. Create **canonical** `.agents/plugin.json` (see `plugin-structure` skill and `spec/enact.json`):
+4. Create **canonical** `.agents/plugin.json` (see `plugin-structure` skill and `spec/enact.json`). Declare only the components that exist on disk — an undeclared dir silently fails to install, and a declared-but-empty component (e.g. `"hooks"` pointing at `{ "hooks": {} }`) is a guard error:
    ```json
    {
      "name": "plugin-name",
@@ -148,12 +155,12 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
      "description": "[brief description]",
      "targets": ["claude", "codex", "cursor"],
      "skills": "./skills/",
-     "commands": "./commands/",
      "hooks": "./hooks/hooks.json",
      "mcpServers": "./.mcp.json",
      "author": { "name": "[author]" }
    }
    ```
+   There is no `commands` field — that field is banned by the repo guard.
 5. Sync and validate host manifests:
    ```bash
    cd /path/to/plugin-name
@@ -181,8 +188,7 @@ git commit -m "feat: initial plugin structure"
 
 **LOAD RELEVANT SKILLS** before implementing each component type:
 
-- Skills: Load skill-development skill
-- Commands: Load command-development skill
+- Skills (passive + invocable): Load skill-development skill
 - Agents: Load agent-development skill
 - Hooks: Load hook-development skill
 - MCP: Load mcp-integration skill
@@ -207,16 +213,17 @@ git commit -m "feat: initial plugin structure"
    - Create utility scripts if needed
 3. Use skill-reviewer agent to validate each skill
 
-### For Commands
+### For Invocable Skills (slash entry points — formerly "commands")
 
-1. Load command-development skill using Skill tool
-2. For each command:
-   - Write command markdown with frontmatter
-   - Include clear description and argument-hint
-   - Specify allowed-tools (minimal necessary)
-   - Write instructions FOR Claude (not TO user)
-   - Provide usage examples and tips
-   - Reference relevant skills if applicable
+1. Load skill-development skill using Skill tool
+2. For each invocable skill, create a normal `skills/<name>/SKILL.md` and:
+   - Give it invocable frontmatter (slash name, `argument-hint`, optional
+     `allowed-tools` kept minimal)
+   - Consume user input via `$ARGUMENTS`
+   - Write the body as instructions FOR Claude (not TO the user)
+   - Provide usage examples; reference passive skills where useful
+   - Use `references/` and `scripts/` for progressive disclosure
+3. Use skill-reviewer agent to validate it like any other skill
 
 ### For Agents
 
@@ -265,7 +272,7 @@ git commit -m "feat: initial plugin structure"
 1. Load plugin-settings skill using Skill tool
 2. Create settings template in README
 3. Create example .claude/plugin-name.local.md file (as documentation)
-4. Implement settings reading in hooks/commands as needed
+4. Implement settings reading in hooks/skills as needed
 5. Add to .gitignore: `.claude/*.local.md`
 
 **Progress tracking**: Update tasks as each component is completed
@@ -329,7 +336,7 @@ git commit -m "feat: initial plugin structure"
 
 2. **Verification checklist** for user to perform:
    - [ ] Skills load when triggered (ask questions with trigger phrases)
-   - [ ] Commands appear in `/help` and execute correctly
+   - [ ] Invocable skills appear in `/help` and execute correctly
    - [ ] Agents trigger on appropriate scenarios
    - [ ] Hooks activate on events (if applicable)
    - [ ] MCP servers connect (if applicable)
@@ -337,7 +344,7 @@ git commit -m "feat: initial plugin structure"
 
 3. **Testing recommendations**:
    - For skills: Ask questions using trigger phrases from descriptions
-   - For commands: Run `/plugin-name:command-name` with various arguments
+   - For invocable skills: Run `/plugin-name:skill-name` with various arguments
    - For agents: Create scenarios matching agent examples
    - For hooks: Use `claude --debug` to see hook execution
    - For MCP: Use `/mcp` to verify servers and tools
@@ -391,7 +398,7 @@ git commit -m "feat: initial plugin structure"
      - Update marketplace metadata.version (bump patch version)
 
    - If create new marketplace:
-     - Suggest using `/plugin-dev:create-marketplace` command
+     - Suggest using the `/plugin-dev:create-marketplace` skill
      - Or create minimal marketplace.json with this plugin as first entry
    - Validate marketplace after update using plugin-validator agent
 
@@ -399,7 +406,7 @@ git commit -m "feat: initial plugin structure"
    - Mark all tasks complete
    - List what was created:
      - Plugin name and purpose
-     - Components created (X skills, Y commands, Z agents, etc.)
+     - Components created (X skills incl. invocable, Y agents, etc.)
      - Key files and their purposes
      - Total file count and structure
    - If added to marketplace:
@@ -448,7 +455,7 @@ git commit -m "feat: initial plugin structure"
 ### Skills to Load by Phase
 
 - **Phase 2**: plugin-structure
-- **Phase 5**: skill-development, command-development, agent-development, hook-development, mcp-integration, lsp-integration, plugin-settings (as needed)
+- **Phase 5**: skill-development, agent-development, hook-development, mcp-integration, lsp-integration, plugin-settings (as needed)
 - **Phase 6**: (agents will use skills automatically)
 - **Phase 8**: marketplace-structure (if publishing to marketplace)
 
@@ -480,7 +487,7 @@ Every component must meet these standards:
 ### Phase 2: Component Planning
 
 - Skills: 1 (migration best practices)
-- Commands: 3 (create-migration, run-migrations, rollback)
+- Invocable skills: 3 (create-migration, run-migrations, rollback)
 - Agents: 1 (migration-validator)
 - MCP: 1 (database connection)
 

package/extensions/plugin-dev/skills/plugin-dev-guide/SKILL.md

@@ -22,8 +22,7 @@ See `ORGANIZATION.md` in the enact-extensions repo root.
 | Skill | Purpose |
 |-------|---------|
 | **plugin-structure** | Multi-platform layout and manifests |
-| **skill-development** | `skills/*/SKILL.md` |
-| **command-development** | Slash commands in `commands/` |
+| **skill-development** | `skills/*/SKILL.md` — passive and invocable (slash) skills |
 | **hook-development** | `hooks/hooks.json` |
 | **mcp-integration** | `.mcp.json` |
 | **agent-development** | `agents/*.md` (Claude/Cursor) |
@@ -46,14 +45,15 @@ Use when the user needs to:
 - Learn about component auto-discovery
 - Use ${CLAUDE_PLUGIN_ROOT} for portable paths
 
-### Adding User-Facing Commands
+### Adding User-Facing Slash Entry Points (invocable skills)
 
-**Skill: `command-development`**
+**Skill: `skill-development`**
 
-Use when the user needs to:
+There is no separate "command" component — a user-initiated `/name` action is an
+*invocable skill*. Use `skill-development` when the user needs to:
 
-- Create slash commands (/command-name)
-- Configure command frontmatter (description, allowed-tools, model)
+- Create an invocable skill (`/skill-name`)
+- Configure invocable frontmatter (description, allowed-tools, model)
 - Use dynamic arguments ($ARGUMENTS, $1, $2)
 - Reference files with @ syntax
 - Execute bash inline with `[BANG]` backticks
@@ -147,9 +147,8 @@ Use when the user needs to:
 ```
 User wants to...
 ├── Create/organize a plugin structure? → plugin-structure
-├── Add a simple slash command (no bundled resources)? → command-development
+├── Add a slash entry point / any skill (passive or invocable)? → skill-development
 ├── Create an autonomous agent? → agent-development
-├── Add a complex skill with scripts/references? → skill-development
 ├── React to Claude Code events? → hook-development
 ├── Integrate external service/API? → mcp-integration
 ├── Add code intelligence/LSP? → lsp-integration
@@ -162,7 +161,7 @@ User wants to...
 ### Building a Complete Plugin
 
 1. **Start**: Load `plugin-structure` skill to create directory layout
-2. **Add features**: Load `command-development` for user-facing commands
+2. **Add features**: Load `skill-development` for passive and invocable skills
 3. **Automation**: Load `hook-development` for event-driven behavior
 4. **Configuration**: Load `plugin-settings` if user configuration needed
 5. **Validation**: Use plugin-validator agent to validate structure
@@ -171,14 +170,14 @@ User wants to...
 
 1. **Start**: Load `plugin-structure` for basic structure
 2. **Integration**: Load `mcp-integration` to configure MCP servers
-3. **Commands**: Load `command-development` to create commands that use MCP tools
+3. **Skills**: Load `skill-development` to create invocable skills that use MCP tools
 4. **Agents**: Load `agent-development` for autonomous MCP workflows
 
 ### Building a Code Intelligence Plugin
 
 1. **Start**: Load `plugin-structure` for basic structure
 2. **LSP**: Load `lsp-integration` to configure language servers
-3. **Commands**: Load `command-development` for commands using LSP features
+3. **Skills**: Load `skill-development` for invocable skills using LSP features
 
 ### Building a Skill-Focused Plugin
 
@@ -198,9 +197,9 @@ The plugin-dev plugin also provides 3 agents:
 
 Use agents proactively after creating components to ensure quality.
 
-## Available Commands
+## Available Invocable Skills
 
-| Command                          | Purpose                                             |
+| Invocable skill                  | Purpose                                             |
 | -------------------------------- | --------------------------------------------------- |
 | `/plugin-dev:plugin-dev-guide`   | Overview and skill routing                          |
 | `/plugin-dev:start`              | Entry point - choose plugin or marketplace creation |

package/extensions/plugin-dev/skills/skill-development/SKILL.md

@@ -559,6 +559,4 @@ Plugin-dev's skills demonstrate best practices:
 - `../hook-development/` - Progressive disclosure, utilities
 - `../agent-development/` - AI-assisted creation, references
 - `../mcp-integration/` - Comprehensive references
-- `../plugin-settings/` - Real-world examples
-- `../command-development/` - Clear critical concepts
 - `../plugin-structure/` - Good organization

package/extensions/plugin-dev/{commands/start.md → skills/start/SKILL.md}

@@ -1,8 +1,9 @@
 ---
-description: Start plugin development - choose your path
-argument-hint: [description]
-allowed-tools: AskUserQuestion, Skill, TaskCreate, TaskGet, TaskUpdate, TaskList
-model: sonnet
+name: start
+description: >-
+  Entry point for plugin development — routes the user to create or validate an
+  Enact plugin. Use when someone says "start a plugin", "new plugin", "/start",
+  or asks how to begin authoring a plugin.
 disable-model-invocation: true
 ---
 
@@ -34,7 +35,7 @@ Welcome to the Enact Plugin Manager!
 
 **Plugin** → One bundle for Claude, Codex, and Cursor
 - Canonical manifest: .agents/plugin.json
-- Shared components: skills/, commands/, hooks/, .mcp.json
+- Shared components: skills/ (passive + invocable), agents/, hooks/, .mcp.json
 - Host copies: .claude-plugin/, .codex-plugin/, .cursor-plugin/
 - Example: ../enact-operator/extensions/ (sibling top-level submodule of enact-os)
 
@@ -74,7 +75,7 @@ Option 2:
 
 - Load `plugin-structure` when the user is new to multi-platform layout.
 - After editing `.agents/plugin.json`, remind them to run `enact-extensions sync`.
-- Marketplace authoring is archived under `commands/_archive/` — only mention if explicitly requested.
+- Marketplace authoring is archived under `skills/_archive/` — only mention if explicitly requested.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/enact-extensions",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Create and validate Enact multi-platform plugin manifests",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,22 +31,27 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run check:principles && npm run check:hooks && npm run build",
+    "check:principles": "node scripts/check-principles.mjs",
+    "check:hooks": "node scripts/check-hooks.mjs",
+    "check:hooks:smoke": "node scripts/check-hooks.mjs --smoke",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "validate": "npm run build && node scripts/enact-extensions.mjs validate extensions/plugin-dev",
     "sync": "npm run build && node scripts/enact-extensions.mjs sync extensions/plugin-dev",
     "setup:context": "bash scripts/setup-enact-context.sh",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "postinstall": "node scripts/postinstall.mjs"
+    "test": "npm run check:principles && npm run check:hooks:smoke && npm run build && node --test tests/*.test.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepare": "husky"
   },
   "dependencies": {
+    "@iarna/toml": "^2.2.5",
     "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "@iarna/toml": "^2.2.5"
+    "ajv-formats": "^3.0.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.28.0",
+    "husky": "^9.1.7",
     "typescript": "^5.9.3"
   },
   "engines": {

package/scripts/check-hooks.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Repo guard: validate every plugin's hooks before they ship.
+ *
+ * Born from real breakage: enact-operator shipped hook entries for a
+ * doom-loop CLI that had been deleted (module-not-found at runtime), and
+ * enact-factory's npm package omitted `extensions/` from its files whitelist
+ * so `enact-factory hook ...` could never load. Both passed every static check
+ * yet failed the moment Claude Code fired the hook. plugin-dev meanwhile
+ * declared a `hooks` component whose hooks.json was `{ "hooks": {} }` — a
+ * component that installs nothing.
+ *
+ * Two passes:
+ *   STATIC (always, no binaries): every plugin that declares a `hooks` manifest
+ *     field must have a hooks file that is valid JSON, has a NON-EMPTY `hooks`
+ *     object, and whose every entry is a well-formed `command` hook.
+ *   SMOKE (--smoke, best-effort): for each distinct hook command whose binary
+ *     resolves on PATH, actually run it with a synthetic payload in an isolated
+ *     HOME/TMPDIR and fail if it crashes on module resolution (the exact class
+ *     of bug above). Binaries that aren't installed are skipped, so this stays
+ *     green in CI where the plugin CLIs are absent.
+ *
+ * Run via `npm run check:hooks` (static) or `npm run check:hooks:smoke`.
+ */
+import { readFileSync, existsSync, readdirSync, statSync, mkdtempSync, rmSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { spawnSync, execSync } from "node:child_process";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const EXT = join(ROOT, "extensions");
+const SMOKE = process.argv.includes("--smoke");
+
+const errors = [];
+const warnings = [];
+const notes = [];
+const err = (p, m) => errors.push(`[ERROR] ${p}: ${m}`);
+const warn = (p, m) => warnings.push(`[warn]  ${p}: ${m}`);
+const note = (m) => notes.push(`[note]  ${m}`);
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+// Module-resolution / load crash signatures — the failure class this guard exists for.
+const CRASH = [
+  "Cannot find module",
+  "Cannot find package",
+  "ERR_MODULE_NOT_FOUND",
+  "MODULE_NOT_FOUND",
+  "ERR_REQUIRE_ESM",
+  "ERR_PACKAGE_PATH_NOT_EXPORTED",
+];
+
+function onPath(bin) {
+  try { execSync(`command -v ${bin}`, { stdio: "ignore", shell: "/bin/sh" }); return true; }
+  catch { return false; }
+}
+
+// Walk a hooks.json object, yielding { event, command } for every command entry.
+function* commandEntries(hooks, id) {
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) { err(id, `hooks.${event} is not an array`); continue; }
+    for (const g of groups) {
+      const list = g && g.hooks;
+      if (!Array.isArray(list)) { err(id, `hooks.${event} group has no hooks[] array`); continue; }
+      for (const h of list) {
+        if (!h || h.type !== "command") { err(id, `hooks.${event} entry is not a command hook (type="${h && h.type}")`); continue; }
+        if (typeof h.command !== "string" || !h.command.trim()) { err(id, `hooks.${event} command hook has empty command`); continue; }
+        yield { event, command: h.command.trim() };
+      }
+    }
+  }
+}
+
+const smokePayload = JSON.stringify({
+  session_id: "hooks-smoke",
+  transcript_path: "/dev/null",
+  cwd: ROOT,
+  hook_event_name: "Smoke",
+  tool_name: "Bash",
+  tool_input: { command: "true" },
+  tool_response: {},
+});
+
+function smokeRun(command) {
+  const parts = command.split(/\s+/);
+  const bin = parts[0];
+  const args = parts.slice(1);
+  const home = mkdtempSync(join(tmpdir(), "hooks-smoke-"));
+  try {
+    const r = spawnSync(bin, args, {
+      input: smokePayload,
+      timeout: 8000,
+      encoding: "utf8",
+      env: { ...process.env, HOME: home, TMPDIR: home, XDG_CONFIG_HOME: join(home, ".config"), XDG_STATE_HOME: join(home, ".state") },
+    });
+    const out = `${r.stdout || ""}\n${r.stderr || ""}`;
+    if (r.error && r.error.code === "ETIMEDOUT") return { ok: true, soft: "timed out (hook may wait on stdin/state) — not a crash" };
+    if (r.error) return { ok: false, why: r.error.message };
+    const hit = CRASH.find((s) => out.includes(s));
+    if (hit) return { ok: false, why: `module-load crash: "${hit}"` };
+    if (r.signal) return { ok: false, why: `killed by signal ${r.signal}` };
+    return { ok: true };
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
+if (!existsSync(EXT)) {
+  console.error(`No extensions dir at ${EXT}`);
+  process.exit(1);
+}
+
+const smokeCommands = new Set();
+
+for (const name of readdirSync(EXT)) {
+  const root = join(EXT, name);
+  if (!isDir(root)) continue;
+  const manifestPath = join(root, ".agents", "plugin.json");
+  if (!existsSync(manifestPath)) continue;
+  const id = `extensions/${name}`;
+  let m;
+  try { m = JSON.parse(readFileSync(manifestPath, "utf8")); }
+  catch (e) { err(id, `unreadable .agents/plugin.json: ${e.message}`); continue; }
+
+  const field = m.hooks;
+  if (!field) continue; // no hooks declared — nothing to validate here (E2 in check-principles covers undeclared dirs)
+
+  const hooksPath = resolve(root, field);
+  if (!existsSync(hooksPath)) { err(id, `manifest hooks -> "${field}" but file is missing at ${hooksPath}`); continue; }
+
+  let doc;
+  try { doc = JSON.parse(readFileSync(hooksPath, "utf8")); }
+  catch (e) { err(id, `${field} is not valid JSON: ${e.message}`); continue; }
+
+  const hooks = doc && doc.hooks;
+  if (!hooks || typeof hooks !== "object") { err(id, `${field} has no "hooks" object`); continue; }
+  if (Object.keys(hooks).length === 0) {
+    err(id, `${field} declares an empty hooks object — a hooks component that registers nothing; drop the "hooks" manifest field and the file`);
+    continue;
+  }
+
+  for (const { command } of commandEntries(hooks, id)) {
+    smokeCommands.add(command);
+  }
+}
+
+if (SMOKE) {
+  const cmds = [...smokeCommands].sort();
+  const bins = new Set(cmds.map((c) => c.split(/\s+/)[0]));
+  const present = new Set([...bins].filter(onPath));
+  for (const b of bins) if (!present.has(b)) note(`smoke skipped for "${b}" — not on PATH (can't test what isn't installed)`);
+  for (const c of cmds) {
+    const bin = c.split(/\s+/)[0];
+    if (!present.has(bin)) continue;
+    const r = smokeRun(c);
+    if (r.ok && r.soft) warn(`smoke`, `\`${c}\` ${r.soft}`);
+    else if (!r.ok) err(`smoke`, `\`${c}\` ${r.why}`);
+  }
+} else {
+  note(`static only — run with --smoke to exercise installed hook binaries (${smokeCommands.size} distinct commands)`);
+}
+
+for (const n of notes) console.log(n);
+for (const w of warnings) console.log(w);
+for (const e of errors) console.log(e);
+console.log(
+  errors.length
+    ? `\n✗ hooks check FAILED: ${errors.length} error(s), ${warnings.length} warning(s)`
+    : `\n✓ hooks check passed (${warnings.length} warning(s))`,
+);
+process.exit(errors.length ? 1 : 0);

package/scripts/check-principles.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Repo guard: enforce the authoring principles in docs/AUTHORING-GUIDELINES.md.
+ * Fails (exit 1) on any ERROR. Pure Node, no deps. Run via `npm run
+ * check:principles`; also wired into `test` and `prepublishOnly`, and the
+ * optional `.githooks/pre-commit`.
+ *
+ * Rules:
+ *  E1  No commands. A `commands/` dir or a `commands` manifest field is banned —
+ *      commands are skills.
+ *  E2  Declare every component. A `skills/`, `agents/`, or `hooks/` dir on disk
+ *      must be named by the matching manifest field (else it silently doesn't
+ *      install).
+ *  E3  Skill hygiene. Each `skills/<dir>/` needs a `SKILL.md` with `name` +
+ *      `description` frontmatter, and no `README.md`.
+ *  E4  `targets` must not include "enact" (enact is the canonical source).
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const EXT = join(ROOT, "extensions");
+
+const errors = [];
+const warnings = [];
+const err = (p, m) => errors.push(`[ERROR] ${p}: ${m}`);
+const warn = (p, m) => warnings.push(`[warn]  ${p}: ${m}`);
+
+function frontmatter(file) {
+  const t = readFileSync(file, "utf8");
+  if (!t.startsWith("---")) return null;
+  const m = /^---\n([\s\S]*?)\n---/.exec(t);
+  if (!m) return null;
+  const body = m[1];
+  return {
+    name: /(^|\n)name:/.test(body),
+    description: /(^|\n)description:/.test(body),
+  };
+}
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+if (!existsSync(EXT)) {
+  console.error(`No extensions dir at ${EXT}`);
+  process.exit(1);
+}
+
+for (const name of readdirSync(EXT)) {
+  const root = join(EXT, name);
+  if (!isDir(root)) continue;
+  const manifestPath = join(root, ".agents", "plugin.json");
+  if (!existsSync(manifestPath)) continue;
+  const id = `extensions/${name}`;
+  let m;
+  try { m = JSON.parse(readFileSync(manifestPath, "utf8")); }
+  catch (e) { err(id, `unreadable .agents/plugin.json: ${e.message}`); continue; }
+
+  // E1 — no commands
+  if ("commands" in m) err(id, `manifest declares "commands" — commands are skills; remove it`);
+  if (isDir(join(root, "commands"))) err(id, `has a commands/ dir — commands are skills; migrate to skills/`);
+
+  // E4 — targets must not include enact
+  if (Array.isArray(m.targets) && m.targets.includes("enact"))
+    err(id, `targets includes "enact" — enact is the canonical source, never a target`);
+
+  // E2 — declare components that exist on disk
+  for (const comp of ["skills", "agents", "hooks"]) {
+    if (isDir(join(root, comp)) && !m[comp])
+      err(id, `${comp}/ exists on disk but manifest has no "${comp}" field → it will NOT install`);
+  }
+
+  // E3 — skill hygiene
+  const skillsDir = join(root, "skills");
+  if (isDir(skillsDir)) {
+    for (const s of readdirSync(skillsDir)) {
+      const sp = join(skillsDir, s);
+      if (!isDir(sp)) { warn(id, `skills/${s} is a loose file, not a skill dir`); continue; }
+      const smd = join(sp, "SKILL.md");
+      if (!existsSync(smd)) { err(id, `skills/${s} has no SKILL.md`); continue; }
+      const fm = frontmatter(smd);
+      if (!fm) err(id, `skills/${s}/SKILL.md has no YAML frontmatter`);
+      else {
+        if (!fm.name) err(id, `skills/${s}/SKILL.md frontmatter missing "name"`);
+        if (!fm.description) err(id, `skills/${s}/SKILL.md frontmatter missing "description"`);
+      }
+      if (existsSync(join(sp, "README.md"))) err(id, `skills/${s} contains README.md (not allowed in a skill)`);
+    }
+  }
+}
+
+for (const w of warnings) console.log(w);
+for (const e of errors) console.log(e);
+console.log(
+  errors.length
+    ? `\n✗ principles check FAILED: ${errors.length} error(s), ${warnings.length} warning(s)`
+    : `\n✓ principles check passed (${warnings.length} warning(s))`,
+);
+process.exit(errors.length ? 1 : 0);