feat(codex): add lite sharing skills and hooks

Author: visahak

platform-integrations/INSTALL_SPEC.md

@@ -115,12 +115,13 @@ Target: project directory
 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:
+5. Upsert a `SessionStart` hook into `.codex/hooks.json` that runs `plugins/evolve-lite/skills/sync/scripts/sync.py --quiet`
+6. 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
+7. 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.
 
@@ -143,6 +144,7 @@ Codex is currently implemented only in lite mode. Full mode is reserved for futu
 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`
+4. Remove the Evolve `SessionStart` hook from `.codex/hooks.json`
 
 ---
 

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

@@ -1,7 +1,7 @@
 {
   "name": "evolve-lite",
-  "version": "1.0.0",
-  "description": "Recall and save Evolve entities in Codex without MCP.",
+  "version": "1.1.0",
+  "description": "Recall, save, and share Evolve entities in Codex without MCP.",
   "author": {
     "name": "Vinod Muthusamy",
     "url": "https://github.com/AgentToolkit/altk-evolve"
@@ -13,16 +13,18 @@
   "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.",
+    "shortDescription": "Recall, save, and share reusable Evolve entities.",
+    "longDescription": "A lightweight Codex plugin that helps you save reusable entities, publish selected guidance, subscribe to shared repos, and recall relevant memory 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."
+      "Show me the entities stored for this repo.",
+      "Publish one of my Evolve guidelines.",
+      "Subscribe to a teammate's Evolve guidelines repo."
     ],
     "brandColor": "#2563EB"
   }

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

@@ -1,6 +1,6 @@
 # Evolve Lite Plugin for Codex
 
-A plugin that helps Codex learn from conversations by automatically extracting and applying entities.
+A plugin that helps Codex save, recall, and share reusable entities across workspaces.
 
 ⭐ Star the repo: https://github.com/AgentToolkit/altk-evolve
 
@@ -9,20 +9,54 @@ A plugin that helps Codex learn from conversations by automatically extracting a
 - Automatic recall through a repo-level Codex `UserPromptSubmit` hook when Codex hooks are enabled
 - Manual `evolve-lite:learn` skill to save reusable entities into `.evolve/entities/`
 - Manual `evolve-lite:recall` skill to inspect everything stored for the current repo
+- Manual `evolve-lite:publish` skill to publish private guidelines to your public repo
+- Manual `evolve-lite:subscribe` and `evolve-lite:unsubscribe` skills to manage shared guideline repos
+- Automatic or manual `evolve-lite:sync` to mirror subscribed repos into local recall storage
 
 ## Storage
 
-Entities are stored in the active workspace under:
+Entities and sharing data are stored in the active workspace under:
 
 ```text
-.evolve/entities/
-  guideline/
-    use-context-managers-for-file-operations.md
-    cache-api-responses-locally.md
+.evolve/
+  entities/
+    guideline/
+      use-context-managers-for-file-operations.md
+    subscribed/
+      alice/
+        guideline/
+          prefer-small-functions.md
+  public/
+    guideline/
+      no-eval.md
+  subscribed/
+    alice/
+      guideline/
+        prefer-small-functions.md
+  audit.log
 ```
 
 Each entity is a markdown file with lightweight YAML frontmatter.
 
+Sharing configuration lives in `evolve.config.yaml` at the repo root:
+
+```yaml
+identity:
+  user: alice
+
+public_repo:
+  remote: git@github.com:alice/evolve-guidelines.git
+  branch: main
+
+subscriptions:
+  - name: team
+    remote: git@github.com:myorg/evolve-guidelines.git
+    branch: main
+
+sync:
+  on_session_start: true
+```
+
 ## Source Layout
 
 This source tree intentionally omits `lib/`.
@@ -33,7 +67,12 @@ The shared library lives in:
 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.
+`platform-integrations/install.sh` installs Codex in this order:
+
+1. copy the Codex plugin source into `plugins/evolve-lite/`
+2. copy the shared `lib/` from the Claude plugin into `plugins/evolve-lite/lib/`
+3. wire the marketplace entry
+4. wire the Codex hooks
 
 ## Installation
 
@@ -60,6 +99,8 @@ If you do not want to enable Codex hooks, you can still invoke the installed `ev
 
 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.
 
+If `sync.on_session_start` is enabled in `evolve.config.yaml`, the installer also registers a `SessionStart` hook that runs the sync helper quietly whenever a Codex session starts or resumes.
+
 ## Included Skills
 
 ### `evolve-lite:learn`
@@ -69,3 +110,19 @@ Analyze the current session and save proactive Evolve entities as markdown files
 ### `evolve-lite:recall`
 
 Show the entities already stored for the current workspace.
+
+### `evolve-lite:publish`
+
+Copy selected private guidelines into `.evolve/public/`, stamp them as public, and push them to your configured sharing repo.
+
+### `evolve-lite:subscribe`
+
+Clone another user's public guideline repo into `.evolve/subscribed/` and register it in `evolve.config.yaml`.
+
+### `evolve-lite:unsubscribe`
+
+Remove a configured subscription and delete its local clones and mirrored recall entities.
+
+### `evolve-lite:sync`
+
+Pull every configured subscription and mirror its markdown files into `.evolve/entities/subscribed/` so recall can include them automatically.

platform-integrations/codex/plugins/evolve-lite/skills/learn/scripts/save_entities.py

