feat(platform-integrations): add codex evolve-lite installer

platform-integrations/INSTALL_SPEC.md

@@ -3,7 +3,7 @@
 ## Overview
 
 `install.sh` is a single-file bash/Python hybrid installer that sets up Evolve integrations
-into a user's project directory for one or more supported platforms: **Bob**, **Roo**, and **Claude**.
+into a user's project directory for one or more supported platforms: **Bob**, **Roo**, **Claude**, and **Codex**.
 
 It is designed to be run:
 - Locally from within the evolve repo: `./install.sh install`
@@ -48,13 +48,13 @@ Commands:
   status     Show what is currently installed
 
 install options:
-  --platform {bob,roo,claude,all}   Platform to install (default: auto-detect + prompt)
+  --platform {bob,roo,claude,codex,all}   Platform to install (default: auto-detect + prompt)
   --mode     {lite,full}            Installation mode for bob (default: lite)
   --dir      DIR                    Target project directory (default: current working dir)
   --dry-run                         Preview changes without modifying files
 
 uninstall options:
-  --platform {bob,roo,claude,all}   Platform to uninstall (default: prompt)
+  --platform {bob,roo,claude,codex,all}   Platform to uninstall (default: prompt)
   --dir      DIR                    Target project directory (default: current working dir)
   --dry-run                         Preview changes without modifying files
 ```
@@ -70,6 +70,7 @@ Detection checks in order (any match = platform considered available):
 | bob      | `.bob/` dir exists in target dir, OR `bob` on PATH |
 | roo      | `.roomodes` file exists in target dir, OR `roo` or `roo-code` on PATH |
 | claude   | `.claude/` dir exists in target dir, OR `claude` on PATH |
+| codex    | `.codex/` dir exists in target dir, OR `.agents/plugins/marketplace.json` exists, OR `codex` on PATH |
 
 If no `--platform` flag is given, the script runs interactively: shows detected platforms,
 lets the user pick one, multiple, or all.
@@ -105,7 +106,7 @@ Target: project directory
 3. Merge mode entry from `skills/.roomodes` → `.roomodes` in project dir
    - Target `.roomodes` may be JSON or YAML; detected by trying `json.loads` first
    - Upsert by `slug: evolve-lite` (JSON: array upsert; YAML: sentinel block)
-   - If target does not exist, create as JSON
+   - If target does not exist, create as YAML
 
 ### Claude — Lite Mode
 
@@ -118,6 +119,24 @@ Source: `platform-integrations/claude/plugins/evolve-lite/`
    ```
 3. No file-system fallback for Claude (plugin system manages its own state)
 
+### Codex — Lite Mode
+
+Source: `platform-integrations/codex/plugins/evolve-lite/`
+Target: project directory
+
+1. Copy `platform-integrations/codex/plugins/evolve-lite/` → `plugins/evolve-lite/` in the target project
+2. Copy shared lib from `platform-integrations/claude/plugins/evolve-lite/lib/` → `plugins/evolve-lite/lib/`
+3. Upsert plugin entry `evolve-lite` into `.agents/plugins/marketplace.json`
+4. Upsert a `UserPromptSubmit` hook into `.codex/hooks.json` that runs the Evolve recall helper script by walking upward from the current working directory until it finds `plugins/evolve-lite/skills/recall/scripts/retrieve_entities.py` (does not require `git`)
+5. Print post-install guidance that automatic recall requires `~/.codex/config.toml` to include:
+   ```toml
+   [features]
+   codex_hooks = true
+   ```
+6. Print a manual fallback note that users can invoke `evolve-lite:recall` directly if they do not want to enable Codex hooks
+
+Codex is currently implemented only in lite mode. Full mode is reserved for future MCP-backed work.
+
 ---
 
 ## Uninstall Actions
@@ -138,22 +157,27 @@ Source: `platform-integrations/claude/plugins/evolve-lite/`
 1. Attempt `claude plugin uninstall evolve-lite` via subprocess
 2. If that fails, print manual instructions
 
+### Codex
+1. Remove `plugins/evolve-lite/`
+2. Remove the `evolve-lite` entry from `.agents/plugins/marketplace.json`
+3. Remove the Evolve `UserPromptSubmit` hook from `.codex/hooks.json`
+
 ---
 
 ## File Operation Strategies
 
-### JSON Strategy (mcp.json, .roomodes)
+### JSON Strategy (mcp.json, .roomodes, marketplace.json, hooks.json)
 
 All JSON writes use atomic read-modify-write:
 1. Read existing file (or start with `{}` if not found)
 2. Modify the target key/array in memory
 3. Write to `<path>.evolve.tmp`
 4. `os.replace(tmp, path)` — atomic on POSIX
 
