Codex Workflows Skill

Workflow operating system for GPT Codex in VS Code.

It routes natural-language requests into repeatable execution workflows:

• /brainstorm
• /plan
• /create
• /enhance
• /game-dev
• /roblox-game-dev
• /debug
• /test
• /deploy
• /preview
• /status
• /orchestrate
• /ui-ux-pro-max

Short activation aliases:

• cw /<workflow> <objective>
• codex-workflow /<workflow> <objective>

Positioning

This project applies workflow-operating-system patterns to the Codex skill format for VS Code.

• Designed for GPT Codex skill loading and routing
• Independent repository and implementation

What Is Included

skills/
  codex-workflows/
    SKILL.md
    agents/openai.yaml
    scripts/
      route_workflow.py
      route_workflow_fast.py
      routing_data.py
      bootstrap_project_agent.py
      sync_compat_pack.py
      build_compat_manifest.py
      check_compat_drift.py
      check_workflow_parity.py
      check_codex_native_quality.py
      check_codex_native_assets.py
      benchmark_router.py
      codex_workflows_ops.py
    compat/
      manifest.json
    packs/
      antigravity-compat/.agent/** (full compatibility pack)
    references/
      workflow-playbook.md
      workflows/*.md
      routing/intent-matrix.md
      orchestration/phase-gates.md
      templates/output-templates.md
    templates/codex-native/.agent/** (default codex-native profile with native agents and skills)
    templates/.agent/** (full template baseline)
    templates/minimal/.agent/** (lightweight starter)
  codex-backend-pack/
  codex-frontend-pack/
  codex-security-pack/
  codex-qa-pack/
  codex-node-validation-pack/
  codex-python-validation-pack/
  codex-rust-validation-pack/
scripts/
  codexwf.py
  release_automation.py
  install_all_in_one.py
examples/
  node-auth-api/
  python-fastapi-orders/
  rust-events-cli/
  projects/
    node-service/
    python-service/
    rust-service/
website/
  docs/
  .vitepress/
  scripts/sync_reference_docs.py

Installation

Option 1: NPM all-in-one CLI (recommended)

npx @codex-workflow/cw

Install only core:

npx @codex-workflow/cw --core-only

Check prerequisites:

npx @codex-workflow/cw doctor

This command uses Codex's official Python skill installer under the hood and installs all packs in one execution.

Option 2: All-in-one install (direct Python)

python ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo helberfmelo/codex-workflows \
  --path \
    skills/codex-workflows \
    skills/codex-backend-pack \
    skills/codex-frontend-pack \
    skills/codex-security-pack \
    skills/codex-qa-pack \
    skills/codex-node-validation-pack \
    skills/codex-python-validation-pack \
    skills/codex-rust-validation-pack

Windows (PowerShell):

python "$env:USERPROFILE\.codex\skills\.system\skill-installer\scripts\install-skill-from-github.py" `
  --repo "helberfmelo/codex-workflows" `
  --path `
    "skills/codex-workflows" `
    "skills/codex-backend-pack" `
    "skills/codex-frontend-pack" `
    "skills/codex-security-pack" `
    "skills/codex-qa-pack" `
    "skills/codex-node-validation-pack" `
    "skills/codex-python-validation-pack" `
    "skills/codex-rust-validation-pack"

This installs the orchestration core plus all domain and stack packs in one command.

Option 3: All-in-one helper script from this repository

python scripts/install_all_in_one.py

Unified CLI alternative:

python scripts/codexwf.py install

The helper script:

• auto-detects CODEX_HOME (or ~/.codex)
• skips already-installed skills safely
• installs only missing packs

Dry run:

python scripts/install_all_in_one.py --dry-run

Install from a specific tag/ref:

python scripts/install_all_in_one.py --ref v1.1.0

Option 4: Install only the core skill (minimal)

python ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo helberfmelo/codex-workflows \
  --path skills/codex-workflows

Option 5: Composer wrapper (PHP teams, optional)

Composer wrappers call the same official Codex Python installer.

Install all packs:

composer codex:install-all

Install only core:

composer codex:install-core

Install from a specific tag/ref:

composer codex:install-all -- --ref=v1.1.0

Quick Start

1. Restart Codex after installation.
2. Prompt with workflow intent, for example:

• cw /orchestrate harden auth flow with tests
• cw /help
• cw /examples
• Use codex-workflows and run /orchestrate for this feature
• Apply /debug workflow for this failing test
• Use codex-workflows in /game-dev and design the core gameplay loop
• Use codex-workflows in /roblox-game-dev and harden RemoteEvent security

3. Optional: bootstrap local .agent in any project:

python ~/.codex/skills/codex-workflows/scripts/bootstrap_project_agent.py --project .

This default profile is codex-native and uses an independent codex-native .agent template with:

• 13 rewritten workflow contracts (/brainstorm to /ui-ux-pro-max, including /game-dev and /roblox-game-dev)
• native agents/ capability catalog
• native skills/ capability catalog

Equivalent via unified CLI (inside this repository):

python scripts/codexwf.py init --project .

Compatibility profile:

python ~/.codex/skills/codex-workflows/scripts/bootstrap_project_agent.py --project . --profile antigravity-compat

Minimal profile:

python ~/.codex/skills/codex-workflows/scripts/bootstrap_project_agent.py --project . --profile minimal

4. Optional: classify request intent deterministically:

python ~/.codex/skills/codex-workflows/scripts/route_workflow.py "add secure login with tests" --json

5. Optional: refresh compatibility pack from a local .agent compatibility source:

python ~/.codex/skills/codex-workflows/scripts/sync_compat_pack.py --source /path/to/.agent

6. Validate compatibility and workflow parity:

python ~/.codex/skills/codex-workflows/scripts/check_workflow_parity.py \
  --references ~/.codex/skills/codex-workflows/references/workflows \
  --native ~/.codex/skills/codex-workflows/templates/codex-native/.agent/workflows \
  --template ~/.codex/skills/codex-workflows/templates/.agent/workflows \
  --pack ~/.codex/skills/codex-workflows/packs/antigravity-compat/.agent/workflows

python ~/.codex/skills/codex-workflows/scripts/check_compat_drift.py \
  --manifest ~/.codex/skills/codex-workflows/compat/manifest.json \
  --pack ~/.codex/skills/codex-workflows/packs/antigravity-compat/.agent \
  --template-full ~/.codex/skills/codex-workflows/templates/.agent

7. Validate codex-native workflow quality:

python ~/.codex/skills/codex-workflows/scripts/check_codex_native_quality.py \
  --native ~/.codex/skills/codex-workflows/templates/codex-native/.agent/workflows \
  --compat ~/.codex/skills/codex-workflows/packs/antigravity-compat/.agent/workflows \
  --max-similarity 0.35

8. Validate codex-native structural assets:

python ~/.codex/skills/codex-workflows/scripts/check_codex_native_assets.py \
  --native-root ~/.codex/skills/codex-workflows/templates/codex-native/.agent \
  --min-agents 20 \
  --min-skills 37

9. Benchmark routing runtime:

python ~/.codex/skills/codex-workflows/scripts/benchmark_router.py --iterations 10000

10. Run stack validation packs:

python ~/.codex/skills/codex-node-validation-pack/scripts/validate_node_stack.py --project .
python ~/.codex/skills/codex-python-validation-pack/scripts/validate_python_stack.py --project .
python ~/.codex/skills/codex-rust-validation-pack/scripts/validate_rust_stack.py --project .

11. Unified maintenance commands:

python scripts/codexwf.py status
python scripts/codexwf.py validate --tests
python scripts/codexwf.py docs-sync --build

Web Portal (/website)

Portal de documentacao implementado dentro do proprio repositorio, em website/.

Idiomas:

• English (default)
• Portugues (Brasil) em /pt/
• Espanol em /es/
• Francais em /fr/
• 中文 em /zh/

Rodar localmente:

cd website
npm install
npm run docs:dev

Build local:

cd website
npm run docs:build

Deploy:

• workflow dedicado: .github/workflows/docs.yml
• publica build no branch gh-pages
• configure o GitHub Pages para usar gh-pages na primeira vez
• release e CI continuam separados em .github/workflows/release.yml e .github/workflows/ci.yml

Prompting Best Practices

Use explicit skill + workflow phrasing for the most reliable behavior.

1. For complex tasks, start with:

• cw /orchestrate <your objective>
• Use codex-workflows in /orchestrate and <your objective>

2. For focused tasks, keep the workflow explicit:

• cw /debug investigate this error
• cw /plan break this feature into milestones
• Use codex-workflows and run /debug for this error
• Use codex-workflows and run /plan for this feature

3. This works for any workflow name in the catalog, not only /orchestrate.
4. Supported explicit trigger formats:

• cw /<workflow>
• codex-workflow /<workflow>
• codex-workflows /<workflow>
• Use codex-workflows in /<workflow>
• Use codex-workflows em /<workflow>

5. Utility commands:

• cw /help -> activation and usage help
• cw /examples -> workflow list + short summaries + examples

6. In a new chat/session, repeat the activation line in the first message.
7. In the same chat, short continuation prompts are enough:

• Continue with codex-workflows /orchestrate from current plan

8. Treat /orchestrate, /debug, /plan, etc. as intent labels in prompts, not native CLI slash commands.

Recommended activation template:

cw /orchestrate <goal>.
Keep phase gates, verify outputs, and return a concise report.

Automation note:

• Explicit-trigger behavior is covered in tests/test_route_workflow.py for both router implementations.

Behavior Notes

• Slash-like terms (for example /orchestrate) are interpreted as workflow intent in prompts.
• They are not native Codex CLI slash commands.
• If a project has local .agent files, local instructions have priority.

Comparison to Antigravity

See docs/COMPARISON.md for a detailed comparison and adaptation strategy.

Compatibility Scope

This repository includes a full compatibility pack under skills/codex-workflows/packs/antigravity-compat/.agent for optional interoperability with Antigravity-style .agent projects.

The default bootstrap path codex-native is independent from the compatibility pack and is sourced from skills/codex-workflows/templates/codex-native/.agent.

Workflow contracts are split:

• Native parity: references/workflows/*.md <-> templates/codex-native/.agent/workflows/*.md
• Compatibility parity: templates/.agent/workflows/*.md <-> packs/antigravity-compat/.agent/workflows/*.md

Native capability layer is also validated:

• templates/codex-native/.agent/agents/*.md
• templates/codex-native/.agent/skills/*/SKILL.md

