claudekit-codex-sync 0.2.3 → 0.2.5

package/README.md

@@ -13,11 +13,11 @@ 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 agents `.md` → `agents/` (for TOML conversion), commands/output-styles/rules/scripts → `codex_home/` directly |
+| **Asset sync** | Copies agents `.md` → `agents/` (for TOML conversion), output-styles/rules/scripts → `codex_home/` directly |
 | **Skill sync** | Copies skills into `codex_home/skills/` |
 | **Path normalize** | Rewrites `.claude` references to `.codex` |
+| **Hook rules** | Generates rules/ from hook behavior (security-privacy, file-naming, code-quality) |
 | **Config enforce** | Ensures `config.toml`, feature flags, and agent registration |
-| **Prompt export** | Generates Codex-compatible prompt files |
 | **Dep bootstrap** | Symlink-first venv strategy, fallback install |
 | **Runtime verify** | Health-checks synced environment |
 

package/docs/project-roadmap.md

@@ -26,6 +26,18 @@
 - [x] Documentation refresh for new CLI contract
 - [x] Removed legacy standalone `scripts/` and stale `reports/`
 
+## v0.2.5 - Hooks→Rules + Remove Prompts
+
+**Status:** Complete
+
+- [x] Remove hooks sync (Codex has no hooks API)
+- [x] Generate hook-equivalent rules (security-privacy, file-naming, code-quality)
+- [x] Remove commands sync (deprecated concept)
+- [x] Remove prompt export step (deprecated by OpenAI)
+- [x] Update bridge skill for Codex-native routing
+- [x] Add syntax adaptations for Claude→Codex patterns
+- [x] Add test coverage for rules_generator
+
 ## v0.3.0 - Coverage + Reliability
 
 **Status:** Planned

package/docs/system-architecture.md

