bahayonghang/codex-workflow-recommender

Codex Workflow Recommender

Analyze a codebase and the local Codex surface, then recommend a safe implementation order for Codex-specific workflow improvements.

This skill is read-only. It may inspect files and run read-only discovery commands, but it must not create, edit, install, remove, or reconfigure anything. End with implementation options the user can approve separately.

Output Contract

Return exactly these top-level sections unless the user asks for a narrower category:

1. Codebase Profile
2. Current Codex Surface
3. Top Recommendations by category
4. Safe Implementation Order
5. Verification Plan
6. Want me to implement...

Keep recommendations evidence-based. Recommend the highest-value 1-2 items per relevant category, not a catalog dump.

Discovery Workflow

1. Profile the repository

Inspect only enough to classify the project and its verification gates:

# POSIX shells
find . -maxdepth 3 \( -name package.json -o -name pyproject.toml -o -name Cargo.toml -o -name go.mod -o -name justfile -o -name Makefile \) -print
find . -maxdepth 4 \( -name AGENTS.md -o -path './.codex/*' \) -print

# PowerShell
Get-ChildItem -Recurse -Depth 3 -Include package.json,pyproject.toml,Cargo.toml,go.mod,justfile,Makefile | Select-Object -ExpandProperty FullName
Get-ChildItem -Recurse -Depth 4 -Force -Include AGENTS.md | Select-Object -ExpandProperty FullName

Capture:

| Signal | Why it matters | |---|---| | language/runtime manifests | hooks, test commands, subagent expertise | | frontend/backend/data boundaries | Playwright/browser MCP, DB MCP, API docs | | existing AGENTS.md files | root vs nested guidance recommendations | | .codex/skills, .codex/agents | project-local Codex capabilities already present | | ~/.codex/config.toml, ~/.codex/hooks.json when readable | user-level Codex config and hook surface | | CI and local gates | verification plan and safe hook candidates | | external services in dependencies or docs | MCP/plugin candidates | | OMX files such as .omx/ or AGENTS.md OMX sections | optional repo-specific runtime workflows |

2. Confirm the local Codex command surface

Prefer the installed CLI over memory:

codex --help
codex mcp --help
codex plugin --help
codex doctor --help

When available, also inspect configured state without modifying it:

codex mcp list --json
codex plugin list
codex plugin marketplace list

If a command is missing, state that the recommendation depends on the installed Codex version.

3. Load focused references only when needed

• MCP recommendations: references/mcp-servers.md
• Skills recommendations: references/skills-reference.md
• Hooks/config recommendations: references/hooks-patterns.md
• Native subagents: references/subagent-templates.md
• Plugins: references/plugins-reference.md

Do not load every reference by default.

Recommendation Categories

AGENTS.md guidance

Recommend root or nested AGENTS.md changes when the repository has distinct subtrees, commands, generated files, safety boundaries, or verification gates that future Codex agents must know. If the user wants direct AGENTS.md edits, use agents-md-improver instead of this read-only recommender.

Codex skills

Recommend skills for repeatable workflows, project-specific procedures, bundled scripts/templates, or domain knowledge that should be discoverable by Codex. Typical roots include:

• user/system skills: ~/.codex/skills
• project-local skills: .codex/skills
• shared installs used by this repo/user environment: ~/.agents/skills

Confirm the actual roots for the current environment before giving path-specific instructions.

Native subagents

Recommend .codex/agents or ~/.codex/agents only for bounded roles with clear ownership, sandbox expectations, and verification responsibilities. Avoid suggesting a subagent when a skill, prompt, or direct instruction is simpler.

MCP servers

Recommend MCP only when external tool access materially helps: browser automation, live docs, databases, issue trackers, observability, cloud services, or filesystem boundaries. Use codex mcp add/list/get/remove syntax and avoid provider-specific commands from other CLIs.

Plugins

Recommend plugins when the user needs a bundled set of skills/tools or a reusable team distribution unit. Use codex plugin list/add/remove/marketplace syntax and verify marketplaces before recommending a plugin name.

Config and hooks

Recommend ~/.codex/config.toml or hook-related changes only when the current Codex installation and local policy support them. Treat ~/.codex/hooks.json as environment-specific; do not invent a schema when it is not present. For enforcement that must work outside Codex, recommend standard repo gates such as pre-commit, just, npm scripts, or CI.

Codex CLI runtime

Recommend direct CLI features when they match the workflow:

| Need | Codex surface | |---|---| | non-interactive implementation or analysis | codex exec | | read-only diff review | codex review | | continue or branch a previous session | codex resume / codex fork | | diagnose install/auth/config health | codex doctor | | sandboxed local command execution | codex sandbox | | launch desktop app | codex app |

OMX workflows

Mention OMX only when the repository or user environment shows OMX is installed or requested. Present it as an optional enhancement, not a universal Codex capability.

Report Template

## Codex Workflow Recommendations

### Codebase Profile
- **Type**: ...
- **Primary gates**: ...
- **Risk boundaries**: ...

### Current Codex Surface
- **AGENTS.md**: root/nested/global status
- **Skills**: discovered roots and notable project-local skills
- **Subagents**: discovered `.codex/agents` or user agents
- **MCP**: configured or absent
- **Plugins**: configured marketplaces/plugins or absent
- **Config/hooks**: current known surface and unsupported gaps
- **OMX**: present/absent/optional

### Top Recommendations by category

#### AGENTS.md
1. **...**
   - Evidence: ...
   - Why now: ...
   - Suggested scope: ...

#### Skills
...

#### Native subagents
...

#### MCP servers
...

#### Plugins
...

#### Config/hooks
...

#### Codex CLI runtime
...

### Safe Implementation Order
1. Read-only inventory and baseline verification
2. AGENTS.md or docs guidance changes
3. Local/project skill or subagent additions
4. MCP/plugin/config changes behind explicit approval
5. Verification and rollback notes

### Verification Plan
- `codex doctor` for installation/config health
- repository-specific lint/type/test/build gates
- skill or agent validators when new packages are added
- `codex mcp list --json` / `codex plugin list` after configuration changes

### Want me to implement...
I can implement the approved local-file changes next. I will not install plugins, add MCP servers, or change user-level config without explicit approval.

Safety Rules

• Do not modify files or run install/remove/config mutation commands in this skill.
• Do not claim a Codex feature exists solely because another CLI has it.
• Do not recommend secrets in config files; prefer environment variables and bearer-token env var options where supported.
• Do not place OMX recommendations in the critical path unless the current environment actually uses OMX.
• Keep implementation advice reversible and ordered from lowest-risk to highest-risk.