claudekit-codex-sync 0.1.0 → 0.2.1

package/src/claudekit_codex_sync/cli.py

@@ -8,12 +8,18 @@ import json
 import os
 import zipfile
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 from .asset_sync_dir import sync_assets_from_dir, sync_skills_from_dir
 from .asset_sync_zip import sync_assets, sync_skills
 from .bridge_generator import ensure_bridge_skill
-from .config_enforcer import ensure_agents, enforce_config, enforce_multi_agent_flag
+from .clean_target import clean_target
+from .config_enforcer import (
+    enforce_config,
+    enforce_multi_agent_flag,
+    ensure_agents,
+    register_agents,
+)
 from .dep_bootstrapper import bootstrap_deps
 from .path_normalizer import normalize_agent_tomls, normalize_files
 from .prompt_exporter import export_prompts
@@ -26,41 +32,85 @@ from .utils import SyncError, eprint
 def print_summary(summary: Dict[str, Any]) -> None:
     print(json.dumps(summary, indent=2, ensure_ascii=False))
 
+
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(
-        description="All-in-one ClaudeKit -> Codex sync script."
+        prog="ckc-sync",
+        description="Sync ClaudeKit skills, agents, and config to Codex CLI.",
+    )
+    p.add_argument(
+        "-g",
+        "--global",
+        dest="global_scope",
+        action="store_true",
+        help="Sync to ~/.codex/ (default: ./.codex/)",
+    )
+    p.add_argument(
+        "-f",
+        "--fresh",
+        action="store_true",
+        help="Clean target dirs before sync",
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite user-edited files without backup (required for zip write mode)",
+    )
+    p.add_argument(
+        "--zip",
+        dest="zip_path",
+        type=Path,
+        help="Sync from zip instead of live ~/.claude/",
+    )
+    p.add_argument(
+        "--source",
+        type=Path,
+        default=None,
+        help="Custom source dir (default: ~/.claude/)",
+    )
+    p.add_argument(
+        "--mcp",
+        action="store_true",
+        help="Include MCP skills",
+    )
+    p.add_argument(
+        "--no-deps",
+        action="store_true",
+        help="Skip dependency bootstrap (venv)",
+    )
+    p.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="Preview only",
     )
-    p.add_argument("--zip", dest="zip_path", type=Path, help="Specific ClaudeKit zip path")
-    p.add_argument("--codex-home", type=Path, default=None, help="Codex home (default: $CODEX_HOME or ~/.codex)")
-    p.add_argument("--workspace", type=Path, default=Path.cwd(), help="Workspace root for AGENTS.md")
-    p.add_argument("--source-mode", choices=["auto", "live", "zip"], default="auto", help="Source mode")
-    p.add_argument("--source-dir", type=Path, default=None, help="Source directory for live mode")
-    p.add_argument("--include-mcp", action="store_true", help="Include MCP skills/prompts")
-    p.add_argument("--include-hooks", action="store_true", help="Include hooks")
-    p.add_argument("--include-conflicts", action="store_true", help="Include conflicting skills")
-    p.add_argument("--include-test-deps", action="store_true", help="Install test requirements")
-    p.add_argument("--skip-bootstrap", action="store_true", help="Skip dependency bootstrap")
-    p.add_argument("--skip-verify", action="store_true", help="Skip verification")
-    p.add_argument("--skip-agent-toml", action="store_true", help="Skip agent TOML normalization")
-    p.add_argument("--respect-edits", action="store_true", help="Backup user-edited files")
-    p.add_argument("--dry-run", action="store_true", help="Preview changes only")
     return p.parse_args()
 
 
 def main() -> int:
     args = parse_args()
-    codex_home = (args.codex_home or Path(os.environ.get("CODEX_HOME", "~/.codex"))).expanduser().resolve()
-    workspace = args.workspace.expanduser().resolve()
-    workspace.mkdir(parents=True, exist_ok=True)
 
-    # Load registry for backup/respect-edits
+    if args.global_scope:
+        codex_home = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser().resolve()
+    else:
+        codex_home = (Path.cwd() / ".codex").resolve()
+
+    workspace = Path.cwd().resolve()
+    if not args.dry_run:
+        codex_home.mkdir(parents=True, exist_ok=True)
+
+    if args.fresh:
+        removed = clean_target(codex_home, dry_run=args.dry_run)
+        print(f"fresh: removed {removed} files")
+
     registry = load_registry(codex_home)
 
