Hikkywannafly/vibe-codex

Vibe Codex

Use this skill to run the vibe-kit product-building workflow inside Codex. Treat the bundled Claude Code files as source material, not as executable Claude slash commands.

File Paths

The Codex installer puts files in two locations:

• Skills → ~/.agents/skills/<skill-name>/ (Codex global skills directory, $AGENTS_SKILLS_DIR)
• Shared reference files (agents, presets, templates) → ~/.codex/vibe-kit/ (or $CODEX_HOME/vibe-kit/)

Resolve paths using these variables (Windows uses \, Unix uses /):

| Variable | Default | | ------------------- | ------------------ | | AGENTS_SKILLS_DIR | ~/.agents/skills | | CODEX_HOME | ~/.codex |

Read First

Load only the files needed for the current request. Use AGENTS_SKILLS_DIR for skills and CODEX_HOME/vibe-kit for shared files:

• Always read $AGENTS_SKILLS_DIR/vibe/templates/clarify-questions.md for question selection.
• Always read $AGENTS_SKILLS_DIR/vibe/templates/plan-bullet-format.md before rendering a plan.
• For preset starts, read $CODEX_HOME/vibe-kit/presets/<name>.md.
• For stack-specific work, read $AGENTS_SKILLS_DIR/nextjs-app-router/SKILL.md, $AGENTS_SKILLS_DIR/shadcn-ui/SKILL.md, $AGENTS_SKILLS_DIR/supabase-setup/SKILL.md, etc.
• For role expectations, read $CODEX_HOME/vibe-kit/agents/planner.md, fullstack-dev.md, mobile-dev.md, tester.md, reviewer.md as checklists.
• For porting another Claude-only skill to Codex, read references/codex-tool-mapping.md.

Fallback: if a file is not found at the expected path, search for it under ~/.agents/skills/ and ~/.codex/ before giving up.

Language Rule (enforced at EVERY step)

Detect language from the user's first message. Vietnamese input (kể cả mixed VN/EN) → ALL user-visible output in Vietnamese (Southern, friendly, short sentences, no jargon). English input → English. Ambiguous or very short input → default Vietnamese.

Vietnamese MUST use full diacritics (có dấu đầy đủ). Never write Vietnamese without tone marks or accents (e.g., write Bắt đầu not Bat dau, Tiêu đề not Tieu de). ASCII-safe/no-accent Vietnamese is NOT acceptable, even for code comments or progress lines.

Scope: clarify questions, plan bullets, approval prompts, progress lines, error messages, UI copy inside the generated app, and the final summary. Internal reasoning, variable names, file paths, and code comments stay in English.

Workflow

1. Intake

Parse the user's product request and classify it as exactly one category:

• landing-page
• shop-online
• crm
• blog
• dashboard
• other

Detect mode before asking questions:

• yolo if the request contains yolo, --yolo, --fast, auto, nhanh nha, nhanh di, nhanh đi, lam luon, làm luôn, khoi hoi, khỏi hỏi, khong can hoi, không cần hỏi, chay luon, or chạy luôn.
• safe otherwise.

Detect the user's language (Vietnamese or English) and store it as "lang": "vi" or "lang": "en" in .vibe/intent.json. Default to "vi" when input is ambiguous. From this point forward, all user-visible output must match the detected language.

Create .vibe/intent.json with the category, raw user text, matched keywords, mode, and lang. Redact secrets before writing any .vibe/ file.

2. Clarify

For safe mode, ask one message with 3-5 numbered questions from <kit-root>/skills/vibe/templates/clarify-questions.md. Skip questions already answered by the user. Wait for the user's reply before planning.

For yolo mode, skip clarification and apply sensible defaults:

• Project name from the category and a short slug.
• Deploy target vercel, unless the user specified another target.
• Contact/lead forms save to Supabase when relevant.
• Generated UI copy follows the user's input language.

Append clarifications or defaults to .vibe/intent.json.

3. Plan And Gate

Render exactly 3-5 numbered plan bullets using <kit-root>/skills/vibe/templates/plan-bullet-format.md. Show the plan to the user and write the same plan to .vibe/plan.md.

For safe mode, wait for approval before writing app code:

Does this plan look good? (type: yes / edit / cancel)

Accept equivalent Vietnamese approvals such as co, có, duoc, được, chay di, and làm đi. On edit, revise the plan. On cancel, write .vibe/checkpoint.json with {"status":"cancelled"} and stop.

For yolo mode, mark the plan auto-approved and proceed.

4. Implement In Codex

Environment Probe (run ONCE before any install or build step)

