codex-sync

name	codex-sync
description	[Codex] Use when you need to run full Codex mirror sync (migrate → hooks → context → verify) standalone, no npm/package JSON needed.
disable-model-invocation	true

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
• User-question prompts mean to ask the user directly in Codex.
• Ignore Claude-specific mode-switch instructions when they appear.
• Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
• For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
• If a required step/tool cannot run in this environment, stop and ask the user before adapting.

Codex Project-Reference Loading (No Hooks)

Codex does not receive Claude hook-based doc injection. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

Missing-file hard stop: If docs/project-config.json, the docs index, lessons.md, or any task-required reference doc is missing, stop immediately and ask the user to run $project-config and $scan-all.

Situation-based docs:

• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md, project-structure-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec/test-case planning or TC mapping: feature-docs-reference.md
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

Quick Summary

Goal: Run full Codex mirror sync standalone — equivalent to npm run codex:sync without package.json or npm.

Also bootstraps team-wide Codex completion notifications by copying the portable .claude/scripts/codex/codex-notify.mjs helper into .codex/scripts/codex/ and upserting notification plus TUI status-line keys into .codex/config.toml.

Workflow:

1. Run — node .claude/skills/codex-sync/scripts/run-codex-sync.mjs
2. Verify — Exit code 0 = pass; check stdout summary
3. Inspect — On failure, re-run failing stage manually with --only=<stage> and --verbose

Key Rules:

• MUST run all 8 stages in order — orchestrator fails fast on first non-zero exit
• NEVER edit .agents/skills/codex-sync/** (auto-mirror) — edit .claude/skills/codex-sync/** source instead
• .claude is the source for skills/workflows/hooks; generated acceptance targets are .agents/skills/**, .codex/CODEX_CONTEXT.md, and AGENTS.md
• Stages 1-3 mutate .agents/skills/, .codex/, AGENTS.md; stages 4-8 are read-only verifiers
• Stage 1 upserts [tui].status_line to show model+reasoning, current directory, project root, context used, five-hour limit, and weekly limit by default
• Stage 3 mirrors full CLAUDE.md into AGENTS.md, then appends the generated Codex hook/context mirror and shared AI-SDD markers so Codex has both source instructions and hookless parity context
• Stage 1 must not inline docs/project-reference/lessons.md content into .agents/skills/**; generated skill mirrors reference the project-reference loading gate instead
• The SYNC:ai-sdd-artifact-contract marker must appear after sync in .codex/CODEX_CONTEXT.md and AGENTS.md
• No npm dependency — pure node + spawned subprocesses
• Idempotent — safe to re-run; second run produces only timestamp diffs

Bootstrap Gate (when AGENTS.md is missing or incomplete)

This skill is the route the agent-files bootstrap gate offers for a missing — or incomplete — root AGENTS.md, the generated Codex mirror of CLAUDE.md. Because Codex has no hooks, the universal session-start guides must be embedded in AGENTS.md directly; stage 3 produces that mirror (full CLAUDE.md copy, so the <!-- CK:UNIVERSAL-GUIDES v1 --> sentinel propagates) + hookless-parity context.

"Incomplete" means the file exists but lacks the universal guides — same three-state detection as the CLAUDE.md route (missing → init, incomplete → update smart-merge preserving project content, ok → no block), decided by the shared sentinel-then-anchors check.

The gate is user-invoke-only for this route (disable-model-invocation: true) — the AI cannot self-run $codex-sync, so the gate instructs it to ask the user to run it. Detection is shared with the CLAUDE.md route via .claude/hooks/lib/agent-files-state.cjs. Opt out of completeness enforcement with portability.requireUniversalGuides: false in docs/project-config.json (default true); skip init dismisses both hooks for 24h. Generate CLAUDE.md first (via $claude-md-init) — stage 3 reads it as the mirror source.

Stages

8 stages, sequential, matching npm run codex:sync:

#	Stage	Script	Effect
1	migrate	.claude/scripts/codex/migrate-claude-to-codex.mjs	Migrate Claude agents → .codex/agents/; mirror skills → .agents/skills/; setup Codex notifications
2	hooks	.claude/scripts/codex/sync-hooks.mjs	Generate .codex/hooks.json + sync report
3	context	.claude/scripts/codex/sync-context-workflows.mjs	Regenerate .codex/CODEX_CONTEXT.md + AGENTS.md with workflow context and shared AI-SDD markers
4	tests	node --test .claude/scripts/codex/tests/*.test.mjs	Run codex tooling unit tests
5	wf-cycle	.claude/scripts/codex/verify-workflow-cycle-compliance.mjs	Verify workflow sequence cycle compliance
6	sk-proto	.claude/scripts/codex/verify-skill-protocol-compliance.mjs	Verify skill strict-execution-contract
7	residue	.claude/scripts/codex/verify-no-project-residue.mjs	Verify no project residue in generated and generic source artifacts
8	sdd	.claude/scripts/codex/verify-sdd-semantic-compliance.mjs	Verify AI-SDD semantic contract coverage

Usage

# Full sync (standalone, no npm):
node .claude/skills/codex-sync/scripts/run-codex-sync.mjs

# Stream live child output:
node .claude/skills/codex-sync/scripts/run-codex-sync.mjs --verbose

# Full sync while forcing skill copy mode:
node .claude/skills/codex-sync/scripts/run-codex-sync.mjs --copy-skills

# Read-only verifiers (no mutation):
node .claude/skills/codex-sync/scripts/run-codex-sync.mjs --only=tests,wf-cycle,sk-proto,residue,sdd

# Skip stages while debugging:
node .claude/skills/codex-sync/scripts/run-codex-sync.mjs --skip=migrate,hooks

Exit codes: 0 all pass · 1 orchestrator failure · non-zero propagates from failing stage.

Closing Reminders

MUST ATTENTION invoke ONLY when user explicitly requests codex sync — never auto-invoke MUST ATTENTION edit source .claude/skills/codex-sync/**, NEVER the .agents/skills/codex-sync/** mirror MUST ATTENTION keep .codex/scripts/codex/codex-notify.mjs generated from .claude/scripts/codex/codex-notify.mjs; edit the .claude source first MUST ATTENTION keep Codex config upserts surgical; preserve unrelated .codex/config.toml keys and tables while updating the managed notification/status-line keys MUST ATTENTION keep AGENTS.md sync comprehensive; mirror full CLAUDE.md plus generated hook/context blocks, and preserve unmanaged AGENTS.md preface text MUST ATTENTION keep learned-lessons content out of .agents/skills/**; skills may point to docs/project-reference/lessons.md but must not embed its entries MUST ATTENTION orchestrator fails fast — re-run single failing stage with --only=<id> --verbose to debug MUST ATTENTION working directory auto-resolves to repo root from script path — do not pass --cwd MUST ATTENTION stages 1-3 mutate; stages 4-8 verify only — use --only= for non-destructive validation

Anti-Rationalization:

Evasion	Rebuttal
"Just edit the .agents mirror directly"	Next sync overwrites it. Always edit .claude/skills/codex-sync/ source
"Skip a stage to save time"	Verifiers (4-8) catch drift; skipping = silent regression risk
"Auto-invoke since user mentioned codex"	disable-model-invocation: true is binding. Wait for explicit $codex-sync
"Sync looks idempotent, skip verify"	Timestamp diffs are normal; structural diffs = bug. Always run verifiers

[USER-INVOKED ONLY] Manually triggered via $codex-sync. Claude MUST NOT auto-invoke — disable-model-invocation: true enforces this. [FAILS FAST] First non-zero stage exit aborts chain. Re-run failing stage manually to debug. [REPO ROOT] Orchestrator auto-resolves repo root from its own path. NEVER pass --cwd.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact.

Hookless Prompt Protocol Mirror (Auto-Synced)

Source: .claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason.

Generic portability boundary: Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from shared/sdd-artifact-contract.md. Read docs/project-config.json and docs/project-reference/docs-index-reference.md, then open the project reference docs named there. If either file or a required reference doc is missing, stop immediately and ask the user to run the project-config and scan-all skills. Any supported AI tool may execute when this shared context and local docs are available.

1. DETECT: Match prompt against workflow catalog
2. ANALYZE: Find best-match workflow AND evaluate if a custom step combination would fit better
3. ASK (REQUIRED FORMAT): Use a direct user question with this structure unless the user explicitly invoked a workflow/skill and the local protocol treats explicit invocation as confirmation:
   • Question: "Which workflow do you want to activate?"
   • Option 1: "Activate [BestMatch Workflow] (Recommended)"
   • Option 2: "Activate custom workflow: [step1 → step2 → ...]" (include one-line rationale)
4. ACTIVATE (if confirmed): Call $workflow-start <workflowId> for standard; sequence custom steps manually
5. CREATE TASKS: task tracking for ALL workflow steps
6. EXECUTE: Follow each step in sequence [CRITICAL-THINKING-MINDSET] Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination principle: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. AI Attention principle (Primacy-Recency): Put the 3 most critical rules at both top and bottom of long prompts/protocols so instruction adherence survives long context windows. Goal-driven execution: Define success criteria first, loop until verified, and stop only when observable checks pass. Tests verify intent: Tests must protect business rules/invariants and fail when the protected intent breaks, not only mirror current behavior.

[LESSON-LEARNED-REMINDER] [BLOCKING] Task Planning & Continuous Improvement — MANDATORY. Do not skip.

Break work into small tasks (task tracking) before starting. Add final task: "Analyze AI mistakes & lessons learned".

Extract lessons — ROOT CAUSE ONLY, not symptom fixes:

1. Name the FAILURE MODE (reasoning/assumption failure), not symptom — "assumed API existed without reading source" not "used wrong enum value".
2. Generality test: does this failure mode apply to ≥3 contexts/codebases? If not, abstract one level up.
3. Write as a universal rule — strip project-specific names/paths/classes. Useful on any codebase.
4. Consolidate: multiple mistakes sharing one failure mode → ONE lesson.
5. Recurrence gate: "Would this recur in future session WITHOUT this reminder?" — No → skip $learn.
6. Auto-fix gate: "Could $code-review/$code-simplifier/$security/$lint catch this?" — Yes → improve review skill instead.
7. BOTH gates pass → ask user to run $learn. [TASK-PLANNING] [MANDATORY] BEFORE executing any workflow or skill step, create/update task tracking for all planned steps, then keep it synchronized as each step starts/completes.