-    source_mode = args.source_mode
-    use_live = source_mode == "live" or (source_mode == "auto" and args.source_dir)
+    use_live = args.zip_path is None
+    if not use_live and not args.force and not args.dry_run:
+        raise SyncError("zip sync requires --force for write mode")
 
     if use_live:
-        source = args.source_dir or detect_claude_source()
+        source = args.source or detect_claude_source()
         validation = validate_source(source)
         print(f"source: {source} (live)")
         print(f"validation: {validation}")
@@ -71,101 +121,85 @@ def main() -> int:
         registry["sourceDir"] = None
 
     print(f"codex_home: {codex_home}")
-    print(f"workspace: {workspace}")
-    print(
-        f"include_mcp={args.include_mcp} include_hooks={args.include_hooks} "
-        f"dry_run={args.dry_run} respect_edits={args.respect_edits}"
-    )
-
-    codex_home.mkdir(parents=True, exist_ok=True)
+    print(f"scope: {'global' if args.global_scope else 'project'}")
+    print(f"fresh={args.fresh} force={args.force} mcp={args.mcp} dry_run={args.dry_run}")
 
     if use_live:
         assets_stats = sync_assets_from_dir(
-            source, codex_home=codex_home, include_hooks=args.include_hooks, dry_run=args.dry_run
+            source,
+            codex_home=codex_home,
+            include_hooks=True,
+            dry_run=args.dry_run,
+            registry=registry,
+            force=args.force,
         )
         skills_stats = sync_skills_from_dir(
             source,
             codex_home=codex_home,
-            include_mcp=args.include_mcp,
-            include_conflicts=args.include_conflicts,
+            include_mcp=args.mcp,
+            include_conflicts=False,
             dry_run=args.dry_run,
         )
     else:
-        with zipfile.ZipFile(zip_path) as zf:  # type: ignore
+        with zipfile.ZipFile(zip_path) as zf:
             assets_stats = sync_assets(
-                zf, codex_home=codex_home, include_hooks=args.include_hooks, dry_run=args.dry_run
+                zf,
+                codex_home=codex_home,
+                include_hooks=True,
+                dry_run=args.dry_run,
             )
             skills_stats = sync_skills(
                 zf,
                 codex_home=codex_home,
-                include_mcp=args.include_mcp,
-                include_conflicts=args.include_conflicts,
+                include_mcp=args.mcp,
+                include_conflicts=False,
                 dry_run=args.dry_run,
             )
 
-    print(
-        f"assets: added={assets_stats['added']} updated={assets_stats['updated']} "
-        f"removed={assets_stats['removed']}"
-    )
-    print(
-        f"skills: added={skills_stats['added']} updated={skills_stats['updated']} "
-        f"skipped={skills_stats['skipped']}"
-    )
+    print(f"assets: added={assets_stats['added']} updated={assets_stats['updated']}")
+    print(f"skills: added={skills_stats['added']} updated={skills_stats['updated']}")
 
-    changed = normalize_files(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run)
+    changed = normalize_files(codex_home=codex_home, include_mcp=args.mcp, dry_run=args.dry_run)
     print(f"normalize_changed={changed}")
 
-    # Agent TOML normalization
-    agent_toml_changed = 0
-    if not args.skip_agent_toml:
-        agent_toml_changed = normalize_agent_tomls(codex_home=codex_home, dry_run=args.dry_run)
-        print(f"agent_toml_changed={agent_toml_changed}")
+    agent_toml_changed = normalize_agent_tomls(codex_home=codex_home, dry_run=args.dry_run)
+    print(f"agent_toml_changed={agent_toml_changed}")
+
+    agents_registered = register_agents(codex_home=codex_home, dry_run=args.dry_run)
+    print(f"agents_registered={agents_registered}")
 
     baseline_changed = 0
     if ensure_agents(workspace=workspace, dry_run=args.dry_run):
         baseline_changed += 1
