aiblueprint-cli 1.4.97 → 1.4.98

package/README.md

@@ -146,6 +146,7 @@ npx skills add Melvynx/aiblueprint --skill skill-manager
 | `create-pr` | Auto-generated pull requests |
 | `fix-pr-comments` | Resolve PR review comments |
 | `grill-me` | Stress-test a plan with focused questions |
+| `hooks-manager` | Create and debug Claude Code hooks |
 | `merge` | Context-aware branch merging |
 | `environments-manager` | Set up per-worktree agent environments |
 | `oneshot` | Implement one focused change quickly |

package/agents-config/skills/hooks-manager/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: hooks-manager
+description: Create, edit, configure, and debug Claude Code hooks. Use when working with hooks, event listeners, command validation, automated workflows, notifications, or hook events such as PreToolUse, PostToolUse, Stop, SessionStart, and UserPromptSubmit.
+---
+
+# Hooks Manager
+
+Configure Claude Code hooks as event-driven commands or prompts. Use hooks for validation, logging, formatting, notifications, context injection, and bounded completion checks.
+
+## Quick workflow
+
+1. Identify the scope: project `.claude/hooks.json` or user `~/.claude/hooks.json`.
+2. Select the event (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`, `PreCompact`, or `Notification`).
+3. Choose a command hook for deterministic shell logic, or a prompt hook when natural-language reasoning is required.
+4. Add a regex matcher for the tools that should trigger it.
+5. Validate the JSON with `jq` and test with `claude --debug`.
+
+## Hook shape
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "./.claude/hooks/check.sh", "timeout": 30000 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Command hooks receive JSON on stdin and may return JSON on stdout. Prompt hooks receive `#$ARGUMENTS` and should return a structured decision. Blocking hooks use `{"decision":"block","reason":"..."}`; non-blocking hooks may return a `systemMessage`.
+
+## Safety requirements
+
+- Check `stop_hook_active` in `Stop` and `SubagentStop` hooks to prevent recursive blocking.
+- Set reasonable timeouts, especially for external commands.
+- Use `$CLAUDE_PROJECT_DIR` or another trusted absolute path for scripts.
+- Validate hook JSON with `jq` before relying on it.
+- Keep blocking rules selective so normal work is not accidentally interrupted.
+- Ensure referenced scripts are executable.
+
+## References
+
+- `references/hook-types.md`: events, input/output, and blocking behavior.
+- `references/command-vs-prompt.md`: choose command versus prompt hooks.
+- `references/matchers.md`: regex and MCP matcher patterns.
+- `references/input-output-schemas.md`: event schemas and response fields.
+- `references/examples.md`: notifications, logging, formatting, tests, and safety examples.
+- `references/troubleshooting.md`: debug, JSON, matcher, permission, and timeout checks.

package/agents-config/skills/hooks-manager/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Hooks Manager"
+  short_description: "Create, edit, configure, and debug Claude Code hooks"
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#868259"
+  default_prompt: "Use $hooks-manager to help with this task."

package/agents-config/skills/hooks-manager/assets/codex-icon.svg

@@ -0,0 +1,5 @@
+<svg role="img" aria-label="hooks-manager skill icon" width="64" height="64" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
+  <rect width="64" height="64" rx="16" fill="#868259"/>
+  <path d="M20 22h24v6H20v-6Zm0 14h16v6H20v-6Zm0 14h24v6H20v-6Z" fill="#fff"/>
+  <circle cx="44" cy="39" r="7" fill="#868259" stroke="#fff" stroke-width="4"/>
+</svg>

package/agents-config/skills/hooks-manager/references/command-vs-prompt.md

@@ -0,0 +1,12 @@
+# Command vs Prompt Hooks
+
+Use command hooks for deterministic, fast work: file checks, regex validation, formatters, linters, logs, and notifications. They receive JSON through stdin and may emit JSON through stdout.
+
+Use prompt hooks when the decision requires semantic or natural-language reasoning. They are slower and consume model/API budget. Include `#$ARGUMENTS` and specify the exact JSON response shape.
+
+```json
+{
+  "type": "prompt",
+  "prompt": "Evaluate this change: #$ARGUMENTS\nReturn {\"decision\":\"approve\" or \"block\",\"reason\":\"...\"}"
+}
+```

package/agents-config/skills/hooks-manager/references/examples.md

@@ -0,0 +1,15 @@
+# Hook Examples
+
+Log Bash commands:
+
+```json
+{"type":"command","command":"jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"}
+```
+
+Format files after edits:
+
+```json
+{"type":"command","command":"prettier --write \"$CLAUDE_PROJECT_DIR\"","timeout":10000}
+```
+
+Block destructive commands with a `PreToolUse` prompt hook, or run a test-checking command on `Stop`. Keep examples scoped to the project and validate the resulting JSON with `jq`.

package/agents-config/skills/hooks-manager/references/hook-types.md

@@ -0,0 +1,13 @@
+# Hook Types and Events
+
+| Event | Fires | Can block? |
+| --- | --- | --- |
+| `PreToolUse` | Before a tool runs | Yes |
+| `PostToolUse` | After a tool completes | No |
+| `UserPromptSubmit` | When the user submits a prompt | Yes |
+| `Stop` / `SubagentStop` | Before an agent stops | Yes |
+| `SessionStart` / `SessionEnd` | At session boundaries | No |
+| `PreCompact` | Before context compaction | Yes |
+| `Notification` | When Claude needs input | No |
+
+Blocking responses should include `decision: "block"` and a useful `reason`. Stop hooks must honor `stop_hook_active` to avoid infinite loops.

package/agents-config/skills/hooks-manager/references/input-output-schemas.md

@@ -0,0 +1,11 @@
+# Input and Output Schemas
+
+Common hook input includes `session_id`, `transcript_path`, `cwd`, `permission_mode`, and `hook_event_name`. Tool events also include `tool_name` and `tool_input`; prompt submission includes `prompt`.
+
+Blocking output:
+
+```json
+{"decision":"block","reason":"Explain what must change"}
+```
+
+Non-blocking output may include `systemMessage` and `suppressOutput`. `PreToolUse` may additionally return `permissionDecision` and `updatedInput`. `Stop` may return `continue: true` and should not block when `stop_hook_active` is true.

package/agents-config/skills/hooks-manager/references/matchers.md

@@ -0,0 +1,9 @@
+# Matchers
+
+Matchers are JavaScript regular expressions tested against the tool name. Use `Bash` for one tool, `Write|Edit` for alternatives, `^Bash` for a tool family, `mcp__.*` for all MCP tools, and `mcp__github__.*` for one MCP server. Omitting `matcher` matches every tool for that event.
+
+Patterns are case-sensitive. Validate uncertain patterns in isolation:
+
+```bash
+node -e "console.log(/Bash/.test('Bash'))"
+```

package/agents-config/skills/hooks-manager/references/troubleshooting.md

@@ -0,0 +1,10 @@
+# Troubleshooting
+
+1. Run `claude --debug` and confirm the event and matcher were found.
+2. Check the config location: `.claude/hooks.json`, `~/.claude/hooks.json`, or the plugin hook file.
+3. Validate syntax with `jq . .claude/hooks.json`.
+4. Confirm matcher case and regex escaping; `bash` does not match `Bash`.
+5. Run command hooks directly with representative JSON on stdin.
+6. Check script permissions, dependencies such as `jq`, trusted paths, and timeout values.
+
+If a Stop hook blocks repeatedly, inspect `stop_hook_active` and return an allow/no-decision response when it is true.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiblueprint-cli",
-  "version": "1.4.97",
+  "version": "1.4.98",
   "description": "AIBlueprint CLI for setting up AI coding configurations",
   "author": "AIBlueprint",
   "license": "MIT",