-**Key upsert** (`mcpServers.evolve`): navigate nested keys via `dict.setdefault`, set leaf value.
+**Key upsert** (`mcpServers.evolve`, `hooks.UserPromptSubmit` scaffolding): navigate nested keys via `dict.setdefault`, merge matching dict values in place, and only replace scalar/list leaves.
 
-**Array upsert** (`.roomodes` `customModes`): iterate array, find item where `item["slug"] == target_slug`,
-replace in-place; append if not found.
+**Array upsert** (`.roomodes` `customModes`, `marketplace.json` `plugins`): iterate array, find item where the identity key matches,
+merge matching dict items in place; append if not found.
 
 **Array remove**: filter array by `item["slug"] != target_slug`, write back.
 
@@ -165,14 +189,14 @@ YAML files use sentinel comment blocks:
 customModes:
   - slug: other-mode
     ...
-# >>>evolve-lite<<<
+# >>>evolve:evolve-lite<<<
   - slug: evolve-lite
     name: Evolve Lite
     ...
-# <<<evolve-lite<<<
+# <<<evolve:evolve-lite<<<
 ```
 
-**Install**: check if sentinel `# >>>evolve-lite<<<` exists in file. If yes, replace the block
+**Install**: check if sentinel `# >>>evolve:evolve-lite<<<` exists in file. If yes, replace the block
 between sentinels. If no, append sentinel block to end of file.
 
 **Uninstall**: find sentinel start and end lines, remove all lines between them (inclusive).
@@ -190,6 +214,7 @@ All operations are safe to run multiple times:
 - JSON writes upsert (replace-if-exists, insert-if-not)
 - YAML writes check for sentinel before appending
 - Claude plugin install is idempotent by the Claude CLI itself
+- Codex marketplace and hook writes merge matching Evolve entries and preserve user-owned entries
 
 ---
 

platform-integrations/codex/plugins/evolve-lite/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "evolve-lite",
+  "version": "1.0.0",
+  "description": "Recall and save Evolve entities in Codex without MCP.",
+  "author": {
+    "name": "Vinod Muthusamy",
+    "url": "https://github.com/AgentToolkit/altk-evolve"
+  },
+  "homepage": "https://github.com/AgentToolkit/altk-evolve",
+  "repository": "https://github.com/AgentToolkit/altk-evolve",
+  "license": "MIT",
+  "keywords": ["evolve", "codex", "entities", "memory"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Evolve Lite",
+    "shortDescription": "Recall and save reusable Evolve entities.",
+    "longDescription": "A lightweight Codex plugin that helps you save reusable entities from successful sessions and recall them automatically on new prompts.",
+    "developerName": "AgentToolkit",
+    "category": "Productivity",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://github.com/AgentToolkit/altk-evolve",
+    "defaultPrompt": [
+      "Recall Evolve entities for this task.",
+      "Save new Evolve learnings from this session.",
+      "Show me the entities stored for this repo."
+    ],
+    "brandColor": "#2563EB"
+  }
+}

platform-integrations/codex/plugins/evolve-lite/README.md

@@ -0,0 +1,69 @@
+# Evolve Lite Plugin for Codex
+
+Evolve Lite for Codex provides lightweight file-backed learning and recall without MCP.
+
+## Features
+
+- Automatic recall through a repo-level Codex `UserPromptSubmit` hook when Codex hooks are enabled
+- Manual `learn` skill to save reusable entities into `.evolve/entities/`
+- Manual `recall` skill to inspect everything stored for the current repo
+
+## Storage
+
+Entities are stored in the active workspace under:
+
+```text
+.evolve/entities/
+  guideline/
+    use-context-managers-for-file-operations.md
+    cache-api-responses-locally.md
+```
+
+Each entity is a markdown file with lightweight YAML frontmatter.
+
+## Source Layout
+
+This source tree intentionally omits `lib/`.
+
+The shared library lives in:
+
+```text
+platform-integrations/claude/plugins/evolve-lite/lib/
+```
+
+`platform-integrations/install.sh` copies that shared library into the installed Codex plugin so the installed layout is self-contained.
+
+## Installation
+
+Use the platform installer from the repo root:
+
+```bash
+platform-integrations/install.sh install --platform codex
+```
+
+That installs:
+
+- `plugins/evolve-lite/`
+- `.agents/plugins/marketplace.json`
+- `.codex/hooks.json`
+
+Automatic recall requires Codex hooks to be enabled in `~/.codex/config.toml`:
+
+```toml
+[features]
+codex_hooks = true
+```
+
+If you do not want to enable Codex hooks, you can still invoke the installed `evolve-lite:recall` skill manually to load or inspect the saved guidance for the current repo.
+
+The installed Codex hook does not require `git`. It walks upward from the current working directory until it finds the repo-local `plugins/evolve-lite/.../retrieve_entities.py` script.
+
+## Included Skills
+
+### `learn`
+
+Analyze the current session and save proactive Evolve entities as markdown files.
+
+### `recall`
+
+Show the entities already stored for the current workspace.

