claudekit-codex-sync 0.1.0

package/plans/260223-0951-refactor-and-upgrade/phase-05-agent-toml-config.md

@@ -0,0 +1,88 @@
+# Phase 5: Agent TOML Normalization + Multi-Agent Config
+
+Status: pending
+Priority: critical
+Effort: 0.5d
+
+## Goal
+Fix 16 `.claude` references in agent TOMLs. Enable `multi_agent = true`.
+
+## Agent TOML Normalization
+
+Add to `path_normalizer.py`:
+```python
+AGENT_TOML_REPLACEMENTS: List[Tuple[str, str]] = [
+    ("$HOME/.claude/skills/", "${CODEX_HOME:-$HOME/.codex}/skills/"),
+    ("$HOME/.claude/scripts/", "${CODEX_HOME:-$HOME/.codex}/claudekit/scripts/"),
+    ("$HOME/.claude/rules/", "${CODEX_HOME:-$HOME/.codex}/claudekit/rules/"),
+    ("$HOME/.claude/.ck.json", "${CODEX_HOME:-$HOME/.codex}/claudekit/.ck.json"),
+    ("$HOME/.claude/.mcp.json", "${CODEX_HOME:-$HOME/.codex}/claudekit/.mcp.json"),
+    ("$HOME/.claude/", "${CODEX_HOME:-$HOME/.codex}/"),
+    ("~/.claude/", "~/.codex/"),
+]
+
+def normalize_agent_tomls(*, codex_home: Path, dry_run: bool) -> int:
+    agents_dir = codex_home / "agents"
+    if not agents_dir.exists():
+        return 0
+    changed = 0
+    for toml_file in sorted(agents_dir.glob("*.toml")):
+        text = toml_file.read_text(encoding="utf-8")
+        new_text = apply_replacements(text, AGENT_TOML_REPLACEMENTS)
+        if new_text != text:
+            changed += 1
+            if not dry_run:
+                toml_file.write_text(new_text, encoding="utf-8")
+    return changed
+```
+
+## Adapt Claude-Specific Syntax
+
+Strip from developer_instructions:
+```python
+CLAUDE_SYNTAX_ADAPTATIONS = [
+    # Task() tool references → natural language
+    ("Task(Explore)", "the explore agent"),
+    ("Task(researcher)", "the researcher agent"),
+    ("Task(", "delegate to "),
+    # Claude-specific paths
+    ("$HOME/.claude/skills/*", "${CODEX_HOME:-$HOME/.codex}/skills/*"),
+]
+```
+
+## Multi-Agent Config
+
+Add to `config_enforcer.py`:
+```python
+def enforce_multi_agent_flag(config_path: Path, dry_run: bool) -> bool:
+    text = config_path.read_text() if config_path.exists() else ""
+    if "[features]" in text:
+        if "multi_agent" not in text:
+            text = text.replace("[features]", "[features]\nmulti_agent = true")
+    else:
+        text += "\n[features]\nmulti_agent = true\n"
+    if not dry_run:
+        config_path.write_text(text)
+    return True
+```
+
+## Verification
+```bash
+# Before: expect 16 hits
+grep -c '\.claude' ~/.codex/agents/*.toml
+
+# After: expect 0
+grep -c '\.claude' ~/.codex/agents/*.toml
+
+# Multi-agent:
+codex features list | grep multi_agent
+# Expected: multi_agent    experimental    true
+```
+
+## Todo
+- [ ] Add AGENT_TOML_REPLACEMENTS
+- [ ] Add normalize_agent_tomls()
+- [ ] Add Claude syntax adaptations
+- [ ] Add enforce_multi_agent_flag()
+- [ ] Test: 0 .claude refs in TOMLs
+- [ ] Test: multi_agent = true

package/plans/260223-0951-refactor-and-upgrade/phase-06-backup-registry.md

