feat: replace platforms/codex/ with real Codex plugin (#129)

Author: tzachbon

.agents/plugins/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "smart-ralph",
+  "interface": {
+    "displayName": "Smart Ralph Plugins"
+  },
+  "plugins": [
+    {
+      "name": "ralph-specum-codex",
+      "source": {
+        "source": "local",
+        "path": "./plugins/ralph-specum-codex"
+      },
+      "policy": {
+        "installation": "AVAILABLE"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.github/workflows/bats-tests.yml

@@ -4,13 +4,15 @@ on:
   push:
     paths:
       - 'plugins/**/*.sh'
+      - 'plugins/ralph-specum-codex/**'
       - 'tests/**/*.bats'
       - 'tests/helpers/**'
       - 'tests/fixtures/**'
       - '.github/workflows/bats-tests.yml'
   pull_request:
     paths:
       - 'plugins/**/*.sh'
+      - 'plugins/ralph-specum-codex/**'
       - 'tests/**/*.bats'
       - 'tests/helpers/**'
       - 'tests/fixtures/**'

.github/workflows/codex-version-check.yml

@@ -3,7 +3,7 @@ name: Codex Version Check
 on:
   pull_request:
     paths:
-      - 'platforms/codex/**'
+      - 'plugins/ralph-specum-codex/**'
 
 jobs:
   check-version-bump:
@@ -18,7 +18,7 @@ jobs:
       - name: Check Codex manifest version
         run: |
           BASE_BRANCH="${{ github.base_ref }}"
-          MANIFEST="platforms/codex/manifest.json"
+          MANIFEST="plugins/ralph-specum-codex/.codex-plugin/plugin.json"
 
           version_greater() {
             local v1=$1 v2=$2
@@ -50,8 +50,8 @@ jobs:
             exit 1
           fi
 
-          if ! git diff --quiet "origin/${BASE_BRANCH}...HEAD" -- platforms/codex/; then
-            echo "Detected changes under platforms/codex/"
+          if ! git diff --quiet "origin/${BASE_BRANCH}...HEAD" -- plugins/ralph-specum-codex/; then
+            echo "Detected changes under plugins/ralph-specum-codex/"
           else
             echo "No Codex package changes detected"
             exit 0

.github/workflows/plugin-version-check.yml

@@ -95,11 +95,15 @@ jobs:
             echo ""
             echo "=== Checking $plugin_name ==="
 
+            # Check both Claude (.claude-plugin) and Codex (.codex-plugin) manifest paths
             PLUGIN_JSON="plugins/${plugin_name}/.claude-plugin/plugin.json"
+            if [ ! -f "$PLUGIN_JSON" ]; then
+              PLUGIN_JSON="plugins/${plugin_name}/.codex-plugin/plugin.json"
+            fi
 
             if [ ! -f "$PLUGIN_JSON" ]; then
               echo "❌ ERROR: No plugin.json found for $plugin_name!"
-              echo "Plugin changes detected but plugin.json is missing at: $PLUGIN_JSON"
+              echo "Checked: plugins/${plugin_name}/.claude-plugin/plugin.json and plugins/${plugin_name}/.codex-plugin/plugin.json"
               ALL_PASSED=false
               continue
             fi
@@ -115,10 +119,16 @@ jobs:
             echo "plugin.json:      ${BASE_PLUGIN_VERSION:-new} → $PR_PLUGIN_VERSION"
             echo "marketplace.json: ${BASE_MARKETPLACE_VERSION:-new} → $PR_MARKETPLACE_VERSION"
 
-            # Check if plugin exists in marketplace
+            # Check if plugin exists in Claude marketplace
+            # Codex plugins use .agents/plugins/marketplace.json (no version field) and are exempt
             if [ "$PR_MARKETPLACE_VERSION" == "null" ] || [ -z "$PR_MARKETPLACE_VERSION" ]; then
-              echo "❌ ERROR: Plugin $plugin_name not found in marketplace.json!"
-              echo "Please add an entry for $plugin_name in $MARKETPLACE_JSON"
+              echo "ℹ️  Plugin $plugin_name not in Claude marketplace ($MARKETPLACE_JSON)"
+              echo "   Checking if it has its own manifest..."
+              if [ -f "$PLUGIN_JSON" ]; then
+                echo "✅ $plugin_name has manifest at $PLUGIN_JSON (version: $PR_PLUGIN_VERSION)"
+                continue
+              fi
+              echo "❌ ERROR: Plugin $plugin_name not found in any marketplace!"
               ALL_PASSED=false
               continue
             fi

README.md

@@ -51,103 +51,88 @@ Named after the [Ralph agentic loop pattern](https://ghuntley.com/ralph/) and ev
 
 ### Codex
 
-Codex support ships as a versioned package under `platforms/codex/`. Current package version: `4.8.4`.
+**Personal install** (available in every project you open with Codex):
 
-Install the primary skill from this repo:
-
-Prompt to send to Codex:
-
-```text
-Use $skill-installer to install the Smart Ralph Codex skill from repo `tzachbon/smart-ralph` at path `platforms/codex/skills/ralph-specum`.
-First ask whether to install globally under `$CODEX_HOME/skills` or project-local inside this repo.
-Before installing, check whether an existing install already has a `manifest.json` version for Smart Ralph Codex.
-Compare that installed version to `platforms/codex/manifest.json` in this repo.
-If no install exists or the versions differ, run the installer for the selected target.
-If the versions match, say it is already up to date and skip reinstalling.
+```bash
+# 1. Download the plugin
+git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
+mkdir -p ~/.codex/plugins
+cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ~/.codex/plugins/ralph-specum-codex
+rm -rf /tmp/smart-ralph
+
+# 2. Register it in your personal marketplace
+mkdir -p ~/.agents/plugins
+cat > ~/.agents/plugins/marketplace.json << 'EOF'
+{
+  "name": "smart-ralph",
+  "plugins": [{
+    "name": "ralph-specum-codex",
+    "source": {"source": "local", "path": "~/.codex/plugins/ralph-specum-codex"},
+    "policy": {"installation": "AVAILABLE"},
+    "category": "Productivity"
+  }]
+}
+EOF
+
+# 3. Restart Codex, open the plugin directory, install ralph-specum-codex
 ```
 
+**Per-project install** (available only in one repo):
+
 ```bash
-python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
-  --repo tzachbon/smart-ralph \
-  --path platforms/codex/skills/ralph-specum
+# From your project root
+git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
+mkdir -p ./plugins
+cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ./plugins/ralph-specum-codex
+cp -R /tmp/smart-ralph/.agents ./.agents
+rm -rf /tmp/smart-ralph
+
+# Restart Codex, open the plugin directory, install ralph-specum-codex
 ```
 
-Install the helper bundle when you want explicit skill entrypoints:
+**Optional**: Enable the Stop hook for automatic task execution:
 
-Prompt to send to Codex:
+```toml
+# ~/.codex/config.toml
+[features]
+codex_hooks = true
+```
+
+**Or just ask Codex to do it for you:**
 
+Install prompt:
 ```text
-Use $skill-installer to install the Smart Ralph Codex skills from repo `tzachbon/smart-ralph` at these paths:
-- `platforms/codex/skills/ralph-specum`
-- `platforms/codex/skills/ralph-specum-start`
-- `platforms/codex/skills/ralph-specum-triage`
-- `platforms/codex/skills/ralph-specum-research`
-- `platforms/codex/skills/ralph-specum-requirements`
-- `platforms/codex/skills/ralph-specum-design`
-- `platforms/codex/skills/ralph-specum-tasks`
-- `platforms/codex/skills/ralph-specum-implement`
-- `platforms/codex/skills/ralph-specum-status`
-- `platforms/codex/skills/ralph-specum-switch`
-- `platforms/codex/skills/ralph-specum-cancel`
-- `platforms/codex/skills/ralph-specum-index`
-- `platforms/codex/skills/ralph-specum-refactor`
-- `platforms/codex/skills/ralph-specum-feedback`
-- `platforms/codex/skills/ralph-specum-help`
-First ask whether to install globally under `$CODEX_HOME/skills` or project-local inside this repo.
-Before installing, check whether an existing Smart Ralph Codex install already has a `manifest.json` version.
-Compare that installed version to `platforms/codex/manifest.json` in this repo.
-If no install exists or the versions differ, run the installer for the selected target.
-If the versions match, say it is already up to date and skip reinstalling.
+Install the Smart Ralph Codex plugin from repo tzachbon/smart-ralph.
+The plugin is at plugins/ralph-specum-codex. Copy it to my personal
+plugins directory at ~/.codex/plugins/ralph-specum-codex, create a
+personal marketplace entry at ~/.agents/plugins/marketplace.json,
+and restart Codex.
 ```
 
-```bash
-python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
-  --repo tzachbon/smart-ralph \
-  --path \
-    platforms/codex/skills/ralph-specum \
-    platforms/codex/skills/ralph-specum-start \
-    platforms/codex/skills/ralph-specum-triage \
-    platforms/codex/skills/ralph-specum-research \
-    platforms/codex/skills/ralph-specum-requirements \
-    platforms/codex/skills/ralph-specum-design \
-    platforms/codex/skills/ralph-specum-tasks \
-    platforms/codex/skills/ralph-specum-implement \
-    platforms/codex/skills/ralph-specum-status \
-    platforms/codex/skills/ralph-specum-switch \
-    platforms/codex/skills/ralph-specum-cancel \
-    platforms/codex/skills/ralph-specum-index \
-    platforms/codex/skills/ralph-specum-refactor \
-    platforms/codex/skills/ralph-specum-feedback \
-    platforms/codex/skills/ralph-specum-help
+Migrate prompt (if upgrading from the old `platforms/codex/` skills):
+```text
+Migrate from the old Smart Ralph Codex skills to the new plugin.
+Remove all ralph-specum* skills from ~/.codex/skills/ and
+$CODEX_HOME/skills/. Then install the Smart Ralph plugin from
+repo tzachbon/smart-ralph at plugins/ralph-specum-codex into
+my personal plugins directory. Create the marketplace entry
+and restart Codex.
 ```
 
-Upgrade prompt to send to Codex:
+See [`plugins/ralph-specum-codex/README.md`](plugins/ralph-specum-codex/README.md) for agent configs and full details.
 
-```text
-Use $skill-installer to update the Smart Ralph Codex install from repo `tzachbon/smart-ralph`.
-First ask whether the current install lives globally under `$CODEX_HOME/skills` or project-local inside this repo.
-Check the installed Smart Ralph Codex `manifest.json` version and compare it to `platforms/codex/manifest.json` in this repo.
-Only if the versions differ, reinstall these paths into the selected target:
-- `platforms/codex/skills/ralph-specum`
-- `platforms/codex/skills/ralph-specum-start`
-- `platforms/codex/skills/ralph-specum-triage`
-- `platforms/codex/skills/ralph-specum-research`
-- `platforms/codex/skills/ralph-specum-requirements`
-- `platforms/codex/skills/ralph-specum-design`
-- `platforms/codex/skills/ralph-specum-tasks`
-- `platforms/codex/skills/ralph-specum-implement`
-- `platforms/codex/skills/ralph-specum-status`
-- `platforms/codex/skills/ralph-specum-switch`
-- `platforms/codex/skills/ralph-specum-cancel`
-- `platforms/codex/skills/ralph-specum-index`
-- `platforms/codex/skills/ralph-specum-refactor`
-- `platforms/codex/skills/ralph-specum-feedback`
-- `platforms/codex/skills/ralph-specum-help`
-If the versions match, say it is already up to date and do not reinstall.
-Then restart Codex.
-```
+<details>
+<summary>Migrating from old skills (platforms/codex/)?</summary>
+
+The old `platforms/codex/` skill-installer approach is deprecated. Remove your old skill installs and switch to the plugin:
+
+1. Remove old skills: `rm -rf $CODEX_HOME/skills/ralph-specum*`
+2. Follow the plugin install steps above
+3. All 15 skills ship in one package now
 
-More Codex packaging details, including the package manifest at `platforms/codex/manifest.json`, live in [`platforms/codex/README.md`](platforms/codex/README.md).
+See the [migration guide](plugins/ralph-specum-codex/README.md#migration-from-old-skills-platformscodex) for full details.
+
+</details>
 
 <details>
 <summary>Troubleshooting & alternative methods</summary>
@@ -212,7 +197,7 @@ Codex Ralph is approval-gated by default. After each spec artifact, Ralph stops
 
 ## Commands
 
-For Codex, the equivalent public surface is the primary `$ralph-specum` skill plus the installable helper skills under `platforms/codex/skills/`.
+For Codex, the equivalent surface is `$ralph-specum` plus 14 helper skills installed via the `ralph-specum-codex` plugin.
 
 | Command | What it does |
 |---------|--------------|
@@ -391,14 +376,22 @@ smart-ralph/
 ├── .claude-plugin/
 │   └── marketplace.json
 ├── plugins/
-│   ├── ralph-specum/           # Spec workflow (self-contained)
+│   ├── ralph-specum/           # Claude Code plugin (self-contained)
 │   │   ├── .claude-plugin/
 │   │   │   └── plugin.json
 │   │   ├── agents/             # Sub-agent definitions
 │   │   ├── commands/           # Slash commands
 │   │   ├── hooks/              # Stop watcher (controls execution loop)
 │   │   ├── templates/          # Spec templates
 │   │   └── schemas/            # Validation schemas
+│   ├── ralph-specum-codex/     # Codex plugin (full parity)
+│   │   ├── .codex-plugin/
+│   │   │   └── plugin.json
+│   │   ├── skills/             # 15 skills ($ralph-specum-*)
+│   │   ├── hooks/              # Stop watcher (Codex format)
+│   │   ├── agent-configs/      # 9 TOML bootstrap templates
+│   │   ├── templates/          # Spec templates
+│   │   └── references/         # Workflow, state, parity docs
 │   └── ralph-speckit/          # Spec-kit methodology
 │       ├── .claude-plugin/
 │       │   └── plugin.json