agentbundle 0.31.1__tar.gz → 0.33.0__tar.gz

{agentbundle-0.31.1/agentbundle.egg-info → agentbundle-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.31.1
+Version: 0.33.0
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License-Expression: Apache-2.0 OR MIT
@@ -29,7 +29,7 @@ Requires-Dist: pyyaml>=6.0; extra == "lint"
 ## Quick start
 
 ```bash
-pip install agentbundle
+python -m pip install agentbundle
 ```
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
@@ -50,8 +50,36 @@ agentbundle install --pack desk-research --scope user
 
 User-scope packs land in your home directory, not the repo — they're yours, not the team's, and they're there in every project you open.
 
+**Try a pack without committing it** — so the pack is live in this clone while
+`git status` stays clean:
+
+```bash
+agentbundle install --pack core --scope local
+```
+
+Local scope projects the same runtime files as repo scope, then records them in
+`.git/info/exclude`. It requires a Git work tree. Uninstalling removes both the
+projected files and the managed exclude entries; local and repo installs of the
+same pack cannot coexist.
+
 The install auto-detects your agent (`--adapter` overrides). Multi-IDE? Install the same pack for each agent at the same scope — they coexist, and the agents that read `.agents/skills/` (codex, cursor, gemini, copilot) share one skill copy instead of fighting over it. To install from a **different** catalogue, pass it as a trailing argument — a git URL or a local path (`agentbundle install --pack core <catalogue>`); a `config set source <catalogue>` makes that the default, and an editable clone (`pip install -e`) defaults to itself.
 
+## Claude Code marketplace
+
+Claude Code users can install any pack that permits user scope without first
+installing this CLI:
+
+```bash
+claude plugin marketplace add eugenelim/agent-ready-repo
+claude plugin install architect@agent-ready-repo
+```
+
+The marketplace excludes repo-only packs because Claude plugins live in a
+global cache. Install `core` and other repo-only packs with `agentbundle` so
+their files land in the project. For hook-bearing user-scope packs, the
+generated marketplace description lists the authored hook event, matcher,
+timeout, interpreter, and body path before publication.
+
 ## More commands
 
 ```bash
@@ -172,7 +200,12 @@ agentbundle catalogue package \
   --output dist/
 ```
 
-Produces a `catalogue-source-<release>.tar.gz` from a positive allowlist (packs, profiles, guides, marketplace manifest, legal files), with the same build-residue exclusions as the default flavour. Includes a `self-hosted-source-manifest.json` with per-file SHA-256 digests and provenance fields. `agentbundle install` refuses to install a source archive, preventing accidental misuse.
+Produces a `catalogue-source-<release>.tar.gz` from a positive allowlist
+(`catalogue.toml`, packs, profiles, guides, a marketplace manifest when
+present, and legal files), with the same build-residue exclusions as the
+default flavour. Includes a `self-hosted-source-manifest.json` with per-file
+SHA-256 digests and provenance fields. `agentbundle install` refuses to install
+a source archive, preventing accidental misuse.
 
 **Org bootstrap — ship the default channel in your fork:**
 
@@ -198,14 +231,17 @@ Artifactory bootstrap and editable-install detection entirely. `agentbundle` fal
 straight through to the packaged default, so hosts without network access to Artifactory
 still resolve a source without errors.
 
-See the full enterprise adoption guide at
-`docs/guides/_shared/how-to/use-an-artifactory-catalogue.md` for all six flows
-(org bootstrap, repo-scope CI upgrade, user-scope MDM, source-conflict remediation,
-disconnected hosts, and security controls).
+See [Configure catalogue enterprise
+distribution](https://github.com/eugenelim/agent-ready-repo/blob/main/guides/_shared/how-to/configure-catalogue-enterprise-distribution.md)
+for channel setup, authentication, CI upgrades, disconnected hosts, and the
+security boundary.
 
 ## Build your own catalogue
 
-`agentbundle` isn't tied to the agent-ready-repo catalogue. Any repo that lays its packs out the same way can use it.
+`agentbundle` isn't tied to the agent-ready-repo catalogue. A catalogue source
+has two required root markers: a valid `catalogue.toml` and a literal `packs/`
+directory. A custom `catalogue.paths.packs` value controls where pack content
+is read from; it does not replace the root `packs/` marker.
 
 **Bootstrap a new catalogue** in an empty directory:
 
@@ -248,6 +284,7 @@ my-pack/
       evals/                 # activation + output-quality evals, skill-local
     agents/<name>.md         # subagents
     hooks/<name>.py          # lifecycle hooks
+    hook-wiring/<name>.toml  # adapter event wiring for a shipped hook body
   tests/                     # implementation tests — NEVER projected
     skills/<name>/
     hooks/
@@ -276,6 +313,12 @@ on the published distribution branch, and every entry is schema-validated at
 build time against `marketplace-entry.schema.json`. Extra fields stay in `pack.toml`; the projection
 is deliberately lossy per tool.
 
+A hook-bearing pack that permits user scope must explicitly set
+`[pack.install] user-scope-hooks = true`. On the Claude-plugin route,
+`agentbundle` compiles supported Claude-shaped wiring into native plugin hooks
+and rejects unsafe event, matcher, timeout, command, or body-path shapes before
+creating output. Direct CLI installs keep their adapter-native wiring contract.
+
 Point a catalogue URI (a git URL or a local path) at the repo that holds your packs. Then `validate` a pack against the adapter contract, `render` it to preview the projection, and `install` it into a target repo. `scaffold` drops a pack's seeds into a fresh directory to start from. The build pipeline (`agentbundle.build`) is the same engine `make build` runs.
 
 **Org adapter default:** If your org ships a private `agentbundle` wheel (or a fork pinned to your internal catalogue), you can set a default adapter for all developers without requiring them to run `agentbundle config set` or pass `--adapter` on every install. Add an `[organization]` table to `_data/install-defaults.toml` in your fork:
@@ -285,7 +328,7 @@ Point a catalogue URI (a git URL or a local path) at the repo that holds your pa
 preferred_adapter = "cursor"
 ```
 
-The org hint fires after the user-config but before the on-disk IDE probe — so `--adapter`, user-config, and upgrade state-hints all take priority. An invalid value exits 1 before writing anything. See the [`agentbundle` reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/reference/agentbundle.md#org-adapter-default) for the full cascade.
+The org hint fires after the user-config but before the on-disk IDE probe — so `--adapter`, user-config, and upgrade state-hints all take priority. An invalid value exits 1 before writing anything. See the [`agentbundle` reference](https://github.com/eugenelim/agent-ready-repo/blob/main/guides/_shared/reference/agentbundle.md#org-adapter-default) for the full cascade.
 
 **Bundled contracts** — the wheel ships the machine contracts used for offline validation:
 `pack.schema.json`, `skill.schema.json`, `guide.schema.json`, `skill-manifest.schema.json`,
@@ -299,6 +342,11 @@ The org hint fires after the user-config but before the on-disk IDE probe — so
 agentbundle catalogue lint --root .
 ```
 
+Lint validates both source markers and then checks the configured pack content.
+It requires `.claude-plugin/marketplace.json` only when the effective self-host
+adapters include `claude-code`. A Kiro-only catalogue can omit that Claude
+artifact; the default Claude Code and Codex projection still requires it.
+
 For full [agentskills.io spec](https://agentskills.io/specification) compliance (frontmatter key set, description policy, encoding, evals schema), install the `lint` extra and run with `--deep`:
 
 ```bash
@@ -346,7 +394,7 @@ When `preferred-adapter` names an adapter not in the upstream `SELF_HOST_ADAPTER
 agentbundle pack evals run --pack <pack-name> --catalogue-root .
 ```
 
-See the [pack layout reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/architecture/pack-layout.md) and [authoring a skill](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/how-to/author-a-skill.md).
+See the [pack layout reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/architecture/pack-layout.md) and [authoring a skill](https://github.com/eugenelim/agent-ready-repo/blob/main/guides/_shared/how-to/author-a-skill.md).
 
 ## Catalogue defaults and pack config API
 

{agentbundle-0.31.1 → agentbundle-0.33.0}/README-pypi.md

@@ -9,7 +9,7 @@
 ## Quick start
 
 ```bash
-pip install agentbundle
+python -m pip install agentbundle
 ```
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
@@ -30,8 +30,36 @@ agentbundle install --pack desk-research --scope user
 
 User-scope packs land in your home directory, not the repo — they're yours, not the team's, and they're there in every project you open.
 
+**Try a pack without committing it** — so the pack is live in this clone while
+`git status` stays clean:
+
+```bash
+agentbundle install --pack core --scope local
+```
+
+Local scope projects the same runtime files as repo scope, then records them in
+`.git/info/exclude`. It requires a Git work tree. Uninstalling removes both the
+projected files and the managed exclude entries; local and repo installs of the
+same pack cannot coexist.
+
 The install auto-detects your agent (`--adapter` overrides). Multi-IDE? Install the same pack for each agent at the same scope — they coexist, and the agents that read `.agents/skills/` (codex, cursor, gemini, copilot) share one skill copy instead of fighting over it. To install from a **different** catalogue, pass it as a trailing argument — a git URL or a local path (`agentbundle install --pack core <catalogue>`); a `config set source <catalogue>` makes that the default, and an editable clone (`pip install -e`) defaults to itself.
 
+## Claude Code marketplace
+
+Claude Code users can install any pack that permits user scope without first
+installing this CLI:
+
+```bash
+claude plugin marketplace add eugenelim/agent-ready-repo
+claude plugin install architect@agent-ready-repo
+```
+
+The marketplace excludes repo-only packs because Claude plugins live in a
+global cache. Install `core` and other repo-only packs with `agentbundle` so
+their files land in the project. For hook-bearing user-scope packs, the
+generated marketplace description lists the authored hook event, matcher,
+timeout, interpreter, and body path before publication.
+
 ## More commands
 
 ```bash
@@ -152,7 +180,12 @@ agentbundle catalogue package \
   --output dist/
 ```
 
-Produces a `catalogue-source-<release>.tar.gz` from a positive allowlist (packs, profiles, guides, marketplace manifest, legal files), with the same build-residue exclusions as the default flavour. Includes a `self-hosted-source-manifest.json` with per-file SHA-256 digests and provenance fields. `agentbundle install` refuses to install a source archive, preventing accidental misuse.
+Produces a `catalogue-source-<release>.tar.gz` from a positive allowlist
+(`catalogue.toml`, packs, profiles, guides, a marketplace manifest when
+present, and legal files), with the same build-residue exclusions as the
+default flavour. Includes a `self-hosted-source-manifest.json` with per-file
+SHA-256 digests and provenance fields. `agentbundle install` refuses to install
+a source archive, preventing accidental misuse.
 
 **Org bootstrap — ship the default channel in your fork:**
 
@@ -178,14 +211,17 @@ Artifactory bootstrap and editable-install detection entirely. `agentbundle` fal
 straight through to the packaged default, so hosts without network access to Artifactory
 still resolve a source without errors.
 
-See the full enterprise adoption guide at
-`docs/guides/_shared/how-to/use-an-artifactory-catalogue.md` for all six flows
-(org bootstrap, repo-scope CI upgrade, user-scope MDM, source-conflict remediation,
-disconnected hosts, and security controls).
+See [Configure catalogue enterprise
+distribution](https://github.com/eugenelim/agent-ready-repo/blob/main/guides/_shared/how-to/configure-catalogue-enterprise-distribution.md)
+for channel setup, authentication, CI upgrades, disconnected hosts, and the
+security boundary.
 
 ## Build your own catalogue
 
-`agentbundle` isn't tied to the agent-ready-repo catalogue. Any repo that lays its packs out the same way can use it.
+`agentbundle` isn't tied to the agent-ready-repo catalogue. A catalogue source
+has two required root markers: a valid `catalogue.toml` and a literal `packs/`
+directory. A custom `catalogue.paths.packs` value controls where pack content
+is read from; it does not replace the root `packs/` marker.
 
 **Bootstrap a new catalogue** in an empty directory:
 
@@ -228,6 +264,7 @@ my-pack/
       evals/                 # activation + output-quality evals, skill-local
     agents/<name>.md         # subagents
     hooks/<name>.py          # lifecycle hooks
+    hook-wiring/<name>.toml  # adapter event wiring for a shipped hook body
   tests/                     # implementation tests — NEVER projected
     skills/<name>/
     hooks/
@@ -256,6 +293,12 @@ on the published distribution branch, and every entry is schema-validated at
 build time against `marketplace-entry.schema.json`. Extra fields stay in `pack.toml`; the projection
 is deliberately lossy per tool.
 
+A hook-bearing pack that permits user scope must explicitly set
+`[pack.install] user-scope-hooks = true`. On the Claude-plugin route,
+`agentbundle` compiles supported Claude-shaped wiring into native plugin hooks
+and rejects unsafe event, matcher, timeout, command, or body-path shapes before
+creating output. Direct CLI installs keep their adapter-native wiring contract.
+
 Point a catalogue URI (a git URL or a local path) at the repo that holds your packs. Then `validate` a pack against the adapter contract, `render` it to preview the projection, and `install` it into a target repo. `scaffold` drops a pack's seeds into a fresh directory to start from. The build pipeline (`agentbundle.build`) is the same engine `make build` runs.
 
 **Org adapter default:** If your org ships a private `agentbundle` wheel (or a fork pinned to your internal catalogue), you can set a default adapter for all developers without requiring them to run `agentbundle config set` or pass `--adapter` on every install. Add an `[organization]` table to `_data/install-defaults.toml` in your fork:
@@ -265,7 +308,7 @@ Point a catalogue URI (a git URL or a local path) at the repo that holds your pa
 preferred_adapter = "cursor"
 ```
 
-The org hint fires after the user-config but before the on-disk IDE probe — so `--adapter`, user-config, and upgrade state-hints all take priority. An invalid value exits 1 before writing anything. See the [`agentbundle` reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/reference/agentbundle.md#org-adapter-default) for the full cascade.
+The org hint fires after the user-config but before the on-disk IDE probe — so `--adapter`, user-config, and upgrade state-hints all take priority. An invalid value exits 1 before writing anything. See the [`agentbundle` reference](https://github.com/eugenelim/agent-ready-repo/blob/main/guides/_shared/reference/agentbundle.md#org-adapter-default) for the full cascade.
 
 **Bundled contracts** — the wheel ships the machine contracts used for offline validation:
 `pack.schema.json`, `skill.schema.json`, `guide.schema.json`, `skill-manifest.schema.json`,
@@ -279,6 +322,11 @@ The org hint fires after the user-config but before the on-disk IDE probe — so
 agentbundle catalogue lint --root .
 ```
 
+Lint validates both source markers and then checks the configured pack content.
+It requires `.claude-plugin/marketplace.json` only when the effective self-host
+adapters include `claude-code`. A Kiro-only catalogue can omit that Claude
+artifact; the default Claude Code and Codex projection still requires it.
+
 For full [agentskills.io spec](https://agentskills.io/specification) compliance (frontmatter key set, description policy, encoding, evals schema), install the `lint` extra and run with `--deep`:
 
 ```bash
@@ -326,7 +374,7 @@ When `preferred-adapter` names an adapter not in the upstream `SELF_HOST_ADAPTER
 agentbundle pack evals run --pack <pack-name> --catalogue-root .
 ```
 
-See the [pack layout reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/architecture/pack-layout.md) and [authoring a skill](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/how-to/author-a-skill.md).
+See the [pack layout reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/architecture/pack-layout.md) and [authoring a skill](https://github.com/eugenelim/agent-ready-repo/blob/main/guides/_shared/how-to/author-a-skill.md).
 
 ## Catalogue defaults and pack config API
 

{agentbundle-0.31.1 → agentbundle-0.33.0}/agentbundle/_data/adapter.schema.json

@@ -54,6 +54,25 @@
                   ]
                 },
                 "target-path": {"type": "string"},
+                "plugin-target-path": {"type": "string"},
+                "plugin-mode": {
+                  "type": "string",
+                  "enum": [
+                    "direct-directory",
+                    "direct-file",
+                    "merge-json",
+                    "user-merge-json",
+                    "merge-into-agent-json",
+                    "instruction-file",
+                    "managed-block-inline",
+                    "degraded-info-log",
+                    "dropped",
+                    "codex-agent-toml",
+                    "copilot-agent-md",
+                    "copilot-hooks-json",
+                    "gemini-command-toml"
+                  ]
+                },
                 "on-conflict": {
                   "type": "string",
                   "enum": [

{agentbundle-0.31.1 → agentbundle-0.33.0}/agentbundle/_data/adapter.toml

@@ -90,7 +90,10 @@
 # reader cohort. cursor/gemini/copilot route the `skill` primitive to the shared
 # `.agents/skills/` home (joining codex) and gain it in `allowed-prefixes` at
 # both scopes; their agent/hook/command projection stays native.
-version = "0.17"
+# v0.18 (Claude-plugin hook parity): `hook-body` gains the plugin-root
+# `hooks/` target and `hook-wiring` is dropped from the ordinary projection on
+# that route after its entries are compiled into plugin.json.
+version = "0.18"
 
 # Sibling schemas this contract references — pack metadata and the
 # per-pack Claude-plugin manifest.
@@ -202,11 +205,13 @@ on-conflict = "prompt-then-preserve"
 primitive = "hook-body"
 mode = "direct-file"
 target-path = "tools/hooks/"
+plugin-target-path = "hooks/"
 on-conflict = "prompt-then-preserve"
 
 [[adapter."claude-code".projection]]
 primitive = "hook-wiring"
 mode = "merge-json"
+plugin-mode = "dropped"
 target-path = ".claude/settings.local.json"
 managed-key = "hooks"
 on-conflict = "merge-managed-key-only"

{agentbundle-0.31.1 → agentbundle-0.33.0}/agentbundle/_data/plugin-manifest.derived.schema.json

@@ -105,36 +105,39 @@
     },
     "hooks": {
       "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "SessionStart": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "additionalProperties": false,
-            "properties": {
-              "hooks": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "required": [
-                    "type",
-                    "command"
-                  ],
-                  "additionalProperties": false,
-                  "properties": {
-                    "type": {
-                      "type": "string",
-                      "enum": [
-                        "command"
-                      ]
-                    },
-                    "command": {
-                      "type": "string"
-                    },
-                    "timeout": {
-                      "type": "integer"
-                    }
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "hooks"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "matcher": {
+              "type": "string"
+            },
+            "hooks": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "type",
+                  "command"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "command"
+                    ]
+                  },
+                  "command": {
+                    "type": "string"
+                  },
+                  "timeout": {
+                    "type": "integer"
                   }
                 }
               }