Merge pull request #97 from microsoft/copilot/add-support-for-hooks

feat: Support Hooks as an Agent Primitive

Author: danielmeppiel

README.md

@@ -57,6 +57,7 @@ Skill registries install skills. APM manages **every primitive** your AI agents
 | **Skills** | AI capabilities, workflows | Form builder, code reviewer |
 | **Prompts** | Reusable slash commands | `/security-audit`, `/design-review` |
 | **Agents** | Specialized personas | Accessibility auditor, API designer |
+| **Hooks** | Lifecycle event handlers | Pre-tool validation, post-tool linting |
 | **MCP Servers** | Tool integrations | Database access, API connectors |
 
 All declared in one manifest. All installed with one command — including transitive dependencies:
@@ -119,7 +120,8 @@ my-standards/
     ├── instructions/    # Guardrails (.instructions.md)
     ├── prompts/         # Slash commands (.prompt.md)
     ├── skills/          # Agent Skills (SKILL.md)
-    └── agents/          # Personas (.agent.md)
+    ├── agents/          # Personas (.agent.md)
+    └── hooks/           # Event handlers (.json)
 ```
 
 Add a guardrail and publish:

docs/cli-reference.md

@@ -168,6 +168,8 @@ apm install --exclude codex
 - **Claude Skills**: Repositories with `SKILL.md` (auto-generates `apm.yml` upon installation)
   - Example: `apm install ComposioHQ/awesome-claude-skills/brand-guidelines`
   - Skills are transformed to `.github/agents/*.agent.md` for VSCode target
+- **Hook Packages**: Repositories with `hooks/*.json` (no `apm.yml` or `SKILL.md` required)
+  - Example: `apm install anthropics/claude-plugins-official/plugins/hookify`
 - **Virtual Packages**: Single files or collections installed directly from URLs
   - Single `.prompt.md` or `.agent.md` files from any GitHub repository
   - Collections from curated sources (e.g., `github/awesome-copilot`)
@@ -215,6 +217,7 @@ When you run `apm install`, APM automatically integrates primitives from install
 - **Chatmodes**: `.chatmode.md` files → `.github/agents/*-apm.agent.md` (renamed to modern format)
 - **Control**: Disable with `apm config set auto-integrate false`
 - **Smart updates**: Only updates when package version/commit changes
+- **Hooks**: Hook `.json` files → `.github/hooks/*-apm.json` with scripts bundled
 - **Naming**: Integrated files use `-apm` suffix (e.g., `accessibility-audit-apm.prompt.md`)
 - **GitIgnore**: Pattern `*-apm.prompt.md` automatically added to `.gitignore`
 
@@ -224,6 +227,7 @@ APM also integrates with Claude Code when `.claude/` directory exists:
 
 - **Agents**: `.agent.md` and `.chatmode.md` files → `.claude/agents/*-apm.md`
 - **Commands**: `.prompt.md` files → `.claude/commands/*-apm.md`
+- **Hooks**: Hook definitions merged into `.claude/settings.json` hooks key
 
 **Skill Integration:**
 
@@ -278,6 +282,8 @@ apm uninstall microsoft/apm-sample-package --dry-run
 | Integrated chatmodes | `.github/agents/*-apm.agent.md` |
 | Claude commands | `.claude/commands/*-apm.md` |
 | Skill folders | `.github/skills/{folder-name}/` |
+| Integrated hooks | `.github/hooks/*-apm.json` |
+| Claude hook settings | `.claude/settings.json` (hooks key cleaned) |
 | Lockfile entries | `apm.lock` (removed packages + orphaned transitives) |
 
 **Behavior:**

docs/compilation.md

@@ -41,7 +41,7 @@ target: vscode  # or claude, or all
 | `all` | Both `AGENTS.md` and `CLAUDE.md` | Universal compatibility |
 | `minimal` | `AGENTS.md` only | Works everywhere, no folder integration |
 
-> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](integrations.md) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, and `.claude/commands/`.
+> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](integrations.md) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, and `.claude/commands/`.
 
 ### How It Works
 

docs/concepts.md

@@ -157,6 +157,7 @@ Package your prompt engineering into reusable, configurable components:
 - **Agents** (.agent.md) - AI assistant personalities
 - **Skills** (SKILL.md) - Package meta-guides for AI agents
 - **Context** (.context.md) - Project knowledge base
+- **Hooks** (.json) - Lifecycle event handlers
 
 ### Layer 3: Context Engineering
 
@@ -234,6 +235,20 @@ Optimized project knowledge for AI consumption:
 - Event-driven communication between services
 ```
 
+### Hooks (.json)
+Lifecycle event handlers that run scripts at specific points during AI operations:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": { "tool_name": "write_file" },
+      "hooks": [{ "type": "command", "command": "./scripts/lint.sh" }]
+    }]
+  }
+}
+```
+
 ## Universal Compatibility
 
 APM generates context files for all major coding agents:

docs/dependencies.md

@@ -18,8 +18,7 @@ APM supports multiple dependency types:
 | Type | Detection | Example |
 |------|-----------|---------|
 | **APM Package** | Has `apm.yml` | `microsoft/apm-sample-package` |
-| **Claude Skill** | Has `SKILL.md` (no `apm.yml`) | `ComposioHQ/awesome-claude-skills/brand-guidelines` |
-| **Virtual Subdirectory Package** | Folder path in monorepo | `ComposioHQ/awesome-claude-skills/mcp-builder` |
+| **Claude Skill** | Has `SKILL.md` (no `apm.yml`) | `ComposioHQ/awesome-claude-skills/brand-guidelines` || **Hook Package** | Has `hooks/*.json` (no `apm.yml` or `SKILL.md`) | `anthropics/claude-plugins-official/plugins/hookify` || **Virtual Subdirectory Package** | Folder path in monorepo | `ComposioHQ/awesome-claude-skills/mcp-builder` |
 | **Virtual Subdirectory Package** | Folder path in repo | `github/awesome-copilot/skills/review-and-refactor` |
 | **ADO Package** | Azure DevOps repo | `dev.azure.com/org/project/_git/repo` |
 

docs/integrations.md

@@ -152,6 +152,9 @@ apm install microsoft/apm-sample-package
 
 # Agents are automatically integrated to:
 # .github/agents/*-apm.agent.md (verbatim copy)
+
+# Hooks are automatically integrated to:
+# .github/hooks/*-apm.json (hook definitions with rewritten script paths)
 ```
 
 **How Auto-Integration Works**:
@@ -163,13 +166,14 @@ apm install microsoft/apm-sample-package
 
 **Integration Flow**:
 1. Run `apm install` to fetch APM packages
-2. APM automatically creates `.github/prompts/` and `.github/agents/` directories if needed
-3. Discovers `.prompt.md` and `.agent.md` files in each package
+2. APM automatically creates `.github/prompts/`, `.github/agents/`, and `.github/hooks/` directories if needed
+3. Discovers `.prompt.md`, `.agent.md`, and hook `.json` files in each package
 4. Copies prompts to `.github/prompts/` with `-apm` suffix (e.g., `accessibility-audit-apm.prompt.md`)
 5. Copies agents to `.github/agents/` with `-apm` suffix (e.g., `security-apm.agent.md`)
-6. Updates `.gitignore` to exclude integrated prompts and agents
-7. VSCode automatically loads all prompts and agents for your coding agents
-8. Run `apm uninstall` to automatically remove integrated prompts and agents
+6. Copies hooks to `.github/hooks/` with `-apm` suffix (e.g., `hookify-hooks-apm.json`) and copies referenced scripts
+7. Updates `.gitignore` to exclude integrated prompts, agents, and hooks
+8. VSCode automatically loads all prompts, agents, and hooks for your coding agents
+9. Run `apm uninstall` to automatically remove integrated primitives
 
 **Intent-First Discovery**:
 The `-apm` suffix pattern enables natural autocomplete in VSCode:
@@ -222,10 +226,11 @@ When you run `apm compile`, APM generates Claude-native files:
 When you run `apm install`, APM integrates package primitives into Claude's native structure:
 
 | Location | Purpose |
-|----------|---------||
+|----------|---------|
 | `.claude/agents/*-apm.md` | Sub-agents from installed packages (from `.agent.md` files) |
 | `.claude/commands/*-apm.md` | Slash commands from installed packages (from `.prompt.md` files) |
 | `.claude/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
+| `.claude/settings.json` (hooks key) | Hooks from installed packages (merged into settings) |
 
 ### Automatic Agent Integration
 
@@ -286,6 +291,33 @@ apm install ComposioHQ/awesome-claude-skills/mcp-builder
 3. Updates `.gitignore` to exclude integrated skills
 4. `apm uninstall` removes the skill folder
 
+### Automatic Hook Integration
+
+APM automatically integrates hooks from installed packages. Hooks define lifecycle event handlers (e.g., `PreToolUse`, `PostToolUse`, `Stop`) supported by both VSCode Copilot and Claude Code.
+
+> **Note:** Hook packages must be authored in the target platform's native format. APM handles path rewriting and file placement but does not translate between hook schema formats (e.g., Claude's `command` key vs GitHub Copilot's `bash`/`powershell` keys, or event name casing differences).
+
+```bash
+# Install a package with hooks
+apm install anthropics/claude-plugins-official/plugins/hookify
+
+# VSCode result (.github/hooks/):
+# .github/hooks/hookify-hooks-apm.json       → Hook definitions
+# .github/hooks/scripts/hookify/hooks/*.py   → Referenced scripts
+
+# Claude result (.claude/settings.json):
+# Hooks merged into .claude/settings.json hooks key
+# Scripts copied to .claude/hooks/hookify/
+```
+
+**How hook integration works:**
+1. `apm install` discovers hook JSON files in `.apm/hooks/` or `hooks/` directories
+2. For VSCode: copies hook JSON to `.github/hooks/` with `-apm` suffix and rewrites script paths
+3. For Claude: merges hook definitions into `.claude/settings.json` under the `hooks` key
+4. Copies referenced scripts to the target location
+5. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
+6. `apm uninstall` removes hook files and cleans up merged settings
+
 ### Target-Specific Compilation
 
 Generate only Claude formats when needed:

docs/primitives.md

@@ -69,12 +69,13 @@ apm run review-copilot --param files="src/auth/"
 
 ## Overview
 
-The APM CLI supports four types of primitives:
+The APM CLI supports the following types of primitives:
 
 - **Agents** (`.agent.md`) - Define AI assistant personalities and behaviors (legacy: `.chatmode.md`)
 - **Instructions** (`.instructions.md`) - Provide coding standards and guidelines for specific file types
 - **Skills** (`SKILL.md`) - Package meta-guides that help AI agents understand what a package does
 - **Context** (`.context.md`, `.memory.md`) - Supply background information and project context
+- **Hooks** (`.json` in `.apm/hooks/` or `hooks/`) - Define lifecycle event handlers with script references
 
 > **Note**: Both `.agent.md` (new format) and `.chatmode.md` (legacy format) are fully supported. VSCode provides Quick Fix actions to help migrate from `.chatmode.md` to `.agent.md`.
 
@@ -95,8 +96,12 @@ APM discovers primitives in these locations:
 │   └── *.instructions.md
 ├── context/            # Project context files
 │   └── *.context.md
-└── memory/             # Team info, contacts, etc.
-    └── *.memory.md
+├── memory/             # Team info, contacts, etc.
+│   └── *.memory.md
+└── hooks/              # Lifecycle event handlers
+    ├── *.json          # Hook definitions (JSON)
+    └── scripts/        # Referenced scripts
+        └── *.sh, *.py
 
 # VSCode-compatible structure  
 .github/
@@ -117,7 +122,7 @@ APM discovers primitives in these locations:
 
 ## Component Types Overview
 
-Context implements the complete [AI-Native Development framework](https://danielmeppiel.github.io/awesome-ai-native/docs/concepts/) through four core component types:
+Context implements the complete [AI-Native Development framework](https://danielmeppiel.github.io/awesome-ai-native/docs/concepts/) through the following core component types:
 
 ### Instructions (.instructions.md)
 **Context Engineering Layer** - Targeted guidance by file type and domain
@@ -340,6 +345,38 @@ Team information (`.apm/memory/team-contacts.memory.md`):
 - Sprint planning: Mondays 2:00 PM PST
 ```
 
+### Hooks
+
+Hooks define lifecycle event handlers that run scripts at specific points during AI agent operations (e.g., before/after tool use).
+
+**Format:** `.json` files in `hooks/` or `.apm/hooks/`
+
+**Structure:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": { "tool_name": "write_file" },
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./scripts/lint-changed.sh $TOOL_INPUT_path"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Supported Events:** `PreToolUse`, `PostToolUse`, `Stop`, `Notification`, `SubagentStop`
+
+**Integration:**
+- VSCode: Hook JSON files are copied to `.github/hooks/*-apm.json` with script paths rewritten
+- Claude: Hooks are merged into `.claude/settings.json` under the `hooks` key
+- Scripts referenced by hooks are bundled alongside the hook definitions
+
 ## Discovery and Parsing
 
 The APM CLI automatically discovers and parses all primitive files in your project.

docs/skills.md

@@ -276,6 +276,7 @@ APM automatically detects package types:
 |-----|------|-----------|
 | `apm.yml` only | APM Package | Standard APM primitives |
 | `SKILL.md` only | Claude Skill | Treated as native skill |
+| `hooks/*.json` only | Hook Package | Hook handlers only |
 | Both files | Hybrid Package | Best of both worlds |
 
 ## Target Detection