claudekit-codex-sync 0.1.0

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "claudekit-codex-sync",
+  "version": "0.1.0",
+  "description": "Sync ClaudeKit skills, agents, and config to Codex CLI",
+  "main": "bin/ck-codex-sync.js",
+  "bin": {
+    "ck-codex-sync": "bin/ck-codex-sync.js"
+  },
+  "scripts": {
+    "sync": "python3 src/claudekit_codex_sync/cli.py",
+    "test": "python3 -m pytest tests/",
+    "lint": "python3 -m py_compile src/claudekit_codex_sync/*.py"
+  },
+  "keywords": ["claudekit", "codex", "sync", "skills"],
+  "license": "MIT"
+}

package/plans/260222-2051-claudekit-codex-community-sync/phase-01-productization.md

@@ -0,0 +1,36 @@
+# Phase 01: Productization Baseline
+
+## Goal
+Turn current private script set into a repository-grade project layout ready for public collaboration.
+
+## Tasks
+1. Define repository structure (`packages`, `scripts`, `docs`, `fixtures`, `tests`).
+2. Add base metadata:
+   - `README.md`
+   - `LICENSE`
+   - `CONTRIBUTING.md`
+   - `SECURITY.md`
+   - `CODE_OF_CONDUCT.md`
+3. Add configuration conventions:
+   - `.editorconfig`
+   - `.gitignore`
+   - formatting/lint standards
+4. Define support matrix doc:
+   - OS support
+   - Codex version compatibility
+   - Python/Node requirements
+
+## Deliverables
+- Public repo skeleton with contribution standards.
+- Clear scope and support boundaries.
+
+## Acceptance Criteria
+- New contributor can clone repo and understand project purpose in <5 minutes.
+- Required project policy files exist and are coherent.
+- Basic local setup instructions are complete and tested once.
+
+## Risks
+- Over-documentation before stable CLI behavior.
+
+## Mitigation
+- Keep docs minimal for v1 and expand only after phase 5.

package/plans/260222-2051-claudekit-codex-community-sync/phase-02-core-refactor.md

@@ -0,0 +1,32 @@
+# Phase 02: Core Refactor
+
+## Goal
+Refactor existing `claudekit-sync-all.py` into maintainable modules while preserving behavior.
+
+## Tasks
+1. Split monolithic script into modules:
+   - zip/source discovery
+   - asset sync
+   - skill sync
+   - normalization/patches
+   - prompt export
+   - verification
+2. Introduce typed config object and explicit defaults.
+3. Add stable machine-readable output mode (`--json`).
+4. Preserve existing flags and backward compatibility behavior.
+5. Add regression tests against current fixture zip.
+
+## Deliverables
+- Modular core package with testable units.
+- No functional regressions versus current script baseline.
+
+## Acceptance Criteria
+- Existing command scenarios produce equivalent outputs (except intentional formatting changes).
+- Unit tests cover critical branches (zip selection, exclusion rules, manifests, idempotency).
+- Re-run idempotency verified on fixture workspace.
+
+## Risks
+- Refactor introduces hidden behavior drift.
+
+## Mitigation
+- Snapshot-based regression assertions before/after refactor.

package/plans/260222-2051-claudekit-codex-community-sync/phase-03-agent-transpiler.md

@@ -0,0 +1,33 @@
+# Phase 03: Agent Transpiler
+
+## Goal
+Convert Claude agent definitions into Codex-compatible role config with predictable behavior.
+
+## Tasks
+1. Parse `~/.claude/agents/*.md` frontmatter + body.
+2. Build normalization pipeline:
+   - path remap (`.claude` -> `.codex` equivalents)
+   - remove/translate Claude-only tool semantics
+   - preserve behavioral intent in `developer_instructions`
+3. Generate Codex role artifacts:
+   - `[agents.<role>]` in config
+   - `~/.codex/agents/<role>.toml`
+4. Support modes:
+   - default prefixed roles (`ck-*`)
+   - optional built-in override mode
+5. Add dry-run diff report for generated roles.
+
+## Deliverables
+- Deterministic agent transpilation command.
+- Compatibility layer from Claude role semantics to Codex role semantics.
+
+## Acceptance Criteria
+- Generated role files pass TOML parse and Codex config validation.
+- Default mode does not override `default/worker/explorer` unexpectedly.
+- At least 10 common Claude agents transpiled without fatal errors.
+
+## Risks
+- Literal translation can create noisy or invalid instructions.
+
+## Mitigation
+- Rule-based sanitizer + max-size bounds + warning report for unsupported directives.

