codex-workflow-recommender

name	codex-workflow-recommender
description	>- Use when this capability is needed.

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
-  for installation/config health
 repository-specific lint/type/test/build gates
 skill or agent validators when new packages are added
  /  after configuration changes


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.

---

Source: bahayonghang/my-claude-code-settings — distributed by TomeVault.