@@ -0,0 +1,58 @@
+# Phase 6: Backup + Registry
+
+Status: pending
+Priority: high
+Effort: 0.5d
+
+## Goal
+Track synced files with SHA-256 checksums. Backup before overwrite.
+
+## Registry Format (`~/.codex/.claudekit-sync-registry.json`)
+```json
+{
+  "version": 1,
+  "lastSync": "2026-02-23T02:26:00Z",
+  "sourceDir": "~/.claude",
+  "entries": {
+    "skills/brainstorm/SKILL.md": {
+      "sourceHash": "abc...",
+      "targetHash": "def...",
+      "syncedAt": "2026-02-23T02:26:00Z"
+    }
+  }
+}
+```
+
+## Add to utils.py
+```python
+import hashlib, json, datetime
+
+def compute_hash(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+def create_backup(path: Path) -> Path:
+    ts = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = path.with_suffix(f".ck-backup-{ts}{path.suffix}")
+    shutil.copy2(path, backup)
+    return backup
+```
+
+## New `sync_registry.py` (~120 lines)
+```python
+def load_registry(codex_home: Path) -> dict: ...
+def save_registry(codex_home: Path, registry: dict): ...
+def check_user_edit(entry: dict, target: Path) -> bool:
+    return compute_hash(target) != entry["targetHash"]
+def update_entry(registry, rel_path, source, target): ...
+```
+
+## Integration
+Before overwriting:
+1. Check registry → if user edited, backup + warn
+2. After writing → update registry with new hashes
+
+## Todo
+- [ ] Add compute_hash, create_backup to utils
+- [ ] Create sync_registry.py
+- [ ] Integrate into asset_sync and path_normalizer
+- [ ] Add --respect-edits flag

package/plans/260223-0951-refactor-and-upgrade/phase-07-tests-docs-push.md

@@ -0,0 +1,54 @@
+# Phase 7: Tests + Docs + Git Push
+
+Status: pending
+Priority: high
+Effort: 0.5d
+
+## Tests
+
+### `tests/test_path_normalizer.py`
+```python
+from claudekit_codex_sync.path_normalizer import apply_replacements, SKILL_MD_REPLACEMENTS
+
+def test_claude_to_codex_path():
+    text = "$HOME/.claude/skills/brainstorm/SKILL.md"
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert ".claude" not in result
+    assert ".codex" in result or "CODEX_HOME" in result
+```
+
+### `tests/test_config_enforcer.py`
+```python
+from claudekit_codex_sync.config_enforcer import enforce_multi_agent_flag
+
+def test_adds_multi_agent(tmp_path):
+    config = tmp_path / "config.toml"
+    config.write_text("[features]\n")
+    enforce_multi_agent_flag(config, dry_run=False)
+    assert "multi_agent = true" in config.read_text()
+```
+
+## Docs
+
+### `docs/codex-vs-claude-agents.md`
+Sub-agent limitations doc:
+- Claude Code: tools/model/memory frontmatter, Task() delegation
+- Codex: developer_instructions text only, auto-spawn via multi_agent
+- What transfers: text instructions, sandbox_mode
+- What's lost: tool restriction, model selection, explicit delegation
+
+## Git Push
+
+```bash
+cd /home/vinhawk/claudekit-codex-sync
+git add -A
+git commit -m "refactor: modularize codebase, npm structure, upgrade for Codex"
+git push
+```
+
+## Todo
+- [ ] Write test_path_normalizer.py
+- [ ] Write test_config_enforcer.py
+- [ ] Write codex-vs-claude-agents.md
+- [ ] Run tests
+- [ ] Git add, commit, push

package/plans/260223-0951-refactor-and-upgrade/plan.md

