Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
9 changes: 9 additions & 0 deletions .github/workflows/validate-rules.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ on:
pull_request:
paths:
- '.github/workflows/validate-rules.yml'
- '.claude-plugin/**'
- '.codex-plugin/**'
- 'skills/codeguard/**'
- 'sources/**'
- 'src/**'
- 'pyproject.toml'
Expand All @@ -17,6 +20,9 @@ on:
- develop
paths:
- '.github/workflows/validate-rules.yml'
- '.claude-plugin/**'
- '.codex-plugin/**'
- 'skills/codeguard/**'
- 'sources/**'
- 'src/**'
- 'pyproject.toml'
Expand All @@ -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/

Expand Down
67 changes: 67 additions & 0 deletions docs/codex-skill-plugin.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion docs/images/codeguard-install-flowchart.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
15 changes: 8 additions & 7 deletions docs/install-paths.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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) |
Expand Down
2 changes: 1 addition & 1 deletion docs/personas.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 7 additions & 2 deletions src/convert_to_ide_formats.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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}")


Expand Down
53 changes: 45 additions & 8 deletions src/validate_versions.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@
- pyproject.toml
- .claude-plugin/plugin.json
- .claude-plugin/marketplace.json
- .codex-plugin/plugin.json
- skills/codeguard/SKILL.md
"""

import json
Expand Down Expand Up @@ -34,15 +36,15 @@ 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)
return data["version"]


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)
Expand All @@ -52,16 +54,35 @@ 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)
return data["plugins"][0]["version"]


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)
Expand Down Expand Up @@ -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.

Expand All @@ -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,
Expand Down
Loading