diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..f4f81dd --- /dev/null +++ b/.codex-plugin/plugin.json @@ -0,0 +1,26 @@ +{ + "name": "codeguard-security", + "description": "Security code review skill based on Project CodeGuard's comprehensive security rules. Helps AI coding agents write secure code and prevent common vulnerabilities.", + "version": "1.4.0", + "skills": "./skills/", + "author": { + "name": "Project CodeGuard", + "url": "https://project-codeguard.org" + }, + "homepage": "https://github.com/cosai-oasis/project-codeguard", + "repository": "https://github.com/cosai-oasis/project-codeguard.git", + "license": "CC-BY-4.0", + "keywords": [ + "security", + "secure-coding", + "vulnerability-prevention", + "code-review", + "appsec" + ], + "interface": { + "displayName": "CodeGuard Security", + "shortDescription": "Secure-by-default guidance for AI coding agents", + "developerName": "Project CodeGuard", + "websiteURL": "https://project-codeguard.org" + } +} diff --git a/.github/workflows/validate-rules.yml b/.github/workflows/validate-rules.yml index 06b63f4..ccfb7b7 100644 --- a/.github/workflows/validate-rules.yml +++ b/.github/workflows/validate-rules.yml @@ -8,6 +8,9 @@ on: pull_request: paths: - '.github/workflows/validate-rules.yml' + - '.claude-plugin/**' + - '.codex-plugin/**' + - 'skills/codeguard/**' - 'sources/**' - 'src/**' - 'pyproject.toml' @@ -17,6 +20,9 @@ on: - develop paths: - '.github/workflows/validate-rules.yml' + - '.claude-plugin/**' + - '.codex-plugin/**' + - 'skills/codeguard/**' - 'sources/**' - 'src/**' - 'pyproject.toml' @@ -43,6 +49,9 @@ jobs: - name: Install dependencies run: uv sync + - name: Validate versions + run: uv run python src/validate_versions.py "$(uv version --short)" + - name: Validate unified rules run: uv run python src/validate_unified_rules.py sources/ diff --git a/docs/codex-skill-plugin.md b/docs/codex-skill-plugin.md new file mode 100644 index 0000000..348025b --- /dev/null +++ b/docs/codex-skill-plugin.md @@ -0,0 +1,67 @@ +# CodeGuard Codex Plugin + +## Overview + +Project CodeGuard ships a `.codex-plugin/plugin.json` manifest so Codex can +install and update the `skills/codeguard` skill through its plugin marketplace. + +The plugin intentionally packages only `./skills/`, even though Codex supports +multiple skill paths. It does not include `sources/skills/`, the +`codeguard-reviewer` custom agent, hooks, or an MCP server. See +[Choosing an Install Path](install-paths.md) for those routes. + +## Installation + +### Prerequisites + +- [Codex CLI 0.142.0](https://github.com/openai/codex/releases/tag/rust-v0.142.0) + or newer. Version 0.142.0 added support for marketplace plugins whose source + is the repository root (`./`), which is the layout this repository uses. + +!!! warning "Trust note" + Plugins can provide skills, hooks, and MCP servers. + Only install marketplaces and plugins from sources you trust. + +### Installation steps + +1. **Add the Project CodeGuard marketplace:** + + ```text + codex plugin marketplace add cosai-oasis/project-codeguard + ``` + +2. **Install the CodeGuard plugin from that marketplace:** + + ```text + codex plugin add codeguard-security@project-codeguard + ``` + +### Verifying the installed plugin + +Confirm that Codex reports `codeguard-security` as installed and enabled: + +```text +codex plugin list --marketplace project-codeguard +``` + +Start a new Codex session after installation so the refreshed skill catalog is +available to the model. + +## Updating + +```text +codex plugin marketplace upgrade project-codeguard +codex plugin list --marketplace project-codeguard +``` + +Use the second command to confirm the installed plugin's version and enabled +state, then start a new Codex session. + +## Relationship to the other install routes + +- [Claude Code Plugin](claude-code-skill-plugin.md) — the equivalent managed + install for Claude Code. +- [Choosing an Install Path](install-paths.md) — rule files, Agent Skills, ZIP + bundles, and MCP, including the routes that cover the reviewer agent and the + `sources/skills/` content. +- [Skills](skills.md) — what the skill contains and how it activates. diff --git a/docs/images/codeguard-install-flowchart.svg b/docs/images/codeguard-install-flowchart.svg index a4c5e96..7456e03 100644 --- a/docs/images/codeguard-install-flowchart.svg +++ b/docs/images/codeguard-install-flowchart.svg @@ -169,7 +169,7 @@ Agent Skills — model-invoked on demand, loads only when task is security-relevant → most context-efficient - Plugin marketplace — one-command install, no local files, auto-updates → lowest maintenance + Plugin marketplace — managed install and refresh, no copied rule files → lowest maintenance IDE marketplace extension (.vsix) — one-click install from the IDE's extension marketplace; auto-updates; writes standard rule files under the hood diff --git a/docs/install-paths.md b/docs/install-paths.md index da16641..fe01fbe 100644 --- a/docs/install-paths.md +++ b/docs/install-paths.md @@ -14,7 +14,7 @@ This page helps you pick the right path for your situation. For step-by-step ins |:---|:---|:---| | **Solo developer, one repo** | Rule / instruction files | Glob-scoped — only rules matching the file you're editing load. Lowest token cost, simplest setup. | | **Team sharing via git** | Rule files or Agent Skills, **project-scoped** | Committed to the repo — every contributor gets CodeGuard automatically on clone. | -| **Want zero local files / auto-updates** | Plugin marketplace (Claude Code) or remote instructions (OpenCode) | One command, no files to maintain, always current. | +| **Want a host-managed install and updates** | Plugin marketplace (Claude Code or Codex) or remote instructions (OpenCode) | No copied rule files to maintain; the host manages the installed package. | | **Prefer a one-click install from your IDE's extension marketplace** | IDE marketplace extension (Cursor, Windsurf, Antigravity, VS Code host for Copilot) | Familiar "install extension" UX; auto-updates through the marketplace; one package covers all four VS Code-family IDEs. | | **Org admin enforcing policy** | Org-managed dashboard (Cursor Team Rules, Copilot org instructions) | Centrally enforced across every repo without per-project setup. | | **Already running MCP infrastructure** | MCP server (self-hosted) | Rules served dynamically; integrates with your existing MCP tooling. | @@ -131,12 +131,13 @@ A skill is a self-describing capability the model invokes **on demand** when the ### Plugin marketplace -A managed install: one command, the tool fetches and updates the skill for you. +A managed install: register the marketplace once, then let the host's plugin +tooling install and refresh the skill for you. -- **Supported by:** Claude Code (`/plugin install codeguard-security@project-codeguard`) -- **Best for:** Claude Code users who want the lowest-maintenance setup. -- **Tradeoffs:** Claude Code only. See the [Claude Code Plugin guide](claude-code-skill-plugin.md) for details. -- **Responsible CoSAI personas:** Application Developer, with Agentic Platform and Framework Providers (Claude Code) and AI System Governance for managed-settings enforcement. +- **Supported by:** Claude Code (`/plugin install codeguard-security@project-codeguard`), Codex (`codex plugin marketplace add cosai-oasis/project-codeguard`, then `codex plugin add codeguard-security@project-codeguard`) +- **Best for:** Claude Code and Codex users who want the lowest-maintenance setup. +- **Tradeoffs:** Marketplace installation is available only for Claude Code and Codex. Both plugins include only the CodeGuard skill. Use the ZIP bundle or source files for the reviewer agent. The MCP server remains a separate self-hosted option. See the [Claude Code Plugin guide](claude-code-skill-plugin.md) and the [Codex Plugin guide](codex-skill-plugin.md) for installation details. +- **Responsible CoSAI personas:** Application Developer, with Agentic Platform and Framework Providers (Claude Code, Codex) and AI System Governance for managed-settings enforcement. ### IDE marketplace extension @@ -278,7 +279,7 @@ Project CodeGuard aligns with the [CoSAI standard personas](personas.md) (see th | Rule / instruction files (user scope) | Application Developer, AI System Users | — | | Agent Skills (project scope) | Application Developer | AI System Governance, Agentic Platform and Framework Providers | | Agent Skills (user scope) | Application Developer, AI System Users | Agentic Platform and Framework Providers | -| Plugin marketplace (Claude Code) | Application Developer | Agentic Platform and Framework Providers, AI System Governance | +| Plugin marketplace (Claude Code, Codex) | Application Developer | Agentic Platform and Framework Providers, AI System Governance | | IDE marketplace extension (Cursor, Windsurf, Antigravity, VS Code host for Copilot) | Application Developer | Agentic Platform and Framework Providers, AI System Governance | | Remote instructions / installer (OpenCode, Codex) | Application Developer | Agentic Platform and Framework Providers | | Org-managed dashboard (Cursor Team Rules, GitHub Copilot org custom instructions, Claude Code managed settings) | AI System Governance | Agentic Platform and Framework Providers, AI Platform Provider (for endpoint management) | diff --git a/docs/personas.md b/docs/personas.md index 690d925..7216fa3 100644 --- a/docs/personas.md +++ b/docs/personas.md @@ -35,7 +35,7 @@ The most common persona implementing CodeGuard. - Rule / instruction files (project and user scope) - Agent Skills (project and user scope) -- Plugin marketplace (Claude Code) +- Plugin marketplace (Claude Code, Codex) - Remote instructions / installer (OpenCode, Codex) - Self-service build from source diff --git a/mkdocs.yml b/mkdocs.yml index 9377617..4a24441 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,6 +49,7 @@ nav: - Choosing an Install Path: install-paths.md - CoSAI Personas: personas.md - Claude Code Plugin: claude-code-skill-plugin.md + - Codex Plugin: codex-skill-plugin.md - MCP Server: mcp-server.md - CodeGuard Reviewer: codeguard-reviewer.md - Skills: skills.md diff --git a/src/convert_to_ide_formats.py b/src/convert_to_ide_formats.py index 0024290..af9abe6 100644 --- a/src/convert_to_ide_formats.py +++ b/src/convert_to_ide_formats.py @@ -28,7 +28,11 @@ ClaudeFormat, ) from utils import get_version_from_pyproject -from validate_versions import set_plugin_version, set_marketplace_version +from validate_versions import ( + set_codex_plugin_version, + set_marketplace_version, + set_plugin_version, +) # Project root is always one level up from src/ PROJECT_ROOT = Path(__file__).parent.parent @@ -39,13 +43,14 @@ def sync_plugin_metadata(version: str) -> None: """ - Sync version from pyproject.toml to Agent Skills metadata files. + Sync the project version to the Claude Code and Codex plugin metadata. Args: version: Version string from pyproject.toml """ set_plugin_version(version, PROJECT_ROOT) set_marketplace_version(version, PROJECT_ROOT) + set_codex_plugin_version(version, PROJECT_ROOT) print(f"✅ Synced plugin metadata to {version}") diff --git a/src/validate_versions.py b/src/validate_versions.py index 1af0623..2dff93f 100644 --- a/src/validate_versions.py +++ b/src/validate_versions.py @@ -6,6 +6,8 @@ - pyproject.toml - .claude-plugin/plugin.json - .claude-plugin/marketplace.json +- .codex-plugin/plugin.json +- skills/codeguard/SKILL.md """ import json @@ -34,7 +36,7 @@ def get_pyproject_version(root: Path) -> str: def get_plugin_version(root: Path) -> str: - """Get version from plugin.json.""" + """Get version from the Claude Code plugin manifest.""" plugin_path = root / ".claude-plugin" / "plugin.json" with open(plugin_path, encoding="utf-8") as f: data = json.load(f) @@ -42,7 +44,7 @@ def get_plugin_version(root: Path) -> str: def set_plugin_version(version: str, root: Path) -> None: - """Set version in plugin.json.""" + """Set version in the Claude Code plugin manifest.""" plugin_path = root / ".claude-plugin" / "plugin.json" with open(plugin_path, encoding="utf-8") as f: data = json.load(f) @@ -52,8 +54,27 @@ def set_plugin_version(version: str, root: Path) -> None: f.write("\n") +def get_codex_plugin_version(root: Path) -> str: + """Get version from the Codex plugin.json.""" + plugin_path = root / ".codex-plugin" / "plugin.json" + with open(plugin_path, encoding="utf-8") as f: + data = json.load(f) + return data["version"] + + +def set_codex_plugin_version(version: str, root: Path) -> None: + """Set version in the Codex plugin.json.""" + plugin_path = root / ".codex-plugin" / "plugin.json" + with open(plugin_path, encoding="utf-8") as f: + data = json.load(f) + data["version"] = version + with open(plugin_path, "w", encoding="utf-8") as f: + json.dump(data, f, indent=2) + f.write("\n") + + def get_marketplace_version(root: Path) -> str: - """Get version from marketplace.json.""" + """Get version from the Claude Code marketplace entry.""" marketplace_path = root / ".claude-plugin" / "marketplace.json" with open(marketplace_path, encoding="utf-8") as f: data = json.load(f) @@ -61,7 +82,7 @@ def get_marketplace_version(root: Path) -> str: def set_marketplace_version(version: str, root: Path) -> None: - """Set version in marketplace.json.""" + """Set version in the Claude Code marketplace entry.""" marketplace_path = root / ".claude-plugin" / "marketplace.json" with open(marketplace_path, encoding="utf-8") as f: data = json.load(f) @@ -95,7 +116,9 @@ def get_skill_codeguard_version(root: Path) -> str: return _read_front_matter_value(skill_path, "codeguard-version") -def validate_versions(expected_version: str, root: Path = None) -> list[VersionCheck]: +def validate_versions( + expected_version: str, root: Path | None = None +) -> list[VersionCheck]: """ Validate all versions match the expected version. @@ -113,12 +136,26 @@ def validate_versions(expected_version: str, root: Path = None) -> list[VersionC VersionCheck( "pyproject.toml", expected_version, get_pyproject_version(root), False ), - VersionCheck("plugin.json", expected_version, get_plugin_version(root), False), VersionCheck( - "marketplace.json", expected_version, get_marketplace_version(root), False + ".claude-plugin/plugin.json", + expected_version, + get_plugin_version(root), + False, + ), + VersionCheck( + ".claude-plugin/marketplace.json", + expected_version, + get_marketplace_version(root), + False, + ), + VersionCheck( + ".codex-plugin/plugin.json", + expected_version, + get_codex_plugin_version(root), + False, ), VersionCheck( - "SKILL.md", + "skills/codeguard/SKILL.md", expected_version, get_skill_codeguard_version(root), False,