platform-integrations/codex/plugins/evolve-lite/skills/learn/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: learn
+description: Extract actionable entities from Codex conversation trajectories. Systematically identifies errors, failures, and inefficiencies to generate proactive entities that prevent them from recurring.
+---
+
+# Entity Generator
+
+## Overview
+
+This skill analyzes the current Codex conversation to extract actionable entities that would help on similar tasks in the future. It **prioritizes errors encountered during the conversation** such as tool failures, exceptions, wrong approaches, and retry loops, then turns them into proactive recommendations that prevent them from recurring.
+
+## Workflow
+
+### Step 1: Analyze the Conversation
+
+Identify from your current conversation:
+
+- **Task/Request**: What was the user asking for?
+- **Steps Taken**: What reasoning, actions, and observations occurred?
+- **What Worked**: Which approaches succeeded?
+- **What Failed**: Which approaches did not work and why?
+- **Errors Encountered**: Tool failures, exceptions, permission errors, retry loops, dead ends, and wrong initial approaches
+
+### Step 2: Identify Errors and Root Causes
+
+Scan the conversation for these error signals:
+
+1. **Tool or command failures**: Non-zero exit codes, error messages, exceptions, stack traces
+2. **Permission or access errors**: "Permission denied", "not found", sandbox restrictions
+3. **Wrong initial approach**: First attempt abandoned in favor of a different strategy
+4. **Retry loops**: Same action attempted multiple times with variations before succeeding
+5. **Missing prerequisites**: Missing dependencies, packages, or configs discovered mid-task
+6. **Silent failures**: Actions that appeared to succeed but produced wrong results
+
+For each error found, document:
+
+| | Error Example | Root Cause | Resolution | Prevention Guideline |
+|---|---|---|---|---|
+| 1 | `exiftool: command not found` | System tool unavailable in sandbox | Switched to Python PIL | Use PIL for image metadata in sandboxed environments |
+| 2 | `git push` rejected (no upstream) | Branch not tracked to remote | Added `-u origin branch` | Always set upstream when pushing a new branch |
+| 3 | Tried regex parsing of HTML, got wrong results | Regex cannot handle nested tags | Switched to BeautifulSoup | Use a proper HTML parser, never regex |
+
+If no errors are found, continue to Step 3 and extract entities from successful patterns.
+
+### Step 3: Extract Entities
+
+Extract 3-5 proactive entities. **Prioritize entities derived from errors identified in Step 2.**
+
+Follow these principles:
+
+1. **Reframe failures as proactive recommendations**
+   If an approach failed due to permissions, recommend the alternative first.
+
+2. **Focus on what worked, stated as the primary approach**
+   Bad: "If exiftool fails, use PIL instead"
+   Good: "In sandboxed environments, use Python libraries like PIL or Pillow for image metadata extraction"
+
+3. **Triggers should be situational context, not failure conditions**
+   Bad trigger: "When apt-get fails"
+   Good trigger: "When working in containerized or sandboxed environments"
+
+4. **For retry loops, recommend the final working approach as the starting point**
+   If three variations were tried before one worked, the entity should recommend the working variation directly.
+
+### Step 4: Output Entities JSON
+
+Output entities in this JSON format:
+
+```json
+{
+  "entities": [
+    {
+      "content": "Proactive entity stating what TO DO",
+      "rationale": "Why this approach works better",
+      "type": "guideline",
+      "trigger": "Situational context when this applies"
+    }
+  ]
+}
+```
+
+### Step 5: Save Entities
+
+After generating the entities JSON, save them using the helper script:
+
+#### Method 1: Direct Pipe
+
+```bash
+echo '<your-json-output>' | python3 "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/plugins/evolve-lite/skills/learn/scripts/save_entities.py"
+```
+
+#### Method 2: From File
+
+```bash
+cat entities.json | python3 "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/plugins/evolve-lite/skills/learn/scripts/save_entities.py"
+```
+
+#### Method 3: Interactive
+
+```bash
+python3 "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/plugins/evolve-lite/skills/learn/scripts/save_entities.py"
+```
+
+The script will:
+
+- Find or create the entities directory at `.evolve/entities/`
+- Write each entity as a markdown file in `{type}/` subdirectories
+- Deduplicate against existing entities
+- Display confirmation with the total count
+
+## Best Practices
+
+1. Prioritize error-derived entities first.
+2. Keep entities specific and actionable.
+3. Include rationale so the future agent understands why the guidance matters.
+4. Use situational triggers instead of failure-based triggers.
+5. Limit output to the 3-5 most valuable entities.