Restructure plugin layout to unlock Gemini-format hooks

Author: MajidAbuRmila

.agents/plugins/marketplace.json

@@ -7,8 +7,8 @@
     {
       "name": "cpln",
       "source": {
-        "source": "url",
-        "url": "https://github.com/controlplane-com/ai-plugin.git"
+        "source": "local",
+        "path": "./plugins/cpln"
       },
       "policy": {
         "installation": "INSTALLED_BY_DEFAULT",

.claude-plugin/marketplace.json

@@ -1,5 +1,6 @@
 {
   "name": "controlplane",
+  "description": "Official Control Plane marketplace. Skills, agents, guardrails, and MCP configuration for deploying and managing containerized workloads across AWS, GCP, Azure, and private clouds.",
   "owner": {
     "name": "Control Plane",
     "email": "support@controlplane.com"
@@ -9,7 +10,8 @@
       "name": "cpln",
       "source": {
         "source": "github",
-        "repo": "controlplane-com/ai-plugin"
+        "repo": "controlplane-com/ai-plugin",
+        "path": "plugins/cpln"
       },
       "description": "Control Plane AI workflows, skills, guardrails, and MCP configuration.",
       "version": "1.1.0",

CHANGELOG.md

@@ -8,8 +8,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this
 
 ### Added
 
+- Gemini-format hook config at repo-root `hooks/hooks.json` (`BeforeTool` guards on `run_shell_command` for generic `cpln secret create` and `cpln apply` missing `--file`). Gemini auto-discovers it; Claude and Codex never see it because their plugin root now resolves to `plugins/cpln/`.
+
 ### Changed
 
+- **Repo restructured.** All Claude + Codex plugin content (skills, agents, commands, rules, references, assets, hooks, `.claude-plugin/plugin.json`, `.codex-plugin/`, `.claude-mcp.json`, `.app.json`) moved into `plugins/cpln/`. Marketplaces (`.claude-plugin/marketplace.json`, `.agents/plugins/marketplace.json`) now point at `plugins/cpln`. Gemini extension manifest, marketplace JSONs, and contributor docs stay at repo root. Existing install commands are unchanged; users get the new layout on their next `/plugin upgrade` or marketplace re-add.
+- Claude + Codex hooks now ship in `plugins/cpln/hooks/cpln-hooks.json` and are declared explicitly via the `hooks` field in each plugin manifest, replacing the auto-discovered default path.
+
 ### Fixed
 
 ### Removed

CLAUDE.md

@@ -4,38 +4,51 @@ For end-user installation, capabilities, and supported clients, see `README.md`.
 
 ## Repo layout
 
+The repo is split into two zones: **repo root** holds marketplace manifests, the Gemini extension, and contributor docs; **`plugins/cpln/`** holds the actual Claude + Codex plugin content. Both Claude and Codex resolve their plugin root to `plugins/cpln/` via their marketplace manifests; Gemini uses the repo root as its extension dir. This split exists because Gemini, Claude, and Codex all auto-discover `hooks/hooks.json` at their respective roots with incompatible schemas — keeping their roots distinct lets each tool ship its own hook config without cross-tool warnings or load failures. The Apr 27, 2026 audit confirmed this layout against each CLI's source.
+
+### Repo root (marketplace + Gemini)
+
+- `.claude-plugin/marketplace.json` — Claude marketplace entry. `source.path` points at `plugins/cpln`.
+- `.agents/plugins/marketplace.json` — Codex marketplace entry. `source` is `{local, path: "./plugins/cpln"}`.
+- `gemini-extension.json` — Gemini CLI extension manifest. Declares the `cpln` MCP server and points `contextFileName` at `GEMINI.md`. Gemini treats this directory (the repo root) as the extension dir.
+- `GEMINI.md` — Gemini runtime guardrails. Loaded for every Gemini session via `contextFileName`. Keep it short.
+- `hooks/hooks.json` — **Gemini-only** hook config. Uses Gemini's schema (`BeforeTool`/`AfterTool`, matcher on `run_shell_command`, output `{decision:"deny", reason:"..."}`). Gemini auto-discovers this file from the extension dir; the path is hardcoded in `packages/cli/src/config/extension-manager.ts` and cannot be redirected via the manifest.
+- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `LICENSE`, `SECURITY.md`, `CLAUDE.md` — contributor and end-user docs.
+
+### `plugins/cpln/` (Claude + Codex plugin content)
+
 - `skills/` — Domain-knowledge skill modules. Each lives in its own subdirectory with a `SKILL.md` carrying frontmatter (`name`, `description`).
 - `agents/` — Guided workflow agents. Each is a top-level `<agent>.md` with frontmatter. Companion reference docs that an agent loads on demand live under `references/<agent>/` (kept out of `agents/` so the loader doesn't try to register them as standalone agents).
-- `references/` — On-demand reference docs cited by agents (e.g., `references/workload-troubleshooter/diagnostics.md`). Plain markdown, no frontmatter required. Ships with the plugin install.
+- `references/` — On-demand reference docs cited by agents (e.g., `references/workload-troubleshooter/diagnostics.md`). Plain markdown, no frontmatter required.
 - `commands/` — Slash commands. Each command has a paired `<command>.md` (Claude) and `<command>.toml` (Gemini-style prompt template); keep them aligned.
-- `rules/` — Validation guardrails and manifest references. Files with `alwaysApply: true` in frontmatter (`cli-conventions.md`, `cpln-guardrails.md`) are concatenated and injected into every Claude Code session by the `SessionStart` entry in `hooks/hooks.json`. `alwaysApply` is **not** a native Claude Code field — the hook is what gives it meaning, so adding a new always-on rule means dropping a file with `alwaysApply: true` and nothing else. Treat changes to those files as broad-impact.
-- `hooks/hooks.json` — **Claude-specific** PreToolUse guards on `cpln` Bash patterns plus the `SessionStart` rule injector. Gemini and Codex ignore this file; the Gemini-side equivalents live in `GEMINI.md`.
-- `assets/` — Logos and icons referenced by plugin/marketplace manifests.
-- `.claude-plugin/` — Claude plugin manifest (`plugin.json`) and marketplace entry (`marketplace.json`).
-- `.codex-plugin/plugin.json` — Codex plugin manifest.
-- `.agents/plugins/marketplace.json` — Codex marketplace entry.
-- `gemini-extension.json` — Gemini CLI extension manifest. Declares the `cpln` MCP server and points `contextFileName` at `GEMINI.md` (loaded for end users every session — keep it short).
-- `.claude-mcp.json`, `.codex-plugin/mcp.json`, MCP block in `gemini-extension.json` — three per-client MCP configs pointing at the same hosted server (`https://mcp.cpln.io/mcp`). Keep all three in sync when changing the server URL or auth shape. The Codex file lives inside `.codex-plugin/` (rather than at the repo root as `.mcp.json`) so Claude Code's cwd auto-discovery doesn't try to parse the Codex-format file as a project MCP config when developing in this repo.
+- `rules/` — Validation guardrails and manifest references. Files with `alwaysApply: true` in frontmatter (`cli-conventions.md`, `cpln-guardrails.md`) are concatenated and injected into every Claude **and Codex** session by the `SessionStart` entry in `hooks/cpln-hooks.json`. `alwaysApply` is not a native field — the hook is what gives it meaning. Codex works out of the box because it sets `CLAUDE_PLUGIN_ROOT` for OOTB compatibility (verified in `codex-rs/hooks/src/engine/discovery.rs`) and accepts the same `hookSpecificOutput.additionalContext` schema. Gemini gets the same rules content from `GEMINI.md` via `contextFileName`.
+- `hooks/cpln-hooks.json` — Shared **Claude + Codex** hook config (`PreToolUse` Bash guards + `SessionStart` rule injector). Declared explicitly in `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` via the `hooks` field. Lives at a non-default name so neither tool's strict auto-discovery picks it up alongside the manifest declaration; Claude merges defaults with manifest hooks and Codex 0.x merges too in some paths, so an explicit path is the safest.
+- `assets/` — Logos and icons referenced by plugin manifests.
+- `.claude-plugin/plugin.json` — Claude plugin manifest. All paths in this file (`./skills/`, `./hooks/cpln-hooks.json`, etc.) are relative to `plugins/cpln/`.
+- `.codex-plugin/plugin.json` — Codex plugin manifest. Same path conventions.
+- `.codex-plugin/mcp.json` — Codex MCP config. Lives inside `.codex-plugin/` (rather than as a project-level `.mcp.json`) so Claude's cwd auto-discovery doesn't try to parse the Codex-format file as a project MCP config when developing.
+- `.claude-mcp.json`, `.codex-plugin/mcp.json`, MCP block in `gemini-extension.json` — three per-client MCP configs pointing at the same hosted server (`https://mcp.cpln.io/mcp`). Keep them in sync when changing the server URL or auth shape.
+- `.app.json` — Codex app-level metadata.
 
 ## Authoring conventions
 
 - File names: kebab-case (`workload-manifest-reference.md`, `setup-secret.md`).
-- Frontmatter on skills, agents, and commands: `name` and `description`. Don't add a `version:` field — Claude Code, Codex, and Gemini all ignore it, and the only version users see comes from the per-client manifests (`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`). Rules use `description` plus `alwaysApply` when applicable.
+- Frontmatter on skills, agents, and commands: `name` and `description`. Don't add a `version:` field — Claude, Codex, and Gemini all ignore it, and the only version users see comes from the per-client manifests (`plugins/cpln/.claude-plugin/plugin.json`, `plugins/cpln/.codex-plugin/plugin.json`, `gemini-extension.json`). Rules use `description` plus `alwaysApply` when applicable.
 - Inside skill/rule examples, YAML uses uppercase placeholders: `WORKLOAD`, `GVC`, `ORG`.
 - MCP tool names in Claude-side examples use the `mcp__cpln__` prefix (Claude Code's convention); Gemini and Codex use the bare tool name.
-- **Never write a `cpln` command from memory** when authoring or editing examples in skills/agents/rules. Verify shape and flags with `cpln <command> --help` or `mcp__cpln__cpln_suggest`. `rules/cli-conventions.md` is the canonical CLI reference inside this repo; if you change CLI examples, cross-check against it.
+- **Never write a `cpln` command from memory** when authoring or editing examples in skills/agents/rules. Verify shape and flags with `cpln <command> --help` or `mcp__cpln__cpln_suggest`. `plugins/cpln/rules/cli-conventions.md` is the canonical CLI reference inside this repo; if you change CLI examples, cross-check against it.
 
 ## Local development
 
 Two install paths — pick based on what you're doing.
 
-**Fast iteration** — load the plugin directly from this working tree, no marketplace round-trip. This is the inner-loop workflow most edits use:
+**Fast iteration** — load the plugin directly from this working tree, no marketplace round-trip. The plugin lives in a subdirectory, so target it explicitly:
 
 ```bash
-claude --plugin-dir .
+claude --plugin-dir ./plugins/cpln
 ```
 
-`--plugin-dir` loads the plugin for that session only. Edits to skills, agents, commands, and rules pick up on `/reload-plugins`; edits to `plugin.json`, `hooks/hooks.json`, or MCP config files require restarting the session.
+`--plugin-dir` loads the plugin for that session only. Edits to skills, agents, commands, and rules pick up on `/reload-plugins`; edits to `plugin.json`, `hooks/cpln-hooks.json`, or MCP config files require restarting the session.
 
 **Pre-release verification** — exercise the actual user-facing install path before tagging a release:
 
@@ -49,24 +62,31 @@ Use this to catch install-time issues `--plugin-dir` skips: missing files in the
 ### Validation
 
 ```bash
-claude plugin validate .                       # validates .claude-plugin/* manifests
-jq empty .claude-mcp.json .app.json \
-  .claude-plugin/plugin.json .claude-plugin/marketplace.json \
-  .codex-plugin/plugin.json .codex-plugin/mcp.json \
-  gemini-extension.json hooks/hooks.json \
-  .agents/plugins/marketplace.json
+claude plugin validate .                       # validates .claude-plugin/marketplace.json
+gemini extensions validate .                   # validates gemini-extension.json + hooks/hooks.json
+jq empty \
+  .claude-plugin/marketplace.json \
+  .agents/plugins/marketplace.json \
+  gemini-extension.json \
+  hooks/hooks.json \
+  plugins/cpln/.claude-plugin/plugin.json \
+  plugins/cpln/.codex-plugin/plugin.json \
+  plugins/cpln/.codex-plugin/mcp.json \
+  plugins/cpln/.claude-mcp.json \
+  plugins/cpln/.app.json \
+  plugins/cpln/hooks/cpln-hooks.json
 ```
 
+Codex has no native validator on the CLI; it validates implicitly at install/load. After `codex plugin marketplace add "$(pwd)"`, start a session and check `~/.codex/log/codex-tui.log` for `cpln` or `controlplane` warnings — none should appear.
+
 ### Debug plugin loading
 
 ```bash
-claude --debug
+claude --plugin-dir ./plugins/cpln --debug hooks
 ```
 
-Look for "loading plugin" messages and confirm each component directory (skills, agents, commands, hooks) appears. Use `--debug hooks` (or other category filters shown in `claude --help`) to narrow the output.
-
-To exercise a hook, trigger the matching tool call (Bash for the current hooks) and watch for the `BLOCK:` stderr message; hook definitions live in `hooks/hooks.json`.
+Look for "loading plugin" messages and confirm each component directory (skills, agents, commands, hooks) appears. Use `--debug hooks` (or other category filters shown in `claude --help`) to narrow the output. To exercise a hook, trigger the matching tool call (Bash for the current hooks) and watch for the deny message — hook definitions for Claude/Codex live in `plugins/cpln/hooks/cpln-hooks.json` and the Gemini equivalents live in `hooks/hooks.json` at repo root.
 
 ## Versioning
 
-Versions in `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and `gemini-extension.json` must stay aligned. See `CONTRIBUTING.md` for the full release checklist.
+Versions in `plugins/cpln/.claude-plugin/plugin.json`, `plugins/cpln/.codex-plugin/plugin.json`, and `gemini-extension.json` must stay aligned. See `CONTRIBUTING.md` for the full release checklist.

CONTRIBUTING.md

@@ -5,14 +5,24 @@
 - Keep wording precise and operational, not promotional.
 - Do not invent unsupported client features, marketplace listings, commands, or URLs.
 - Prefer least-privilege and explicit-confirmation guidance for write-capable workflows.
-- Verify `cpln` CLI syntax against `rules/cli-conventions.md`, `skills/cpln/SKILL.md`, `cpln <command> --help`, or MCP suggestion tools.
+- Verify `cpln` CLI syntax against `plugins/cpln/rules/cli-conventions.md`, `plugins/cpln/skills/cpln/SKILL.md`, `cpln <command> --help`, or MCP suggestion tools.
 
 ## Local Checks
 
 Run checks that match the files you changed:
 
 ```bash
-jq empty .claude-mcp.json .app.json .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json .codex-plugin/mcp.json gemini-extension.json hooks/hooks.json .agents/plugins/marketplace.json
+jq empty \
+  .claude-plugin/marketplace.json \
+  .agents/plugins/marketplace.json \
+  gemini-extension.json \
+  hooks/hooks.json \
+  plugins/cpln/.claude-plugin/plugin.json \
+  plugins/cpln/.codex-plugin/plugin.json \
+  plugins/cpln/.codex-plugin/mcp.json \
+  plugins/cpln/.claude-mcp.json \
+  plugins/cpln/.app.json \
+  plugins/cpln/hooks/cpln-hooks.json
 gemini extensions validate .
 ```
 
@@ -22,12 +32,12 @@ For Markdown-only changes, review links, tables, frontmatter, and command exampl
 
 This repo follows [Semantic Versioning](https://semver.org/). The version lives in four manifests that must stay aligned:
 
-| File                                | Path                          |
-| ----------------------------------- | ----------------------------- |
-| `.claude-plugin/plugin.json`        | `.version`                    |
-| `.claude-plugin/marketplace.json`   | `.plugins[0].version`         |
-| `.codex-plugin/plugin.json`         | `.version`                    |
-| `gemini-extension.json`             | `.version`                    |
+| File                                          | Path                          |
+| --------------------------------------------- | ----------------------------- |
+| `plugins/cpln/.claude-plugin/plugin.json`     | `.version`                    |
+| `.claude-plugin/marketplace.json`             | `.plugins[0].version`         |
+| `plugins/cpln/.codex-plugin/plugin.json`      | `.version`                    |
+| `gemini-extension.json`                       | `.version`                    |
 
 Pick the bump based on what changed since the last tag:
 
@@ -81,12 +91,12 @@ Run before tagging:
 - `CHANGELOG.md` `[Unreleased]` section is empty (everything moved into the new versioned section).
 - `README.md` install instructions match the published marketplace IDs.
 - No real secrets, service account tokens, or org-specific values in the diff.
-- `.codex-plugin/mcp.json` uses Codex MCP fields (`url`, `bearer_token_env_var`) and not raw auth headers.
-- `.claude-mcp.json` uses Claude Code MCP fields (`type`, `url`, `headers`) with environment interpolation.
+- `plugins/cpln/.codex-plugin/mcp.json` uses Codex MCP fields (`url`, `bearer_token_env_var`) and not raw auth headers.
+- `plugins/cpln/.claude-mcp.json` uses Claude Code MCP fields (`type`, `url`, `headers`) with environment interpolation.
 - `gemini-extension.json` MCP block uses Gemini CLI fields (`httpUrl`, `headers`) and declares any required extension settings.
 - `LICENSE`, `SECURITY.md`, `.env.example`, `.gitignore` are present.
 - `gemini extensions validate .` is clean.
-- `claude plugin validate .claude-plugin/plugin.json` is clean (or only the deliberate developer-CLAUDE.md warning).
+- `claude plugin validate .` is clean (or only the deliberate developer-CLAUDE.md warning).
 
 ## Pull Requests