-        print(f"upsert: {workspace / 'AGENTS.md'}")
-    if enforce_config(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run):
+    if enforce_config(codex_home=codex_home, include_mcp=args.mcp, dry_run=args.dry_run):
         baseline_changed += 1
-        print(f"upsert: {codex_home / 'config.toml'}")
     if ensure_bridge_skill(codex_home=codex_home, dry_run=args.dry_run):
         baseline_changed += 1
-        print(f"upsert: {codex_home / 'skills' / 'claudekit-command-bridge'}")
 
-    # Enable multi_agent flag
     config_path = codex_home / "config.toml"
-    if enforce_multi_agent_flag(config_path, dry_run=args.dry_run):
-        print(f"upsert: multi_agent = true in {config_path}")
-
+    enforce_multi_agent_flag(config_path, dry_run=args.dry_run)
     print(f"baseline_changed={baseline_changed}")
 
-    prompt_stats = export_prompts(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run)
-    print(
-        f"prompts: added={prompt_stats['added']} updated={prompt_stats['updated']} "
-        f"total_generated={prompt_stats['total_generated']}"
-    )
+    prompt_stats = export_prompts(codex_home=codex_home, include_mcp=args.mcp, dry_run=args.dry_run)
+    print(f"prompts: added={prompt_stats['added']} total={prompt_stats['total_generated']}")
 
     bootstrap_stats = None
-    if not args.skip_bootstrap:
+    if not args.no_deps:
         bootstrap_stats = bootstrap_deps(
             codex_home=codex_home,
-            include_mcp=args.include_mcp,
-            include_test_deps=args.include_test_deps,
+            include_mcp=args.mcp,
             dry_run=args.dry_run,
         )
         print(
-            f"bootstrap: python_ok={bootstrap_stats['python_ok']} "
-            f"python_fail={bootstrap_stats['python_fail']}"
+            f"bootstrap: py_ok={bootstrap_stats['python_ok']} "
+            f"py_fail={bootstrap_stats['python_fail']}"
         )
         if (bootstrap_stats["python_fail"] or bootstrap_stats["node_fail"]) and not args.dry_run:
             raise SyncError("Dependency bootstrap reported failures")
 
-    verify_stats = None
-    if not args.skip_verify:
-        verify_stats = verify_runtime(codex_home=codex_home, dry_run=args.dry_run)
-        print(f"verify: {verify_stats}")
+    verify_stats = verify_runtime(codex_home=codex_home, dry_run=args.dry_run)
+    print(f"verify: {verify_stats}")
 
-    # Save registry
     if not args.dry_run:
         save_registry(codex_home, registry)
 
@@ -173,21 +207,19 @@ def main() -> int:
         "source": str(source) if use_live else str(zip_path),
         "source_mode": "live" if use_live else "zip",
         "codex_home": str(codex_home),
-        "workspace": str(workspace),
-        "dry_run": args.dry_run,
-        "include_mcp": args.include_mcp,
-        "include_hooks": args.include_hooks,
+        "scope": "global" if args.global_scope else "project",
+        "fresh": args.fresh,
         "assets": assets_stats,
         "skills": skills_stats,
         "normalize_changed": changed,
         "agent_toml_changed": agent_toml_changed,
-        "baseline_changed": baseline_changed,
+        "agents_registered": agents_registered,
         "prompts": prompt_stats,
         "bootstrap": bootstrap_stats,
         "verify": verify_stats,
     }
     print_summary(summary)
-    print("done: claudekit all-in-one sync completed")
+    print("done: ckc-sync completed")
     return 0
 
 

package/src/claudekit_codex_sync/constants.py

@@ -2,19 +2,8 @@
 
 from typing import List, Set, Tuple
 
-ASSET_DIRS = {"agents", "commands", "output-styles", "rules", "scripts"}
-ASSET_FILES = {
-    "CLAUDE.md",
-    ".ck.json",
-    ".ckignore",
-    ".env.example",
-    ".mcp.json.example",
-    "settings.json",
-    "metadata.json",
-    "statusline.cjs",
-    "statusline.sh",
-    "statusline.ps1",
-}
+ASSET_DIRS = {"commands", "output-styles", "scripts"}
+ASSET_FILES = {".env.example"}
 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