package/plans/260222-2051-claudekit-codex-community-sync/phase-04-parity-harness.md

@@ -0,0 +1,43 @@
+# Phase 04: Parity Benchmark Harness
+
+## Goal
+Provide objective evidence for "near-similar behavior" between Claude flow and Codex transpiled flow.
+
+## Tasks
+1. Define benchmark suite (20-30 scenarios):
+   - planning
+   - code review
+   - bug debug
+   - docs update
+   - research orchestration
+2. Define scoring rubric:
+   - task success
+   - artifact completeness
+   - policy compliance
+   - orchestration quality
+   - severity-weighted output quality
+3. Implement benchmark runner:
+   - fixture setup
+   - command execution
+   - result collection
+   - score aggregation
+4. Add report outputs:
+   - JSON raw results
+   - Markdown summary
+   - trend comparison across versions
+5. Add fail threshold gates for CI (`--min-parity`).
+
+## Deliverables
+- Reproducible parity suite and scorer.
+- Public benchmark report format.
+
+## Acceptance Criteria
+- Single command runs full suite and outputs machine-readable report.
+- Score reproducibility within acceptable variance window.
+- Threshold gate blocks release when parity score is below target.
+
+## Risks
+- Benchmark bias or non-determinism.
+
+## Mitigation
+- Freeze fixtures, pin prompts, repeat-run averaging, and publish methodology.

package/plans/260222-2051-claudekit-codex-community-sync/phase-05-distribution-npm.md

@@ -0,0 +1,35 @@
+# Phase 05: NPM Distribution
+
+## Goal
+Ship a clean npm user experience without rewriting core logic.
+
+## Tasks
+1. Create Node CLI wrapper package:
+   - preflight checks (`python3`, `codex` availability)
+   - argument passthrough
+   - error mapping with actionable remediation
+2. Commands:
+   - `sync`
+   - `transpile-agents`
+   - `benchmark`
+   - `verify`
+3. Add npm metadata:
+   - bin entry
+   - semver strategy
+   - changelog generation
+4. Add smoke tests for `npx` path on Linux/macOS/WSL.
+
+## Deliverables
+- Installable npm package runnable via `npx`.
+- CLI docs with examples.
+
+## Acceptance Criteria
+- `npx <package> sync --help` works on supported environments.
+- Wrapper cleanly forwards exit codes from core engine.
+- Common failure modes have clear remediation text.
+
+## Risks
+- Python missing in user environment.
+
+## Mitigation
+- Preflight + auto-detected install hints per OS.

package/plans/260222-2051-claudekit-codex-community-sync/phase-06-git-clone-docs.md

@@ -0,0 +1,28 @@
+# Phase 06: Git-Clone Workflow and Docs
+
+## Goal
+Ensure users who prefer direct clone can run the toolkit with zero ambiguity.
+
+## Tasks
+1. Add `scripts/install.sh` and `scripts/install.ps1` for bootstrap.
+2. Add one-command usage examples for:
+   - latest zip auto-sync
+   - explicit zip path
+   - global vs workspace scope
+   - dry-run and rollback flow
+3. Add migration guide from private script path to community repo CLI.
+4. Add troubleshooting section for common environment issues.
+
+## Deliverables
+- Git-clone installation path fully documented.
+- Copy/paste-ready command docs for common workflows.
+
+## Acceptance Criteria
+- Fresh machine can clone and run sync in <=10 minutes using docs only.
+- Troubleshooting covers top 10 expected errors.
+
+## Risks
+- Docs drift from implementation.
+
+## Mitigation
+- Add docs validation checklist in release process.

package/plans/260222-2051-claudekit-codex-community-sync/phase-07-qa-release.md

