claudekit-codex-sync 0.2.0 → 0.2.2

package/AGENTS.md

@@ -35,11 +35,8 @@ Codex working profile for this workspace, adapted from ClaudeKit rules and workf
 - Activate relevant skills intentionally per task.
 - For legacy ClaudeKit command intents (`/ck-help`, `/coding-level`, `/ask`, `/docs/*`, `/journal`, `/watzup`), use `$claudekit-command-bridge`.
 
-## Reference Material (Imported from ClaudeKit)
-
-- `~/.codex/claudekit/CLAUDE.md`
-- `~/.codex/claudekit/rules/development-rules.md`
-- `~/.codex/claudekit/rules/primary-workflow.md`
-- `~/.codex/claudekit/rules/orchestration-protocol.md`
-- `~/.codex/claudekit/rules/documentation-management.md`
-- `~/.codex/claudekit/rules/team-coordination-rules.md`
+## Reference Material
+
+- `README.md`
+- `docs/`
+- `plans/`

package/README.md

@@ -13,7 +13,7 @@ ClaudeKit uses `~/.claude/` conventions and agent markdown frontmatter. Codex us
 | **Scope select** | Sync to project `./.codex/` (default) or global `~/.codex/` (`-g`) |
 | **Fresh clean** | Optional `-f` cleanup of target dirs before sync |
 | **Source resolve** | Uses live `~/.claude/` or `--zip` export |
-| **Asset sync** | Copies commands/output-styles/scripts and `.env.example` to `codex_home/claudekit/` |
+| **Asset sync** | Copies agents `.md` → `agents/` (for TOML conversion), commands/output-styles/rules/scripts → `codex_home/claudekit/` |
 | **Skill sync** | Copies skills into `codex_home/skills/` |
 | **Path normalize** | Rewrites `.claude` references to `.codex` |
 | **Config enforce** | Ensures `config.toml`, feature flags, and agent registration |

package/docs/codebase-summary.md

@@ -18,7 +18,7 @@
 ### Core Orchestration
 
 - **`cli.py`** — Main entry point with 8-flag interface (`-g`, `-f`, `--force`, `--zip`, `--source`, `--mcp`, `--no-deps`, `-n`).
-- **`clean_target.py`** — Fresh-sync cleaner for `--fresh` (preserves `skills/.venv`).
+- **`clean_target.py`** — Fresh-sync cleaner for `--fresh` (deletes real `.venv`, keeps symlinks).
 
 ### Source Resolution
 
@@ -26,7 +26,7 @@
 
 ### Asset & Skill Sync
 
-- **`asset_sync_dir.py`** — Live sync for assets and skills with registry-aware overwrite/backup behavior for managed assets.
+- **`asset_sync_dir.py`** — Live sync for assets, agents, and skills. Copies agents directly to `codex_home/agents/` for TOML conversion. Registry-aware overwrite/backup.
 - **`asset_sync_zip.py`** — Zip-based sync path.
 
 ### Normalization & Conversion
@@ -75,6 +75,6 @@ Configured Codex home (.codex project scope or ~/.codex global)
 |---|---|
 | `tests/test_config_enforcer.py` | 4 |
 | `tests/test_path_normalizer.py` | 7 |
-| `tests/test_clean_target.py` | 4 |
+| `tests/test_clean_target.py` | 5 |
 | `tests/test_cli_args.py` | 6 |
-| **Total** | **21** |
+| **Total** | **22** |

package/docs/system-architecture.md

@@ -6,9 +6,11 @@
 ┌─────────────────────┐    ┌──────────────────────────┐
 │ ClaudeKit Source     │    │ Codex Target              │
 │ ~/.claude/ or zip    │───▶│ ./.codex or ~/.codex      │
