Register plugin-dev and enforce hooks wrapper

Promote plugins/plugin-dev to a v1.0.0 marketplace plugin and update validation/docs to require the hooks wrapper format. Changes include: add plugin-dev entry to .claude-plugin/marketplace.json; update CI (.github/workflows/plugin-validation.yml) to include all plugins (no longer excluding plugin-dev) and to verify marketplace sync against all plugin dirs; add AGENTS.md to .gitignore; update copilot-instructions, PLUGIN_GUIDELINES, SKILL.md, and migration docs to document governance/atomic workflow and the mandatory wrapper format for hooks ({"hooks": {...}}); improve validation messaging and known-gotchas (CRLF frontmatter issue, validate-agent arithmetic bug notes); and enhance the hook validator (validate-hook-schema.sh) to detect and unwrap the wrapper format before schema checks. These changes align docs, CI, and validators with the new policy that plugin-dev is a first-class marketplace plugin and that hooks must be supplied in the required wrapper format.

Author: nsalvacao

.claude-plugin/marketplace.json

@@ -11,6 +11,17 @@
     "description": "Marketplace for Nuno Salvacao's Claude Code plugins"
   },
   "plugins": [
+    {
+      "name": "plugin-dev",
+      "description": "Comprehensive toolkit for developing Claude Code plugins — hooks, MCP integration, plugin structure, settings, commands, agents, and skills. Forked from anthropics/claude-plugins-official with improvements: wrapper-format support in validator and arithmetic bug fix.",
+      "version": "1.0.0",
+      "author": {
+        "name": "Nuno Salvacao",
+        "email": "nuno.salvacao@gmail.com"
+      },
+      "source": "./plugins/plugin-dev",
+      "category": "development"
+    },
     {
       "name": "strategy-toolkit",
       "description": "Strategic ideation and execution planning toolkit with reproducible frameworks",

.github/copilot-instructions.md

@@ -51,15 +51,14 @@ jobs:
           set -euo pipefail
           while IFS= read -r dir; do
             [ -f "$dir/README.md" ] || { echo "❌ Missing README: $dir/README.md"; exit 1; }
-          done < <(find plugins -mindepth 1 -maxdepth 1 -type d | grep -v '/plugin-dev$' | sort)
+          done < <(find plugins -mindepth 1 -maxdepth 1 -type d | sort)
           echo "✅ All plugins have README.md"
 
       # ── marketplace.json sync ─────────────────────────────────────────────────
       - name: marketplace.json sync with plugins/
         run: |
           set -euo pipefail
-          # plugin-dev is the official toolkit, not a marketplace plugin
-          mapfile -t dirs   < <(find plugins -mindepth 1 -maxdepth 1 -type d -printf "%f\n" | grep -v '^plugin-dev$' | sort)
+          mapfile -t dirs   < <(find plugins -mindepth 1 -maxdepth 1 -type d -printf "%f\n" | sort)
           mapfile -t listed < <(jq -r '.plugins[].name' .claude-plugin/marketplace.json | sort)
           errors=0
           for plugin in "${dirs[@]}"; do

.github/workflows/plugin-validation.yml

@@ -48,3 +48,4 @@ CLAUDE.md
 dashboard.html
 /memory
 TASKS.md
+AGENTS.md

.gitignore

@@ -72,6 +72,50 @@ Before opening a PR for a plugin:
 - [ ] Side effects and generated files are documented
 - [ ] Marketplace entry has been added/updated
 
+## Governance Workflow (Atomic Delivery)
+
+Use this loop for any plugin change (new plugin, plugin update, docs, scripts, hooks, agents, skills).
+
+1. **Plan one logical change** with explicit scope and files.
+2. **Split into atomic subtasks** with clear done conditions.
+3. **Choose verification mode** (behavior changes: test-first where practical; docs/schema/metadata changes: validation-first).
+4. **Implement minimal change** for the current subtask.
+5. **Run relevant local validators** for touched artifacts.
+6. **Check repository consistency** (`plugins/` and `.claude-plugin/marketplace.json` alignment, frontmatter completeness, hook schema compatibility).
+7. **Commit atomically** with a Conventional Commit message.
+8. **Push and open PR**, then wait for online GitHub review and full CI pass in `.github/workflows/plugin-validation.yml`.
+9. **Do not merge as agent**. Merge is manual and happens only after explicit reviewer/user approval.
+
+### Atomic Commit Rules
+
+- One commit should map to one logical objective.
+- Keep coupled updates together when required for consistency (for example validator logic + matching documentation).
+- Do not batch unrelated roadmap/plugin tasks in one commit.
+- Allowed commit types: `feat`, `fix`, `docs`, `refactor`, `chore`, `plugin`, `update`.
+
+### Validation Baseline
+
+Run what applies to your change:
+
+- `jq empty .claude-plugin/marketplace.json`
+- `jq empty plugins/<name>/.claude-plugin/plugin.json`
+- `bash plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh <hooks.json>`
+- `bash plugins/plugin-dev/skills/hook-development/scripts/hook-linter.sh <script.sh>`
+- `bash plugins/plugin-dev/skills/agent-development/scripts/validate-agent.sh <agent.md>`
+- `bash plugins/plugin-dev/skills/plugin-settings/scripts/parse-frontmatter.sh <file> <field>`
+- `shellcheck <script.sh>`
+- `markdownlint-cli2 <changed-docs>`
+
+### Mandatory Cross-Doc Read Order (Agents)
+
+Before implementation and before any commit/PR operation, agents must read and follow:
+
+1. `AGENTS.md`
+2. `.github/copilot-instructions.md`
+3. `CLAUDE.md`
+4. This document (`docs/PLUGIN_GUIDELINES.md`)
+5. Roadmap workflow details when applicable (`.ideas/plugin-dev-roadmap.md`)
+
 ## Versioning Guidance
 
 - Start new plugins at `0.1.0`

docs/PLUGIN_GUIDELINES.md

@@ -61,21 +61,22 @@ Execute bash commands for deterministic checks:
 
 ### Plugin hooks.json Format
 
-**For plugin hooks** in `hooks/hooks.json`, use direct format (canonical):
+**For plugin hooks** in `hooks/hooks.json`, use wrapper format:
 
 ```json
 {
-  "PreToolUse": [...],
-  "Stop": [...],
-  "SessionStart": [...]
+  "hooks": {
+    "PreToolUse": [...],
+    "Stop": [...],
+    "SessionStart": [...]
+  }
 }
 ```
 
 **Key points:**
-- Direct format (shown above) is **canonical and preferred** for new plugins
-- Each hook event is a top-level key (PreToolUse, Stop, SessionStart, etc.)
-- Legacy wrapper format `{"hooks": {...}}` is also accepted by validation but not recommended for new code
-- Older documentation referenced the wrapper format; this has been superseded
+- `hooks` field is **required** wrapper containing actual hook events
+- `description` field is optional (brief explanation of what the hooks do)
+- This is the **plugin-specific format** — distinct from settings format
 
 **Example:**
 ```json
@@ -341,40 +342,42 @@ In plugins, define hooks in `hooks/hooks.json`:
 
 ```json
 {
-  "PreToolUse": [
-    {
-      "matcher": "Write|Edit",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Validate file write safety"
-        }
-      ]
-    }
-  ],
-  "Stop": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Verify task completion"
-        }
-      ]
-    }
-  ],
-  "SessionStart": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
-          "timeout": 10
-        }
-      ]
-    }
-  ]
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Validate file write safety"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Verify task completion"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
 }
 ```