@@ -0,0 +1,35 @@
+# Phase 07: QA, CI, and Release
+
+## Goal
+Ship safely with repeatable quality gates and predictable releases.
+
+## Tasks
+1. CI matrix:
+   - Ubuntu
+   - macOS
+   - WSL smoke runner (if available)
+2. Test pipeline:
+   - unit
+   - integration
+   - parity benchmark threshold gate
+3. Release pipeline:
+   - semantic versioning
+   - changelog generation
+   - npm publish
+   - git tag/release notes
+4. Add compatibility matrix and deprecation policy.
+
+## Deliverables
+- Automated CI + release workflow.
+- Stable release quality bars documented and enforced.
+
+## Acceptance Criteria
+- Release candidate fails if parity below threshold.
+- Tagged release publishes npm package and changelog.
+- Rollback procedure validated once.
+
+## Risks
+- Flaky parity tests block releases.
+
+## Mitigation
+- Separate flaky detector and quarantine process; keep stable core gate strict.

package/plans/260222-2051-claudekit-codex-community-sync/plan.md

@@ -0,0 +1,99 @@
+---
+title: "ClaudeKit Codex Community Toolkit"
+description: "Productize sync scripts for npm + git clone and add parity proof between Claude and Codex workflows"
+status: pending
+priority: P1
+effort: 5d
+branch: local/home-vinhawk
+tags: [feature, tooling, codex, claudekit, community]
+created: 2026-02-22
+---
+
+# ClaudeKit Codex Community Toolkit
+
+## Summary
+Build a community-ready toolkit that syncs ClaudeKit -> Codex with full automation, supports npm and git-clone distribution, and includes measurable parity testing to support "near-similar behavior" claims.
+
+## Scope
+### In scope
+- Productize current sync engine into reusable CLI package.
+- Add Claude-agent -> Codex-agent role transpiler.
+- Add parity benchmark harness with reproducible scoring.
+- Publish via npm (`npx`) and git clone workflow.
+- Add docs, CI, release process, compatibility matrix.
+
+### Out of scope (v1)
+- Full TypeScript rewrite of existing Python core.
+- MCP/hooks parity as default behavior.
+- Proprietary cloud telemetry or hosted backend.
+
+## Key Decisions
+1. Keep Python core for v1 to reduce regression risk.
+2. Add Node wrapper for npm UX (`npx`).
+3. Use prefixed roles (`ck-*`) by default to avoid accidental built-in override.
+4. Prove parity with benchmark metrics, not subjective statements.
+5. Ship staged releases (`v1` -> `v1.1`) instead of big-bang rewrite.
+
+## Phases
+| Phase | File | Goal | Effort |
+|---|---|---|---|
+| Phase 1 | [phase-01-productization.md](./phase-01-productization.md) | Repo/product baseline and public packaging structure | 0.5d |
+| Phase 2 | [phase-02-core-refactor.md](./phase-02-core-refactor.md) | Refactor current script into maintainable core modules | 1d |
+| Phase 3 | [phase-03-agent-transpiler.md](./phase-03-agent-transpiler.md) | Claude agent definitions -> Codex roles transpilation | 1d |
+| Phase 4 | [phase-04-parity-harness.md](./phase-04-parity-harness.md) | Deterministic benchmark + scoring and reports | 1d |
+| Phase 5 | [phase-05-distribution-npm.md](./phase-05-distribution-npm.md) | npm wrapper, npx flow, preflight checks | 0.75d |
+| Phase 6 | [phase-06-git-clone-docs.md](./phase-06-git-clone-docs.md) | Git-clone install flow, docs, examples | 0.5d |
+| Phase 7 | [phase-07-qa-release.md](./phase-07-qa-release.md) | CI matrix, release automation, quality gates | 0.25d |
+
+## Architecture Overview
+```
+┌───────────────────────────────────────────────────────────────────┐
+│ community repo (public)                                           │
+│  ├─ packages/cli-node (npm wrapper, preflight, UX)               │
+│  ├─ packages/core-python (sync engine + transpiler + benchmark)  │
+│  ├─ fixtures/ (zip + ~/.claude snapshots for tests)              │
+│  ├─ docs/ (install, config, parity methodology)                  │
+│  └─ .github/workflows/ (CI matrix + release)                     │
+└───────────────────────────────────────────────────────────────────┘
+                       │
+                       ▼
+             user machine (Ubuntu/macOS/WSL)
+                       │
+         ┌─────────────┴─────────────┐
+         │                           │
+         ▼                           ▼
+   npx claudekit-codex-sync      git clone + ./scripts/install.sh
+```
+
+## Success Criteria
+1. Install and run success >=95% on Ubuntu/macOS/WSL.
+2. Sync + verify pass >=98% on supported fixtures.
+3. Parity benchmark >=85% before public parity claim.
+4. Re-run idempotency: second run produces no destructive drift.
+5. Clear rollback path documented and tested.
+
+## Risks & Mitigations
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Runtime semantics differ Claude vs Codex | False parity claims | Use outcome-based scoring + publish raw reports |
+| npm wrapper fails due missing Python | Install friction | Preflight checks + one-line remediation |
+| Agent transpiler overfits one kit version | Fragile updates | Schema validation + fixture regression tests |
+| Codex feature drift (`multi_agent`) | Break role flows | Version matrix + compatibility checks |
+
+## Deliverables
+- Public-ready repository structure.
+- CLI commands for sync, transpile, benchmark, verify.
+- Published npm package + tagged git release.
+- Benchmark report template and reproducible results.
+- Operational docs for users and contributors.
+
+## Implementation Notes
+- Keep MCP/hooks opt-in flags intact.
+- Preserve latest-zip selection behavior as default.
+- Ensure `--dry-run` and `--json` output for automation consumers.
+- Add "strict mode" for CI (non-zero exit on parity threshold miss).
+
+## Open Questions
+1. Final npm package name preference (`claudekit-codex-sync` vs alternatives)?
+2. License choice for community repo (MIT/Apache-2.0)?
+3. Initial support policy: LTS + latest Codex only, or broad version range?