@@ -0,0 +1,72 @@
+# Plan: Refactor & Upgrade ClaudeKit-Codex-Sync
+
+Status: ready
+Priority: high
+
+## Overview
+
+Refactor monolithic codebase (1151-line Python + 635-line bash) into modular npm-based project, then upgrade with new capabilities for near-100% Codex effectiveness.
+
+## Phases
+
+- [Phase 1: Project Structure](./phase-01-project-structure.md) — npm init, .gitignore, module dirs | **0.5d**
+- [Phase 2: Extract Templates](./phase-02-extract-templates.md) — Move 295 lines of inline strings to files | **0.25d**
+- [Phase 3: Modularize Python](./phase-03-modularize-python.md) — Split into 11 modules <200 lines each | **1d**
+- [Phase 4: Live Source + Detection](./phase-04-live-source-detection.md) — Add ~/.claude/ direct read + auto-detection | **0.5d**
+- [Phase 5: Agent TOML + Config](./phase-05-agent-toml-config.md) — Normalize paths + multi_agent flag | **0.5d**
+- [Phase 6: Backup + Registry](./phase-06-backup-registry.md) — SHA-256 checksum tracking + rollback | **0.5d**
+- [Phase 7: Tests + Docs + Push](./phase-07-tests-docs-push.md) — Tests, docs, git push | **0.5d**
+
+**Total: ~3.75 days**
+
+## Key Decisions
+
+- **npm + git push** (not pip/PyPI)
+- **Python scripts** remain Python, npm wraps them as CLI
+- **Bash scripts** deleted (duplicate Python logic)
+- **Plans/reports** kept as reference
+- **`~/.claude/` live read** as default source (zip fallback)
+- **Sub-agent instructions adapted** for Codex model (strip Claude-specific syntax)
+
+## Architecture
+
+```
+claudekit-codex-sync/
+├── package.json              # npm package
+├── bin/
+│   └── ck-codex-sync.js      # npm CLI entry → calls Python
+├── src/
+│   └── claudekit_codex_sync/
+│       ├── __init__.py
+│       ├── cli.py             # (~100 lines)
+│       ├── source_resolver.py # (~80 lines)
+│       ├── asset_sync.py      # (~160 lines)
+│       ├── path_normalizer.py # (~120 lines)
+│       ├── config_enforcer.py # (~80 lines)
+│       ├── prompt_exporter.py # (~100 lines)
+│       ├── dep_bootstrapper.py# (~60 lines)
+│       ├── runtime_verifier.py# (~30 lines)
+│       ├── bridge_generator.py# (~30 lines)
+│       └── utils.py           # (~90 lines)
+├── templates/
+│   ├── agents-md.md
+│   ├── command-map.md
+│   ├── bridge-skill.md
+│   ├── bridge-resolve-command.py
+│   ├── bridge-docs-init.sh
+│   └── bridge-project-status.sh
+├── tests/
+├── docs/
+├── plans/
+└── reports/
+```
+
+## Success Criteria
+
+- [ ] All Python modules < 200 lines
+- [ ] `npm install -g .` works
+- [ ] `ck-codex-sync --source-mode live` syncs from ~/.claude/
+- [ ] Agent TOMLs: 0 `.claude` references after sync
+- [ ] `codex features list | grep multi_agent` → true after sync
+- [ ] Tests pass
+- [ ] Git clean, ready to push

package/reports/brainstorm-260222-2051-claudekit-codex-community-sync.md