+│   agents/*.md        │    │   agents/*.toml (convert) │
 │   skills/*           │    │   skills/*                │
 │   commands/          │    │   claudekit/commands/     │
 │   output-styles/     │    │   claudekit/output-styles/│
+│   rules/             │    │   claudekit/rules/        │
 │   scripts/           │    │   claudekit/scripts/      │
 └─────────────────────┘    │   prompts/* (generated)   │
                             │   config.toml             │
@@ -25,12 +27,15 @@ Workspace baseline: `./AGENTS.md` is ensured in the current working directory.
 - Select source: live (`~/.claude/`) or zip (`--zip`)
 
 2. **Asset/skill sync**
-- Copy managed assets and skills
+- Copy agents `.md` directly to `codex_home/agents/` (for TOML conversion)
+- Copy managed assets (commands, output-styles, rules, scripts) to `codex_home/claudekit/`
+- Copy skills to `codex_home/skills/`
 - Apply registry-aware overwrite behavior (`--force`)
 
 3. **Normalization**
 - Rewrite `.claude` references to `.codex`
-- Normalize agent TOMLs and compatibility patches
+- Convert agent `.md` (YAML frontmatter) → `.toml` with model mapping
+- Normalize existing agent TOMLs and compatibility patches
 
 4. **Config enforcement**
 - Enforce `config.toml` defaults
@@ -64,6 +69,7 @@ Workspace baseline: `./AGENTS.md` is ensured in the current working directory.
 ## Design Notes
 
 - Project-first scope reduces accidental global writes while developing.
-- `clean_target.py` preserves `skills/.venv` to keep refresh runs fast.
+- Agents copied to top-level `agents/` (not `claudekit/agents/`) to match conversion function expectations.
+- `clean_target.py` deletes real `.venv` dirs (keeps symlinks) so re-symlink works on refresh.
+- Bootstrap skips pip install when venv is symlinked — packages already present.
 - Registry writes are defensive (`mkdir` before save) to avoid missing-path failures.
-- Bootstrap path prefers symlink reuse for speed; fallback path ensures portability.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudekit-codex-sync",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Sync ClaudeKit skills, agents, and config to Codex CLI",
   "main": "bin/ck-codex-sync.js",
   "bin": {
@@ -12,6 +12,11 @@
     "test": "PYTHONPATH=src python3 -m pytest tests/",
     "lint": "python3 -m py_compile src/claudekit_codex_sync/*.py"
   },
-  "keywords": ["claudekit", "codex", "sync", "skills"],
+  "keywords": [
+    "claudekit",
+    "codex",
+    "sync",
+    "skills"
+  ],
   "license": "MIT"
 }

package/src/claudekit_codex_sync/asset_sync_dir.py

@@ -112,6 +112,28 @@ def sync_assets_from_dir(
         if registry and not dry_run and dst.exists():
             update_entry(registry, rel_path, src, dst)
 
+    # Copy agents directly to codex_home/agents/ (NOT claudekit/agents/)
+    # so convert_agents_md_to_toml() can find and convert them
+    agents_src = source / "agents"
+    if agents_src.exists():
+        agents_dst = codex_home / "agents"
+        if not dry_run:
+            agents_dst.mkdir(parents=True, exist_ok=True)
+        for src_file in sorted(agents_src.rglob("*.md")):
+            if not src_file.is_file():
+                continue
+            rel = src_file.relative_to(agents_src)
+            dst = agents_dst / rel
+            data = src_file.read_bytes()
+            changed, is_added = write_bytes_if_changed(dst, data, mode=None, dry_run=dry_run)
+            if changed:
+                if is_added:
+                    added += 1
+                    print(f"add: agents/{rel}")
+                else:
+                    updated += 1
+                    print(f"update: agents/{rel}")
+
     return {"added": added, "updated": updated, "removed": 0, "skipped": skipped}
 
 

package/src/claudekit_codex_sync/clean_target.py

@@ -23,6 +23,16 @@ def clean_target(codex_home: Path, *, dry_run: bool) -> int:
     if skills.exists():
         for item in skills.iterdir():
             if item.name == ".venv":
+                # Keep symlinks (pointing to ~/.claude/skills/.venv)
+                # Delete real venv dirs so symlink can be created on next bootstrap
+                if item.is_symlink():
+                    continue
+                # Real venv dir → delete so symlink-first strategy works
+                count = sum(1 for p in item.rglob("*") if p.is_file())
+                removed += count
+                if not dry_run:
+                    shutil.rmtree(item)
+                print("fresh: rm skills/.venv (real dir, will be re-symlinked)")
                 continue
             if item.is_dir():
                 count = sum(1 for path in item.rglob("*") if path.is_file())

package/src/claudekit_codex_sync/constants.py

@@ -2,8 +2,8 @@
 
 from typing import List, Set, Tuple
 
-ASSET_DIRS = {"commands", "output-styles", "scripts"}
-ASSET_FILES = {".env.example"}
+ASSET_DIRS = {"commands", "output-styles", "rules", "scripts"}
+ASSET_FILES = {".env.example", ".ck.json"}
 ASSET_MANIFEST = ".sync-manifest-assets.txt"
 PROMPT_MANIFEST = ".claudekit-generated-prompts.txt"
 REGISTRY_FILE = ".claudekit-sync-registry.json"

package/src/claudekit_codex_sync/dep_bootstrapper.py

@@ -88,24 +88,28 @@ def bootstrap_deps(
         run_cmd(["python3", "-m", "venv", str(venv_dir)], dry_run=dry_run)
         run_cmd([str(py_bin), "-m", "pip", "install", "--upgrade", "pip"], dry_run=dry_run)
 
-    req_files = sorted(skills_dir.rglob("requirements*.txt"))
-    for req in req_files:
-        if is_excluded_path(req.parts):
-            continue
-        if not include_mcp and ("mcp-builder" in req.parts or "mcp-management" in req.parts):
-            continue
-        try:
-            run_cmd([str(py_bin), "-m", "pip", "install", "-r", str(req)], dry_run=dry_run)
-            py_ok += 1
-        except subprocess.CalledProcessError:
-            py_fail += 1
-            eprint(f"python deps failed: {req}")
-
-    node_ok, node_fail = _install_node_deps(
-        skills_dir=skills_dir,
-        include_mcp=include_mcp,
-        dry_run=dry_run,
-    )
+    # Skip dependency install when venv is symlinked — packages already in source
+    if not symlinked:
+        req_files = sorted(skills_dir.rglob("requirements*.txt"))
+        for req in req_files:
+            if is_excluded_path(req.parts):
+                continue
+            if not include_mcp and ("mcp-builder" in req.parts or "mcp-management" in req.parts):
+                continue
+            try:
+                run_cmd([str(py_bin), "-m", "pip", "install", "-r", str(req)], dry_run=dry_run)
+                py_ok += 1
+            except subprocess.CalledProcessError:
+                py_fail += 1
+                eprint(f"python deps failed: {req}")
+
+        node_ok, node_fail = _install_node_deps(
+            skills_dir=skills_dir,
+            include_mcp=include_mcp,
+            dry_run=dry_run,
+        )
+    else:
+        print("skip: deps install (venv symlinked, packages shared)")
 
     return {
         "python_ok": py_ok,

package/src/claudekit_codex_sync/runtime_verifier.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
+import shutil
+import subprocess
 from pathlib import Path
-from typing import Dict, Optional, Any
-
-from .utils import run_cmd
+from typing import Any, Dict
 
 
 def verify_runtime(*, codex_home: Path, dry_run: bool) -> Dict[str, Any]:
@@ -13,19 +13,29 @@ def verify_runtime(*, codex_home: Path, dry_run: bool) -> Dict[str, Any]:
     if dry_run:
         return {"skipped": True}
 
-    run_cmd(["codex", "--help"], dry_run=False)
+    # Silent codex check — just verify it exists and runs
+    codex_bin = shutil.which("codex")
+    codex_ok = False
+    if codex_bin:
+        result = subprocess.run(
+            [codex_bin, "--version"], capture_output=True, timeout=10
+        )
+        codex_ok = result.returncode == 0
 
+    # Silent copywriting check
     copy_script = codex_home / "skills" / "copywriting" / "scripts" / "extract-writing-styles.py"
     py_bin = codex_home / "skills" / ".venv" / "bin" / "python3"
     copywriting_ok = False
     if copy_script.exists() and py_bin.exists():
-        run_cmd([str(py_bin), str(copy_script), "--list"], dry_run=False)
-        copywriting_ok = True
+        result = subprocess.run(
+            [str(py_bin), str(copy_script), "--list"], capture_output=True, timeout=30
+        )
+        copywriting_ok = result.returncode == 0
 
     prompts_count = len(list((codex_home / "prompts").glob("*.md")))
     skills_count = len(list((codex_home / "skills").rglob("SKILL.md")))
     return {
-        "codex_help": "ok",
+        "codex": "ok" if codex_ok else "missing",
         "copywriting": "ok" if copywriting_ok else "skipped",
         "prompts": prompts_count,
         "skills": skills_count,

package/tests/test_clean_target.py

@@ -18,23 +18,43 @@ def test_clean_removes_agents(tmp_path: Path):
     assert removed >= 2
 
 
-def test_clean_keeps_venv(tmp_path: Path):
-    """Clean keeps skills/.venv intact."""
+def test_clean_keeps_venv_symlink(tmp_path: Path):
+    """Clean keeps symlinked .venv but deletes real .venv dirs."""
     skills = tmp_path / "skills"
     skills.mkdir()
+
+    # Create a real source venv to symlink to
+    source_venv = tmp_path / "source_venv"
+    source_venv.mkdir()
+    (source_venv / "bin").mkdir()
+    (source_venv / "bin" / "python3").write_text("#!/usr/bin/env python3")
+
+    # Symlink .venv → source_venv (simulates symlink to ~/.claude/skills/.venv)
     venv = skills / ".venv"
-    venv.mkdir()
-    (venv / "bin").mkdir()
-    (venv / "bin" / "python3").write_text("#!/usr/bin/env python3")
+    venv.symlink_to(source_venv)
+
     skill = skills / "my-skill"
     skill.mkdir()
     (skill / "SKILL.md").write_text("# test")
 
     clean_target(tmp_path, dry_run=False)
-    assert venv.exists(), ".venv should survive cleaning"
+    assert venv.is_symlink(), "symlinked .venv should survive cleaning"
     assert not skill.exists(), "skill dirs should be removed"
 
 
+def test_clean_deletes_real_venv(tmp_path: Path):
+    """Clean deletes real (non-symlink) .venv for re-symlinking."""
+    skills = tmp_path / "skills"
+    skills.mkdir()
+    venv = skills / ".venv"
+    venv.mkdir()
+    (venv / "bin").mkdir()
+    (venv / "bin" / "python3").write_text("#!/usr/bin/env python3")
+
+    clean_target(tmp_path, dry_run=False)
+    assert not venv.exists(), "real .venv should be deleted for re-symlinking"
+
+
 def test_clean_dry_run(tmp_path: Path):
     """Dry run counts but doesn't delete."""
     agents = tmp_path / "agents"