package/plans/260223-0951-refactor-and-upgrade/phase-01-project-structure.md

@@ -0,0 +1,79 @@
+# Phase 1: Project Structure
+
+Status: pending
+Priority: critical
+Effort: 0.5d
+
+## Goal
+Initialize npm project structure, .gitignore, and module directories.
+
+## Steps
+
+### 1.1 Initialize npm
+```bash
+cd /home/vinhawk/claudekit-codex-sync
+npm init -y
+```
+
+Edit `package.json`:
+```json
+{
+  "name": "claudekit-codex-sync",
+  "version": "0.1.0",
+  "description": "Sync ClaudeKit skills, agents, and config to Codex CLI",
+  "main": "bin/ck-codex-sync.js",
+  "bin": { "ck-codex-sync": "bin/ck-codex-sync.js" },
+  "scripts": {
+    "sync": "python3 src/claudekit_codex_sync/cli.py",
+    "test": "python3 -m pytest tests/",
+    "lint": "python3 -m py_compile src/claudekit_codex_sync/*.py"
+  },
+  "keywords": ["claudekit", "codex", "sync", "skills"],
+  "license": "MIT"
+}
+```
+
+### 1.2 Create bin/ck-codex-sync.js
+```javascript
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+const path = require('path');
+const script = path.join(__dirname, '..', 'src', 'claudekit_codex_sync', 'cli.py');
+try {
+  execSync(`python3 "${script}" ${process.argv.slice(2).join(' ')}`, { stdio: 'inherit' });
+} catch (e) {
+  process.exit(e.status || 1);
+}
+```
+
+### 1.3 Create .gitignore
+```
+node_modules/
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+```
+
+### 1.4 Create directories
+```bash
+mkdir -p src/claudekit_codex_sync templates tests docs
+touch src/claudekit_codex_sync/__init__.py
+```
+
+### 1.5 Delete redundant bash scripts
+```bash
+git rm scripts/normalize-claudekit-for-codex.sh
+git rm scripts/export-claudekit-prompts.sh
+git rm scripts/bootstrap-claudekit-skill-scripts.sh
+```
+
+## Todo
+- [ ] npm init + package.json
+- [ ] bin/ck-codex-sync.js
+- [ ] .gitignore
+- [ ] Create src/ templates/ tests/ docs/ dirs
+- [ ] Delete redundant bash scripts