@@ -0,0 +1,113 @@
+# Brainstorm Report: ClaudeKit -> Codex Community Toolkit
+
+## Problem Statement
+You want a community-shareable toolkit that syncs ClaudeKit assets into Codex with minimal manual work, supports latest zip detection, and proves behavior is close to Claude workflows.
+
+## Requirements
+- Full-auto sync entrypoint (latest zip auto-select).
+- Pull from both zip and local `~/.claude` where needed.
+- Keep current exclusions default (`mcp`, `hooks`) but support opt-in.
+- Add agent-role sync compatible with Codex multi-agent system.
+- Publish for community consumption via:
+  - `npm`/`npx` install path.
+  - `git clone` + local run path.
+- Provide evidence that behavior is close to ClaudeKit orchestration (not only file-copy parity).
+
+## Current Reality Check
+- Current script (`~/.codex/scripts/claudekit-sync-all.py`) is strong for assets/skills/rules/prompts sync.
+- It is not yet productized as a public package.
+- It does not yet implement Claude-agent -> Codex-agent role transpilation + parity benchmark harness.
+- Behavior parity is therefore not yet provable by metrics.
+
+## Approaches Evaluated
+
+### Approach A: Keep Python Core + Add NPM Wrapper (Recommended for v1)
+Pros:
+- Fastest to ship.
+- Reuses proven sync logic now.
+- Lower regression risk.
+- Easy to support both `npx` and `python3` direct run.
+
+Cons:
+- Requires Python on user machine.
+- Wrapper layer adds runtime dependency checks.
+
+### Approach B: Full Rewrite to TypeScript Core
+Pros:
+- Native npm experience.
+- Simpler JS ecosystem integration.
+
+Cons:
+- High rewrite cost.
+- High regression risk in edge behavior already solved in Python.
+- Slower time-to-community release.
+
+### Approach C: Maintain Two Cores (Python + TS)
+Pros:
+- Maximum flexibility.
+
+Cons:
+- Highest maintenance burden.
+- Divergence risk.
+- Not YAGNI.
+
+## Recommended Strategy
+- **Ship staged hybrid strategy**:
+1. **v1**: Python core as source of truth + npm wrapper + git-clone workflow.
+2. **v1.1**: Add agent transpiler and parity benchmark harness.
+3. **v2**: Consider TS native core only if adoption justifies rewrite.
+
+This gives speed now and keeps path to long-term polish without over-engineering.
+
+## Claude -> Codex Customization That Matters Most
+- Agent transpiler that converts Claude `agents/*.md` into Codex role config:
+  - `~/.codex/config.toml` `[agents.<role>]`
+  - `~/.codex/agents/<role>.toml`
+- Role strategy:
+  - Prefix custom roles (`ck-*`) to avoid overriding built-ins accidentally.
+  - Allow explicit override mode if user wants `default/worker/explorer` replacement.
+- Instruction normalization:
+  - rewrite Claude-specific paths/tooling references to Codex equivalents.
+  - preserve intent, not literal syntax.
+- Execution guardrails:
+  - per-role `sandbox_mode`, `model_reasoning_effort`, `developer_instructions`.
+
+## Proof Plan: “Near-Similar Behavior”
+Define parity suite and publish numbers:
+- 20-30 canonical scenarios:
+  - planning, research, review, debug, docs update, testing loops.
+- A/B runs:
+  - A: Claude original flow.
+  - B: Codex transpiled flow.
+- Score dimensions:
+  - task success rate.
+  - required artifact completeness.
+  - policy compliance (test/lint/docs gates).
+  - orchestration quality (spawn/wait/close behavior).
+  - defect quality (severity-weighted findings for review/debug cases).
+
+Target thresholds:
+- >=85% parity: acceptable “near-similar”.
+- >=90% parity: strong community-grade claim.
+
+## Risks and Mitigations
+- Risk: Codex/Claude runtime semantics differ.
+  - Mitigation: parity scoring by outcomes, not literal step parity.
+- Risk: multi-agent feature drift across Codex versions.
+  - Mitigation: version compatibility matrix + CI smoke tests.
+- Risk: wrapper install friction.
+  - Mitigation: clear preflight checks + actionable errors.
+
+## Success Metrics
+- Install success rate >=95% on Ubuntu/macOS/WSL for default path.
+- End-to-end sync success rate >=98% on supported fixtures.
+- Parity benchmark >=85% before public “near-similar” claim.
+- Time to run full sync + verify under 3 minutes on standard machine.
+
+## Next Steps
+- Create implementation plan with phases for:
+  - productization,
+  - transpiler,
+  - benchmark harness,
+  - npm + git distribution,
+  - release process.

