docs: sync KB — codex-agents-marketplace.md

productivity/codex-agents-marketplace.md

@@ -0,0 +1,62 @@
+---
+title: "Codex-to-Claude Agent Converter & Plugin Marketplace"
+description: "Pipeline that converts VoltAgent/awesome-codex-subagents TOML definitions to Claude Code plugin marketplace format, hosted at cal/codex-agents on Gitea."
+type: reference
+domain: productivity
+tags: [claude-code, automation, plugins, agents, gitea]
+---
+
+# Codex Agents Marketplace
+
+## Overview
+
+136+ specialized agent definitions converted from [VoltAgent/awesome-codex-subagents](https://github.com/VoltAgent/awesome-codex-subagents) (OpenAI Codex format) to Claude Code plugin marketplace format.
+
+- **Repo**: `cal/codex-agents` on Gitea (`git@git.manticorum.com:cal/codex-agents.git`)
+- **Local path**: `/mnt/NV2/Development/codex-agents/`
+- **Upstream**: Cloned to `upstream/` (gitignored), pulled on each sync
+
+## Sync Pipeline
+
+```bash
+cd /mnt/NV2/Development/codex-agents
+./sync.sh              # pull upstream + convert changed agents
+./sync.sh --force      # re-convert all regardless of hash
+./sync.sh --dry-run    # preview only
+./sync.sh --verbose    # per-agent status
+```
+
+- `convert.py` handles TOML → Markdown+YAML frontmatter conversion
+- SHA-256 per-file hashes in `codex-manifest.json` skip unchanged agents
+- Deleted upstream agents are auto-removed locally
+- `.claude-plugin/marketplace.json` is regenerated on each sync
+
+## Format Mapping
+
+| Codex | Claude Code |
+|-------|------------|
+| `gpt-5.4` + `high` | `model: opus` |
+| `gpt-5.3-codex-spark` + `medium` | `model: sonnet` |
+| `sandbox_mode: read-only` | `disallowedTools: Edit, Write` |
+| `sandbox_mode: workspace-write` | full tool access |
+| `developer_instructions` | markdown body |
+| `"parent agent"` | replaced with `"orchestrating agent"` |
+
+## Installing Agents
+
+Add marketplace to `~/.claude/settings.json`:
+```json
+"extraKnownMarketplaces": {
+  "codex-agents": { "source": { "source": "git", "url": "https://git.manticorum.com/cal/codex-agents.git" } }
+}
+```
+
+Then:
+```bash
+claude plugin update codex-agents
+claude plugin install docker-expert@codex-agents --scope user
+```
+
+## Agent Categories
+
+10 categories: Core Development (12), Language Specialists (27), Infrastructure (16), Quality & Security (16), Data & AI (12), Developer Experience (13), Specialized Domains (12), Business & Product (11), Meta & Orchestration (10), Research & Analysis (7).