package/plans/260223-0951-refactor-and-upgrade/phase-02-extract-templates.md

@@ -0,0 +1,36 @@
+# Phase 2: Extract Templates
+
+Status: pending
+Priority: high
+Effort: 0.25d
+
+## Goal
+Move 295 lines of inline template strings from `claudekit-sync-all.py` to separate files in `templates/`.
+
+## Mapping
+
+| Constant (in Python) | Target File | Lines |
+|---|---|---|
+| `AGENTS_TEMPLATE` (L57-102) | `templates/agents-md.md` | 45 |
+| `COMMAND_MAP_TEMPLATE` (L105-149) | `templates/command-map.md` | 44 |
+| `BRIDGE_SKILL_TEMPLATE` (L152-215) | `templates/bridge-skill.md` | 63 |
+| `BRIDGE_RESOLVE_SCRIPT` (L218-270) | `templates/bridge-resolve-command.py` | 52 |
+| `BRIDGE_DOCS_INIT_SCRIPT` (L273-298) | `templates/bridge-docs-init.sh` | 25 |
+| `BRIDGE_STATUS_SCRIPT` (L301-350) | `templates/bridge-project-status.sh` | 49 |
+
+## Loading Pattern
+
+In Python modules, use:
+```python
+from pathlib import Path
+
+TEMPLATES_DIR = Path(__file__).parent.parent.parent / "templates"
+
+def load_template(name: str) -> str:
+    return (TEMPLATES_DIR / name).read_text(encoding="utf-8")
+```
+
+## Todo
+- [ ] Create 6 template files from inline strings
+- [ ] Remove inline strings from Python
+- [ ] Add `load_template()` utility

package/plans/260223-0951-refactor-and-upgrade/phase-03-modularize-python.md

@@ -0,0 +1,107 @@
+# Phase 3: Modularize Python
+
+Status: pending
+Priority: critical
+Effort: 1d
+
+## Goal
+Split 1151-line `claudekit-sync-all.py` into 11 modules, each <200 lines.
+
+## Module Split
+
+### `src/claudekit_codex_sync/utils.py` (~90 lines)
+From lines: 394-502
+```python
+# Functions: SyncError, eprint, run_cmd, ensure_parent,
+# write_bytes_if_changed, write_text_if_changed, zip_mode,
+# find_latest_zip (→ moved to source_resolver), load_manifest,
+# save_manifest, apply_replacements, is_excluded_path
+```
+
+### `src/claudekit_codex_sync/source_resolver.py` (~80 lines)
+From lines: 453-591
+```python
+# Functions: find_latest_zip, collect_skill_entries
+# NEW: detect_claude_source, validate_claude_source
+```
+
+### `src/claudekit_codex_sync/asset_sync.py` (~160 lines)
+From lines: 505-656
+```python
+# Functions: sync_assets, sync_skills
+# NEW: sync_assets_from_dir, sync_skills_from_dir
+```
+
+### `src/claudekit_codex_sync/path_normalizer.py` (~120 lines)
+From lines: 353-391, 493-497, 659-772
+```python
+# Constants: SKILL_MD_REPLACEMENTS, PROMPT_REPLACEMENTS
+# NEW: AGENT_TOML_REPLACEMENTS
+# Functions: apply_replacements, normalize_files, patch_copywriting_script
+# NEW: normalize_agent_tomls
+```
+
+### `src/claudekit_codex_sync/config_enforcer.py` (~80 lines)
+From lines: 795-846
+```python
+# Functions: ensure_agents, enforce_config
+# NEW: enforce_multi_agent_flag
+```
+
+### `src/claudekit_codex_sync/prompt_exporter.py` (~100 lines)
+From lines: 849-937
+```python
+# Functions: ensure_frontmatter, export_prompts
+```
+
+### `src/claudekit_codex_sync/dep_bootstrapper.py` (~60 lines)
+From lines: 940-998
+```python
+# Functions: bootstrap_deps
+```
+
+### `src/claudekit_codex_sync/runtime_verifier.py` (~30 lines)
+From lines: 1001-1021
+```python
+# Functions: verify_runtime
+```
+
+### `src/claudekit_codex_sync/bridge_generator.py` (~30 lines)
+From lines: 775-792
+```python
+# Functions: ensure_bridge_skill (reads templates from files)
+```
+
+### `src/claudekit_codex_sync/cli.py` (~100 lines)
+From lines: 1028-1151
+```python
+# Functions: parse_args, main, print_summary
+# Imports all modules, orchestrates the sync
+```
+
+## Import Structure
+```
+cli.py
+├── source_resolver.py
+├── asset_sync.py ── utils.py
+├── path_normalizer.py ── utils.py
+├── config_enforcer.py ── utils.py
+├── prompt_exporter.py ── utils.py, path_normalizer.py
+├── dep_bootstrapper.py ── utils.py
+├── runtime_verifier.py ── utils.py
+└── bridge_generator.py ── utils.py
+```
+
+## Todo
+- [ ] Create utils.py
+- [ ] Create source_resolver.py
+- [ ] Create asset_sync.py
+- [ ] Create path_normalizer.py
+- [ ] Create config_enforcer.py
+- [ ] Create prompt_exporter.py
+- [ ] Create dep_bootstrapper.py
+- [ ] Create runtime_verifier.py
+- [ ] Create bridge_generator.py
+- [ ] Create cli.py (orchestrator)
+- [ ] Delete old scripts/claudekit-sync-all.py
+- [ ] Verify: each module <200 lines