package/scripts/bootstrap-claudekit-skill-scripts.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+SKILLS_DIR="${CODEX_HOME}/skills"
+VENV_DIR="${SKILLS_DIR}/.venv"
+RUN_PYTHON=true
+RUN_NODE=true
+DRY_RUN=false
+INCLUDE_TEST_DEPS=false
+INCLUDE_MCP=false
+
+usage() {
+  cat <<'EOF'
+Install runtime dependencies for ClaudeKit skills synced into Codex.
+
+Usage:
+  bootstrap-claudekit-skill-scripts.sh [options]
+
+Options:
+  --python-only        Install Python dependencies only
+  --node-only          Install Node.js dependencies only
+  --include-test-deps  Also install requirements from test folders
+  --include-mcp        Also include mcp-builder and mcp-management skills
+  --dry-run            Print actions only
+  -h, --help           Show help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --python-only)
+      RUN_PYTHON=true
+      RUN_NODE=false
+      ;;
+    --node-only)
+      RUN_PYTHON=false
+      RUN_NODE=true
+      ;;
+    --include-test-deps)
+      INCLUDE_TEST_DEPS=true
+      ;;
+    --include-mcp)
+      INCLUDE_MCP=true
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+if [[ ! -d "$SKILLS_DIR" ]]; then
+  echo "Skills directory not found: $SKILLS_DIR" >&2
+  exit 1
+fi
+
+py_ok=0
+py_fail=0
+node_ok=0
+node_fail=0
+
+skip_mcp_path() {
+  local p="$1"
+  if [[ "$INCLUDE_MCP" == true ]]; then
+    return 1
+  fi
+  [[ "$p" == *"/mcp-builder/"* || "$p" == *"/mcp-management/"* ]]
+}
+
+if [[ "$RUN_PYTHON" == true ]]; then
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "python3 not found" >&2
+    exit 1
+  fi
+
+  if [[ "$DRY_RUN" == true ]]; then
+    echo "[dry-run] python3 -m venv \"$VENV_DIR\""
+  else
+    python3 -m venv "$VENV_DIR"
+    "$VENV_DIR/bin/python3" -m pip install --upgrade pip >/dev/null
+  fi
+
+  while IFS= read -r req; do
+    if skip_mcp_path "$req"; then
+      continue
+    fi
+    if [[ "$DRY_RUN" == true ]]; then
+      echo "[dry-run] $VENV_DIR/bin/python3 -m pip install -r \"$req\""
+      py_ok=$((py_ok + 1))
+      continue
+    fi
+    if "$VENV_DIR/bin/python3" -m pip install -r "$req" >/dev/null; then
+      py_ok=$((py_ok + 1))
+    else
+      echo "python deps failed: $req" >&2
+      py_fail=$((py_fail + 1))
+    fi
+  done < <(
+    find "$SKILLS_DIR" \
+      \( -path '*/.system/*' -o -path '*/node_modules/*' -o -path '*/.venv/*' -o -path '*/dist/*' -o -path '*/build/*' \) -prune -o \
+      -type f -name 'requirements*.txt' -print \
+      | if [[ "$INCLUDE_TEST_DEPS" == true ]]; then cat; else grep -Ev '/tests?/'; fi \
+      | sort -u
+  )
+fi
+
+if [[ "$RUN_NODE" == true ]]; then
+  if ! command -v npm >/dev/null 2>&1; then
+    echo "npm not found" >&2
+    exit 1
+  fi
+
+  while IFS= read -r pkg; do
+    if skip_mcp_path "$pkg"; then
+      continue
+    fi
+    dir="$(dirname "$pkg")"
+    if [[ "$DRY_RUN" == true ]]; then
+      echo "[dry-run] npm install --prefix \"$dir\""
+      node_ok=$((node_ok + 1))
+      continue
+    fi
+    if npm install --prefix "$dir" >/dev/null; then
+      node_ok=$((node_ok + 1))
+    else
+      echo "node deps failed: $dir" >&2
+      node_fail=$((node_fail + 1))
+    fi
+  done < <(
+    find "$SKILLS_DIR" \
+      \( -path '*/.system/*' -o -path '*/node_modules/*' -o -path '*/.venv/*' -o -path '*/dist/*' -o -path '*/build/*' \) -prune -o \
+      -type f -name package.json -print \
+      | sort -u
+  )
+fi
+
+echo "python_ok=$py_ok python_fail=$py_fail node_ok=$node_ok node_fail=$node_fail"
+if [[ $py_fail -gt 0 || $node_fail -gt 0 ]]; then
+  exit 2
+fi