@@ -5,6 +5,7 @@
 in the entities directory, organized by type.
 """
 
+import argparse
 import json
 import sys
 from pathlib import Path
@@ -13,9 +14,14 @@
 _script = Path(__file__).resolve()
 _lib = None
 for _ancestor in _script.parents:
-    _candidate = _ancestor / "lib"
-    if (_candidate / "entity_io.py").is_file():
-        _lib = _candidate
+    for _candidate in (
+        _ancestor / "lib",
+        _ancestor / "platform-integrations" / "claude" / "plugins" / "evolve-lite" / "lib",
+    ):
+        if (_candidate / "entity_io.py").is_file():
+            _lib = _candidate
+            break
+    if _lib is not None:
         break
 if _lib is None:
     raise ImportError(f"Cannot find plugin lib directory above {_script}")
@@ -42,6 +48,10 @@ def normalize(text):
 
 
 def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--user", default=None, help="Stamp owner on every entity written")
+    args = parser.parse_args()
+
     try:
         input_data = json.load(sys.stdin)
         log(f"Received input with keys: {list(input_data.keys())}")
@@ -82,6 +92,11 @@ def main():
             log(f"Skipping duplicate: {content[:60]}")
             continue
 
+        if args.user and not entity.get("owner"):
+            entity["owner"] = args.user
+        if not entity.get("visibility"):
+            entity["visibility"] = "private"
+
         path = write_entity_file(entities_dir, entity)
         existing_contents.add(normalize(content))
         added_count += 1

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

@@ -0,0 +1,77 @@
+---
+name: publish
+description: Publish a private guideline to your public repo so others can subscribe to it.
+---
+
+# Publish Guideline
+
+## Overview
+
+This skill publishes one or more private guidelines from your local `.evolve/entities/guideline/` directory to your public git repository, making them available for others to subscribe to.
+
+## Workflow
+
+### Step 1: Bootstrap config if missing or incomplete
+
+Check whether `evolve.config.yaml` exists in the project root.
+
+If it does not exist, ask the user for:
+
+- a username such as `vatche`
+- the remote URL for the public guidelines repo
+
+Create `evolve.config.yaml` with:
+
+```yaml
+identity:
+  user: {username}
+public_repo:
+  remote: {remote}
+  branch: main
+subscriptions: []
+sync:
+  on_session_start: true
+```
+
+If the file exists but `identity.user` or `public_repo.remote` is missing, ask only for the missing values and update the file.
+
+### Step 2: First-time setup
+
+Ensure `.evolve/` is gitignored at the project root:
+
+```bash
+grep -qxF '.evolve/' .gitignore 2>/dev/null || echo '.evolve/' >> .gitignore
+```
+
+If `.evolve/public/` does not already contain a `.git` directory, initialize it and add the configured remote:
+
+```bash
+git init .evolve/public
+git -C .evolve/public remote add origin {public_repo.remote}
+```
+
+### Step 3: List and select entities
+
+List the files in `.evolve/entities/guideline/` and ask the user which ones to publish.
+
+### Step 4: Run publish script
+
+For each selected file, run:
+
+```bash
+python3 plugins/evolve-lite/skills/publish/scripts/publish.py \
+  --entity "{filename}" \
+  --user "{identity.user}"
+```
+
+### Step 5: Commit and push
+
+```bash
+git -C .evolve/public add .
+git -C .evolve/public commit -m "[evolve] publish: {name}"
+git -C .evolve/public push origin "{public_repo.branch}"
+```
+
+### Step 6: Confirm
+
+Tell the user what was published and where it was pushed.

platform-integrations/codex/plugins/evolve-lite/skills/publish/scripts/publish.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Publish a private guideline entity to the public directory."""
+
+import argparse
+import datetime
+import os
+import sys
+from pathlib import Path
+
+# Walk up from the script location to find the installed plugin lib directory.
+_script = Path(__file__).resolve()
+_lib = None
+for _ancestor in _script.parents:
+    for _candidate in (
+        _ancestor / "lib",
+        _ancestor / "platform-integrations" / "claude" / "plugins" / "evolve-lite" / "lib",
+    ):
+        if (_candidate / "entity_io.py").is_file():
+            _lib = _candidate
+            break
+    if _lib is not None:
+        break
+if _lib is None:
+    raise ImportError(f"Cannot find plugin lib directory above {_script}")
+sys.path.insert(0, str(_lib))
+from audit import append as audit_append  # noqa: E402
+from entity_io import entity_to_markdown, markdown_to_entity  # noqa: E402
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--entity", required=True, help="Basename of the .md file to publish")
+    parser.add_argument("--user", default=None, help="Username to stamp as owner")
+    args = parser.parse_args()
+
+    evolve_dir = Path(os.environ.get("EVOLVE_DIR", ".evolve"))
+    src_base = (evolve_dir / "entities" / "guideline").resolve()
+    src_path = (evolve_dir / "entities" / "guideline" / args.entity).resolve()
+
+    if not src_path.is_relative_to(src_base):
+        print(f"Error: invalid entity name: {args.entity!r}", file=sys.stderr)
+        sys.exit(1)
+
+    if not src_path.exists():
+        print(f"Error: entity file not found: {src_path}", file=sys.stderr)
+        sys.exit(1)
+
+    entity = markdown_to_entity(src_path)
+    entity["visibility"] = "public"
+    if args.user:
+        entity["owner"] = args.user
+    entity["published_at"] = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    dest_dir = evolve_dir / "public" / "guideline"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_base = dest_dir.resolve()
+    dest_path = (dest_dir / args.entity).resolve()
+    if not dest_path.is_relative_to(dest_base):
+        print(f"Error: invalid entity name: {args.entity!r}", file=sys.stderr)
+        sys.exit(1)
+    dest_path.write_text(entity_to_markdown(entity), encoding="utf-8")
+
+    audit_append(
+        project_root=str(evolve_dir.parent) if evolve_dir.name != ".evolve" else ".",
+        action="publish",
+        actor=args.user or "unknown",
+        entity=args.entity,
+    )
+
+    print(f"Published: {args.entity} -> {dest_path}")
+
+
+if __name__ == "__main__":
+    main()