Before running any npm, pnpm, or node command, resolve the runtime using this probe sequence:

1. Try node --version in the current shell. If it exits 0, the runtime is in PATH — proceed normally.
2. If that fails, search these Windows locations in order:
   • $env:ProgramFiles\nodejs\node.exe
   • $env:APPDATA\nvm\current\node.exe (nvm-windows default)
   • $env:LOCALAPPDATA\nvm\current\node.exe
   • C:\nvm4w\nodejs\node.exe (nvm4w — NVM for Windows alternate installer)
   • C:\nvm\nodejs\node.exe
   • $env:LOCALAPPDATA\Volta\bin\node.exe
   • $env:ProgramFiles\Volta\bin\node.exe
   • Dynamic fallback: run Get-ChildItem -Path C:\,D:\,E:\ -Filter node.exe -Recurse -Depth 4 -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName to discover any non-standard install root.
3. If found at a non-PATH location, prepend its parent directory to $env:PATH for the current session ($env:PATH = "<dir>;$env:PATH"), then retry node --version.
4. Repeat the same probe for pnpm ($env:APPDATA\npm\pnpm.cmd, $env:LOCALAPPDATA\pnpm\pnpm.cmd) and npm (same dir as node).
5. Only if ALL probes fail: ask the user — "Mình không tìm thấy Node.js. Bạn cài Node ở đâu, hay có thể chạy node --version trong terminal bình thường được không?" (Vietnamese) or equivalent English. Do NOT silently fall back to static HTML.

HARD RULE — No silent stack changes: The approved plan defines the tech stack (e.g., Next.js + Tailwind + Supabase). Codex MUST NOT change this stack unilaterally for any reason, including a missing runtime or tool. If a required tool is unavailable, stop and ask the user. Do not substitute a different output format (static HTML, plain JS, etc.) without explicit approval.

Language enforcement

Read lang from .vibe/intent.json before generating any user-visible string. If lang == "vi", all UI copy (button labels, headings, error messages, email templates, form placeholders) inside the generated app must be Vietnamese. Never default to English UI copy for a Vietnamese-language project.

Use Codex's native tools and the repository's existing patterns:

• Use shell_command for shell work and apply_patch for manual file edits.
• Use multi_tool_use.parallel for independent reads and searches.
• Use rg first when available; fall back to platform-native search when missing.
• Use spawn_agent only when current Codex rules allow it and the user explicitly asked for sub-agents, delegation, or parallel agent work. Otherwise, execute the planner, research, implementation, testing, and review steps locally.
• Browse current official docs when package behavior, versions, deployment rules, or pricing may have changed.
• Keep generated apps aligned with the default vibe-kit stack unless the user asks otherwise: Next.js App Router, TypeScript, Tailwind, shadcn/ui, Supabase, Polar or local payment fallback, Vercel/Docker/VPS deployment.
• For mobile work, use Expo, Expo Router, NativeWind, Supabase RN auth/session patterns, and EAS where appropriate.

Write/update .vibe/checkpoint.json after major milestones: plan ready, code written, tests run, review complete, deploy attempted.

5. Validate

Run the project's relevant checks before final output:

• Install dependencies only when needed and allowed by the current environment.
• Run build/typecheck/test commands discovered from package.json.
• For frontend work, inspect the UI with the available browser/screenshot workflow when practical.
• Run a focused security review: no plaintext secrets, .env* ignored except examples, no unsafe SQL concatenation, no uncontrolled HTML injection, and no committed local tool state.

If a check fails, fix once using the smallest coherent change. If it still fails, write .vibe/checkpoint.json with the last error and tell the user the exact next action.

6. Deploy Or Finish

Deploy only when the approved plan includes deployment and the required credentials/tools are present. Ask for any sandbox, network, or external-service approval through Codex's normal approval flow.

Persist deploy output to .vibe/deploy-url.txt when there is a live URL. If deploy is skipped or blocked, return the local project path and the next concrete command to run.

Output Rules

• Match the user's language for user-visible text. Default to Vietnamese for ambiguous Vietnamese/English mixed requests.
• Keep progress concise. Do not expose internal reasoning.
• Do not instruct the user to use Claude-only slash commands unless explicitly discussing the Claude version.
• End with the app status, path, verification result, and next useful step.

Codex Compatibility

Codex skill frontmatter must contain only name and description. Do not add Claude-only keys such as argument-hint or allowed-tools.

When adapting existing vibe-kit skills, keep reusable domain instructions and replace Claude-specific tool names with Codex-native actions. Use references/codex-tool-mapping.md as the conversion guide.