@@ -10,60 +10,106 @@ from typing import Dict
 from .utils import eprint, is_excluded_path, run_cmd
 
 
+def _try_symlink_venv(codex_home: Path, *, dry_run: bool) -> bool:
+    """Try to symlink from existing ClaudeKit venv. Returns True if successful."""
+    source_venv = Path.home() / ".claude" / "skills" / ".venv"
+    target_venv = codex_home / "skills" / ".venv"
+
+    if target_venv.is_symlink() and not target_venv.resolve().exists():
+        if not dry_run:
+            target_venv.unlink()
+
+    if target_venv.is_symlink() and target_venv.resolve().exists():
+        print("skip: skills/.venv (symlink intact)")
+        return True
+    if target_venv.exists() and not target_venv.is_symlink():
+        print("skip: skills/.venv (exists)")
+        return True
+
+    if source_venv.exists():
+        if not dry_run:
+            target_venv.parent.mkdir(parents=True, exist_ok=True)
+            if target_venv.is_symlink():
+                target_venv.unlink()
+            target_venv.symlink_to(source_venv)
+        print(f"symlink: skills/.venv -> {source_venv}")
+        return True
+
+    return False
+
+
+def _install_node_deps(*, skills_dir: Path, include_mcp: bool, dry_run: bool) -> tuple[int, int]:
+    """Install Node dependencies for skills."""
+    node_ok = node_fail = 0
+    npm = shutil.which("npm")
+    if not npm:
+        eprint("npm not found; skipping Node dependency bootstrap")
+        return node_ok, node_fail
+
+    pkg_files = sorted(skills_dir.rglob("package.json"))
+    for pkg in pkg_files:
+        if is_excluded_path(pkg.parts):
+            continue
+        if not include_mcp and ("mcp-builder" in pkg.parts or "mcp-management" in pkg.parts):
+            continue
+        try:
+            run_cmd([npm, "install", "--prefix", str(pkg.parent)], dry_run=dry_run)
+            node_ok += 1
+        except subprocess.CalledProcessError:
+            node_fail += 1
+            eprint(f"node deps failed: {pkg.parent}")
+    return node_ok, node_fail
+
+
 def bootstrap_deps(
     *,
     codex_home: Path,
     include_mcp: bool,
-    include_test_deps: bool,
     dry_run: bool,
 ) -> Dict[str, int]:
     """Bootstrap Python and Node dependencies for skills."""
     skills_dir = codex_home / "skills"
-    venv_dir = skills_dir / ".venv"
-
-    if not shutil.which("python3"):
-        from .utils import SyncError
-        raise SyncError("python3 not found")
-
     py_ok = py_fail = node_ok = node_fail = 0
 
-    run_cmd(["python3", "-m", "venv", str(venv_dir)], dry_run=dry_run)
+    symlinked = _try_symlink_venv(codex_home, dry_run=dry_run)
+    venv_dir = skills_dir / ".venv"
     py_bin = venv_dir / "bin" / "python3"
-    run_cmd([str(py_bin), "-m", "pip", "install", "--upgrade", "pip"], dry_run=dry_run)
+    if symlinked and not dry_run and not py_bin.exists():
+        eprint("warn: skills/.venv missing bin/python3, recreating local venv")
+        if venv_dir.is_symlink():
+            venv_dir.unlink()
+        symlinked = False
 
-    req_files = sorted(skills_dir.rglob("requirements*.txt"))
-    for req in req_files:
-        rel = req.relative_to(skills_dir).as_posix()
-        if is_excluded_path(req.parts):
-            continue
-        if not include_test_deps and "/test" in rel:
-            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}")
+    if not symlinked:
+        if not shutil.which("python3"):
+            from .utils import SyncError
 
-    npm = shutil.which("npm")
-    if npm:
-        pkg_files = sorted(skills_dir.rglob("package.json"))
-        for pkg in pkg_files:
-            rel = pkg.relative_to(skills_dir).as_posix()
-            if is_excluded_path(pkg.parts):
+            raise SyncError("python3 not found")
+        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)
+
+    # 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 pkg.parts or "mcp-management" in pkg.parts):
+            if not include_mcp and ("mcp-builder" in req.parts or "mcp-management" in req.parts):
                 continue
             try:
-                run_cmd([npm, "install", "--prefix", str(pkg.parent)], dry_run=dry_run)
-                node_ok += 1
+                run_cmd([str(py_bin), "-m", "pip", "install", "-r", str(req)], dry_run=dry_run)
+                py_ok += 1
             except subprocess.CalledProcessError:
-                node_fail += 1
-                eprint(f"node deps failed: {pkg.parent}")
+                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:
-        eprint("npm not found; skipping Node dependency bootstrap")
+        print("skip: deps install (venv symlinked, packages shared)")
 
     return {
         "python_ok": py_ok,

package/src/claudekit_codex_sync/path_normalizer.py

@@ -83,6 +83,8 @@ def convert_agents_md_to_toml(*, codex_home: Path, dry_run: bool) -> int:
     agents_dir = codex_home / "agents"
     if not agents_dir.exists():
         return 0
+    if not dry_run:
+        agents_dir.mkdir(parents=True, exist_ok=True)
 
     converted = 0
     for md_file in sorted(agents_dir.glob("*.md")):

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/src/claudekit_codex_sync/source_resolver.py

@@ -41,7 +41,7 @@ def detect_claude_source() -> Path:
     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.")
+    raise SyncError("Claude Code not found. Use --source to specify.")
 
 
 def validate_source(source: Path) -> Dict[str, bool]:
@@ -61,11 +61,19 @@ def collect_skill_entries(zf: zipfile.ZipFile) -> Dict[str, List[Tuple[str, str]
     for name in zf.namelist():
         if name.endswith("/") or not name.startswith(".claude/skills/"):
             continue
-        rel = name[len(".claude/skills/") :]
+        rel = name[len(".claude/skills/") :].replace("\\", "/")
+        path = Path(rel)
+        if path.is_absolute() or ".." in path.parts:
+            raise SyncError(f"Unsafe zip entry path: {name}")
         parts = rel.split("/", 1)
         if len(parts) != 2:
             continue
         skill, inner = parts
+        inner_path = Path(inner)
+        if Path(skill).is_absolute() or ".." in Path(skill).parts:
+            raise SyncError(f"Unsafe skill name in zip entry: {name}")
+        if inner_path.is_absolute() or ".." in inner_path.parts:
+            raise SyncError(f"Unsafe skill file path in zip entry: {name}")
         skill_files.setdefault(skill, []).append((name, inner))
     return skill_files
 

package/src/claudekit_codex_sync/sync_registry.py

@@ -28,6 +28,7 @@ def load_registry(codex_home: Path) -> Dict[str, Any]:
 def save_registry(codex_home: Path, registry: Dict[str, Any]) -> None:
     """Save sync registry to disk."""
     registry_path = codex_home / REGISTRY_FILE
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
     registry["lastSync"] = datetime.now(timezone.utc).isoformat()
     registry_path.write_text(json.dumps(registry, indent=2), encoding="utf-8")
 

package/templates/agents-md.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/tests/test_clean_target.py

@@ -0,0 +1,75 @@
+"""Tests for clean_target module."""
+
+import json
+from pathlib import Path
+
+from claudekit_codex_sync.clean_target import clean_target
+
+
+def test_clean_removes_agents(tmp_path: Path):
+    """Clean removes agents dir."""
+    agents = tmp_path / "agents"
+    agents.mkdir()
+    (agents / "planner.toml").write_text("model = 'test'")
+    (agents / "researcher.toml").write_text("model = 'test'")
+
+    removed = clean_target(tmp_path, dry_run=False)
+    assert not agents.exists()
+    assert removed >= 2
+
+
+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.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.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"
+    agents.mkdir()
+    (agents / "test.toml").write_text("x = 1")
+
+    removed = clean_target(tmp_path, dry_run=True)
+    assert removed >= 1
+    assert agents.exists(), "dry-run should not delete"
+
+
+def test_clean_removes_registry(tmp_path: Path):
+    """Clean clears sync registry."""
+    registry = tmp_path / ".claudekit-sync-registry.json"
+    registry.write_text(json.dumps({"version": 1}))
+
+    clean_target(tmp_path, dry_run=False)
+    assert not registry.exists()