package/plans/260223-0951-refactor-and-upgrade/phase-04-live-source-detection.md

@@ -0,0 +1,76 @@
+# Phase 4: Live Source + Claude Dir Detection
+
+Status: pending
+Priority: critical
+Effort: 0.5d
+
+## Goal
+Add `--source-mode live` to read directly from `~/.claude/` instead of zip. Auto-detect Claude installation.
+
+## Changes to `source_resolver.py`
+
+```python
+def detect_claude_source() -> Path:
+    """Auto-detect Claude Code installation."""
+    candidates = [
+        Path.home() / ".claude",
+        Path(os.environ.get("USERPROFILE", "")) / ".claude",
+    ]
+    for p in candidates:
+        if p.exists() and (p / "skills").is_dir():
+            return p
+    raise SyncError("Claude Code not found. Use --source-dir to specify.")
+
+def validate_source(source: Path) -> dict:
+    return {
+        "skills": (source / "skills").is_dir(),
+        "agents": (source / "agents").is_dir(),
+        "commands": (source / "commands").is_dir(),
+        "rules": (source / "rules").is_dir(),
+        "claude_md": (source / "CLAUDE.md").is_file(),
+    }
+```
+
+## Changes to `cli.py`
+
+Add args:
+```python
+p.add_argument("--source-mode", choices=["auto", "live", "zip"], default="auto")
+p.add_argument("--source-dir", type=Path, default=None)
+```
+
+Route in main:
+```python
+if source_mode == "live" or (source_mode == "auto" and source_dir):
+    source = source_dir or detect_claude_source()
+    sync_assets_from_dir(source, ...)
+    sync_skills_from_dir(source, ...)
+else:
+    zip_path = find_latest_zip(args.zip_path)
+    with zipfile.ZipFile(zip_path) as zf:
+        sync_assets(zf, ...)
+        sync_skills(zf, ...)
+```
+
+## Changes to `asset_sync.py`
+
+```python
+def sync_skills_from_dir(source: Path, *, codex_home: Path, ...) -> Dict[str, int]:
+    skills_src = source / "skills"
+    skills_dst = codex_home / "skills"
+    for skill_dir in sorted(skills_src.iterdir()):
+        if not skill_dir.is_dir() or skill_dir.name.startswith("."):
+            continue
+        # apply same exclusion logic as sync_skills
+        dst = skills_dst / skill_dir.name
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.copytree(skill_dir, dst)
+```
+
+## Todo
+- [ ] Add detect_claude_source() + validate
+- [ ] Add --source-mode, --source-dir args
+- [ ] Add sync_assets_from_dir()
+- [ ] Add sync_skills_from_dir()
+- [ ] Route in main()