Domain Packs

Independent packs are available for targeted installation:

• skills/codex-backend-pack
• skills/codex-frontend-pack
• skills/codex-security-pack
• skills/codex-qa-pack
• skills/codex-node-validation-pack
• skills/codex-python-validation-pack
• skills/codex-rust-validation-pack

The routers also return recommended_packs based on detected domains.

Release Automation

Use scripts/release_automation.py to automate changelog cut, commit, tag, and optional push.

Dry run:

python scripts/release_automation.py --version 1.1.0

Apply and publish:

python scripts/release_automation.py --version 1.1.0 --apply --commit --tag --push

GitHub Actions release workflow:

• .github/workflows/release.yml (workflow_dispatch)
• Auto publish on tag push (v*) using docs/releases/<tag>.md when available

End-to-End Examples

• examples/node-auth-api/README.md
• examples/python-fastapi-orders/README.md
• examples/rust-events-cli/README.md
• examples/projects/README.md (real runnable fixtures used by CI matrix)

CI and Quality Gates

• CI pipeline: .github/workflows/ci.yml
• Release pipeline: .github/workflows/release.yml
• Real stack matrix on fixtures: Node/Python/Rust in .github/workflows/ci.yml
• Skill validation: scripts/ci_validate_skill.py
• Unit tests: tests/test_*.py

Contributing

See CONTRIBUTING.md.

Community and Governance

• Issue templates:
  • .github/ISSUE_TEMPLATE/bug_report.yml
  • .github/ISSUE_TEMPLATE/feature_request.yml
• Pull request template:
  • .github/PULL_REQUEST_TEMPLATE.md
• Code ownership:
  • .github/CODEOWNERS

Changelog

See CHANGELOG.md.

Compatibility

• GPT Codex with skills support
• VS Code Codex workflow
• Windows, macOS, Linux

License

MIT