@@ -8,12 +8,10 @@
 │ ~/.claude/ or zip    │───▶│ ./.codex or ~/.codex      │
 │   agents/*.md        │    │   agents/*.toml (convert) │
 │   skills/*           │    │   skills/*                │
-│   commands/          │    │   commands/               │
 │   output-styles/     │    │   output-styles/          │
 │   rules/             │    │   rules/                  │
 │   scripts/           │    │   scripts/                │
-└─────────────────────┘    │   prompts/* (generated)   │
-                            │   config.toml             │
+└─────────────────────┘    │   config.toml             │
                             └──────────────────────────┘
 ```
 
@@ -28,7 +26,7 @@ Workspace baseline: `./AGENTS.md` is ensured in the current working directory.
 
 2. **Asset/skill sync**
 - Copy agents `.md` directly to `codex_home/agents/` (for TOML conversion)
-- Copy managed assets (commands, output-styles, rules, scripts) to `codex_home/` directly
+- Copy managed assets (output-styles, rules, scripts) to `codex_home/` directly
 - Copy skills to `codex_home/skills/`
 - Apply registry-aware overwrite behavior (`--force`)
 
@@ -43,8 +41,8 @@ Workspace baseline: `./AGENTS.md` is ensured in the current working directory.
 - Register agents from `agents/*.toml`
 - Ensure workspace-level `AGENTS.md` baseline file exists
 
-5. **Prompt export**
-- Generate prompt files for Codex runtime from `commands/*.md`
+5. **Hook rules generation**
+- Generate rules/ from hook behavior templates (security-privacy, file-naming, code-quality)
 
 6. **Dependency bootstrap**
 - Try symlink reuse of `~/.claude/skills/.venv`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudekit-codex-sync",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Sync ClaudeKit skills, agents, and config to Codex CLI",
   "main": "bin/ck-codex-sync.js",
   "bin": {

package/plans/260223-1737-hooks-to-rules-cleanup/phase-01-hooks-to-rules.md

@@ -0,0 +1,202 @@
+# Phase 1: Remove Hooks, Generate Rules
+
+Status: pending
+Priority: critical
+Effort: 0.5d
+
+## Goal
+
+Stop syncing hooks (dead code). Create rules that replicate hook behavior at startup.
+
+## Context
+
+- 15 hooks use Claude Code's hook API (SessionStart, PreToolUse, etc.)
+- Codex CLI has NO hooks support — hooks dir is dead code
+- Rules (`~/.codex/rules/*.md`) load at startup = always in context = equivalent to hooks
+
+## Steps
+
+### 1.1 Remove `"hooks"` from ASSET_DIRS
+
+**File:** [constants.py](file:///home/vinhawk/claudekit-codex-sync/src/claudekit_codex_sync/constants.py)
+
+```diff
+-ASSET_DIRS = {"commands", "output-styles", "rules", "scripts", "hooks"}
++ASSET_DIRS = {"output-styles", "rules", "scripts"}
+```
+
+> Also removes `"commands"` — Phase 2 handles this.
+
+### 1.2 Create rule templates
+
+**File:** `templates/rule-security-privacy.md` [NEW]
+
+```markdown
+# Security & Privacy
+
+## Sensitive File Access
+Ask user for explicit approval before reading:
+- `.env`, `.env.*` (API keys, passwords, tokens)
+- `*.key`, `*.pem`, `*.p12`, `credentials.*`, `secrets.*`
+- Files in `~/.ssh/`, `~/.gnupg/`, `~/.aws/`
+
+**Flow:** State which file and why → wait for "yes" → read via cat → never output full secrets.
+
+## Directory Access Control
+Respect `.ckignore` patterns if present in project root:
+- Read `.ckignore` at session start
+- Do NOT access matching directories
+- Common: `node_modules/`, `dist/`, `build/`, `.git/objects/`
+```
+
+**File:** `templates/rule-file-naming.md` [NEW]
+
+```markdown
+# File Naming
+
+Apply before every file creation (skip for markdown/text):
+- **JS/TS/Python/shell**: kebab-case with descriptive names
+- **C#/Java/Kotlin/Swift**: PascalCase
+- **Go/Rust**: snake_case
+- Goal: self-documenting names for LLM tools (Grep, Glob, Search)
+```
+
+**File:** `templates/rule-code-quality.md` [NEW]
+
+```markdown
+# Code Quality Reminders
+
+## Code Simplification
+After significant file edits (5+), consider running code-simplifier agent.
+
+## Post-Planning
+After creating an implementation plan, always activate the cook skill before implementation.
+
+## Modularization
+If a code file exceeds 200 lines, consider modularizing it.
+```
+
+### 1.3 Create rules_generator module
+
+**File:** `src/claudekit_codex_sync/rules_generator.py` [NEW]
+
+```python
+"""Generate hook-equivalent rules from templates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .utils import load_template, write_text_if_changed
+
+
+RULE_TEMPLATES = {
+    "security-privacy.md": "rule-security-privacy.md",
+    "file-naming.md": "rule-file-naming.md",
+    "code-quality-reminders.md": "rule-code-quality.md",
+}
+
+
+def generate_hook_rules(*, codex_home: Path, dry_run: bool) -> int:
+    """Generate rules that replace ClaudeKit hook behavior."""
+    rules_dir = codex_home / "rules"
+    if not dry_run:
+        rules_dir.mkdir(parents=True, exist_ok=True)
+
+    generated = 0
+    for rule_name, template_name in RULE_TEMPLATES.items():
+        content = load_template(template_name)
+        target = rules_dir / rule_name
+        if write_text_if_changed(target, content, dry_run=dry_run):
+            generated += 1
+            print(f"upsert: rules/{rule_name}")
+
+    return generated
+```
+
+### 1.4 Fix `set-active-plan.cjs` hooks/lib dependency
+
+> [!WARNING]
+> **Discovered via Codex CLI live testing (`cxp --full-auto`)**:
+> `set-active-plan.cjs` line 16: `require('../hooks/lib/ck-config-utils.cjs')`.
+> Currently works because hooks ARE synced. **Will break after removing hooks.**
+> Only uses 2 functions: `readSessionState` + `writeSessionState` (~20 lines total).
+
+**File:** `scripts/set-active-plan.cjs` (source in `~/.claude/scripts/`)
+
+Inline the 3 tiny functions to remove hooks/lib dependency:
+
+```diff
+-const { writeSessionState, readSessionState } = require('../hooks/lib/ck-config-utils.cjs');
++// Inlined from hooks/lib/ck-config-utils.cjs (hooks removed in v0.2.5)
++function getSessionTempPath(sessionId) {
++  return path.join(os.tmpdir(), `ck-session-${sessionId}.json`);
++}
++function readSessionState(sessionId) {
++  if (!sessionId) return null;
++  const tempPath = getSessionTempPath(sessionId);
++  try {
++    if (!fs.existsSync(tempPath)) return null;
++    return JSON.parse(fs.readFileSync(tempPath, 'utf8'));
++  } catch (e) { return null; }
++}
++function writeSessionState(sessionId, state) {
++  if (!sessionId) return false;
++  const tempPath = getSessionTempPath(sessionId);
++  const tmpFile = tempPath + '.' + Math.random().toString(36).slice(2);
++  try {
++    fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2));
++    fs.renameSync(tmpFile, tempPath);
++    return true;
++  } catch (e) {
++    try { fs.unlinkSync(tmpFile); } catch (_) {}
++    return false;
++  }
++}
+```
+
+Also need to add `const os = require('os');` if not already present.
+
+**Option**: Instead of modifying source, apply this patch during sync in `path_normalizer.py`
+by replacing the `require('../hooks/lib/...')` line with inlined functions.
+
+## Codex CLI Live Test Results (cxp --full-auto)
+
+| Script | Status | Notes |
+|---|---|---|
+| `ck-help.py` | ✅ OK | |
+| `resolve_env.py` | ✅ OK | |
+| `scan_commands.py` | ✅ OK | |
+| `scan_skills.py` | ✅ OK | |
+| `set-active-plan.cjs` (no args) | ⚠️ FAIL | Expected: usage error |
+| `set-active-plan.cjs` (with plan) | ✅ OK | BUT depends on `../hooks/lib/` |
+| `test-ck-help.py` | ✅ OK | |
+| `test_ck_help.py` | ⚠️ FAIL | Pre-existing: intent detection mismatch |
+| `test_ck_help_integration.py` | ⚠️ FAIL | Pre-existing: 17 pass / 2 fail |
+| `validate-docs.cjs` | ✅ OK | |
+| `win_compat.py` | ✅ OK | |
+| `worktree.cjs` (no args) | ⚠️ FAIL | Expected: usage error |
+| `worktree.test.cjs` | ⚠️ FAIL | Pre-existing test failures |
+
+**Summary**: 8 OK / 5 FAIL. Of 5 FAILs: 2 expected (no-args usage), 2 pre-existing test bugs, 1 dependency issue (set-active-plan → hooks/lib).
+
+## Todo
+
+- [ ] Remove `"hooks"` and `"commands"` from `ASSET_DIRS`
+- [ ] Create `templates/rule-security-privacy.md`
+- [ ] Create `templates/rule-file-naming.md`
+- [ ] Create `templates/rule-code-quality.md`
+- [ ] Create `src/claudekit_codex_sync/rules_generator.py`
+- [ ] Fix `set-active-plan.cjs` hooks/lib dependency (inline or patch during sync)
+- [ ] Compile check: `python3 -m py_compile src/claudekit_codex_sync/rules_generator.py`
+
+## Verification
+
+```bash
+python3 -m py_compile src/claudekit_codex_sync/rules_generator.py
+python3 -m py_compile src/claudekit_codex_sync/constants.py
+ls templates/rule-*.md  # should show 3 files
+# After sync, verify set-active-plan.cjs no longer depends on hooks:
+grep -c "hooks/lib" ~/.codex/scripts/set-active-plan.cjs  # should be 0
+node ~/.codex/scripts/set-active-plan.cjs plans/test 2>&1 | head -5  # should not MODULE_NOT_FOUND
+```

package/plans/260223-1737-hooks-to-rules-cleanup/phase-02-remove-commands-prompts.md

@@ -0,0 +1,82 @@
+# Phase 2: Remove Commands & Prompts Sync
+
+Status: pending
+Priority: high
+Effort: 0.5d
+
+## Goal
+
+Eliminate commands/prompts duplication from pipeline. Commands already removed from `ASSET_DIRS` in Phase 1, now remove prompt generation.
+
+## Context
+
+- Codex [deprecated custom prompts](https://developers.openai.com/codex/custom-prompts) in favor of skills
+- `prompt_exporter.py` generates duplicates of every command → wasteful
+- Bridge skill already maps legacy `/commands` → Codex skills
+- Both `commands/` and `prompts/` produce identical content
+
+## Steps
+
+### 2.1 Remove prompt export from CLI
+
+**File:** [cli.py](file:///home/vinhawk/claudekit-codex-sync/src/claudekit_codex_sync/cli.py)
+
+Remove import and call:
+
+```diff
+-from .prompt_exporter import export_prompts
++from .rules_generator import generate_hook_rules
+```
+
+Remove prompt export call (~line 188):
+
+```diff
+-    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']}")
+```
+
+Add rules generation call after normalize step (~line 163):
+
+```diff
++    rules_generated = generate_hook_rules(codex_home=codex_home, dry_run=args.dry_run)
++    print(f"hook_rules_generated={rules_generated}")
+```
+
+Update summary dict:
+
+```diff
+-        "prompts": prompt_stats,
++        "rules_generated": rules_generated,
+```
+
+### 2.2 Remove prompts manifest from clean_target
+
+**File:** [clean_target.py](file:///home/vinhawk/claudekit-codex-sync/src/claudekit_codex_sync/clean_target.py)
+
+`".claudekit-generated-prompts.txt"` stays in cleanup list (for cleaning old installs) but `"prompts"` is already in the subdir cleanup loop — no change needed.
+
+### 2.3 Remove PROMPT_MANIFEST/PROMPT_REPLACEMENTS usage
+
+**File:** [constants.py](file:///home/vinhawk/claudekit-codex-sync/src/claudekit_codex_sync/constants.py)
+
+Keep `PROMPT_REPLACEMENTS` and `PROMPT_MANIFEST` constants (no harm, `prompt_exporter.py` still importable). But mark as deprecated with comment:
+
+```python
+# DEPRECATED: prompt_exporter.py no longer called from CLI pipeline (v0.2.5)
+PROMPT_MANIFEST = ".claudekit-generated-prompts.txt"
+```
+
+## Todo
+
+- [ ] Remove `export_prompts` import from `cli.py`
+- [ ] Remove prompt export call from `cli.py`
+- [ ] Add `generate_hook_rules` import and call to `cli.py`
+- [ ] Update summary dict in `cli.py`
+- [ ] Mark `PROMPT_MANIFEST` as deprecated in `constants.py`
+
+## Verification
+
+```bash
+python3 -m py_compile src/claudekit_codex_sync/cli.py
+PYTHONPATH=src python3 -m claudekit_codex_sync.cli -g -n  # dry-run should not error
+```

package/plans/260223-1737-hooks-to-rules-cleanup/phase-03-bridge-and-syntax.md

@@ -0,0 +1,59 @@
+# Phase 3: Update Bridge Skill + Syntax Adaptations
+
+Status: pending
+Priority: medium
+Effort: 0.25d
+
+## Goal
+
+Update bridge skill description. Add syntax adaptations for remaining Claude-specific patterns.
+
+## Steps
+
+### 3.1 Update bridge skill template
+
+**File:** [templates/bridge-skill.md](file:///home/vinhawk/claudekit-codex-sync/templates/bridge-skill.md)
+
+```diff
+ ---
+ name: claudekit-command-bridge
+-description: Bridge legacy ClaudeKit commands to Codex-native workflows. Use when users mention /ck-help, /coding-level, /ask, /docs/*, /journal, /watzup, or ask for Claude command equivalents.
++description: Bridge legacy ClaudeKit slash commands to Codex-native skills. Activates when users mention /ck-help, /coding-level, /ask, /docs/*, /journal, /watzup, or ask for Claude command equivalents.
+ ---
+
+-# ClaudeKit Command Bridge
++# ClaudeKit → Codex Bridge
+
+-Translate ClaudeKit command intent into Codex skills/workflows.
++Translate ClaudeKit command intent into Codex-native skills.
+```
+
+### 3.2 Add syntax adaptations
+
+**File:** [constants.py](file:///home/vinhawk/claudekit-codex-sync/src/claudekit_codex_sync/constants.py)
+
+Add entries to `CLAUDE_SYNTAX_ADAPTATIONS`:
+
+```diff
+ CLAUDE_SYNTAX_ADAPTATIONS: List[Tuple[str, str]] = [
+     ("Task(Explore)", "the explore agent"),
+     ("Task(researcher)", "the researcher agent"),
+     ("Task(", "delegate to "),
+     ("$HOME/.claude/skills/*", "${CODEX_HOME:-$HOME/.codex}/skills/*"),
++    ("via Task tool", "via agent delegation"),
++    ("Claude Code", "Codex CLI"),
++    ("claude code", "Codex CLI"),
+ ]
+```
+
+## Todo
+
+- [ ] Update `templates/bridge-skill.md` description
+- [ ] Add syntax adaptations to `constants.py`
+
+## Verification
+
+```bash
+python3 -m py_compile src/claudekit_codex_sync/constants.py
+grep "Codex-native skills" templates/bridge-skill.md  # should match
+```

package/plans/260223-1737-hooks-to-rules-cleanup/phase-04-version-docs-tests.md

@@ -0,0 +1,135 @@
+# Phase 4: Version Bump, Docs, Tests
+
+Status: pending
+Priority: medium
+Effort: 0.5d
+
+## Goal
+
+Bump to v0.2.5. Update docs. Add tests for `rules_generator`. Run full verification.
+
+## Steps
+
+### 4.1 Version bump
+
+**File:** [package.json](file:///home/vinhawk/claudekit-codex-sync/package.json)
+
+```diff
+-  "version": "0.2.4",
++  "version": "0.2.5",
+```
+
+### 4.2 Add test for rules_generator
+
+**File:** `tests/test_rules_generator.py` [NEW]
+
+```python
+"""Tests for rules_generator module."""
+
+from pathlib import Path
+
+from claudekit_codex_sync.rules_generator import generate_hook_rules
+
+
+def test_generates_all_rule_files(tmp_path: Path):
+    """Generates 3 rule files."""
+    count = generate_hook_rules(codex_home=tmp_path, dry_run=False)
+    assert count == 3
+    assert (tmp_path / "rules" / "security-privacy.md").exists()
+    assert (tmp_path / "rules" / "file-naming.md").exists()
+    assert (tmp_path / "rules" / "code-quality-reminders.md").exists()
+
+
+def test_idempotent(tmp_path: Path):
+    """Second run returns 0 (no changes)."""
+    generate_hook_rules(codex_home=tmp_path, dry_run=False)
+    count = generate_hook_rules(codex_home=tmp_path, dry_run=False)
+    assert count == 0
+
+
+def test_dry_run(tmp_path: Path):
+    """Dry run counts but doesn't create."""
+    count = generate_hook_rules(codex_home=tmp_path, dry_run=True)
+    assert count == 3
+    assert not (tmp_path / "rules").exists()
+```
+
+### 4.3 Update README
+
+**File:** [README.md](file:///home/vinhawk/claudekit-codex-sync/README.md)
+
+Update "What It Does" table:
+- Remove `Prompt export` row
+- Remove hooks from `Asset sync` description
+- Add `Hook rules` row: "Generates rules/ from hook behavior (security-privacy, file-naming, code-quality)"
+
+### 4.4 Update system-architecture
+
+**File:** [docs/system-architecture.md](file:///home/vinhawk/claudekit-codex-sync/docs/system-architecture.md)
+
+- Remove Step 5 (Prompt export) from pipeline
+- Add step: "Hook rules generation"
+- Remove `hooks/` from architecture diagram
+- Remove `prompts/* (generated)` from diagram
+
+### 4.5 Update project roadmap
+
+**File:** [docs/project-roadmap.md](file:///home/vinhawk/claudekit-codex-sync/docs/project-roadmap.md)
+
+Add v0.2.5 section:
+
+```markdown
+## v0.2.5 - Hooks→Rules + Remove Prompts
+
+**Status:** Complete
+
+- [x] Remove hooks sync (Codex has no hooks API)
+- [x] Generate hook-equivalent rules (security-privacy, file-naming, code-quality)
+- [x] Remove commands sync (deprecated concept)
+- [x] Remove prompt export step (deprecated by OpenAI)
+- [x] Update bridge skill for Codex-native routing
+- [x] Add syntax adaptations for Claude→Codex patterns
+- [x] Add test coverage for rules_generator
+```
+
+## Todo
+
+- [ ] Bump version in `package.json`
+- [ ] Create `tests/test_rules_generator.py`
+- [ ] Update `README.md`
+- [ ] Update `docs/system-architecture.md`
+- [ ] Update `docs/project-roadmap.md`
+
+## Final Verification (all 10 steps)
+
+```bash
+# 1. Compile check
+python3 -m py_compile src/claudekit_codex_sync/*.py
+
+# 2. Run all tests
+PYTHONPATH=src python3 -m pytest tests/ -v
+
+# 3. Dry-run sync
+PYTHONPATH=src python3 -m claudekit_codex_sync.cli -g -n
+
+# 4. Actual sync (fresh)
+PYTHONPATH=src python3 -m claudekit_codex_sync.cli -g -f --force
+
+# 5. Verify hooks NOT synced
+ls ~/.codex/hooks/ 2>/dev/null && echo "FAIL" || echo "OK: no hooks"
+
+# 6. Verify rules generated
+ls ~/.codex/rules/security-privacy.md ~/.codex/rules/file-naming.md ~/.codex/rules/code-quality-reminders.md
+
+# 7. Verify no prompts generated
+[ ! -f ~/.codex/prompts/.claudekit-generated-prompts.txt ] && echo "OK" || echo "FAIL"
+
+# 8. Verify no commands dir
+ls ~/.codex/commands/ 2>/dev/null && echo "WARN: commands exist" || echo "OK"
+
+# 9. Verify existing rules intact
+ls ~/.codex/rules/development-rules.md ~/.codex/rules/primary-workflow.md
+
+# 10. Token budget check
+du -b ~/.codex/rules/*.md | awk '{sum+=$1} END {print "Rules: " sum " bytes / 32768 limit"}'
+```

package/plans/260223-1737-hooks-to-rules-cleanup/plan.md

@@ -0,0 +1,49 @@
+# v0.2.5 — Hooks→Rules, Remove Commands/Prompts, Harden Pipeline
+
+Remove non-functional hooks, eliminate commands/prompts bloat, generate hook-equivalent rules.
+
+## Problem
+
+- 15+ hooks copied to `~/.codex/hooks/` but Codex CLI has no hooks API → dead code
+- Commands duplicated as both `commands/` and `prompts/` → bloat
+- Custom prompts [deprecated by OpenAI](https://developers.openai.com/codex/custom-prompts)
+- Bridge skill already maps legacy commands → Codex skills
+
+## Phases
+
+| # | Phase | Status | Key Changes |
+|---|---|---|---|
+| 1 | [Remove hooks, generate rules](phase-01-hooks-to-rules.md) | `[x]` | `constants.py`, 3 templates, `rules_generator.py` |
+| 2 | [Remove commands/prompts](phase-02-remove-commands-prompts.md) | `[x]` | `cli.py`, `clean_target.py` |
+| 3 | [Update bridge skill + syntax](phase-03-bridge-and-syntax.md) | `[x]` | `templates/bridge-skill.md`, `constants.py` |
+| 4 | [Version bump, docs, tests](phase-04-version-docs-tests.md) | `[x]` | `package.json`, `README.md`, docs, tests |
+
+## Before → After
+
+```
+~/.codex/                     ~/.codex/
+  hooks/  ❌ NOT WORKING        rules/
+    15+ .cjs files               development-rules.md    ← existing
+  commands/  ⚠️ deprecated       primary-workflow.md     ← existing
+    18+ .md files                 security-privacy.md     ← NEW from hooks
+  prompts/   ⚠️ duplicate        file-naming.md          ← NEW from hooks
+    18+ .md files                 code-quality-reminders.md ← NEW from hooks
+  rules/   ✅                   skills/  ✅ unchanged
+  skills/  ✅                   agents/  ✅ unchanged
+  agents/  ✅                   scripts/ ✅ unchanged
+```
+
+## Dependencies
+
+Phase 1 → Phase 2 → Phase 3 → Phase 4 (strict sequential)
+
+## Research Sources
+
+- [Codex Skills docs](https://developers.openai.com/codex/skills): Skills at `$HOME/.agents/skills/`
+- [Custom Prompts docs](https://developers.openai.com/codex/custom-prompts): **Deprecated**, use skills
+- Codex rules: `~/.codex/rules/*.md` loaded at startup, always in context
+- Token budget: 37 KiB used / 65 KiB limit → ~28 KiB remaining
+
+## Risk
+
+Low — removes dead code, generates static rules from templates. No logic change to working features.

package/plans/reports/tester-260223-1625-pre-push-deep-test.md

@@ -0,0 +1,78 @@
+# Test Report: claudekit-codex-sync v0.2.3+fix
+
+**Date:** 2026-02-23 16:25  
+**Scope:** Pre-push deep verification after eliminating `claudekit/` subdirectory  
+**Changes tested:** `constants.py`, `clean_target.py`, `asset_sync_dir.py`, `asset_sync_zip.py`, `path_normalizer.py`, `prompt_exporter.py`
+
+---
+
+## 1. Unit Tests — 22/22 ✅
+
+| Module | Tests | Status |
+|---|---|---|
+| `test_clean_target.py` | 5 | ✅ |
+| `test_cli_args.py` | 6 | ✅ |
+| `test_config_enforcer.py` | 4 | ✅ |
+| `test_path_normalizer.py` | 7 | ✅ |
+
+## 2. Compile Check — 8/8 ✅
+
+All 8 modified Python modules compile without errors.
+
+## 3. E2E Sync (local source, `--fresh`) — ✅
+
+| Metric | Value |
+|---|---|
+| Assets added | 146 |
+| Skills added | 54 (4 skipped) |
+| Normalize changed | 28 |
+| Agents converted & registered | 14 |
+| Prompts generated | 20 |
+| Verify | codex=ok, copywriting=ok |
+
+## 4. Filesystem Validation — 7/7 ✅
+
+| Check | Result |
+|---|---|
+| `~/.codex/claudekit/` does NOT exist | ✅ |
+| `~/.codex/scripts/` (17 files) | ✅ |
+| `~/.codex/rules/` (5 files) | ✅ |
+| `~/.codex/commands/` (22 files) | ✅ |
+| `~/.codex/hooks/` (81 files) | ✅ |
+| `~/.codex/output-styles/` (6 files) | ✅ |
+| `~/.codex/.ck.json` + `.env.example` | ✅ |
+
+## 5. Reference Integrity — 5/5 ✅
+
+Zero stale `claudekit/` filesystem paths found in:
+
+| Location | Stale refs |
+|---|---|
+| Skills | 0 |
+| Agent TOMLs | 0 |
+| Prompts | 0 (1 GitHub URL, correctly excluded) |
+| Rules | 0 |
+| Commands | 0 |
+
+## 6. Runtime Script Execution — 5/5 ✅
+
+| Script | Language | Exit | Notes |
+|---|---|---|---|
+| `set-active-plan.cjs` | Node.js | 0 | Requires `../hooks/lib/` — now synced |
+| `validate-docs.cjs` | Node.js | 0 | Generated validation report |
+| `worktree.cjs list` | Node.js | 0 | Listed 1 worktree |
+| `ck-help.py` | Python | 0 | CK help search works |
+| `fix-shebang-permissions.sh` | Bash | 0 | Expected "Error: .claude not found" (runs from codex context) |
+
+---
+
+## Bugs Found & Fixed
+
+| Bug | Severity | Fix |
+|---|---|---|
+| Scripts crash with `MODULE_NOT_FOUND` for `../hooks/lib/` | **High** | Added `hooks` to `ASSET_DIRS` in `constants.py` |
+| Stale `claudekit/` dir not cleaned on fresh sync | **Medium** | Added `"claudekit"` to clean list in `clean_target.py` |
+
+## Verdict
+
+**✅ ALL 6 TEST CATEGORIES PASS — READY TO PUSH**

package/src/claudekit_codex_sync/clean_target.py

@@ -10,8 +10,8 @@ def clean_target(codex_home: Path, *, dry_run: bool) -> int:
     """Remove agents, skills (keep .venv), prompts, asset dirs before fresh sync."""
     removed = 0
 
-    # Clean top-level asset dirs (was: "agents", "prompts", "claudekit")
-    for subdir in ("agents", "prompts", "commands", "output-styles", "rules", "scripts", "hooks"):
+    # Clean top-level asset dirs + legacy claudekit/ from pre-v0.2.3
+    for subdir in ("agents", "prompts", "commands", "output-styles", "rules", "scripts", "hooks", "claudekit"):
         target = codex_home / subdir
         if target.exists():
             count = sum(1 for item in target.rglob("*") if item.is_file())

package/src/claudekit_codex_sync/cli.py

@@ -22,7 +22,7 @@ from .config_enforcer import (
 )
 from .dep_bootstrapper import bootstrap_deps
 from .path_normalizer import normalize_agent_tomls, normalize_files
-from .prompt_exporter import export_prompts
+from .rules_generator import generate_hook_rules
 from .runtime_verifier import verify_runtime
 from .source_resolver import detect_claude_source, find_latest_zip, validate_source
 from .sync_registry import load_registry, save_registry
@@ -162,6 +162,9 @@ def main() -> int:
     changed = normalize_files(codex_home=codex_home, include_mcp=args.mcp, dry_run=args.dry_run)
     print(f"normalize_changed={changed}")
 
+    rules_generated = generate_hook_rules(codex_home=codex_home, dry_run=args.dry_run)
+    print(f"hook_rules_generated={rules_generated}")
+
     # enforce_config BEFORE register_agents — enforce_config rewrites config.toml
     baseline_changed = 0
     if ensure_agents(workspace=workspace, dry_run=args.dry_run):
@@ -185,9 +188,6 @@ def main() -> int:
     agents_registered = register_agents(codex_home=codex_home, dry_run=args.dry_run)
     print(f"agents_registered={agents_registered}")
 
-    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.no_deps:
         bootstrap_stats = bootstrap_deps(
@@ -219,7 +219,7 @@ def main() -> int:
         "normalize_changed": changed,
         "agent_toml_changed": agent_toml_changed,
         "agents_registered": agents_registered,
-        "prompts": prompt_stats,
+        "rules_generated": rules_generated,
         "bootstrap": bootstrap_stats,
         "verify": verify_stats,
     }

package/src/claudekit_codex_sync/constants.py

@@ -2,9 +2,10 @@
 
 from typing import List, Set, Tuple
 
-ASSET_DIRS = {"commands", "output-styles", "rules", "scripts", "hooks"}
+ASSET_DIRS = {"output-styles", "rules", "scripts"}
 ASSET_FILES = {".env.example", ".ck.json"}
 ASSET_MANIFEST = ".sync-manifest-assets.txt"
+# DEPRECATED: prompt_exporter.py no longer called from CLI pipeline (v0.2.5)
 PROMPT_MANIFEST = ".claudekit-generated-prompts.txt"
 REGISTRY_FILE = ".claudekit-sync-registry.json"
 
@@ -67,6 +68,9 @@ CLAUDE_SYNTAX_ADAPTATIONS: List[Tuple[str, str]] = [
     ("Task(researcher)", "the researcher agent"),
     ("Task(", "delegate to "),
     ("$HOME/.claude/skills/*", "${CODEX_HOME:-$HOME/.codex}/skills/*"),
+    ("via Task tool", "via agent delegation"),
+    ("Claude Code", "Codex CLI"),
+    ("claude code", "Codex CLI"),
 ]
 
 # Claude model → Codex model mapping (per developers.openai.com/codex/multi-agent)

package/src/claudekit_codex_sync/rules_generator.py

@@ -0,0 +1,31 @@
+"""Generate hook-equivalent rules from templates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .utils import load_template, write_text_if_changed
+
+
+RULE_TEMPLATES = {
+    "security-privacy.md": "rule-security-privacy.md",
+    "file-naming.md": "rule-file-naming.md",
+    "code-quality-reminders.md": "rule-code-quality.md",
+}
+
+
+def generate_hook_rules(*, codex_home: Path, dry_run: bool) -> int:
+    """Generate rules that replace ClaudeKit hook behavior."""
+    rules_dir = codex_home / "rules"
+    if not dry_run:
+        rules_dir.mkdir(parents=True, exist_ok=True)
+
+    generated = 0
+    for rule_name, template_name in RULE_TEMPLATES.items():
+        content = load_template(template_name)
+        target = rules_dir / rule_name
+        if write_text_if_changed(target, content, dry_run=dry_run):
+            generated += 1
+            print(f"upsert: rules/{rule_name}")
+
+    return generated

package/templates/bridge-skill.md

@@ -1,11 +1,11 @@
 ---
 name: claudekit-command-bridge
-description: Bridge legacy ClaudeKit commands to Codex-native workflows. Use when users mention /ck-help, /coding-level, /ask, /docs/*, /journal, /watzup, or ask for Claude command equivalents.
+description: Bridge legacy ClaudeKit slash commands to Codex-native skills. Activates when users mention /ck-help, /coding-level, /ask, /docs/*, /journal, /watzup, or ask for Claude command equivalents.
 ---
 
-# ClaudeKit Command Bridge
+# ClaudeKit → Codex Bridge
 
-Translate ClaudeKit command intent into Codex skills/workflows.
+Translate ClaudeKit command intent into Codex-native skills.
 
 ## Quick Mapping
 

package/templates/rule-code-quality.md

@@ -0,0 +1,10 @@
+# Code Quality Reminders
+
+## Code Simplification
+After significant file edits (5+), consider running code-simplifier agent.
+
+## Post-Planning
+After creating an implementation plan, always activate the cook skill before implementation.
+
+## Modularization
+If a code file exceeds 200 lines, consider modularizing it.

package/templates/rule-file-naming.md

@@ -0,0 +1,7 @@
+# File Naming
+
+Apply before every file creation (skip for markdown/text):
+- **JS/TS/Python/shell**: kebab-case with descriptive names
+- **C#/Java/Kotlin/Swift**: PascalCase
+- **Go/Rust**: snake_case
+- Goal: self-documenting names for LLM tools (Grep, Glob, Search)

package/templates/rule-security-privacy.md

@@ -0,0 +1,15 @@
+# Security & Privacy
+
+## Sensitive File Access
+Ask user for explicit approval before reading:
+- `.env`, `.env.*` (API keys, passwords, tokens)
+- `*.key`, `*.pem`, `*.p12`, `credentials.*`, `secrets.*`
+- Files in `~/.ssh/`, `~/.gnupg/`, `~/.aws/`
+
+**Flow:** State which file and why → wait for "yes" → read via cat → never output full secrets.
+
+## Directory Access Control
+Respect `.ckignore` patterns if present in project root:
+- Read `.ckignore` at session start
+- Do NOT access matching directories
+- Common: `node_modules/`, `dist/`, `build/`, `.git/objects/`

package/tests/test_rules_generator.py

@@ -0,0 +1,28 @@
+"""Tests for rules_generator module."""
+
+from pathlib import Path
+
+from claudekit_codex_sync.rules_generator import generate_hook_rules
+
+
+def test_generates_all_rule_files(tmp_path: Path):
+    """Generates 3 rule files."""
+    count = generate_hook_rules(codex_home=tmp_path, dry_run=False)
+    assert count == 3
+    assert (tmp_path / "rules" / "security-privacy.md").exists()
+    assert (tmp_path / "rules" / "file-naming.md").exists()
+    assert (tmp_path / "rules" / "code-quality-reminders.md").exists()
+
+
+def test_idempotent(tmp_path: Path):
+    """Second run returns 0 (no changes)."""
+    generate_hook_rules(codex_home=tmp_path, dry_run=False)
+    count = generate_hook_rules(codex_home=tmp_path, dry_run=False)
+    assert count == 0
+
+
+def test_dry_run(tmp_path: Path):
+    """Dry run counts but doesn't create."""
+    count = generate_hook_rules(codex_home=tmp_path, dry_run=True)
+    assert count == 3
+    assert not (tmp_path / "rules").exists()